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:

• 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 -nc 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 -nm flag.

complex=0

Disables just the expansion of COMPLEX@(x,y) macros. Same as -nx.

multipass=5

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 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 -W flag.

quiet=1

Disables warnings completely (see -w option).

interpolate=token

Phrep has two basic modes to search and replace constants and macros.

• The default tokenizer scheme only looks within <?php code sections.
• All all other modes are regex variants, that look for literal CONSTANT notations.

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 {{{CONSTANT_NAME}}} within the assembled output will be replaced. Same for {{{MACRO(1,2,3)}}}, but everything else left alone.
erb	Another variation of the regex mode, that utilizes Ruby/ERB-style enclosures like %{CONSTNAME}.
delim $$ $$	Allows to set custom delimiters as constant enclosures, such as $$CONSTNAME$$ or %%CONSTNAME%%.

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 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 -I 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.