phrep

Artifact [b48a9e1853]
Login

Artifact b48a9e1853c49ba5ef90f5464485ae10a4899d35:

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