gcc2-cpp-macro-doc.patch

   1 # DP: cpp.texi: add a node documenting macro varargs.
   2
   3 Sat Aug  7 14:56:50 1999  Matthias Klose  <doko@cs.tu-berlin.de>
   4
   5         * cpp.texi: cpp.texi: add a node documenting macro varargs (copied
   6         from extend.texi.
   7
   8 --- gcc/cpp.texi~       Wed May 19 13:22:57 1999
   9 +++ gcc/cpp.texi        Sat Aug  7 14:53:42 1999
  10 @@ -542,6 +542,7 @@
  11  * Simple Macros::    Macros that always expand the same way.
  12  * Argument Macros::  Macros that accept arguments that are substituted
  13                         into the macro expansion.
  14 +* Macro Varargs::    Macros with variable number of arguments.
  15  * Predefined::       Predefined macros that are always available.
  16  * Stringification::  Macro arguments converted into string constants.
  17  * Concatenation::    Building tokens from parts taken from macro arguments.
  18 @@ -645,7 +646,7 @@
  19  that the result of its expansion is checked for more macro names.
  20  @xref{Cascaded Macros}.
  21
  22 -@node Argument Macros, Predefined, Simple Macros, Macros
  23 +@node Argument Macros, Macro Varargs, Simple Macros, Macros
  24  @subsection Macros with Arguments
  25  @cindex macros with argument
  26  @cindex arguments in macro definitions
  27 @@ -799,7 +800,68 @@
  28  the left parenthesis; it's the @emph{definition} where it matters whether
  29  there is a space.
  30
  31 -@node Predefined, Stringification, Argument Macros, Macros
  32 +@node Macro Varargs, Predefined, Argument Macros, Macros
  33 +@subsection Macros with Variable Numbers of Arguments
  34 +@cindex variable number of arguments
  35 +@cindex macro with variable arguments
  36 +@cindex rest argument (in macro)
  37 +
  38 +In GNU C, a macro can accept a variable number of arguments, much as a
  39 +function can.  The syntax for defining the macro looks much like that
  40 +used for a function.  Here is an example:
  41 +
  42 +@example
  43 +#define eprintf(format, args...)  \
  44 + fprintf (stderr, format , ## args)
  45 +@end example
  46 +
  47 +Here @code{args} is a @dfn{rest argument}: it takes in zero or more
  48 +arguments, as many as the call contains.  All of them plus the commas
  49 +between them form the value of @code{args}, which is substituted into
  50 +the macro body where @code{args} is used.  Thus, we have this expansion:
  51 +
  52 +@example
  53 +eprintf ("%s:%d: ", input_file_name, line_number)
  54 +@expansion{}
  55 +fprintf (stderr, "%s:%d: " , input_file_name, line_number)
  56 +@end example
  57 +
  58 +@noindent
  59 +Note that the comma after the string constant comes from the definition
  60 +of @code{eprintf}, whereas the last comma comes from the value of
  61 +@code{args}.
  62 +
  63 +The reason for using @samp{##} is to handle the case when @code{args}
  64 +matches no arguments at all.  In this case, @code{args} has an empty
  65 +value.  In this case, the second comma in the definition becomes an
  66 +embarrassment: if it got through to the expansion of the macro, we would
  67 +get something like this:
  68 +
  69 +@example
  70 +fprintf (stderr, "success!\n" , )
  71 +@end example
  72 +
  73 +@noindent
  74 +which is invalid C syntax.  @samp{##} gets rid of the comma, so we get
  75 +the following instead:
  76 +
  77 +@example
  78 +fprintf (stderr, "success!\n")
  79 +@end example
  80 +
  81 +This is a special feature of the GNU C preprocessor: @samp{##} before a
  82 +rest argument that is empty discards the preceding sequence of
  83 +non-whitespace characters from the macro definition.  (If another macro
  84 +argument precedes, none of it is discarded.)
  85 +
  86 +It might be better to discard the last preprocessor token instead of the
  87 +last preceding sequence of non-whitespace characters; in fact, we may
  88 +someday change this feature to do so.  We advise you to write the macro
  89 +definition so that the preceding sequence of non-whitespace characters
  90 +is just a single token, so that the meaning will not change if we change
  91 +the definition of this feature.
  92 +
  93 +@node Predefined, Stringification, Macro Varargs, Macros
  94  @subsection Predefined Macros
  95
  96  @cindex predefined macros