Syntax Specification

The syntax of a macro call is the following : it must start with a sequence of characters matching the macro start sequence as specified in the current mode, followed immediately by the name of the macro, which must be a valid identifier, i.e. a sequence of letters, digits, or underscores ("_"). The macro name must be followed by a short macro end sequence if the macro has no arguments, or by a sequence of arguments initiated by an argument start sequence. The various arguments are then separated by an argument separator, and the macro ends with a long macro end sequence.

In all cases, the parameters of the current context, i.e. the arguments passed to the body being evaluated, can be referred to by using an argument reference sequence followed by a digit between 1 and 9. Macro parameters may alternately be named (see below). Furthermore, to avoid interference between the gpp syntax and the contents of the input file a quote character is provided. The quote character can be used to prevent the interpretation of a macro call, comment, or string as anything but plain text. The quote character "protects" the following character, and always gets removed during evaluation. Two consecutive quote characters evaluate as a single quote character.

Finally, to facilitate proper argument delimitation, certain characters can be "stacked" when they occur in a macro argument, so that the argument separator or macro end sequence are not parsed if the argument body is not balanced. This allows nesting macro calls without using quotes. If an improperly balanced argument is needed, quote characters should be added in front of some stacked characters to make it balanced.

The macro construction sequences described above can be different for meta-macros and for user macros: this is e.g. the case in cpp mode. Note that, since meta-macros can only have up to two arguments, the delimitation rules for the second argument are somewhat sloppier, and unquoted argument separator sequences are allowed in the second argument of a meta-macro.

Unless one of the standard operating modes is selected, the above syntax sequences can be specified either on the command-line, using the -M and -U options respectively for meta-macros and user macros, or inside an input file via the #mode meta and #mode user meta-macro calls. In both cases the mode description consists of 9 parameters for user macro specifications, namely the macro start sequence, the short macro end sequence, the argument start sequence, the argument separator, the long macro end sequence, the string listing characters to stack, the string listing characters to unstack, the argument reference sequence, and finally the quote character. As explained below these sequences should be supplied using the syntax of C strings; they must start with a non-alphanumeric character, and in the first five strings special matching sequences can be used (see below). If the argument corresponding to the quote character is the empty string that functionality is disabled. For meta-macro specifications there are only 7 parameters, as the argument reference sequence and quote character are shared with the user macro syntax.

The structure of a comment/string is the following : it must start with a sequence of characters matching the given comment/string start sequence, and always ends at the first occurrence of the comment/string end sequence, unless it is preceded by an odd number of occurrences of the string-quote character (if such a character has been specified). In certain cases comment/strings can be specified to enable macro evaluation inside the comment/string: in that case, if a quote character has been defined for macros it can be used as well to prevent the comment/string from ending, with the difference that the macro quote character is always removed from output whereas the string-quote character is always output. Also note that under certain circumstances a comment/string specification can be disabled, in which case the comment/string start sequence is simply ignored. Finally, it is possible to specify a string warning character whose presence inside a comment/string will cause gpp to output a warning (this is useful e.g. to locate unterminated strings in cpp mode). Note that input files are not allowed to contain unterminated comments/strings.

A comment/string specification can be declared from within the input file using the #mode comment meta-macro call (or equivalently #mode string), in which case the number of C strings to be given as arguments to describe the comment/string can be anywhere between 2 and 4: the first two arguments (mandatory) are the start sequence and the end sequence, and can make use of the special matching sequences (see below). They may not start with alphanumeric characters. The first character of the third argument, if there is one, is used as string-quote character (use an empty string to disable the functionality), and the first character of the fourth argument, if there is one, is used as string-warning character. A specification may also be given from the command-line, in which case there must be two arguments if using the +c option and three if using the +s option.

The behavior of a comment/string is specified by a three-character modifier string, which may be passed as an optional argument either to the +c/+s command-line options or to the #mode comment/ #mode string meta-macros. If no modifier string is specified, the default value is "ccc" for comments and "sss" for strings. The first character corresponds to the behavior inside meta-macro calls (including user-macro definitions since these come inside a #define meta-macro call), the second character corresponds to the behavior inside user-macro parameters, and the third character corresponds to the behavior outside of any macro call. Each of these characters can take the following values:

• i: disable the comment/string specification.
• c: comment (neither evaluated nor output).
• s: string (the string and its delimiter sequences are output as is).
• q: quoted string (the string is output as is, without the delimiter sequences).
• C: evaluated comment (macros are evaluated, but output is discarded).
• S: evaluated string (macros are evaluated, delimiters are output).
• Q: evaluated quoted string (macros are evaluated, delimiters are not output).

Important note: any occurrence of a comment/string start sequence inside another comment/string is always ignored, even if macro evaluation is enabled. In other words, comments/strings cannot be nested. In particular, the 'Q' modifier can be a convenient way of defining a syntax for temporarily disabling all comment and string specifications.

Syntax specification strings should always be provided as C strings, whether they are given as arguments to a #mode meta-macro call or on the command-line of a Unix shell. If command-line arguments are given via another method than a standard Unix shell, then the shell behavior must be emulated, i.e. the surrounding "" quotes should be removed, all occurrences of '$\backslash$$\backslash$' should be replaced by a single backslash, and similarly '$\backslash$"' should be replaced by '"'. Sequences like '$\backslash$n' are recognized by gpp and should be left as is.

Special sequences matching certain subsets of the character set can be used. They are of the form '$\backslash$ x', where x is one of:

• b: matches any sequence of one or more spaces or TAB characters ('$\backslash$b' is identical to ' ').
• w: matches any sequence of zero or more spaces or TAB characters.
• B: matches any sequence of one or more spaces, tabs or newline characters.
• W: matches any sequence of zero or more spaces, tabs or newline characters.
• a: an alphabetic character ('a' to 'z' and 'A' to 'Z').
• A: an alphabetic character, or a space, tab or newline.
• #: a digit ('0' to '9').
• i: an identifier character. The set of matched characters is customizable using the #mode charset id command. The default setting matches alphanumeric characters and underscores ('a' to 'z', 'A' to 'Z', '0' to '9' and '_').
• t: a TAB character.
• n: a newline character.
• o: an operator character. The set of matched characters is customizable using the #mode charset op command. The default setting matches all characters in "+-*/$\backslash$^$<$$>$=`$\sim$:.?@#&!%$\vert$", except in Prolog mode where '!', '%' and '$\vert$' are not matched.
• O: an operator character or a parenthesis character. The set of additional matched characters in comparison with '$\backslash$o' is customizable using the #mode charset par command. The default setting is to have the characters in "()[]{}" as parentheses.

Moreover, all of these matching subsets except '$\backslash$w' and '$\backslash$W' can be negated by inserting a '!', i.e. by writing '$\backslash$! x' instead of '$\backslash$ x'.

Note an important distinctive feature of start sequences: when the first character of a macro or comment/string start sequence is ' ' or one of the above special sequences, it is not taken to be part of the sequence itself but is used instead as a context check: for example a start sequence beginning with '$\backslash$n' matches only at the beginning of a line, but the matching newline character is not taken to be part of the sequence. Similarly a start sequence beginning with ' ' matches only if some whitespace is present, but the matching whitespace is not considered to be part of the start sequence and is therefore sent to output. If a context check is performed at the very beginning of a file (or more generally of any body to be evaluated), the result is the same as matching with a newline character (this makes it possible for a cpp-mode file to start with a meta-macro call).