xenial (1) gpp.1.gz

Provided by: gpp_2.24-3_amd64 bug

NAME

       GPP - Generic Preprocessor

SYNOPSIS

         gpp [-{o|O} outfile] [-I/include/path] [-Dname=val ...]
             [-z|+z] [-x] [-m] [-C|-T|-H|-X|-P|-U ... [-M ...]]
             [-n|+n] [+c<n> str1 str2] [+s<n> str1 str2 c]
             [-c str1] [--nostdinc] [--nocurinc]
             [--curdirinclast] [--warninglevel n]
             [--includemarker str] [--include file]
             [infile]

         gpp --help

         gpp --version

DESCRIPTION

       GPP  is  a  general-purpose  preprocessor  with  customizable  syntax,  suitable  for  a  wide  range  of
       preprocessing tasks. Its independence from any programming language makes it  much  more  versatile  than
       cpp, while its syntax is lighter and more flexible than that of m4.

       GPP  is  targeted  at  all  common  preprocessing  tasks  where  cpp  is  not  suitable and where no very
       sophisticated features are needed. In order to be able to  process  equally  efficiently  text  files  or
       source  code  in  a  variety  of languages, the syntax used by GPP is fully customizable. The handling of
       comments and strings is especially advanced.

       Initially, GPP only understands a minimal set of built-in macros, called meta-macros.  These  meta-macros
       allow  the  definition  of  user  macros  as  well  as  some  basic  operations  forming  the core of the
       preprocessing system, including conditional tests, arithmetic evaluation, wildcard  matching  (globbing),
       and  syntax  specification.  All  user  macro  definitions  are  global  -- i.e., they remain valid until
       explicitly removed; meta-macros cannot be redefined. With each user macro definition GPP keeps  track  of
       the corresponding syntax specification so that a macro can be safely invoked regardless of any subsequent
       change in operating mode.

       In addition to macros, GPP understands comments and strings, whose syntax  and  behavior  can  be  widely
       customized  to fit any particular purpose.  Internally comments and strings are the same construction, so
       everything that applies to comments applies to strings as well.

