The Tor Browser / file revision

 .. _preprocessor:

 =================

 Text Preprocessor

 =================

 The build system contains a text preprocessor similar to the C preprocessor,

 meant for processing files which have no built-in preprocessor such as XUL

 and JavaScript documents. It is implemented at ``python/mozbuild/mozbuild/preprocessor.py`` and

 is typically invoked via :ref:`jar_manifests`.

 While used to preprocess CSS files, the directives are changed to begin with

 ``%`` instead of ``#`` to avoid conflict of the id selectors.

 Directives

 ==========

 Variable Definition

 -------------------

 define

 ^^^^^^

 ::

    #define variable

    #define variable value

 Defines a preprocessor variable.

 Note that, unlike the C preprocessor, instances of this variable later in the

 source are not automatically replaced (see #filter). If value is not supplied,

 it defaults to ``1``.

 Note that whitespace is significant, so ``"#define foo one"`` and

 ``"#define foo one "`` is different (in the second case, ``foo`` is defined to

 be a four-character string).

 undef

 ^^^^^

 ::

    #undef variable

 Undefines a preprocessor variable.

 Conditionals

 ------------

 if

 ^^

 ::

    #if variable

    #if !variable

    #if variable==string

    #if variable!=string

 Disables output if the conditional is false. This can be nested to arbitrary

 depths. Note that in the equality checks, the variable must come first, and

 the comparison operator must not be surrounded by any whitespace.

 else

 ^^^^

 ::

    #else

 Reverses the state of the previous conditional block; for example, if the

 last ``#if`` was true (output was enabled), an ``#else`` makes it off

 (output gets disabled).

 .. warning:: An ``#else`` is relative to the last conditional block only,

    unlike the C preprocessor.

    It does not matter whether any blocks before it were true. This behavior

    changed on trunk (Gecko 1.9) on 2006-12-07; see Bug 277122 for details.

 ::

    #if 1

      always included

    #elif 1

      never included

    #else

      always included

    #endif

 endif

 ^^^^^

 ::

    #endif

 Ends the conditional block.

 ifdef / ifndef

 ^^^^^^^^^^^^^^

 ::

    #ifdef variable

    #ifndef variable

 An ``#if`` conditional that is true only if the preprocessor variable

 variable is defined (in the case of ``ifdef``) or not defined (``ifndef``).

 elif / elifdef / elifndef

 ^^^^^^^^^^^^^^^^^^^^^^^^^

 ::

    #elif variable

    #elif !variable

    #elif variable == string

    #elif variable != string

    #elifdef variable

    #elifndef variable

 A shorthand to mean an ``#else`` combined with the relevant conditional.

 The following two blocks are equivalent::

    #ifdef foo

      block 1

    #elifdef bar

      block 2

    #endif

 ::

    #ifdef foo

      block 1

    #else

    #ifdef bar

      block 2

    #endif

    #endif

 .. warning:: An ``#elif``, ``#elifdef``, or ``#elifndef`` is relative to

    the last conditional block only (as well as the condition it implies),

    unlike the C preprocessor. It does not matter whether any blocks before

    it were true. This behavior changed on trunk (Gecko 1.9) on 2006-12-07.

    See Bug 277122 for details.

 File Inclusion

 --------------

 include

 ^^^^^^^

 ::

    #include filename

 The file specified by filename is processed as if the contents was placed

 at this position. This also means that preprocessor conditionals can even

 be started in one file and ended in another (but is highly discouraged).

 There is no limit on depth of inclusion, or repeated inclusion of the same

 file, or self inclusion; thus, care should be taken to avoid infinite loops.

 includesubst

 ^^^^^^^^^^^^

 ::

    #includesubst @variable@filename

 Same as a ``#include`` except that all instances of variable in the included

 file is also expanded as in ``#filter`` substitution

 expand

 ^^^^^^

 ::

    #expand string

 All variables wrapped in ``__`` are replaced with their value, for this line

 only. If the variable is not defined, it expands to an empty string. For

 example, if ``foo`` has the value ``bar``, and ``baz`` is not defined, then::

    #expand This <__foo__> <__baz__> gets expanded

 Is expanded to::

    This <bar> <> gets expanded

 filter / unfilter

 ^^^^^^^^^^^^^^^^^

 ::

    #filter filter1 filter2 ... filterN

    #unfilter filter1 filter2 ... filterN

 ``#filter`` turns on the given filter.

 Filters are run in alphabetical order on a per-line basis.

 ``#unfilter`` turns off the given filter. Available filters are:

 emptyLines

    strips blank lines from the output

 slashslash

    strips everything from the first two consecutive slash (``/``)

    characters until the end of the line

 spaces

    collapses consecutive sequences of spaces into a single space,

    and strips leading and trailing spaces

 substitution

    all variables wrapped in @ are replaced with their value. If the

    variable is not defined, it is a fatal error. Similar to ``#expand``

    and ``#filter``

 attemptSubstitution

    all variables wrapped in ``@`` are replaced with their value, or an

    empty string if the variable is not defined. Similar to ``#expand``.

 literal

 ^^^^^^^

 ::

    #literal string

 Output the string (i.e. the rest of the line) literally, with no other fixups.

 This is useful to output lines starting with ``#``, or to temporarily

 disable filters.

 Other

 -----

 #error

 ^^^^^^

 ::

    #error string

 Cause a fatal error at this point, with the error message being the

 given string.