home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / m4.info-1 < prev    next >
Encoding:
GNU Info File  |  1996-10-12  |  49.5 KB  |  1,496 lines
  1. This is Info file m4.info, produced by Makeinfo-1.63 from the input
  2. file m4.texinfo.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * m4: (m4).            A powerful macro processor.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file documents the GNU `m4' utility.
  9.  
  10.    Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994 Free Software
  11. Foundation, Inc.
  12.  
  13.    Permission is granted to make and distribute verbatim copies of this
  14. manual provided the copyright notice and this permission notice are
  15. preserved on all copies.
  16.  
  17.    Permission is granted to copy and distribute modified versions of
  18. this manual under the conditions for verbatim copying, provided that
  19. the entire resulting derived work is distributed under the terms of a
  20. permission notice identical to this one.
  21.  
  22.    Permission is granted to copy and distribute translations of this
  23. manual into another language, under the above conditions for modified
  24. versions, except that this permission notice may be stated in a
  25. translation approved by the Foundation.
  26.  
  27. 
  28. File: m4.info,  Node: Top,  Next: Preliminaries,  Prev: (dir),  Up: (dir)
  29.  
  30. GNU `m4'
  31. ********
  32.  
  33.    GNU `m4' is an implementation of the traditional UNIX macro
  34. processor.  It is mostly SVR4 compatible, although it has some
  35. extensions (for example, handling more than 9 positional parameters to
  36. macros).  `m4' also has builtin functions for including files, running
  37. shell commands, doing arithmetic, etc.  Autoconf needs GNU `m4' for
  38. generating `configure' scripts, but not for running them.
  39.  
  40.    GNU `m4' was originally written by Ren'e Seindal, with subsequent
  41. changes by Franc,ois Pinard and other volunteers on the Internet.  All
  42. names and email addresses can be found in the file `THANKS' from the
  43. GNU `m4' distribution.
  44.  
  45.    This is release 1.4.  It is now to be considered stable, future
  46. releases are only meant to fix bugs, increase speed, or improve
  47. documentation.  However...
  48.  
  49.    An experimental feature, which would improve `m4' usefulness, allows
  50. for changing the syntax for what is a "word" in `m4'.  You should use:
  51.      ./configure --enable-changeword
  52.  
  53. if you want this feature compiled in.  The current implementation slows
  54. down `m4' considerably and is hardly acceptable.  So, it might go away,
  55. do not count on it yet.
  56.  
  57. * Menu:
  58.  
  59. * Preliminaries::               Introduction and preliminaries
  60. * Syntax::                      Lexical and syntactic conventions
  61.  
  62. * Macros::                      How to invoke macros
  63. * Definitions::                 How to define new macros
  64. * Conditionals::                Conditionals and loops
  65.  
  66. * Debugging::                   How to debug macros and input
  67.  
  68. * Input Control::               Input control
  69. * File Inclusion::              File inclusion
  70. * Diversions::                  Diverting and undiverting output
  71.  
  72. * Text handling::               Macros for text handling
  73. * Arithmetic::                  Macros for doing arithmetic
  74. * UNIX commands::               Macros for running UNIX commands
  75. * Miscellaneous::               Miscellaneous builtin macros
  76. * Frozen files::                Fast loading of frozen states
  77.  
  78. * Compatibility::               Compatibility with other versions of m4
  79. * Concept index::               Index for many concepts
  80. * Macro index::                 Index for all m4 macros
  81.  
  82.  -- The Detailed Node Listing --
  83.  
  84. Introduction and preliminaries
  85.  
  86. * Intro::                       Introduction to `m4'
  87. * History::                     Historical references
  88.  
  89. * Invoking m4::                 Invoking `m4'
  90. * Bugs::                        Problems and bugs
  91. * Manual::                      Using this manual
  92.  
  93. Lexical and syntactic conventions
  94.  
  95. * Names::                       Macro names
  96. * Quoted strings::              Quoting input to m4
  97. * Other tokens::                Other kinds of input tokens
  98. * Comments::                    Comments in m4 input
  99.  
  100. How to invoke macros
  101.  
  102. * Invocation::                  Macro invocation
  103. * Inhibiting Invocation::       Preventing macro invocation
  104. * Macro Arguments::             Macro arguments
  105. * Quoting Arguments::           On Quoting Arguments to macros
  106. * Macro expansion::             Expanding macros
  107.  
  108. How to define new macros
  109.  
  110. * Define::                      Defining a new macro
  111. * Arguments::                   Arguments to macros
  112. * Pseudo Arguments::            Pseudo arguments to macros
  113. * Undefine::                    Deleting a macro
  114. * Defn::                        Renaming macros
  115. * Pushdef::                     Temporarily redefining macros
  116.  
  117. * Indir::                       Indirect call of macros
  118. * Builtin::                     Indirect call of builtins
  119.  
  120. Conditionals, loops and recursion
  121.  
  122. * Ifdef::                       Testing if a macro is defined
  123. * Ifelse::                      If-else construct, or multibranch
  124. * Loops::                       Loops and recursion in m4
  125.  
  126. How to debug macros and input
  127.  
  128. * Dumpdef::                     Displaying macro definitions
  129. * Trace::                       Tracing macro calls
  130. * Debug Levels::                Controlling debugging output
  131. * Debug Output::                Saving debugging output
  132.  
  133. Input control
  134.  
  135. * Dnl::                         Deleting whitespace in input
  136. * Changequote::                 Changing the quote characters
  137. * Changecom::                   Changing the comment delimiters
  138. * Changeword::                  Changing the lexical structure of words
  139. * M4wrap::                      Saving input until end of input
  140.  
  141. File inclusion
  142.  
  143. * Include::                     Including named files
  144. * Search Path::                 Searching for include files
  145.  
  146. Diverting and undiverting output
  147.  
  148. * Divert::                      Diverting output
  149. * Undivert::                    Undiverting output
  150. * Divnum::                      Diversion numbers
  151. * Cleardiv::                    Discarding diverted text
  152.  
  153. Macros for text handling
  154.  
  155. * Len::                         Calculating length of strings
  156. * Index::                       Searching for substrings
  157. * Regexp::                      Searching for regular expressions
  158. * Substr::                      Extracting substrings
  159. * Translit::                    Translating characters
  160. * Patsubst::                    Substituting text by regular expression
  161. * Format::                      Formatting strings (printf-like)
  162.  
  163. Macros for doing arithmetic
  164.  
  165. * Incr::                        Decrement and increment operators
  166. * Eval::                        Evaluating integer expressions
  167.  
  168. Running UNIX commands
  169.  
  170. * Syscmd::                      Executing simple commands
  171. * Esyscmd::                     Reading the output of commands
  172. * Sysval::                      Exit codes
  173. * Maketemp::                    Making names for temporary files
  174.  
  175. Miscellaneous builtin macros
  176.  
  177. * Errprint::                    Printing error messages
  178. * M4exit::                      Exiting from m4
  179.  
  180. Compatibility with other versions of `m4'
  181.  
  182. * Extensions::                  Extensions in GNU m4
  183. * Incompatibilities::           Facilities in System V m4 not in GNU m4
  184. * Other Incompat::              Other incompatibilities
  185.  
  186. 
  187. File: m4.info,  Node: Preliminaries,  Next: Syntax,  Prev: Top,  Up: Top
  188.  
  189. Introduction and preliminaries
  190. ******************************
  191.  
  192.    This first chapter explains what is GNU `m4', where `m4' comes from,
  193. how to read and use this documentation, how to call the `m4' program
  194. and how to report bugs about it.  It concludes by giving tips for
  195. reading the remainder of the manual.
  196.  
  197.    The following chapters then detail all the features of the `m4'
  198. language.
  199.  
  200. * Menu:
  201.  
  202. * Intro::                       Introduction to `m4'
  203. * History::                     Historical references
  204. * Invoking m4::                 Invoking `m4'
  205. * Bugs::                        Problems and bugs
  206. * Manual::                      Using this manual
  207.  
  208. 
  209. File: m4.info,  Node: Intro,  Next: History,  Prev: Preliminaries,  Up: Preliminaries
  210.  
  211. Introduction to `m4'
  212. ====================
  213.  
  214.    `m4' is a macro processor, in the sense that it copies its input to
  215. the output, expanding macros as it goes.  Macros are either builtin or
  216. user-defined, and can take any number of arguments.  Besides just doing
  217. macro expansion, `m4' has builtin functions for including named files,
  218. running UNIX commands, doing integer arithmetic, manipulating text in
  219. various ways, recursion, etc...  `m4' can be used either as a front-end
  220. to a compiler, or as a macro processor in its own right.
  221.  
  222.    The `m4' macro processor is widely available on all UNIXes.
  223. Usually, only a small percentage of users are aware of its existence.
  224. However, those who do often become commited users.  The growing
  225. popularity of GNU Autoconf, which prerequires GNU `m4' for *generating*
  226. the `configure' scripts, is an incentive for many to install it, while
  227. these people will not themselves program in `m4'.  GNU `m4' is mostly
  228. compatible with the System V, Release 3 version, except for some minor
  229. differences.  *Note Compatibility:: for more details.
  230.  
  231.    Some people found `m4' to be fairly addictive.  They first use `m4'
  232. for simple problems, then take bigger and bigger challenges, learning
  233. how to write complex `m4' sets of macros along the way.  Once really
  234. addicted, users pursue writing of sophisticated `m4' applications even
  235. to solve simple problems, devoting more time debugging their `m4'
  236. scripts than doing real work.  Beware that `m4' may be dangerous for
  237. the health of compulsive programmers.
  238.  
  239. 
  240. File: m4.info,  Node: History,  Next: Invoking m4,  Prev: Intro,  Up: Preliminaries
  241.  
  242. Historical references
  243. =====================
  244.  
  245.    The historical notes included here are fairly incomplete, and not
  246. authoritative at all.  Please knowledgeable users help us to more
  247. properly write this section.
  248.  
  249.    `GPM' has been an important ancestor of `m4'.  See C. Stratchey: "A
  250. General Purpose Macro generator", Computer Journal 8,3 (1965), pp. 225
  251. ff.  `GPM' is also succintly described into David Gries classic
  252. "Compiler Construction for Digital Computers".
  253.  
  254.    While `GPM' was *pure*, `m4' was meant to deal more with the true
  255. intricacies of real life: macros could be recognized with being
  256. pre-announced, skipping whitespace or end-of-lines was made easier,
  257. more constructs were builtin instead of derived, etc.
  258.  
  259.    Originally, `m4' was the engine for Rational FORTRAN preprocessor,
  260. that is, the `ratfor' equivalent of `cpp'.
  261.  
  262. 
  263. File: m4.info,  Node: Invoking m4,  Next: Bugs,  Prev: History,  Up: Preliminaries
  264.  
  265. Invoking `m4'
  266. =============
  267.  
  268.    The format of the `m4' command is:
  269.  
  270.      `m4' [OPTION...] [MACRO-DEFINITIONS...] [INPUT-FILE...]
  271.  
  272.    All options begin with `-', or if long option names are used, with a
  273. `--'.  A long option name need not be written completely, and
  274. unambigous prefix is sufficient.  `m4' understands the following
  275. options:
  276.  
  277. `--version'
  278.      Print the version number of the program on standard output, then
  279.      immediately exit `m4' without reading any INPUT-FILES.
  280.  
  281. `--help'
  282.      Print an help summary on standard output, then immediately exit
  283.      `m4' without reading any INPUT-FILES.
  284.  
  285. `-G'
  286. `--traditional'
  287.      Suppress all the extensions made in this implementation, compared
  288.      to the System V version.  *Note Compatibility::, for a list of
  289.      these.
  290.  
  291. `-E'
  292. `--fatal-warnings'
  293.      Stop execution and exit `m4' once the first warning has been
  294.      issued, considering all of them to be fatal.
  295.  
  296. `-dFLAGS'
  297. `--debug=FLAGS'
  298.      Set the debug-level according to the flags FLAGS.  The debug-level
  299.      controls the format and amount of information presented by the
  300.      debugging functions.  *Note Debug Levels:: for more details on the
  301.      format and meaning of FLAGS.
  302.  
  303. `-lNUM'
  304. `--arglength=NUM'
  305.      Restrict the size of the output generated by macro tracing.  *Note
  306.      Debug Levels:: for more details.
  307.  
  308. `-oFILE'
  309. `--error-output=FILE'
  310.      Redirect debug and trace output to the named file.  Error messages
  311.      are still printed on the standard error output.  *Note Debug
  312.      Output:: for more details.
  313.  
  314. `-IDIR'
  315. `--include=DIR'
  316.      Make `m4' search DIR for included files that are not found in the
  317.      current working directory.  *Note Search Path:: for more details.
  318.  
  319. `-e'
  320. `--interactive'
  321.      Makes this invocation of `m4' interactive.  This means that all
  322.      output will be unbuffered, and interrupts will be ignored.
  323.  
  324. `-s'
  325. `--synclines'
  326.      Generate synchronisation lines, for use by the C preprocessor or
  327.      other similar tools.  This is useful, for example, when `m4' is
  328.      used as a front end to a compiler.  Source file name and line
  329.      number information is conveyed by directives of the form `#line
  330.      LINENUM "FILENAME"', which are inserted as needed into the middle
  331.      of the input.  Such directives mean that the following line
  332.      originated or was expanded from the contents of input file
  333.      FILENAME at line LINENUM.  The `"FILENAME"' part is often omitted
  334.      when the file name did not change from the previous directive.
  335.  
  336.      Synchronisation directives are always given on complete lines per
  337.      themselves.  When a synchronisation discrepancy occurs in the
  338.      middle of an output line, the associated synchronisation directive
  339.      is delayed until the beginning of the next generated line.
  340.  
  341. `-P'
  342. `--prefix-builtins'
  343.      Internally modify *all* builtin macro names so they all start with
  344.      the prefix `m4_'.  For example, using this option, one should write
  345.      `m4_define' instead of `define', and `m4___file__' instead of
  346.      `__file__'.
  347.  
  348. `-WREGEXP'
  349. `--word-regexp=REGEXP'
  350.      Use an alternative syntax for macro names.  This experimental
  351.      option might not be present on all GNU `m4' implementations.
  352.      (*note Changeword::.).
  353.  
  354. `-HN'
  355. `--hashsize=N'
  356.      Make the internal hash table for symbol lookup be N entries big.
  357.      The number should be prime.  The default is 509 entries.  It
  358.      should not be necessary to increase this value, unless you define
  359.      an excessive number of macros.
  360.  
  361. `-LN'
  362. `--nesting-limit=N'
  363.      Artificially limit the nesting of macro calls to N levels,
  364.      stopping program execution if this limit is ever exceeded.  When
  365.      not specified, nesting is limited to 250 levels.
  366.  
  367.      The precise effect of this option might be more correctly
  368.      associated with textual nesting than dynamic recursion.  It has
  369.      been useful when some complex `m4' input was generated by
  370.      mechanical means.  Most users would never need this option.  If
  371.      shown to be obtrusive, this option (which is still experimental)
  372.      might well disappear.
  373.  
  374.      This option does *not* have the ability to break endless
  375.      rescanning loops, while these do not necessarily consume much
  376.      memory or stack space.  Through clever usage of rescanning loops,
  377.      one can request complex, time-consuming computations to `m4' with
  378.      useful results.  Putting limitations in this area would break `m4'
  379.      power.  There are many pathological cases: `define(`a', `a')a' is
  380.      only the simplest example (but *note Compatibility::.).  Expecting
  381.      GNU `m4' to detect these would be a little like expecting a
  382.      compiler system to detect and diagnose endless loops: it is a
  383.      quite *hard* problem in general, if not undecidable!
  384.  
  385. `-Q'
  386. `--quiet'
  387. `--silent'
  388.      Suppress warnings about missing or superflous arguments in macro
  389.      calls.
  390.  
  391. `-B'
  392. `-S'
  393. `-T'
  394.      These options are present for compatibility with System V `m4', but
  395.      do nothing in this implementation.
  396.  
  397. `-NN'
  398. `--diversions=N'
  399.      These options are present only for compatibility with previous
  400.      versions of GNU `m4', and were controlling the number of possible
  401.      diversions which could be used at the same time.  They do nothing,
  402.      because there is no fixed limit anymore.
  403.  
  404.    Macro definitions and deletions can be made on the command line, by
  405. using the `-D' and `-U' options.  They have the following format:
  406.  
  407. `-DNAME'
  408. `-DNAME=VALUE'
  409. `--define=NAME'
  410. `--define=NAME=VALUE'
  411.      This enters NAME into the symbol table, before any input files are
  412.      read.  If `=VALUE' is missing, the value is taken to be the empty
  413.      string.  The VALUE can be any string, and the macro can be defined
  414.      to take arguments, just as if it was defined from within the input.
  415.  
  416. `-UNAME'
  417. `--undefine=NAME'
  418.      This deletes any predefined meaning NAME might have.  Obviously,
  419.      only predefined macros can be deleted in this way.
  420.  
  421. `-tNAME'
  422. `--trace=NAME'
  423.      This enters NAME into the symbol table, as undefined but traced.
  424.      The macro will consequently be traced from the point it is defined.
  425.  
  426. `-FFILE'
  427. `--freeze-state FILE'
  428.      Once execution is finished, write out the frozen state on the
  429.      specified FILE (*note Frozen files::.).
  430.  
  431. `-RFILE'
  432. `--reload-state FILE'
  433.      Before execution starts, recover the internal state from the
  434.      specified frozen FILE (*note Frozen files::.).
  435.  
  436.    The remaining arguments on the command line are taken to be input
  437. file names.  If no names are present, the standard input is read.  A
  438. file name of `-' is taken to mean the standard input.
  439.  
  440.    The input files are read in the sequence given.  The standard input
  441. can only be read once, so the filename `-' should only appear once on
  442. the command line.
  443.  
  444. 
  445. File: m4.info,  Node: Bugs,  Next: Manual,  Prev: Invoking m4,  Up: Preliminaries
  446.  
  447. Problems and bugs
  448. =================
  449.  
  450.    If you have problems with GNU `m4' or think you've found a bug,
  451. please report it.  Before reporting a bug, make sure you've actually
  452. found a real bug.  Carefully reread the documentation and see if it
  453. really says you can do what you're trying to do.  If it's not clear
  454. whether you should be able to do something or not, report that too; it's
  455. a bug in the documentation!
  456.  
  457.    Before reporting a bug or trying to fix it yourself, try to isolate
  458. it to the smallest possible input file that reproduces the problem.
  459. Then send us the input file and the exact results `m4' gave you.  Also
  460. say what you expected to occur; this will help us decide whether the
  461. problem was really in the documentation.
  462.  
  463.    Once you've got a precise problem, send e-mail to (Internet)
  464. `bug-gnu-utils@prep.ai.mit.edu' or (UUCP)
  465. `mit-eddie!prep.ai.mit.edu!bug-gnu-utils'.  Please include the version
  466. number of `m4' you are using.  You can get this information with the
  467. command `m4 --version'.
  468.  
  469.    Non-bug suggestions are always welcome as well.  If you have
  470. questions about things that are unclear in the documentation or are
  471. just obscure features, please report them too.
  472.  
  473. 
  474. File: m4.info,  Node: Manual,  Prev: Bugs,  Up: Preliminaries
  475.  
  476. Using this manual
  477. =================
  478.  
  479.    This manual contains a number of examples of `m4' input and output,
  480. and a simple notation is used to distinguish input, output and error
  481. messages from `m4'.  Examples are set out from the normal text, and
  482. shown in a fixed width font, like this
  483.  
  484.      This is an example of an example!
  485.  
  486.    To distinguish input from output, all output from `m4' is prefixed
  487. by the string `=>', and all error messages by the string `error-->'.
  488. Thus
  489.  
  490.      Example of input line
  491.      =>Output line from m4
  492.      error-->and an error message
  493.  
  494.    As each of the predefined macros in `m4' is described, a prototype
  495. call of the macro will be shown, giving descriptive names to the
  496. arguments, e.g.,
  497.  
  498.      regexp(STRING, REGEXP, opt REPLACEMENT)
  499.  
  500.    All macro arguments in `m4' are strings, but some are given special
  501. interpretation, e.g., as numbers, filenames, regular expressions, etc.
  502.  
  503.    The `opt' before the third argument shows that this argument is
  504. optional--if it is left out, it is taken to be the empty string.  An
  505. ellipsis (`...') last in the argument list indicates that any number of
  506. arguments may follow.
  507.  
  508.    This document consistently writes and uses "builtin", without an
  509. hyphen, as if it were an English word.  This is how the `builtin'
  510. primitive is spelled within `m4'.
  511.  
  512. 
  513. File: m4.info,  Node: Syntax,  Next: Macros,  Prev: Preliminaries,  Up: Top
  514.  
  515. Lexical and syntactic conventions
  516. *********************************
  517.  
  518.    As `m4' reads its input, it separates it into "tokens".  A token is
  519. either a name, a quoted string, or any single character, that is not a
  520. part of either a name or a string.  Input to `m4' can also contain
  521. comments.
  522.  
  523. * Menu:
  524.  
  525. * Names::                       Macro names
  526. * Quoted strings::              Quoting input to m4
  527. * Other tokens::                Other kinds of input tokens
  528. * Comments::                    Comments in m4 input
  529.  
  530. 
  531. File: m4.info,  Node: Names,  Next: Quoted strings,  Prev: Syntax,  Up: Syntax
  532.  
  533. Names
  534. =====
  535.  
  536.    A name is any sequence of letters, digits, and the character `_'
  537. (underscore), where the first character is not a digit.  If a name has
  538. a macro definition, it will be subject to macro expansion (*note
  539. Macros::.).
  540.  
  541.    Examples of legal names are: `foo', `_tmp', and `name01'.
  542.  
  543. 
  544. File: m4.info,  Node: Quoted strings,  Next: Other tokens,  Prev: Names,  Up: Syntax
  545.  
  546. Quoted strings
  547. ==============
  548.  
  549.    A quoted string is a sequence of characters surrounded by the quotes
  550. ``' and `'', where the number of start and end quotes within the string
  551. balances.  The value of a string token is the text, with one level of
  552. quotes stripped off.  Thus
  553.  
  554.      `'
  555.  
  556.    is the empty string, and
  557.  
  558.      ``quoted''
  559.  
  560.    is the string
  561.  
  562.      `quoted'
  563.  
  564.    The quote characters can be changed at any time, using the builtin
  565. macro `changequote'.  *Note Changequote:: for more information.
  566.  
  567. 
  568. File: m4.info,  Node: Other tokens,  Next: Comments,  Prev: Quoted strings,  Up: Syntax
  569.  
  570. Other tokens
  571. ============
  572.  
  573.    Any character, that is neither a part of a name, nor of a quoted
  574. string, is a token by itself.
  575.  
  576. 
  577. File: m4.info,  Node: Comments,  Prev: Other tokens,  Up: Syntax
  578.  
  579. Comments
  580. ========
  581.  
  582.    Comments in `m4' are normally delimited by the characters `#' and
  583. newline.  All characters between the comment delimiters are ignored,
  584. but the entire comment (including the delimiters) is passed through to
  585. the output--comments are *not* discarded by `m4'.
  586.  
  587.    Comments cannot be nested, so the first newline after a `#' ends the
  588. comment.  The commenting effect of the begin comment character can be
  589. inhibited by quoting it.
  590.  
  591.    The comment delimiters can be changed to any string at any time,
  592. using the builtin macro `changecom'.  *Note Changecom:: for more
  593. information.
  594.  
  595. 
  596. File: m4.info,  Node: Macros,  Next: Definitions,  Prev: Syntax,  Up: Top
  597.  
  598. How to invoke macros
  599. ********************
  600.  
  601.    This chapter covers macro invocation, macro arguments and how macro
  602. expansion is treated.
  603.  
  604. * Menu:
  605.  
  606. * Invocation::                  Macro invocation
  607. * Inhibiting Invocation::       Preventing macro invocation
  608. * Macro Arguments::             Macro arguments
  609. * Quoting Arguments::           On Quoting Arguments to macros
  610. * Macro expansion::             Expanding macros
  611.  
  612. 
  613. File: m4.info,  Node: Invocation,  Next: Inhibiting Invocation,  Prev: Macros,  Up: Macros
  614.  
  615. Macro invocation
  616. ================
  617.  
  618.    Macro invocations has one of the forms
  619.  
  620.      name
  621.  
  622. which is a macro invocation without any arguments, or
  623.  
  624.      name(arg1, arg2, ..., argN)
  625.  
  626. which is a macro invocation with N arguments.  Macros can have any
  627. number of arguments.  All arguments are strings, but different macros
  628. might interpret the arguments in different ways.
  629.  
  630.    The opening parenthesis *must* follow the NAME directly, with no
  631. spaces in between.  If it does not, the macro is called with no
  632. arguments at all.
  633.  
  634.    For a macro call to have no arguments, the parentheses *must* be
  635. left out.  The macro call
  636.  
  637.      name()
  638.  
  639. is a macro call with one argument, which is the empty string, not a call
  640. with no arguments.
  641.  
  642. 
  643. File: m4.info,  Node: Inhibiting Invocation,  Next: Macro Arguments,  Prev: Invocation,  Up: Macros
  644.  
  645. Preventing macro invocation
  646. ===========================
  647.  
  648.    An innovation of the `m4' language, compared to some of its
  649. predecessors (like Stratchey's `GPM', for example), is the ability to
  650. recognize macro calls without resorting to any special, prefixed
  651. invocation character.  While generally useful, this feature might
  652. sometimes be the source of spurious, unwanted macro calls.  So, GNU
  653. `m4' offers several mechanisms or techniques for inhibiting the
  654. recognition of names as macro calls.
  655.  
  656.    First of all, many builtin macros cannot meaningfully be called
  657. without arguments.  For any of these macros, whenever an opening
  658. parenthesis does not immediately follow their name, the builtin macro
  659. call is not triggered.  This solves the most usual cases, like for
  660. `include' or `eval'.  Later in this document, the sentence "This macro
  661. is recognized only when given arguments" refers to this specific
  662. provision.
  663.  
  664.    There is also a command call option (`--prefix-builtins', or `-P')
  665. which requires all builtin macro names to be prefixed by `m4_' for them
  666. to be recognized.  The option has no effect whatsoever on user defined
  667. macros.  For example, with this option, one has to write `m4_dnl' and
  668. even `m4_m4exit'.
  669.  
  670.    If your version of GNU `m4' has the `changeword' feature compiled
  671. in, there it offers far more flexibility in specifying the syntax of
  672. macro names, both builtin or user-defined.  *Note Changeword:: for more
  673. information on this experimental feature.
  674.  
  675.    Of course, the simplest way to prevent a name to be interpreted as a
  676. call to an existing macro is to quote it.  The remainder of this
  677. section studies a little more deeply how quoting affects macro
  678. invocation, and how quoting can be used to inhibit macro invocation.
  679.  
  680.    Even if quoting is usually done over the whole macro name, it can
  681. also be done over only a few characters of this name.  It is also
  682. possible to quote the empty string, but this works only *inside* the
  683. name.  For example:
  684.  
  685.      `divert'
  686.      `d'ivert
  687.      di`ver't
  688.      div`'ert
  689.  
  690. all yield the string `divert'.  While in both:
  691.  
  692.      `'divert
  693.      divert`'
  694.  
  695. the `divert' builtin macro will be called.
  696.  
  697.    The output of macro evaluations is always rescanned.  The following
  698. example would yield the string `de', exactly as if `m4' has been given
  699. `substr(abcde, 3, 2)' as input:
  700.  
  701.      define(`x', `substr(ab')
  702.      define(`y', `cde, 3, 2)')
  703.      x`'y
  704.  
  705.    Unquoted strings on either side of a quoted string are subject to
  706. being recognized as macro names.  In the following example, quoting the
  707. empty string allows for the `dnl' macro to be recognized as such:
  708.  
  709.      define(`macro', `di$1')
  710.      macro(v)`'dnl
  711.  
  712. Without the quotes, this would rather yield the string `divdnl'
  713. followed by an end of line.
  714.  
  715.    Quoting may prevent recognizing as a macro name the concatenation of
  716. a macro expansion with the surrounding characters.  In this example:
  717.  
  718.      define(`macro', `di$1')
  719.      macro(v)`ert'
  720.  
  721. the input will produce the string `divert'.  If the quote was removed,
  722. the `divert' builtin would be called instead.
  723.  
  724. 
  725. File: m4.info,  Node: Macro Arguments,  Next: Quoting Arguments,  Prev: Inhibiting Invocation,  Up: Macros
  726.  
  727. Macro arguments
  728. ===============
  729.  
  730.    When a name is seen, and it has a macro definition, it will be
  731. expanded as a macro.
  732.  
  733.    If the name is followed by an opening parenthesis, the arguments
  734. will be collected before the macro is called.  If too few arguments are
  735. supplied, the missing arguments are taken to be the empty string.  If
  736. there are too many arguments, the excess arguments are ignored.
  737.  
  738.    Normally `m4' will issue warnings if a builtin macro is called with
  739. an inappropriate number of arguments, but it can be suppressed with the
  740. `-Q' command line option.  For user defined macros, there is no check
  741. of the number of arguments given.
  742.  
  743.    Macros are expanded normally during argument collection, and whatever
  744. commas, quotes and parentheses that might show up in the resulting
  745. expanded text will serve to define the arguments as well.  Thus, if FOO
  746. expands to `, b, c', the macro call
  747.  
  748.      bar(a foo, d)
  749.  
  750.    is a macro call with four arguments, which are `a ', `b', `c' and
  751. `d'.  To understand why the first argument contains whitespace,
  752. remember that leading unquoted whitespace is never part of an argument,
  753. but trailing whitespace always is.
  754.  
  755. 
  756. File: m4.info,  Node: Quoting Arguments,  Next: Macro expansion,  Prev: Macro Arguments,  Up: Macros
  757.  
  758. Quoting macro arguments
  759. =======================
  760.  
  761.    Each argument has leading unquoted whitespace removed.  Within each
  762. argument, all unquoted parentheses must match.  For example, if FOO is
  763. a macro,
  764.  
  765.      foo(() (`(') `(')
  766.  
  767.    is a macro call, with one argument, whose value is `() (() ('.
  768.  
  769.    It is common practice to quote all arguments to macros, unless you
  770. are sure you want the arguments expanded.  Thus, in the above example
  771. with the parentheses, the `right' way to do it is like this:
  772.  
  773.      foo(`() (() (')
  774.  
  775.    It is, however, in certain cases necessary to leave out quotes for
  776. some arguments, and there is nothing wrong in doing it.  It just makes
  777. life a bit harder, if you are not careful.
  778.  
  779. 
  780. File: m4.info,  Node: Macro expansion,  Prev: Quoting Arguments,  Up: Macros
  781.  
  782. Macro expansion
  783. ===============
  784.  
  785.    When the arguments, if any, to a macro call have been collected, the
  786. macro is expanded, and the expansion text is pushed back onto the input
  787. (unquoted), and reread.  The expansion text from one macro call might
  788. therefore result in more macros being called, if the calls are included,
  789. completely or partially, in the first macro calls' expansion.
  790.  
  791.    Taking a very simple example, if FOO expands to `bar', and BAR
  792. expands to `Hello world', the input
  793.  
  794.      foo
  795.  
  796. will expand first to `bar', and when this is reread and expanded, into
  797. `Hello world'.
  798.  
  799. 
  800. File: m4.info,  Node: Definitions,  Next: Conditionals,  Prev: Macros,  Up: Top
  801.  
  802. How to define new macros
  803. ************************
  804.  
  805.    Macros can be defined, redefined and deleted in several different
  806. ways.  Also, it is possible to redefine a macro, without losing a
  807. previous value, which can be brought back at a later time.
  808.  
  809. * Menu:
  810.  
  811. * Define::                      Defining a new macro
  812. * Arguments::                   Arguments to macros
  813. * Pseudo Arguments::            Pseudo arguments to macros
  814. * Undefine::                    Deleting a macro
  815. * Defn::                        Renaming macros
  816. * Pushdef::                     Temporarily redefining macros
  817.  
  818. * Indir::                       Indirect call of macros
  819. * Builtin::                     Indirect call of builtins
  820.  
  821. 
  822. File: m4.info,  Node: Define,  Next: Arguments,  Prev: Definitions,  Up: Definitions
  823.  
  824. Defining a macro
  825. ================
  826.  
  827.    The normal way to define or redefine macros is to use the builtin
  828. `define':
  829.  
  830.      define(NAME [, EXPANSION])
  831.  
  832. which defines NAME to expand to EXPANSION.  If EXPANSION is not given,
  833. it is taken to be empty.
  834.  
  835.    The expansion of `define' is void.
  836.  
  837.    The following example defines the macro FOO to expand to the text
  838. `Hello World.'.
  839.  
  840.      define(`foo', `Hello world.')
  841.      =>
  842.      foo
  843.      =>Hello world.
  844.  
  845.    The empty line in the output is there because the newline is not a
  846. part of the macro definition, and it is consequently copied to the
  847. output.  This can be avoided by use of the macro `dnl'.  *Note Dnl::,
  848. for details.
  849.  
  850.    The macro `define' is recognized only with parameters.
  851.  
  852. 
  853. File: m4.info,  Node: Arguments,  Next: Pseudo Arguments,  Prev: Define,  Up: Definitions
  854.  
  855. Arguments to macros
  856. ===================
  857.  
  858.    Macros can have arguments.  The Nth argument is denoted by `$n' in
  859. the expansion text, and is replaced by the Nth actual argument, when
  860. the macro is expanded.  Here is a example of a macro with two
  861. arguments.  It simply exchanges the order of the two arguments.
  862.  
  863.      define(`exch', `$2, $1')
  864.      =>
  865.      exch(arg1, arg2)
  866.      =>arg2, arg1
  867.  
  868.    This can be used, for example, if you like the arguments to `define'
  869. to be reversed.
  870.  
  871.      define(`exch', `$2, $1')
  872.      =>
  873.      define(exch(``expansion text'', ``macro''))
  874.      =>
  875.      macro
  876.      =>expansion text
  877.  
  878.    *Note Quoting Arguments::, for an explanation of the double quotes.
  879.  
  880.    GNU `m4' allows the number following the `$' to consist of one or
  881. more digits, allowing macros to have any number of arguments.  This is
  882. not so in UNIX implementations of `m4', which only recognize one digit.
  883.  
  884.    As a special case, the zero'th argument, `$0', is always the name of
  885. the macro being expanded.
  886.  
  887.      define(`test', ``Macro name: $0'')
  888.      =>
  889.      test
  890.      =>Macro name: test
  891.  
  892.    If you want quoted text to appear as part of the expansion text,
  893. remember that quotes can be nested in quoted strings.  Thus, in
  894.  
  895.      define(`foo', `This is macro `foo'.')
  896.      =>
  897.      foo
  898.      =>This is macro foo.
  899.  
  900. The `foo' in the expansion text is *not* expanded, since it is a quoted
  901. string, and not a name.
  902.  
  903. 
  904. File: m4.info,  Node: Pseudo Arguments,  Next: Undefine,  Prev: Arguments,  Up: Definitions
  905.  
  906. Special arguments to macros
  907. ===========================
  908.  
  909.    There is a special notation for the number of actual arguments
  910. supplied, and for all the actual arguments.
  911.  
  912.    The number of actual arguments in a macro call is denoted by `$#' in
  913. the expansion text.  Thus, a macro to display the number of arguments
  914. given can be
  915.  
  916.      define(`nargs', `$#')
  917.      =>
  918.      nargs
  919.      =>0
  920.      nargs()
  921.      =>1
  922.      nargs(arg1, arg2, arg3)
  923.      =>3
  924.  
  925.    The notation `$*' can be used in the expansion text to denote all
  926. the actual arguments, unquoted, with commas in between.  For example
  927.  
  928.      define(`echo', `$*')
  929.      =>
  930.      echo(arg1,    arg2, arg3 , arg4)
  931.      =>arg1,arg2,arg3 ,arg4
  932.  
  933.    Often each argument should be quoted, and the notation `$@' handles
  934. that.  It is just like `$*', except that it quotes each argument.  A
  935. simple example of that is:
  936.  
  937.      define(`echo', `$@')
  938.      =>
  939.      echo(arg1,    arg2, arg3 , arg4)
  940.      =>arg1,arg2,arg3 ,arg4
  941.  
  942.    Where did the quotes go?  Of course, they were eaten, when the
  943. expanded text were reread by `m4'.  To show the difference, try
  944.  
  945.      define(`echo1', `$*')
  946.      =>
  947.      define(`echo2', `$@')
  948.      =>
  949.      define(`foo', `This is macro `foo'.')
  950.      =>
  951.      echo1(foo)
  952.      =>This is macro This is macro foo..
  953.      echo2(foo)
  954.      =>This is macro foo.
  955.  
  956. *Note Trace::, if you do not understand this.
  957.  
  958.    A `$' sign in the expansion text, that is not followed by anything
  959. `m4' understands, is simply copied to the macro expansion, as any other
  960. text is.
  961.  
  962.      define(`foo', `$$$ hello $$$')
  963.      =>
  964.      foo
  965.      =>$$$ hello $$$
  966.  
  967.    If you want a macro to expand to something like `$12', put a pair of
  968. quotes after the `$'.  This will prevent `m4' from interpreting the `$'
  969. sign as a reference to an argument.
  970.  
  971. 
  972. File: m4.info,  Node: Undefine,  Next: Defn,  Prev: Pseudo Arguments,  Up: Definitions
  973.  
  974. Deleting a macro
  975. ================
  976.  
  977.    A macro definition can be removed with `undefine':
  978.  
  979.      undefine(NAME)
  980.  
  981. which removes the macro NAME.  The macro name must necessarily be
  982. quoted, since it will be expanded otherwise.
  983.  
  984.    The expansion of `undefine' is void.
  985.  
  986.      foo
  987.      =>foo
  988.      define(`foo', `expansion text')
  989.      =>
  990.      foo
  991.      =>expansion text
  992.      undefine(`foo')
  993.      =>
  994.      foo
  995.      =>foo
  996.  
  997.    It is not an error for NAME to have no macro definition.  In that
  998. case, `undefine' does nothing.
  999.  
  1000.    The macro `undefine' is recognized only with parameters.
  1001.  
  1002. 
  1003. File: m4.info,  Node: Defn,  Next: Pushdef,  Prev: Undefine,  Up: Definitions
  1004.  
  1005. Renaming macros
  1006. ===============
  1007.  
  1008.    It is possible to rename an already defined macro.  To do this, you
  1009. need the builtin `defn':
  1010.  
  1011.      defn(NAME)
  1012.  
  1013. which expands to the *quoted definition* of NAME.  If the argument is
  1014. not a defined macro, the expansion is void.
  1015.  
  1016.    If NAME is a user-defined macro, the quoted definition is simply the
  1017. quoted expansion text.  If, instead, NAME is a builtin, the expansion
  1018. is a special token, which points to the builtin's internal definition.
  1019. This token is only meaningful as the second argument to `define' (and
  1020. `pushdef'), and is ignored in any other context.
  1021.  
  1022.    Its normal use is best understood through an example, which shows
  1023. how to rename `undefine' to `zap':
  1024.  
  1025.      define(`zap', defn(`undefine'))
  1026.      =>
  1027.      zap(`undefine')
  1028.      =>
  1029.      undefine(`zap')
  1030.      =>undefine(zap)
  1031.  
  1032.    In this way, `defn' can be used to copy macro definitions, and also
  1033. definitions of builtin macros.  Even if the original macro is removed,
  1034. the other name can still be used to access the definition.
  1035.  
  1036.    The macro `defn' is recognized only with parameters.
  1037.  
  1038. 
  1039. File: m4.info,  Node: Pushdef,  Next: Indir,  Prev: Defn,  Up: Definitions
  1040.  
  1041. Temporarily redefining macros
  1042. =============================
  1043.  
  1044.    It is possible to redefine a macro temporarily, reverting to the
  1045. previous definition at a later time.  This is done with the builtins
  1046. `pushdef' and `popdef':
  1047.  
  1048.      pushdef(NAME [, EXPANSION])
  1049.      popdef(NAME)
  1050.  
  1051. which are quite analogous to `define' and `undefine'.
  1052.  
  1053.    These macros work in a stack-like fashion.  A macro is temporarily
  1054. redefined with `pushdef', which replaces an existing definition of
  1055. NAME, while saving the previous definition, before the new one is
  1056. installed.  If there is no previous definition, `pushdef' behaves
  1057. exactly like `define'.
  1058.  
  1059.    If a macro has several definitions (of which only one is accessible),
  1060. the topmost definition can be removed with `popdef'.  If there is no
  1061. previous definition, `popdef' behaves like `undefine'.
  1062.  
  1063.      define(`foo', `Expansion one.')
  1064.      =>
  1065.      foo
  1066.      =>Expansion one.
  1067.      pushdef(`foo', `Expansion two.')
  1068.      =>
  1069.      foo
  1070.      =>Expansion two.
  1071.      popdef(`foo')
  1072.      =>
  1073.      foo
  1074.      =>Expansion one.
  1075.      popdef(`foo')
  1076.      =>
  1077.      foo
  1078.      =>foo
  1079.  
  1080.    If a macro with several definitions is redefined with `define', the
  1081. topmost definition is *replaced* with the new definition.  If it is
  1082. removed with `undefine', *all* the definitions are removed, and not
  1083. only the topmost one.
  1084.  
  1085.      define(`foo', `Expansion one.')
  1086.      =>
  1087.      foo
  1088.      =>Expansion one.
  1089.      pushdef(`foo', `Expansion two.')
  1090.      =>
  1091.      foo
  1092.      =>Expansion two.
  1093.      define(`foo', `Second expansion two.')
  1094.      =>
  1095.      foo
  1096.      =>Second expansion two.
  1097.      undefine(`foo')
  1098.      =>
  1099.      foo
  1100.      =>foo
  1101.  
  1102.    It is possible to temporarily redefine a builtin with `pushdef' and
  1103. `defn'.
  1104.  
  1105.    The macros `pushdef' and `popdef' are recognized only with
  1106. parameters.
  1107.  
  1108. 
  1109. File: m4.info,  Node: Indir,  Next: Builtin,  Prev: Pushdef,  Up: Definitions
  1110.  
  1111. Indirect call of macros
  1112. =======================
  1113.  
  1114.    Any macro can be called indirectly with `indir':
  1115.  
  1116.      indir(NAME, ...)
  1117.  
  1118. which results in a call to the macro NAME, which is passed the rest of
  1119. the arguments.  This can be used to call macros with "illegal" names
  1120. (`define' allows such names to be defined):
  1121.  
  1122.      define(`$$internal$macro', `Internal macro (name `$0')')
  1123.      =>
  1124.      $$internal$macro
  1125.      =>$$internal$macro
  1126.      indir(`$$internal$macro')
  1127.      =>Internal macro (name $$internal$macro)
  1128.  
  1129.    The point is, here, that larger macro packages can have private
  1130. macros defined, that will not be called by accident.  They can *only* be
  1131. called through the builtin `indir'.
  1132.  
  1133. 
  1134. File: m4.info,  Node: Builtin,  Prev: Indir,  Up: Definitions
  1135.  
  1136. Indirect call of builtins
  1137. =========================
  1138.  
  1139.    Builtin macros can be called indirectly with `builtin':
  1140.  
  1141.      builtin(NAME, ...)
  1142.  
  1143. which results in a call to the builtin NAME, which is passed the rest
  1144. of the arguments.  This can be used, if NAME has been given another
  1145. definition that has covered the original.
  1146.  
  1147.    The macro `builtin' is recognized only with parameters.
  1148.  
  1149. 
  1150. File: m4.info,  Node: Conditionals,  Next: Debugging,  Prev: Definitions,  Up: Top
  1151.  
  1152. Conditionals, loops and recursion
  1153. *********************************
  1154.  
  1155.    Macros, expanding to plain text, perhaps with arguments, are not
  1156. quite enough.  We would like to have macros expand to different things,
  1157. based on decisions taken at run-time.  E.g., we need some kind of
  1158. conditionals.  Also, we would like to have some kind of loop construct,
  1159. so we could do something a number of times, or while some condition is
  1160. true.
  1161.  
  1162. * Menu:
  1163.  
  1164. * Ifdef::                       Testing if a macro is defined
  1165. * Ifelse::                      If-else construct, or multibranch
  1166. * Loops::                       Loops and recursion in m4
  1167.  
  1168. 
  1169. File: m4.info,  Node: Ifdef,  Next: Ifelse,  Prev: Conditionals,  Up: Conditionals
  1170.  
  1171. Testing macro definitions
  1172. =========================
  1173.  
  1174.    There are two different builtin conditionals in `m4'.  The first is
  1175. `ifdef':
  1176.  
  1177.      ifdef(NAME, STRING-1, opt STRING-2)
  1178.  
  1179. which makes it possible to test whether a macro is defined or not.  If
  1180. NAME is defined as a macro, `ifdef' expands to STRING-1, otherwise to
  1181. STRING-2.  If STRING-2 is omitted, it is taken to be the empty string
  1182. (according to the normal rules).
  1183.  
  1184.      ifdef(`foo', ``foo' is defined', ``foo' is not defined')
  1185.      =>foo is not defined
  1186.      define(`foo', `')
  1187.      =>
  1188.      ifdef(`foo', ``foo' is defined', ``foo' is not defined')
  1189.      =>foo is defined
  1190.  
  1191.    The macro `ifdef' is recognized only with parameters.
  1192.  
  1193. 
  1194. File: m4.info,  Node: Ifelse,  Next: Loops,  Prev: Ifdef,  Up: Conditionals
  1195.  
  1196. Comparing strings
  1197. =================
  1198.  
  1199.    The other conditional, `ifelse', is much more powerful.  It can be
  1200. used as a way to introduce a long comment, as an if-else construct, or
  1201. as a multibranch, depending on the number of arguments supplied:
  1202.  
  1203.      ifelse(COMMENT)
  1204.      ifelse(STRING-1, STRING-2, EQUAL, opt NOT-EQUAL)
  1205.      ifelse(STRING-1, STRING-2, EQUAL, ...)
  1206.  
  1207. Used with only one argument, the `ifelse' simply discards it and
  1208. produces no output.  This is a common `m4' idiom for introducing a
  1209. block comment, as an alternative to repeatedly using `dnl'.  This
  1210. special usage is recognized by GNU `m4', so that in this case, the
  1211. warning about missing arguments is never triggered.
  1212.  
  1213.    If called with three or four arguments, `ifelse' expands into EQUAL,
  1214. if STRING-1 and STRING-2 are equal (character for character), otherwise
  1215. it expands to NOT-EQUAL.
  1216.  
  1217.      ifelse(foo, bar, `true')
  1218.      =>
  1219.      ifelse(foo, foo, `true')
  1220.      =>true
  1221.      ifelse(foo, bar, `true', `false')
  1222.      =>false
  1223.      ifelse(foo, foo, `true', `false')
  1224.      =>true
  1225.  
  1226.    However, `ifelse' can take more than four arguments.  If given more
  1227. than four arguments, `ifelse' works like a `case' or `switch' statement
  1228. in traditional programming languages.  If STRING-1 and STRING-2 are
  1229. equal, `ifelse' expands into EQUAL, otherwise the procedure is repeated
  1230. with the first three arguments discarded.  This calls for an example:
  1231.  
  1232.      ifelse(foo, bar, `third', gnu, gnats, `sixth', `seventh')
  1233.      =>seventh
  1234.  
  1235.    Naturally, the normal case will be slightly more advanced than these
  1236. examples.  A common use of `ifelse' is in macros implementing loops of
  1237. various kinds.
  1238.  
  1239.    The macro `ifelse' is recognized only with parameters.
  1240.  
  1241. 
  1242. File: m4.info,  Node: Loops,  Prev: Ifelse,  Up: Conditionals
  1243.  
  1244. Loops and recursion
  1245. ===================
  1246.  
  1247.    There is no direct support for loops in `m4', but macros can be
  1248. recursive.  There is no limit on the number of recursion levels, other
  1249. than those enforced by your hardware and operating system.
  1250.  
  1251.    Loops can be programmed using recursion and the conditionals
  1252. described previously.
  1253.  
  1254.    There is a builtin macro, `shift', which can, among other things, be
  1255. used for iterating through the actual arguments to a macro:
  1256.  
  1257.      shift(...)
  1258.  
  1259. It takes any number of arguments, and expands to all but the first
  1260. argument, separated by commas, with each argument quoted.
  1261.  
  1262.      shift(bar)
  1263.      =>
  1264.      shift(foo, bar, baz)
  1265.      =>bar,baz
  1266.  
  1267.    An example of the use of `shift' is this macro, which reverses the
  1268. order of its arguments:
  1269.  
  1270.      define(`reverse', `ifelse($#, 0, , $#, 1, ``$1'',
  1271.                    `reverse(shift($@)), `$1'')')
  1272.      =>
  1273.      reverse
  1274.      =>
  1275.      reverse(foo)
  1276.      =>foo
  1277.      reverse(foo, bar, gnats, and gnus)
  1278.      =>and gnus, gnats, bar, foo
  1279.  
  1280.    While not a very interesting macro, it does show how simple loops
  1281. can be made with `shift', `ifelse' and recursion.
  1282.  
  1283.    Here is an example of a loop macro that implements a simple forloop.
  1284. It can, for example, be used for simple counting:
  1285.  
  1286.      forloop(`i', 1, 8, `i ')
  1287.      =>1 2 3 4 5 6 7 8
  1288.  
  1289.    The arguments are a name for the iteration variable, the starting
  1290. value, the final value, and the text to be expanded for each iteration.
  1291. With this macro, the macro `i' is defined only within the loop.  After
  1292. the loop, it retains whatever value it might have had before.
  1293.  
  1294.    For-loops can be nested, like
  1295.  
  1296.      forloop(`i', 1, 4, `forloop(`j', 1, 8, `(i, j) ')
  1297.      ')
  1298.      =>(1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8)
  1299.      =>(2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8)
  1300.      =>(3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8)
  1301.      =>(4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8)
  1302.      =>
  1303.  
  1304.    The implementation of the `forloop' macro is fairly straightforward.
  1305. The `forloop' macro itself is simply a wrapper, which saves the
  1306. previous definition of the first argument, calls the internal macro
  1307. `_forloop', and re-establishes the saved definition of the first
  1308. argument.
  1309.  
  1310.    The macro `_forloop' expands the fourth argument once, and tests to
  1311. see if it is finished.  If it has not finished, it increments the
  1312. iteration variable (using the predefined macro `incr', *note Incr::.),
  1313. and recurses.
  1314.  
  1315.    Here is the actual implementation of `forloop':
  1316.  
  1317.      define(`forloop',
  1318.             `pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')popdef(`$1')')
  1319.      define(`_forloop',
  1320.             `$4`'ifelse($1, `$3', ,
  1321.                 `define(`$1', incr($1))_forloop(`$1', `$2', `$3', `$4')')')
  1322.  
  1323.    Notice the careful use of quotes.  Only three macro arguments are
  1324. unquoted, each for its own reason.  Try to find out *why* these three
  1325. arguments are left unquoted, and see what happens if they are quoted.
  1326.  
  1327.    Now, even though these two macros are useful, they are still not
  1328. robust enough for general use. They lack even basic error handling of
  1329. cases like start value less than final value, and the first argument
  1330. not being a name.  Correcting these errors are left as an exercise to
  1331. the reader.
  1332.  
  1333. 
  1334. File: m4.info,  Node: Debugging,  Next: Input Control,  Prev: Conditionals,  Up: Top
  1335.  
  1336. How to debug macros and input
  1337. *****************************
  1338.  
  1339.    When writing macros for `m4', most of the time they woould not work
  1340. as intended (as is the case with most programming languages).  There is
  1341. a little support for macro debugging in `m4'.
  1342.  
  1343. * Menu:
  1344.  
  1345. * Dumpdef::                     Displaying macro definitions
  1346. * Trace::                       Tracing macro calls
  1347. * Debug Levels::                Controlling debugging output
  1348. * Debug Output::                Saving debugging output
  1349.  
  1350. 
  1351. File: m4.info,  Node: Dumpdef,  Next: Trace,  Prev: Debugging,  Up: Debugging
  1352.  
  1353. Displaying macro definitions
  1354. ============================
  1355.  
  1356.    If you want to see what a name expands into, you can use the builtin
  1357. `dumpdef':
  1358.  
  1359.      dumpdef(...)
  1360.  
  1361. which accepts any number of arguments.  If called without any arguments,
  1362. it displays the definitions of all known names, otherwise it displays
  1363. the definitions of the names given.  The output is printed directly on
  1364. the standard error output.
  1365.  
  1366.    The expansion of `dumpdef' is void.
  1367.  
  1368.      define(`foo', `Hello world.')
  1369.      =>
  1370.      dumpdef(`foo')
  1371.      error-->foo:    `Hello world.'
  1372.      =>
  1373.      dumpdef(`define')
  1374.      error-->define:    <define>
  1375.      =>
  1376.  
  1377.    The last example shows how builtin macros definitions are displayed.
  1378.  
  1379.    *Note Debug Levels:: for information on controlling the details of
  1380. the display.
  1381.  
  1382. 
  1383. File: m4.info,  Node: Trace,  Next: Debug Levels,  Prev: Dumpdef,  Up: Debugging
  1384.  
  1385. Tracing macro calls
  1386. ===================
  1387.  
  1388.    It is possible to trace macro calls and expansions through the
  1389. builtins `traceon' and `traceoff':
  1390.  
  1391.      traceon(...)
  1392.      traceoff(...)
  1393.  
  1394. When called without any arguments, `traceon' and `traceoff' will turn
  1395. tracing on and off, respectively,  for all defined macros.  When called
  1396. with arguments, only the named macros are affected.
  1397.  
  1398.    The expansion of `traceon' and `traceoff' is void.
  1399.  
  1400.    Whenever a traced macro is called and the arguments have been
  1401. collected, the call is displayed.  If the expansion of the macro call
  1402. is not void, the expansion can be displayed after the call.  The output
  1403. is printed directly on the standard error output.
  1404.  
  1405.      define(`foo', `Hello World.')
  1406.      =>
  1407.      define(`echo', `$@')
  1408.      =>
  1409.      traceon(`foo', `echo')
  1410.      =>
  1411.      foo
  1412.      error-->m4trace: -1- foo -> `Hello World.'
  1413.      =>Hello World.
  1414.      echo(gnus, and gnats)
  1415.      error-->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
  1416.      =>gnus,and gnats
  1417.  
  1418.    The number between dashes is the depth of the expansion.  It is one
  1419. most of the time, signifying an expansion at the outermost level, but it
  1420. increases when macro arguments contain unquoted macro calls.
  1421.  
  1422.    *Note Debug Levels:: for information on controlling the details of
  1423. the display.
  1424.  
  1425. 
  1426. File: m4.info,  Node: Debug Levels,  Next: Debug Output,  Prev: Trace,  Up: Debugging
  1427.  
  1428. Controlling debugging output
  1429. ============================
  1430.  
  1431.    The `-d' option to `m4' controls the amount of details presented,
  1432. when using the macros described in the preceding sections.
  1433.  
  1434.    The FLAGS following the option can be one or more of the following:
  1435.  
  1436. `t'
  1437.      Trace all macro calls made in this invocation of `m4'.
  1438.  
  1439. `a'
  1440.      Show the actual arguments in each macro call.  This applies to all
  1441.      macro calls if the `t' flag is used, otherwise only the macros
  1442.      covered by calls of `traceon'.
  1443.  
  1444. `e'
  1445.      Show the expansion of each macro call, if it is not void.  This
  1446.      applies to all macro calls if the `t' flag is used, otherwise only
  1447.      the macros covered by calls of `traceon'.
  1448.  
  1449. `q'
  1450.      Quote actual arguments and macro expansions in the display with the
  1451.      current quotes.
  1452.  
  1453. `c'
  1454.      Show several trace lines for each macro call.  A line is shown
  1455.      when the macro is seen, but before the arguments are collected; a
  1456.      second line when the arguments have been collected and a third
  1457.      line after the call has completed.
  1458.  
  1459. `x'
  1460.      Add a unique `macro call id' to each line of the trace output.
  1461.      This is useful in connection with the `c' flag above.
  1462.  
  1463. `f'
  1464.      Show the name of the current input file in each trace output line.
  1465.  
  1466. `l'
  1467.      Show the the current input line number in each trace output line.
  1468.  
  1469. `p'
  1470.      Print a message when a named file is found through the path search
  1471.      mecanism (*note Search Path::.), giving the actual filename used.
  1472.  
  1473. `i'
  1474.      Print a message each time the current input file is changed,
  1475.      giving file name and input line number.
  1476.  
  1477. `V'
  1478.      A shorthand for all of the above flags.
  1479.  
  1480.    If no flags are specified with the `-d' option, the default is
  1481. `aeq'. The examples in the previous two sections assumed the default
  1482. flags.
  1483.  
  1484.    There is a builtin macro `debugmode', which allows on-the-fly
  1485. control of the debugging output format:
  1486.  
  1487.      debugmode(opt FLAGS)
  1488.  
  1489. The argument FLAGS should be a subset of the letters listed above.  As
  1490. special cases, if the argument starts with a `+', the flags are added
  1491. to the current debug flags, and if it starts with a `-', they are
  1492. removed.  If no argument is present, the debugging flags are set to
  1493. zero (as if no `-d' was given), and with an empty argument the flags
  1494. are reset to the default.
  1495.  
  1496.