OPTIONS

       GPP recognizes the following command-line switches and options.   Note  that  the  -nostdinc,  -nocurinc,
       -curdirinclast, -warninglevel, and -includemarker options from version 2.1 and earlier are deprecated and
       should not be used.  Use the "long option" variants instead (--nostdinc, etc.).

       -h --help
              Print a short help message.

       --version
              Print version information.

       -o outfile
              Specify a file to which all output should be sent (by default,  everything  is  sent  to  standard
              output).

       -O outfile
              Specify a file to which all output should be sent; output is simultanously sent to stdout.

       -I/include/path
              Specify  a  path where the #include meta-macro will look for include files if they are not present
              in the current directory. The default is /usr/include if no -I option is  specified.  Multiple  -I
              options may be specified to look in several directories.

       -Dname=val
              Define the user macro name as equal to val. This is strictly equivalent to using the #define meta-
              macro, but makes it possible to define macros from the command-line. If val  makes  references  to
              arguments  or  other macros, it should conform to the syntax of the mode specified on the command-
              line. Starting with version 2.1, macro argument naming is allowed on the command-line. The  syntax
              is  as  follows:  -Dmacro(arg1,...)=definition.  The  arguments  are  specified in C-style syntax,
              without any whitespace, but the definition  should  still  conform  to  the  syntax  of  the  mode
              specified on the command-line.

       +z     Set  text  mode  to  Unix  mode  (LF  terminator). Any CR character in the input is systematically
              discarded. This is the default under Unix systems.

       -z     Set text mode to DOS mode (CR-LF terminator). In this mode all CR characters are removed from  the
              input, and all output LF characters are converted to CR-LF. This is the default if GPP is compiled
              with the WIN_NT option.

       -x     Enable the use of the #exec meta-macro. Since #exec includes the  output  of  an  arbitrary  shell
              command line, it may cause a potential security threat, and is thus disabled unless this option is
              specified.

       -m     Enable automatic mode switching to the cpp compatibility mode if the name of an included file ends
              in `.h' or `.c'. This makes it possible to include C header files with only minor modifications.

       -n     Prevent  newline or whitespace characters from being removed from the input when they occur as the
              end of a macro call or of a comment. By default, when a newline or whitespace character forms  the
              end  of  a  macro  or  a  comment  it is parsed as part of the macro call or comment and therefore
              removed from output. Use the -n option to keep the last character in the input stream  if  it  was
              whitespace or a newline. This is activated in cpp and Prolog modes.

       +n     The  opposite of -n. This is the default in all modes except cpp and Prolog.  Note that +n must be
              placed after -C or -P in order to have any effect.

       -U arg1 ... arg9
              User-defined mode. The nine following command-line arguments are  taken  to  be  respectively  the
              macro  start  sequence,  the  macro  end sequence for a call without arguments, the argument start
              sequence, the argument separator, the argument end sequence, the list of characters to  stack  for
              argument  balancing,  the list of characters to unstack, the string to be used for referring to an
              argument by number, and finally the quote character (if there is none an empty  string  should  be
              provided).   These  settings apply both to user macros and to meta-macros, unless the -M option is
              used to define other settings for meta-macros. See the section on syntax  specification  for  more
              details.

       -M arg1 ... arg7
              User-defined  mode  specifications for meta-macros. This option can only be used together with -M.
              The seven following command-line arguments are taken to be respectively the macro start  sequence,
              the  macro  end  sequence  for a call without arguments, the argument start sequence, the argument
              separator, the argument end sequence, the list of characters to stack for argument balancing,  and
              the list of characters to unstack. See below for more details.

       (default mode)
              The default mode is a vaguely cpp-like mode, but it does not handle comments, and presents various
              incompatibilities with cpp.  Typical meta-macros and user macros look like this:

                #define x y
                macro(arg,...)

              This mode is equivalent to

                -U "" "" "(" "," ")" "(" ")" "#" "\\"
                -M "#" "\n" " " " " "\n" "(" ")"

       -C     cpp compatibility mode. This is the mode where GPP's behavior is  the  closest  to  that  of  cpp.
              Unlike  in  the  default  mode,  meta-macro expansion occurs only at the beginning of lines, and C
              comments and strings are understood. This mode is equivalent to

                -n -U "" "" "(" "," ")" "(" ")" "#" ""
                -M "\n#\w" "\n" " " " " "\n" "" ""
                +c "/*" "*/" +c "//" "\n" +c "\\\n" ""
                +s "\"" "\"" "\\" +s "'" "'" "\\"

       -T     TeX-like mode. In this mode, typical meta-macros and user macros look like this:

                \define{x}{y}
                \macro{arg}{...}

              No comments are understood. This mode is equivalent to

                -U "\\" "" "{" "}{" "}" "{" "}" "#" "@"

       -H     HTML-like mode. In this mode, typical meta-macros and user macros look like this:

                <#define x|y>
                <#macro arg|...>

              No comments are understood. This mode is equivalent to

                -U "<#" ">" "\B" "|" ">" "<" ">" "#" "\\"

       -X     XHTML-like mode. In this mode, typical meta-macros and user macros look like this:

                <#define x|y/>
                <#macro arg|.../>

              No comments are understood. This mode is equivalent to

                -U "<#" "/>" "\B" "|" "/>" "<" ">" "#" "\\"

       -P     Prolog-compatible cpp-like mode. This mode differs from the cpp compatibility mode by its handling
              of comments, and is equivalent to

                -n -U "" "" "(" "," ")" "(" ")" "#" ""
                -M "\n#\w" "\n" " " " " "\n" "" ""
                +ccss "\!o/*" "*/" +ccss "%" "\n" +ccii "\\\n" ""
                +s "\"" "\"" "" +s "\!#'" "'" ""

       +c<n> str1 str2
              Specify  comments.  Any  unquoted  occurrence  of  str1  will be interpreted as the beginning of a
              comment. All input up to the first following occurrence of str2 will be discarded. This option may
              be  used  multiple  times to specify different types of comment delimiters. The optional parameter
              <n> can be specified to alter the behavior of the comment and, e.g., turn it into a string or make
              it ignored under certain circumstances, see below.

       -c str1
              Un-specify  comments  or strings. The comment/string specification whose start sequence is str1 is
              removed. This is useful to alter the built-in comment specifications of a standard mode  --  e.g.,
              the cpp compatibility mode.

       +s<n> str1 str2 c
              Specify strings. Any unquoted occurrence of str1 will be interpreted as the beginning of a string.
              All input up to the first  following  occurrence  of  str2  will  be  output  as  is  without  any
              evaluation.  The  delimiters themselves are output. If c is non-empty, its first character is used
              as a string-quote character -- i.e., a character whose presence immediately before  an  occurrence
              of  str2  prevents it from terminating the string.  The optional parameter <n> can be specified to
              alter the behavior of the string and, e.g., turn it into a comment, enable macro evaluation inside
              the string, or make the string specification ignored under certain circumstances. See below.

       -s str1
              Un-specify comments or strings. Identical to -c.

       --include file
              Process file before infile

       --nostdinc
              Do not look for include files in the standard directory /usr/include.

       --nocurinc
              Do not look for include files in the current directory.

       --curdirinclast
              Look  for include files in the current directory after the directories specified by -I rather than
              before them.

       --warninglevel n
              Set warning level to n (0, 1 or 2). Default is 2 (most verbose).

       --includemarker str
              keep track of #include directives by inserting a marker in the output stream. The  format  of  the
              marker  is  determined  by  str,  which  must  contain  three  occurrences  of the character % (or
              equivalently ?). The first occurrence is replaced with the line number, the second with  the  file
              name,  and  the  third with 1, 2 or blank. When this option is specified in default, cpp or Prolog
              mode, GPP does its best to ensure that line numbers are the same in the output as in the input  by
              inserting blank lines in the place of definitions or comments.

       infile Specify an input file from which GPP reads its input. If no input file is specified, input is read
              from standard input.

