The Tor Browser: comparison build/docs/preprocessor.rst

--1:000000000000
+:8920b700902c
+.. _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.

The Tor Browser / file comparison

comparison: build/docs/preprocessor.rst

build/docs/preprocessor.rst