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

       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)