SYNTAX SPECIFICATION

       The syntax of a macro call is as follows: 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.   Alternatively, macro parameters may 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 the case in cpp mode, for example.  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 nine 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 argument's functionality is disabled. For meta-macro
       specifications there are only seven parameters, as the argument reference sequence  and  quote  character
       are shared with the user macro syntax.

       The structure of a comment/string is as follows: 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  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 two and four: 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 the 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 the 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  `\\'  should  be  replaced  by  a  single
       backslash,  and  similarly `\"' should be replaced by `"'.  Sequences like `\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  `\x',
       where x is one of:

       b      matches any sequence of one or more spaces or tab characters (`\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 "+-*/\^<>=`~:.?@#&!%|",  except  in  Prolog
              mode where `!', `%' and `|' are not matched.

       O      an  operator  character  or  a  parenthesis character. The set of additional matched characters in
              comparison with `\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 `\w' and `\W' can be negated by inserting a `!' -- i.e.,
       by writing `\!x' instead of `\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
       '\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).

       Two special syntax rules were added in version  2.1.  First,  argument  references  (#n)  are  no  longer
       evaluated  when  they  are outside of macro calls and definitions. However, they are no longer allowed to
       appear (unless protected by quote characters) inside a call to a defined user macro; the current behavior
       (backwards compatible) is to remove them silently from the input if that happens.

       Second,  if  the end sequence (either for macros or comments) consists of a single newline character, and
       if delimitation rules lead to evaluation in a context where the final newline character  is  absent,  GPP
       silently  ignores  the  missing newline instead of producing an error. The main consequence is that meta-
       macro calls can now be nested in a simple way in standard, cpp and Prolog modes.

EVALUATION RULES

       Input is read sequentially and interpreted according to the rules of the current mode. All input text  is
       first  matched  against  the  specified  comment/string start sequences of the current mode (except those
       which are disabled by the  'i'  modifier),  unless  the  body  being  evaluated  is  the  contents  of  a
       comment/string  whose  modifier  enables  macro  evaluation.   The  most  recently defined comment/string
       specifications are checked for first. Important note: comments may not appear between the name of a macro
       and its arguments (doing so results in undefined behavior).

       Anything  that  is  not  a comment/string is then matched against a possible meta-macro call, and if that
       fails too, against a possible user-macro call. All remaining  text  undergoes  substitution  of  argument
       reference  sequences  by  the  relevant  argument  text  (empty  unless  the  body being evaluated is the
       definition of a user macro) and removal of the quote character if there is one.

       Note that meta-macro arguments are passed to the meta-macro prior to any evaluation (although  the  meta-
       macro  may  choose  to  evaluate them, see meta-macro descriptions below). In the case of the #mode meta-
       macro, GPP temporarily adds a comment/string specification to enable recognition of C strings ("...") and
       prevent  any  evaluation  inside  them,  so  no  interference of the characters being put in the C string
       arguments to #mode with the current syntax is to be feared.

       On the other hand, the arguments to a user macro are systematically evaluated, and then passed as context
       parameters  to  the macro definition body, which gets evaluated with that environment. The only exception
       is when the macro definition is empty, in which case its arguments  are  not  evaluated.  Note  that  GPP
       temporarily  switches  back  to the mode in which the macro was defined in order to evaluate it, so it is
       perfectly safe to change the operating mode between the time a macro is defined and the time when  it  is
       called. Conversely, if a user macro wishes to work with the current mode instead of the one that was used
       to define it it needs to start with a #mode restore call and end with a #mode save call.

       A user macro may be defined with named arguments (see #define description below). In that case, when  the
       macro  definition  is  being  evaluated,  each  named  parameter  causes  a  temporary virtual user-macro
       definition to be created; such a macro may be called only without arguments and simply returns  the  text
       of the corresponding argument.

       Note that, since macros are evaluated when they are called rather than when they are defined, any attempt
       to call a recursive macro causes undefined behavior except in the very specific case when the macro  uses
       #undef to erase itself after finitely many loop iterations.

       Finally, a special case occurs when a user macro whose definition does not involve any arguments (neither
       named arguments nor the argument reference sequence) is called in a mode where the short  user-macro  end
       sequence is empty (e.g., cpp or TeX mode). In that case it is assumed to be an alias macro: its arguments
       are first evaluated in the current mode as usual, but instead of being passed to the macro definition  as
       parameters  (which  would cause them to be discarded) they are actually appended to the macro definition,
       using the syntax rules of the mode in which the macro was defined, and the resulting  text  is  evaluated
       again.  It  is therefore important to note that, in the case of a macro alias, the arguments actually get
       evaluated twice in two potentially different modes.

META-MACROS

       These macros are always predefined. 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 may be needed  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,  and  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 only as 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 <>.

              The order in which the various directories are searched for  include  files  is  affected  by  the
              -nostdinc, -nocurinc and -curdirinclast command-line options.

              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, for security reasons, this meta-macro is disabled unless the -x command
              line  flag  was  specified.   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 and/or wildcard matching.  The  syntax  and  operator
              precedence for arithmetic expressions are the same as in C; the only missing operators are <<, >>,
              ?:, and the assignment operators.

              POSIX-style wildcard matching ('globbing') is available only on POSIX implementations and  can  be
              invoked  with  the  =~  operator.  In brief, a '?' matches any single character, a '*' matches any
              string (including the empty string), and '[...]' matches any one of  the  characters  enclosed  in
              brackets.   A  '[...]' class is complemented when the first character in the brackets is '!'.  The
              characters in a '[...]'  class can also be specified as a range using the '-' character  --  e.g.,
              '[F-N]' is equivalent to '[FGHIJKLMN]'.

              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
              comparison  operators  ==,  !=, <, >, <=, and >= which, if one of the sides does not evaluate to a
              number, perform string comparison instead (ignoring trailing and leading  spaces).   Additionally,
              the length(...) arithmetic operator returns the length in characters of its evaluated argument.

              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/globbing 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.

       #elif expr
              This  meta-macro  can  be  used  to  avoid  nested  #if  conditions.   #if ... #elif ... #endif is
              equivalent to #if ... #else #if ...  #endif #endif.

       #mode keyword ...
              This meta-macro controls GPP's operating mode. See below for a list of #mode commands.

       #line  This meta-macro evaluates to the line number of the current input file.

       #file  This meta-macro evaluates to the filename of the current input file as it appears on  the  command
              line or in the argument to #include.  If GPP is reading its input from stdin, then #file evaluates
              to `stdin'.

       #date fmt
              This meta-macro evaluates to the current date and time as formatted by the specified format string
              fmt.  See the section DATE AND TIME CONVERSION SPECIFIERS below.

       #error msg
              This  meta-macro  causes  an error message with the current filename and line number, and with the
              text msg, to be printed to the standard error device.  Subsequent processing is then aborted.

       #warning msg
              This meta-macro causes a warning message with the current filename and line number, and  with  the
              text msg, to be printed to the standard error device.  Subsequent processing is then resumed.

       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); xhtml, XHTML (xhtml 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  seven
              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 can be neither alphanumeric nor '_', nor  can  it  be
              one of the special matching sequences.

       #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.

DATE AND TIME CONVERSION SPECIFIERS

       Ordinary  characters placed in the format string are copied to without conversion.  Conversion specifiers
       are introduced by a `%' character, and are replaced as follows:

       %a     The abbreviated weekday name according to the  current locale.

       %A     The  full  weekday  name  according  to the current locale.

       %b     The abbreviated month name according to the current locale.

       %B     The  full  month  name  according  to  the  current locale.

       %c     The preferred date and time representation for  the current locale.

       %d     The day of the month as a decimal number (range  01 to 31).

       %F     Equivalent to %Y-%m-%d (the ISO 8601 date  format).

       %H     The  hour as a decimal number using a 24-hour clock (range 00 to 23).

       %I     The hour as a decimal number using a 12-hour  clock (range 01 to 12).

       %j     The  day of the year as a decimal number (range 001 to 366).

       %m     The month as a decimal number (range 01 to 12).

       %M     The minute as a decimal number (range 00 to 59).

       %p     Either `AM' or `PM' according  to  the  given  time value, or the corresponding  strings  for  the
              current locale.  Noon is treated as `pm'  and  midnight  as `am'.

       %R     The  time  in  24-hour notation (%H:%M).

       %S     The second as a decimal number (range 00 to 61).

       %U     The  week number of the current year  as  a  decimal number,  range  00  to  53, starting with the
              first Sunday as the first day of week 01.

       %w     The  day  of  the  week as a decimal, range 0 to 6, Sunday being 0.

       %W     The week number of the current year  as  a  decimal number,  range  00  to  53, starting with  the
              first Monday as the first day of week 01.

       %x     The preferred date representation for  the  current locale without the time.

       %X     The  preferred  time representation for the current locale without the date.

       %y     The year as a  decimal  number  without  a  century (range 00 to 99).

       %Y     The year as a decimal number including the century.

       %Z     The time zone or name or abbreviation.

       %%     A literal `%' character.

       Depending  on  the  C  compiler  and library used to compile GPP, there may be more conversion specifiers
       available.  Consult your compiler's documentation for the strftime() function.  Note, however,  that  any
       conversion specifiers not listed above may not be portable across installations of GPP.

EXAMPLES

       Here is a basic self-explanatory example in standard or cpp mode:

         #define FOO This is
         #define BAR a message.
         #define concat #1 #2
         concat(FOO,BAR)
         #ifeq (concat(foo,bar)) (foo bar)
         This is output.
         #else
         This is not output.
         #endif

       Using argument naming, the concat macro could alternatively be defined as

         #define concat(x,y) x y

       In TeX mode and using argument naming, the same example becomes:

         \define{FOO}{This is}
         \define{BAR}{a message.}
         \define{\concat{x}{y}}{\x \y}
         \concat{\FOO}{\BAR}
         \ifeq{\concat{foo}{bar}}{foo bar}
         This is output.
         \else
         This is not output.
         \endif

       In HTML mode and without argument naming, one gets similarly:

         <#define FOO|This is>
         <#define BAR|a message.>
         <#define concat|#1 #2>
         <#concat <#FOO>|<#BAR>>
         <#ifeq <#concat foo|bar>|foo bar>
         This is output.
         <#else>
         This is not output.
         <#endif>

       The following example (in standard mode) illustrates the use of the quote character:

         #define FOO This is \
            a multiline definition.
         #define BLAH(x) My argument is x
         BLAH(urf)
         \BLAH(urf)

       Note  that  the  multiline  definition is also valid in cpp and Prolog modes despite the absence of quote
       character, because '\' followed by a newline is then interpreted as a comment and discarded.

       In cpp mode, C strings and comments are understood as such, as illustrated by the following example:

         #define BLAH foo
         BLAH "BLAH" /* BLAH */
         'It\'s a /*string*/ !'

       The main difference between Prolog mode and cpp mode is the handling of strings and comments: in  Prolog,
       a  '...'  string may not begin immediately after a digit, and a /*...*/ comment may not begin immediately
       after an operator character. Furthermore, comments are not removed from the output unless they occur in a
       #command.

       The  differences  between  cpp  mode  and  default  mode  are deeper: in default mode #commands may start
       anywhere, while in cpp mode they must be at the beginning of a line; the default mode has no knowledge of
       comments  and  strings,  but  has  a  quote  character ('\'), while cpp mode has extensive comment/string
       specifications but no quote character. Moreover, the  arguments  to  meta-macros  need  to  be  correctly
       parenthesized in default mode, while no such checking is performed in cpp mode.

       This makes it easier to nest meta-macro calls in default mode than in cpp mode. For example, consider the
       following HTML mode input, which tests for the availability of the #exec command:

         <#ifeq <#exec echo blah>|blah
         > #exec allowed <#else> #exec not allowed <#endif>

       There is no cpp mode equivalent, while in default mode it can be easily translated as

         #ifeq (#exec echo blah
         ) (blah
         )
         \#exec allowed
         #else
         \#exec not allowed
         #endif

       In order to nest meta-macro calls in cpp mode it is necessary to modify the mode description,  either  by
       changing  the  meta-macro  call  syntax, or more elegantly by defining a silent string and using the fact
       that the context at the beginning of an evaluated string is a newline character:

         #mode string QQQ "$" "$"
         #ifeq $#exec echo blah
         $ $blah
         $
         \#exec allowed
         #else
         \#exec not allowed
         #endif

       Note, however, that comments/strings cannot be nested ("..." inside $...$ would go  undetected),  so  one
       needs  to  be  careful  about what to include inside such a silent evaluated string. In this example, the
       loose meta-macro nesting introduced in version 2.1  makes  it  possible  to  use  the  following  simpler
       version:

         #ifeq blah #exec echo -n blah
         \#exec allowed
         #else
         \#exec not allowed
         #endif

       Remember  that  macros  without arguments are actually understood to be aliases when they are called with
       arguments, as illustrated by the following example (default or cpp mode):

         #define DUP(x) x x
         #define FOO and I said: DUP
         FOO(blah)

       The usefulness of the #defeval meta-macro is shown by the following example in HTML mode:

         <#define APPLY|<#defeval TEMP|<\##1 \#1>><#TEMP #2>>
         <#define <#foo x>|<#x> and <#x>>
         <#APPLY foo|BLAH>

       The reason why #defeval is needed is that, since everything is evaluated in a single pass, the input that
       will result in the desired macro call needs to be generated by a first evaluation of the arguments passed
       to APPLY before being evaluated a second time.

       To translate this example in default mode, one needs to resort to parenthesizing in  order  to  nest  the
       #defeval  call  inside the definition of APPLY, but need to do so without outputting the parentheses. The
       easiest solution is

         #define BALANCE(x) x
         #define APPLY(f,v) BALANCE(#defeval TEMP f
         TEMP(v))
         #define foo(x) x and x
         APPLY(\foo,BLAH)

       As explained above the simplest version in cpp mode relies on defining a silent evaluated string to  play
       the role of the BALANCE macro.

       The following example (default or cpp mode) demonstrates arithmetic evaluation:

         #define x 4
         The answer is:
         #eval x*x + 2*(16-x) + 1998%x

         #if defined(x)&&!(3*x+5>17)
         This should be output.
         #endif

       To  finish,  here  are some examples involving mode switching.  The following example is self-explanatory
       (starting in default mode):

         #mode push
         #define f(x) x x
         #mode standard tex
         \f{blah}
         \mode{string}{"$" "$"}
         \mode{comment}{"/*" "*/"}
         $\f{urf}$ /* blah */
         \define{FOO}{bar/* and some more */}
         \mode{pop}
         f($FOO$)

       A good example where a user-defined mode becomes useful is the GPP source  of  this  document  (available
       with GPP's source code distribution).

       Another  interesting  application  is  selectively  forcing evaluation of macros in C strings when in cpp
       mode. For example, consider the following input:

         #define blah(x) "and he said: x"
         blah(foo)

       Obviously one would want the parameter x to be expanded inside the string. There are several ways  around
       this problem:

         #mode push
         #mode nostring "\""
         #define blah(x) "and he said: x"
         #mode pop

         #mode quote "`"
         #define blah(x) `"and he said: x`"

         #mode string QQQ "$$" "$$"
         #define blah(x) $$"and he said: x"$$

       The  first  method  is  very  natural, but has the inconvenience of being lengthy and neutralizing string
       semantics, so that having an unevaluated instance of 'x' in the string, or an occurrence of  '/*',  would
       be impossible without resorting to further contortions.

       The  second  method  is  slightly more efficient because the local presence of a quote character makes it
       easier to control what is evaluated and what isn't, but has the drawback that it is sometimes  impossible
       to  find  a  reasonable  quote  character without having to either significantly alter the source file or
       enclose it inside a #mode push/pop construct. For example, any occurrence of '/*'  in  the  string  would
       have to be quoted.

       The  last method demonstrates the efficiency of evaluated strings in the context of selective evaluation:
       since comments/strings cannot be nested, any occurrence of '"' or '/*' inside the  '$$'  gets  output  as
       plain  text,  as  expected inside a string, and only macro evaluation is enabled. Also note that there is
       much more freedom in the choice of a string delimiter than in the choice of a quote character.

       Starting with version 2.1, meta-macro calls can be nested more efficiently in  default,  cpp  and  Prolog
       modes. This makes it easy to make a user version of a meta-macro, or to increment a counter:

         #define myeval #eval #1

         #define x 1
         #defeval x #eval x+1

ADVANCED EXAMPLES

       Here  are some examples of advanced constructions using GPP. They tend to be pretty awkward and should be
       considered as evidence of GPP's limitations.

       The first example is a recursive macro. The main problem is  that  (since  GPP  evaluates  everything)  a
       recursive  macro  must  be  very careful about the way in which recursion is terminated in order to avoid
       undefined behavior (most of the time GPP will simply crash). In particular, relying on a #if/#else/#endif
       construct  to end recursion is not possible and results in an infinite loop, because GPP scans user macro
       calls even in the unevaluated branch of the conditional block. A safe way to proceed is  for  example  as
       follows (we give the example in TeX mode):

         \define{countdown}{
           \if{#1}
           #1...
           \define{loop}{\countdown}
           \else
           Done.
           \define{loop}{}
           \endif
           \loop{\eval{#1-1}}
         }
         \countdown{10}

       Another example, in cpp mode:

         #mode string QQQ "$" "$"
         #define triangle(x,y) y \
          $#if length(y)<x$ $#define iter triangle$ $#else$ \
          $#define iter$ $#endif
         $ iter(x,*y)
         triangle(20)

       The  following  is an (unfortunately very weak) attempt at implementing functional abstraction in GPP (in
       standard mode). Understanding this example and why it can't be made much simpler is an exercise  left  to
       the curious reader.

         #mode string "`" "`" "\\"
         #define ASIS(x) x
         #define SILENT(x) ASIS()
         #define EVAL(x,f,v) SILENT(
           #mode string QQQ "`" "`" "\\"
           #defeval TEMP0 x
           #defeval TEMP1 (
             \#define \TEMP2(TEMP0) f
           )
           TEMP1
           )TEMP2(v)
         #define LAMBDA(x,f,v) SILENT(
           #ifneq (v) ()
           #define TEMP3(a,b,c) EVAL(a,b,c)
           #else
           #define TEMP3(a,b,c) \LAMBDA(a,b)
           #endif
           )TEMP3(x,f,v)
         #define EVALAMBDA(x,y) SILENT(
           #defeval TEMP4 x
           #defeval TEMP5 y
           )
         #define APPLY(f,v) SILENT(
           #defeval TEMP6 ASIS(\EVA)f
           TEMP6
           )EVAL(TEMP4,TEMP5,v)

       This yields the following results:

         LAMBDA(z,z+z)
           => LAMBDA(z,z+z)

         LAMBDA(z,z+z,2)
           => 2+2

         #define f LAMBDA(y,y*y)
         f
           => LAMBDA(y,y*y)

         APPLY(f,blah)
           => blah*blah

         APPLY(LAMBDA(t,t t),(t t))
           => (t t) (t t)

         LAMBDA(x,APPLY(f,(x+x)),urf)
           => (urf+urf)*(urf+urf)

         APPLY(APPLY(LAMBDA(x,LAMBDA(y,x*y)),foo),bar)
           => foo*bar

         #define test LAMBDA(y,`#ifeq y urf
         y is urf#else
         y is not urf#endif
         `)
         APPLY(test,urf)
           => urf is urf

         APPLY(test,foo)
           => foo is not urf

SEE ALSO

       strftime(3), glob(7), m4(1V), cpp(1)

       GPP home page: http://www.nothingisreal.com/gpp/

AUTHOR

       GPP  was  written  by  Denis  Auroux <auroux@math.mit.edu>.  Since version 2.12 it has been maintained by
       Tristan Miller <psychonaut@nothingisreal.com>.

       Copyright (C) 1996-2001 Denis Auroux.

       Copyright (C) 2003, 2004 Tristan Miller.

       Permission is granted to anyone to make or distribute verbatim copies of this document  as  received,  in
       any  medium, provided that the copyright notice and this permission notice are preserved, thus giving the
       recipient permission to redistribute in turn.

       Permission is granted to distribute modified versions of this document, or of portions of it,  under  the
       above conditions, provided also that they carry prominent notices stating who last changed them.

                                                                                                          GPP(1)