Wiki page
[pragma] by
mario
2015-04-28 22:16:42.
D 2015-04-28T22:16:42.132
L pragma
N text/x-markdown
P 84c6ab325a61f3e2a21b8dbed1a1294375872557
U mario
W 6782
Pragma directives influence phreps behaviour.
* They can be utilized **from within** processed/included files.
* More fine-grained control, avoid too many cmdline <kbd>-flags</kbd>.
There are two *#pragma* syntax variations:
* Assignment/option syntax
#pragma(output=0)
* 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 `#include` scripts.
* And some just influence the later tokenization/substitution phase.
# `output=0`
Allows to suppress output from the current file.
* This flag is also inherited to subincludes.
* It's implied for `*.h` and `*.def` includes (see omit= pragma).
# `omit=*.{h,def}`
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.
# `comments=0`
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
just the `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.
# `constants=0`
Prevents constant substitution. Note that constants are still collected
during preprocessing. They're just exempt from being replaced in PHP
code. Equals <kbd>-nc</kbd> flag.
# `defprefix=`
Adds a name prefix to collected constants/macros. (Don't use this.)
# `macros=0`
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 <kbd>-nm</kbd> flag.
# `complex=0`
Disables just the expansion of `COMPLEX@(x,y)` macros. Same as <kbd>-nx</kbd>.
# `multipass=5`
<img src="raw/e8eb2d6ab065521bfdb010f1919984eeb9b6d0a7?m=image/jpeg"
width=295 height=215 align=right>
Basic macros can reference other macros or constants. The `multipass=`
option limits how much recursion is allowed (to prevent neverending
loops).
* Note that this flag isn't just boolean, but a counter. So `multipass=1`
would 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](wiki/complex) macros.
# `keep_empty=1`
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.
# `fail=1`
Per default *phrep* will happily continue after warning messages.
* Missing `#include` files are usually considered non-critical.
* And invalid `#if` expressions will just evaluate to false.
Skipping conditional sections is therefore often sufficient.
With `fail=1` all warnings are turned into fatal errors however.
So each of these failure conditions will abort the rewrite run.
Same as <kbd>-W</kbd> flag.
# `quiet=1`
Disables warnings completely (see <kbd>-w</kbd> option).
# `interpolate=token`
Phrep has two basic modes to search and replace constants and macros.
* The default <kbd>tokenizer</kbd> scheme only looks within
`<?php` code sections.
* All all other modes are <kbd>regex</kbd> variants, that look for
literal `CONSTANT` notations.
| <kbd>token</kbd> | **Default**. Avoids replacing constants/macros outside of valid PHP syntax constructs. |
| <kbd>regex</kbd> | 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. |
| <kbd>phpp</kbd> | Uses PHPP-style constant enclosures. That is only `{{{CONSTANT_NAME}}}` within the assembled output will be replaced. Same for `{{{MACRO(1,2,3)}}}`, but everything else left alone. |
| <kbd>erb</kbd> | Another variation of the regex mode, that utilizes Ruby/ERB-style enclosures like `%{CONSTNAME}`. |
| <kbd>delim $$ $$</kbd> | Allows to set custom delimiters as constant enclosures, such as `$$CONSTNAME$$` or `%%CONSTNAME%%`. |
The mode can be set per `#pragma` or just via <kbd>phrep -m phpp</kbd> option.
* It's a global option, so shouldn't be fiddled with in #include files,
best just from a main `config.h`
* 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.)
# `dirs=../includes`
*Adds* further search paths for #include lookups.
* This is equivalent to the <kbd>-I</kbd> option.
* Can currently take a list of paths `dirs=./lib/:./add/:./includes/`
* But later versions will just allow a single path to be added.
(Too ambiguous for Windows paths, and prevents reliable phar:// scheme
usage.)
# `preserve=file,line,output`
`preserve` is somewhat of an internal option. (Implemented to compact
some logic actually). It defines which pragma states to retain between
`#include` files.
For example the `line` and `file` are switched out. And the `output`
flag gets reset to its previous state.
# `file=input.php`
Again an internal option, that stores the currently processed/included
file name.
# `line=123`
Is the internal counter for the processed line number.
Theoretically you can adapt this in include files per `#pragma(line=2048)`
to compensate for miscalculations or shifts. (Not overly useful in
practice, which is why this is a `#pragma` option and not a `#line`
directive of its own.)
# `input=main.ph`
Stores the main processed file, as set by `phrep -i`.
It is also mirrored as `__BASE_FILE__` constant, btw.
# `target=filename`
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.
Z 48ceba1d129724729a666257a980a058