Pragma, Preprocessor: add "beforeInclude" hook, extend "once"

[vancluever]

This adds the beforeInclude pragma hook, which fires before a file is included. Its current and only implementation is in the "once" pragma, which has been extended to use it to ensure that #pragma once causes future inclusions of a file to be skipped outright, versus processed until the pragma is hit again.

This prevents scenarios where the directive has not been placed at the top of the file. This is a practice that is carried out in at least the GTK headers, and the current control flow causes inner-inclusion guards
to be hit when they should not be.

Note that since this is a deep-preprocessor event, it has not been added to the compilation-scoped PragmaEvent set, and just implemented as a hook local in the include function. If more event hooks get added in the future, it might be a good idea to review the event system to allow for scope-agnostic event types and payloads.

[vancluever]

This was discovered during our migration of Ghostty to Zig 0.16.0 (current PR is ghostty-org/ghostty#12726). It appears that the #pragma once in gdk/version/gdkversionmacros.h has been placed after the guards in the file, which causes some deeper includes to fail, particularly the include path that starts at gtk/gtkaboutdialog.h in gtk/gtk.h, by which point the GDK includes have been walked enough to undef __GDK_H_INSIDE__ (in addition to __GTK_CSS_H_INSIDE__ through the gtk/css/gtkcss.h path).

Managed to isolate the case to what is seen in the test here. A reproduction in clang seems to be fine, so I'm guessing this is generally the expected behavior.

Let me know if this needs anything!

[ehaas]

The test looks good. The fix works as a targeted solution to the problem; it would be nice if the pragma system itself could express this sort of thing (as it stands, a consumer of aro can provide their own pragmas, but they would not be able to provide a custom pragma that behaved the same as #pragma once since its behavior is now hardcoded into the preprocessor itself.)

I'm imagining something like another PragmaEvent like "before_include" or "should_include" or something like that; the default implementation would just return true but then custom pragmas could override it to allow deciding whether the file should be included.

I don't think implementing that is a blocker, especially since this issue is preventing use on a popular real-world library, just a thought for how we could improve the pragma system.

[vancluever]

@ehaas I think this would be a trivial thing (or at least not a complicated thing) to implement to start out. I'll update the PR in a bit!

[vancluever]

@ehaas PR updated - commentary in the commit and PR description!

[vancluever]

Thanks to the both of you!