phrep

Update of "pragma"
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Artifact ID: b48a9e1853c49ba5ef90f5464485ae10a4899d35
Page Name:pragma
Date: 2015-04-28 22:16:42
Original User: mario
Mimetype:text/x-markdown
Parent: 84c6ab325a61f3e2a21b8dbed1a1294375872557
Content

Pragma directives influence phreps behaviour.

There are two #pragma syntax variations:

Most pragma options behave like global flags for the whole preprocessing run.

output=0

Allows to suppress output from the current file.

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

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

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.

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.

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.

dirs=../includes

Adds further search paths for #include lookups.

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.