Meta-macros

These macros are always pre-defined. Their actual calling sequence depends on the current mode; here we use cpp-like notation.

• #define x y
  This defines the user macro x as y. y can be any valid gpp input, and may for example refer to other macros. x must be an identifier (i.e. a sequence of alphanumeric characters and '_'), unless named arguments are specified. If x is already defined, the previous definition is overwritten. If no second argument is given, x will be defined as a macro that outputs nothing. Neither x nor y are evaluated; the macro definition is only evaluated when it is called, not when it is declared.

  It is also possible to name the arguments in a macro definition: in that case, the argument x should be a user-macro call whose arguments are all identifiers. These identifiers become available as user-macros inside the macro definition; these virtual macros must be called without arguments, and evaluate to the corresponding macro parameter.

• #defeval x y
  This acts in a similar way to #define, but the second argument y is evaluated immediately. Since user macro definitions are also evaluated each time they are called, this means that the macro y will undergo two successive evaluations. The usefulness of #defeval is considerable, as it is the only way to evaluate something more than once, which can be needed e.g. to force evaluation of the arguments of a meta-macro that normally doesn't perform any evaluation. However since all argument references evaluated at define-time are understood as the arguments of the body in which the macro is being defined and not as the arguments of the macro itself, usually one has to use the quote character to prevent immediate evaluation of argument references.
• #undef x
  This removes any existing definition of the user macro x.
• #ifdef x
  This begins a conditional block. Everything that follows is evaluated only if the identifier x is defined, until either a #else or a #endif statement is reached. Note however that the commented text is still scanned thoroughly, so its syntax must be valid. It is in particular legal to have the #else or #endif statement ending the conditional block appear as only the result of a user-macro expansion and not explicitly in the input.
• #ifndef x
  This begins a conditional block. Everything that follows is evaluated only if the identifier x is not defined.
• #ifeq x y
  This begins a conditional block. Everything that follows is evaluated only if the results of the evaluations of x and y are identical as character strings. Any leading or trailing whitespace is ignored for the comparison. Note that in cpp-mode any unquoted whitespace character is understood as the end of the first argument, so it is necessary to be careful.
• #ifneq x y
  This begins a conditional block. Everything that follows is evaluated only if the results of the evaluations of x and y are not identical (even up to leading or trailing whitespace).
• #else
  This toggles the logical value of the current conditional block. What follows is evaluated if and only if the preceding input was commented out.
• #endif
  This ends a conditional block started by a #if... meta-macro.
• #include file
  This causes gpp to open the specified file and evaluate its contents, inserting the resulting text in the current output. All defined user macros are still available in the included file, and reciprocally all macros defined in the included file will be available in everything that follows. The include file is looked for first in the current directory, and then, if not found, in one of the directories specified by the -I command-line option (or /usr/include if no directory was specified). Note that, for compatibility reasons, it is possible to put the file name between "" or <>.

  Upon including a file, gpp immediately saves a copy of the current operating mode onto the mode stack, and restores the operating mode at the end of the included file. The included file may override this behavior by starting with a #mode restore call and ending with a #mode push call. Additionally, when the -m command line option is specified, gpp will automatically switch to the cpp compatibility mode upon including a file whose name ends with either '.c' or '.h'.

• #exec command
  This causes gpp to execute the specified command line and include its standard output in the current output. Note that this meta-macro is disabled unless the -x command line flag was specified, for security reasons. If use of #exec is not allowed, a warning message is printed and the output is left blank. Note that the specified command line is evaluated before being executed, thus allowing the use of macros in the command-line. However, the output of the command is included verbatim and not evaluated. If you need the output to be evaluated, you must use #defeval (see above) to cause a double evaluation.
• #eval expr
  The #eval meta-macro attempts to evaluate expr first by expanding macros (normal gpp evaluation) and then by performing arithmetic evaluation. The syntax and operator precedence for arithmetic expressions are the same as in C ; the only missing operators are «, », ?: and assignment operators. If unable to assign a numerical value to the result, the returned text is simply the result of macro expansion without any arithmetic evaluation. The only exceptions to this rule are the == and != operators which, if one of the sides does not evaluate to a number, perform string comparison instead (ignoring trailing and leading spaces).

  Inside arithmetic expressions, the defined(...) special user macro is also available: it takes only one argument, which is not evaluated, and returns 1 if it is the name of a user macro and 0 otherwise.

