home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / gnu / info / m4.info-2 (.txt) < prev    next >
GNU Info File  |  1994-02-23  |  38KB  |  823 lines
  1. This is Info file m4.info, produced by Makeinfo-1.47 from the input
  2. file m4.texinfo.
  3.    This file documents the GNU m4 utility.
  4.    Copyright (C) 1989, 1990, 1991, 1992, 1993 Free Software Foundation,
  5.    Permission is granted to make and distribute verbatim copies of this
  6. manual provided the copyright notice and this permission notice are
  7. preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided also
  10. that the entire resulting derived work is distributed under the terms
  11. of a permission notice identical to this one.
  12.    Permission is granted to copy and distribute translations of this
  13. manual into another language, under the above conditions for modified
  14. versions.
  15. File: m4.info,  Node: Diversions,  Next: Text handling,  Prev: File Inclusion,  Up: Top
  16. Diverting and undiverting output
  17. ********************************
  18.    Diversions are a way of temporarily saving output.  The output of
  19. `m4' can at any time be diverted to a temporary file, and be reinserted
  20. into the output stream, "undiverted", again at a later time.
  21.    Up to ten numbered diversions (numbered from 0 to 9) are supported in
  22. `m4', of which diversion number 0 is the normal output stream.  The
  23. number of available diversions can be increased with the `-N' option.
  24. * Menu:
  25. * Divert::                      Diverting output
  26. * Undivert::                    Undiverting output
  27. * Divnum::                      Diversion numbers
  28. * Cleardiv::                    Discarding diverted text
  29. File: m4.info,  Node: Divert,  Next: Undivert,  Prev: Diversions,  Up: Diversions
  30. Diverting output
  31. ================
  32.    Output is diverted using `divert':
  33.      divert(opt NUMBER)
  34. where NUMBER is the diversion to be used.  If NUMBER is left out, it is
  35. assumed to be zero.
  36.    The expansion of `divert' is void.
  37.    Diverted output, that hasn't been explicitly undiverted, will be
  38. automatically undiverted to the main output stream when all the input
  39. has been processed.
  40.      divert(1)
  41.      This text is diverted.
  42.      divert
  43.      =>
  44.      This text is not diverted.
  45.      =>This text is not diverted.
  46.      ^D
  47.      =>
  48.      =>This text is diverted.
  49.    Several calls of `divert' with the same argument do not overwrite
  50. the previous diverted text, but append to it.
  51.    If output is diverted to a non-existent diversion, it is simply
  52. discarded.  This can be used to suppress unwanted output.  A common
  53. example of unwanted output is the trailing newlines after macro
  54. definitions.  Here is how to avoid them.
  55.      divert(-1)
  56.      define(`foo', `Macro `foo'.')
  57.      define(`bar', `Macro `bar'.')
  58.      divert
  59.      =>
  60.    This is a common programming idiom in `m4'.
  61. File: m4.info,  Node: Undivert,  Next: Divnum,  Prev: Divert,  Up: Diversions
  62. Undiverting output
  63. ==================
  64.    Diverted text can be undiverted explicitly using the built-in
  65. `undivert':
  66.      undivert(opt NUMBER, ...)
  67. which undiverts the diversions given by the arguments, in the order
  68. given.  If no arguments are supplied, all diversions are undiverted, in
  69. numerical order.
  70.    The expansion of `undivert' is void.
  71.      divert(1)
  72.      This text is diverted.
  73.      divert
  74.      =>
  75.      This text is not diverted.
  76.      =>This text is not diverted.
  77.      undivert(1)
  78.      =>
  79.      =>This text is diverted.
  80.      =>
  81.    Notice the last two blank lines.  One of them comes from the newline
  82. following `undivert', the other from the newline that followed the
  83. `divert'!  A diversion often starts with a blank line like this.
  84.    When diverted text is undiverted, it is *not* reread by `m4', but
  85. rather copied directly to the current output, and it is therefore not
  86. an error to undivert into a diversion.
  87.    When a diversion has been undiverted, the diverted text is discarded,
  88. and it is not possible to bring back diverted text more than once.
  89.      divert(1)
  90.      This text is diverted first.
  91.      divert(0)undivert(1)dnl
  92.      =>
  93.      =>This text is diverted first.
  94.      undivert(1)
  95.      =>
  96.      divert(1)
  97.      This text is also diverted but not appended.
  98.      divert(0)undivert(1)dnl
  99.      =>
  100.      =>This text is also diverted but not appended.
  101.    Attempts to undivert the current diversion are silently ignored.
  102.    GNU `m4' allows named files to be undiverted.  Given a non-numeric
  103. argument, the contents of the file named will be copied, uninterpreted,
  104. to the current output.  This complements the built-in `include' (*note
  105. Include::.).  To illustrate the difference, assume the file `foo'
  106. contains the word `bar':
  107.      define(`bar', `BAR')
  108.      =>
  109.      undivert(`foo')
  110.      =>bar
  111.      =>
  112.      include(`foo')
  113.      =>BAR
  114.      =>
  115. File: m4.info,  Node: Divnum,  Next: Cleardiv,  Prev: Undivert,  Up: Diversions
  116. Diversion numbers
  117. =================
  118.    The built-in `divnum':
  119.      divnum
  120. expands to the number of the current diversion.
  121.      Initial divnum
  122.      =>Initial 0
  123.      divert(1)
  124.      Diversion one: divnum
  125.      divert(2)
  126.      Diversion two: divnum
  127.      divert
  128.      =>
  129.      ^D
  130.      =>
  131.      =>Diversion one: 1
  132.      =>
  133.      =>Diversion two: 2
  134.    The last call of `divert' without argument is necessary, since the
  135. undiverted text would otherwise be diverted itself.
  136. File: m4.info,  Node: Cleardiv,  Prev: Divnum,  Up: Diversions
  137. Discarding diverted text
  138. ========================
  139.    Often it is not known, when output is diverted, whether the diverted
  140. text is actually needed.  Since all non-empty diversion are brought back
  141. on the main output stream when the end of input is seen, a method of
  142. discarding a diversion is needed.  If all diversions should be
  143. discarded, the easiest is to end the input to `m4' with `divert(-1)'
  144. followed by an explicit `undivert':
  145.      divert(1)
  146.      Diversion one: divnum
  147.      divert(2)
  148.      Diversion two: divnum
  149.      divert(-1)
  150.      undivert
  151.      ^D
  152. No output is produced at all.
  153.    Clearing selected diversions can be done with the following macro:
  154.      define(`cleardivert',
  155.      `pushdef(`_num', divnum)divert(-1)undivert($@)divert(_num)popdef(`_num')')
  156.      =>
  157.    It is called just like `undivert', but the effect is to clear the
  158. diversions, given by the arguments.  (This macro has a nasty bug!  You
  159. should try to see if you can find it and correct it.)
  160. File: m4.info,  Node: Text handling,  Next: Arithmetic,  Prev: Diversions,  Up: Top
  161. Macros for text handling
  162. ************************
  163.    There are a number of built-ins in `m4' for manipulating text in
  164. various ways, extracting substrings, searching, substituting, and so on.
  165. * Menu:
  166. * Len::                         Calculating length of strings
  167. * Index::                       Searching for substrings
  168. * Regexp::                      Searching for regular expressions
  169. * Substr::                      Extracting substrings
  170. * Translit::                    Translating characters
  171. * Patsubst::                    Substituting text by regular expression
  172. * Format::                      Formatting strings (printf-like)
  173. File: m4.info,  Node: Len,  Next: Index,  Prev: Text handling,  Up: Text handling
  174. Calculating length of strings
  175. =============================
  176.    The length of a string can be calculated by `len':
  177.      len(STRING)
  178. which expands to the length of STRING, as a decimal number.
  179.      len()
  180.      =>0
  181.      len(`abcdef')
  182.      =>6
  183.    The builtin macro `len' is recognized only when given arguments.
  184. File: m4.info,  Node: Index,  Next: Regexp,  Prev: Len,  Up: Text handling
  185. Searching for substrings
  186. ========================
  187.    Searching for substrings is done with `index':
  188.      index(STRING, SUBSTRING)
  189. which expands to the index of the first occurrence of SUBSTRING in
  190. STRING.  The first character in STRING has index 0.  If SUBSTRING does
  191. not occur in STRING, `index' expands to `-1'.
  192.      index(`gnus, gnats, and armadillos', `nat')
  193.      =>7
  194.      index(`gnus, gnats, and armadillos', `dag')
  195.      =>-1
  196.    The builtin macro `index' is recognized only when given arguments.
  197. File: m4.info,  Node: Regexp,  Next: Substr,  Prev: Index,  Up: Text handling
  198. Searching for regular expressions
  199. =================================
  200.    Searching for regular expressions is done with the built-in `regexp':
  201.      regexp(STRING, REGEXP, opt REPLACEMENT)
  202. which searches for REGEXP in STRING.  The syntax for regular
  203. expre