Pragma directives influence phreps behaviour.
- They can be utilized from within processed/included files.
- More fine-grained control, avoid too many cmdline -flags.
There are two #pragma syntax variations:
And a traditional CPP-style
#pragma option value
Most pragma options behave like global flags for the whole preprocessing run.
- A few can change states between
- And some just influence the later tokenization/substitution phase.
Allows to suppress output from the current file.
- This flag is also inherited to subincludes.
- It's implied for
*.defincludes (see omit= pragma).
Is a glob pattern for #include file extensions. Implicitly sets
#pragma(output=0) for matching files. Used for avoiding literal
output from C header files.
Removes inline comments from constants and macros.
For example it's common that C header .h files declare values like:
#define ETIME 62 /* Timer expired */
Thus would interpolate errno constants in PHP code like:
return ($errno = 62 /* Timer expired */);
Which is actually nice for the implicit documentation. But for compactness
62 might be preferred.
Note that this flag takes action at parse time. So you can just disable comments for a single #include, but reenable it for others.
Prevents constant substitution. Note that constants are still collected during preprocessing. They're just exempt from being replaced in PHP code. Equals -nc flag.
Adds a name prefix to collected constants/macros. (Don't use this.)
Disables the collection of
MACRO(x,y) definitions. Which is useful to
extract C/C++ header file constants, but eschew macro definitions. (Which
may or may not work as PHP expressions).
- Now this flag can be enabled and disabled between includes.
- But if it's still disabled after the collection phase (end of main file), then macro substitution will be completely disabled.
Can be set per -nm flag.
Disables just the expansion of
COMPLEX@(x,y) macros. Same as -nx.
Basic macros can reference other macros or constants. The
option limits how much recursion is allowed (to prevent neverending
- Note that this flag isn't just boolean, but a counter. So
multipass=1would just allow one macro-in-macro expansion.
- It's disabled per default currently, but
#pragma(multipass=5)would likely suffice in most cases.
- It's a global flag, not just for single macros.
- Doesn't effect complex macros.
Will inject empty lines in place of
#directives. It'll also fill up
skipped literal output for inactive conditional sections.
This is mostly a debugging feature, to have a better correlation between input and output file line numbers.
Per default phrep will happily continue after warning messages.
#includefiles are usually considered non-critical.
#ifexpressions will just evaluate to false. Skipping conditional sections is therefore often sufficient.
fail=1 all warnings are turned into fatal errors however.
So each of these failure conditions will abort the rewrite run.
Same as -W flag.
Disables warnings completely (see -w option).
Phrep has two basic modes to search and replace constants and macros.
- The default tokenizer scheme only looks within
- All all other modes are regex variants, that look for
|token||Default. Avoids replacing constants/macros outside of valid PHP syntax constructs.|
|regex||Performs a literal substitution. Such that constants and macros work outside of PHP code context, and for instance within HTML or PHP strings and comments.|
|phpp||Uses PHPP-style constant enclosures. That is only
|erb||Another variation of the regex mode, that utilizes Ruby/ERB-style enclosures like
|delim $$ $$||Allows to set custom delimiters as constant enclosures, such as
The mode can be set per
#pragma or just via phrep -m phpp option.
- It's a global option, so shouldn't be fiddled with in #include files,
best just from a main
- It's useful nonetheless for context-sensitive replacements or macro code expansion in e.g. HTML/output templates. (Please keep in mind that Phrep is not meant as runtime/templating engine however.)
Adds further search paths for #include lookups.
- This is equivalent to the -I option.
- Can currently take a list of paths
- But later versions will just allow a single path to be added. (Too ambiguous for Windows paths, and prevents reliable phar:// scheme usage.)
preserve is somewhat of an internal option. (Implemented to compact
some logic actually). It defines which pragma states to retain between
For example the
file are switched out. And the
flag gets reset to its previous state.
Again an internal option, that stores the currently processed/included file name.
Is the internal counter for the processed line number.
Theoretically you can adapt this in include files per
to compensate for miscalculations or shifts. (Not overly useful in
practice, which is why this is a
#pragma option and not a
directive of its own.)
Stores the main processed file, as set by
It is also mirrored as
__BASE_FILE__ constant, btw.
Sets the output filename if
phrep -otarget is used.
This can be useful in conjunction with build/make scripts.
#ifdef BUILD_LOCAL_PKG #pragma(target=build/local-main.php) #endif
Again, it probably shouldn't be used habitually in #include scripts.