• #if expr
  This meta-macro invokes the arithmetic evaluator in the same manner as #eval, and compares the result of evaluation with the string "0" in order to begin a conditional block. In particular note that the logical value of expr is always true when it cannot be evaluated to a number.
• #mode keyword ...
  This meta-macro controls gpp's operating mode. See below for a list of #mode commands.

The key to gpp's flexibility is the #mode meta-macro. Its first argument is always one of a list of available keywords (see below); its second argument is always a sequence of words separated by whitespace. Apart from possibly the first of them, each of these words is always a delimiter or syntax specifier, and should be provided as a C string delimited by double quotes (" "). The various special matching sequences listed in the section on syntax specification are available. Any #mode command is parsed in a mode where "..." is understood to be a C-style string, so it is safe to put any character inside these strings. Also note that the first argument of #mode (the keyword) is never evaluated, while the second argument is evaluated (except of course for the contents of C strings), so that the syntax specification may be obtained as the result of a macro evaluation.

The available #mode commands are:

• #mode save / #mode push
  Push the current mode specification onto the mode stack.
• #mode restore / #mode pop
  Pop mode specification from the mode stack.
• #mode standard name
  Select one of the standard modes. The only argument must be one of: default (default mode); cpp, C (cpp mode); tex, TeX (tex mode); html, HTML (html mode); prolog, Prolog (prolog mode). The mode name must be given directly, not as a C string.
• #mode user "s1" ... "s9"
  Specify user macro syntax. The 9 arguments, all of them C strings, are the mode specification for user macros (see the -U command-line option and the section on syntax specification). The meta-macro specification is not affected.
• #mode meta {user | "s1" ... "s7"}
  Specify meta-macro syntax. Either the only argument is user (not as a string), and the user-macro mode specifications are copied into the meta-macro mode specifications, or there must be 7 string arguments, whose significance is the same as for the -M command-line option (see section on syntax specification).
• #mode quote ["c"]
  With no argument or "" as argument, removes the quote character specification and disables the quoting functionality. With one string argument, the first character of the string is taken to be the new quote character. The quote character cannot be alphanumeric nor '_', and cannot be one of the special matching sequences either.
• #mode comment [xxx] "start" "end" ["c" ["c"]]
  Add a comment specification. Optionally a first argument consisting of three characters not enclosed in " " can be used to specify a comment/string modifier (see the section on syntax specification). The default modifier is ccc. The first two string arguments are used as comment start and end sequences respectively. The third string argument is optional and can be used to specify a string-quote character (if it is "" the functionality is disabled). The fourth string argument is optional and can be used to specify a string delimitation warning character (if it is "" the functionality is disabled).
• #mode string [xxx] "start" "end" ["c" ["c"]]
  Add a string specification. Identical to #mode comment except that the default modifier is sss.
• #mode nocomment / #mode nostring ["start"]
  With no argument, remove all comment/string specifications. With one string argument, delete the comment/string specification whose start sequence is the argument.
• #mode preservelf { on | off | 1 | 0 }
  Equivalent to the -n command-line switch. If the argument is on or 1, any newline or whitespace character terminating a macro call or a comment/string is left in the input stream for further processing. If the argument is off or 0 this feature is disabled.
• #mode charset { id | op | par } "string"
  Specify the character sets to be used for matching the \o, \O and \i special sequences. The first argument must be one of id (the set matched by \i), op (the set matched by \o) or par (the set matched by \O in addition to the one matched by \o). "string" is a C string which lists all characters to put in the set. It may contain only the special matching sequences \a, \A, \b, \B, and \# (the other sequences and the negated sequences are not allowed). When a '-' is found inbetween two non-special characters this adds all characters inbetween (e.g. "A-Z" corresponds to all uppercase characters). To have '-' in the matched set, either put it in first or last position or place it next to a \x sequence.