home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 7 / FreshFishVol7.bin / bbs / gnu / m4-1.2-src.lha / GNU / src / amiga / m4-1.2 / m4.info-2 (.txt) < prev    next >
GNU Info File  |  1994-07-19  |  51KB  |  1,109 lines
  1. This is Info file m4.info, produced by Makeinfo-1.55 from the input
  2. file m4.texinfo.
  3.    This file documents the GNU `m4' utility.
  4.    Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994 Free Software
  5. Foundation, Inc.
  6.    Permission is granted to make and distribute verbatim copies of this
  7. manual provided the copyright notice and this permission notice are
  8. preserved on all copies.
  9.    Permission is granted to copy and distribute modified versions of
  10. this manual under the conditions for verbatim copying, provided that
  11. the entire resulting derived work is distributed under the terms of a
  12. permission notice identical to this one.
  13.    Permission is granted to copy and distribute translations of this
  14. manual into another language, under the above conditions for modified
  15. versions, except that this permission notice may be stated in a
  16. translation approved by the Foundation.
  17. File: m4.info,  Node: Input Control,  Next: File Inclusion,  Prev: Debugging,  Up: Top
  18. Input control
  19. *************
  20.    This chapter describes various builtin macros for controlling the
  21. input to `m4'.
  22. * Menu:
  23. * Dnl::                         Deleting whitespace in input
  24. * Changequote::                 Changing the quote characters
  25. * Changecom::                   Changing the comment delimiters
  26. * Changeword::                  Changing the lexical structure of words
  27. * M4wrap::                      Saving input until end of input
  28. File: m4.info,  Node: Dnl,  Next: Changequote,  Prev: Input Control,  Up: Input Control
  29. Deleting whitespace in input
  30. ============================
  31.    The builtin `dnl' reads and discards all characters, up to and
  32. including the first newline:
  33.      dnl
  34. and it is often used in connection with `define', to remove the newline
  35. that follow the call to `define'.  Thus
  36.      define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
  37.      foo
  38.      =>Macro foo.
  39.    The input up to and including the next newline is discarded, as
  40. opposed to the way comments are treated (*note Comments::.).
  41.    Usually, `dnl' is immediately followed by an end of line or some
  42. other whitespace.  GNU `m4' will produce a warning diagnostic if `dnl'
  43. is followed by an open parenthesis.  In this case, `dnl' will collect
  44. and process all arguments, looking for a matching close parenthesis.
  45. All predictable side effects resulting from this collection will take
  46. place.  `dnl' will return no output.  The input following the matching
  47. close parenthesis up to and including the next newline, on whatever
  48. line containing it, will still be discarded.
  49. File: m4.info,  Node: Changequote,  Next: Changecom,  Prev: Dnl,  Up: Input Control
  50. Changing the quote characters
  51. =============================
  52.    The default quote delimiters can be changed with the builtin
  53. `changequote':
  54.      changequote(opt START, opt END)
  55. where START is the new start-quote delimiter and END is the new
  56. end-quote delimiter.  If any of the arguments are missing, the default
  57. quotes (``' and `'') are used instead of the void arguments.
  58.    The expansion of `changequote' is void.
  59.      changequote([,])
  60.      =>
  61.      define([foo], [Macro [foo].])
  62.      =>
  63.      foo
  64.      =>Macro foo.
  65.    If no single character is appropriate, START and END can be of any
  66. length.
  67.      changequote([[,]])
  68.      =>
  69.      define([[foo]], [[Macro [[[foo]]].]])
  70.      =>
  71.      foo
  72.      =>Macro [foo].
  73.    Changing the quotes to the empty strings will effectively disable the
  74. quoting mechanism, leaving no way to quote text.
  75.      define(`foo', `Macro `FOO'.')
  76.      =>
  77.      changequote(,)
  78.      =>
  79.      foo
  80.      =>Macro `FOO'.
  81.      `foo'
  82.      =>`Macro `FOO'.'
  83.    There is no way in `m4' to quote a string containing an unmatched
  84. left quote, except using `changequote' to change the current quotes.
  85.    Neither quote string should start with a letter or `_' (underscore),
  86. as they will be confused with names in the input.  Doing so disables
  87. the quoting mechanism.
  88. File: m4.info,  Node: Changecom,  Next: Changeword,  Prev: Changequote,  Up: Input Control
  89. Changing comment delimiters
  90. ===========================
  91.    The default comment delimiters can be changed with the builtin macro
  92. `changecom':
  93.      changecom(opt START, opt END)
  94. where START is the new start-comment delimiter and END is the new
  95. end-comment delimiter.  If any of the arguments are void, the default
  96. comment delimiters (`#' and newline) are used instead of the void
  97. arguments.  The comment delimiters can be of any length.
  98.    The expansion of `changecom' is void.
  99.      define(`comment', `COMMENT')
  100.      =>
  101.      # A normal comment
  102.      =># A normal comment
  103.      changecom(`/*', `*/')
  104.      =>
  105.      # Not a comment anymore
  106.      =># Not a COMMENT anymore
  107.      But: /* this is a comment now */ while this is not a comment
  108.      =>But: /* this is a comment now */ while this is not a COMMENT
  109.    Note how comments are copied to the output, much as if they were
  110. quoted strings.  If you want the text inside a comment expanded, quote
  111. the start comment delimiter.
  112.    Calling `changecom' without any arguments disables the commenting
  113. mechanism completely.
  114.      define(`comment', `COMMENT')
  115.      =>
  116.      changecom
  117.      =>
  118.      # Not a comment anymore
  119.      =># Not a COMMENT anymore
  120. File: m4.info,  Node: Changeword,  Next: M4wrap,  Prev: Changecom,  Up: Input Control
  121. Changing the lexical structure of words
  122. =======================================
  123.      The macro `changeword' and all associated functionnality is
  124.      experimental.  It is only available if the `--enable-changeword'
  125.      option was given to `configure', at GNU `m4' installation time.
  126.      The functionnality might change or even go away in the future.
  127.      *Do not rely on it*.  Please direct your comments about it the
  128.      same way you would do for bugs.
  129.    A file being processed by `m4' is split into quoted strings, words
  130. (potential macro names) and simple tokens (any other single character).
  131. Initially a word is defined by the following regular expression:
  132.      [_a-zA-Z][_a-zA-Z0-9]*
  133.    Using `changeword', you can change this regular expression.  Relaxing
  134. `m4''s lexical rules might be useful (for example) if you wanted to
  135. apply translations to a file of numbers:
  136.      changeword(`[_a-zA-Z0-9]+')
  137.      define(1, 0)
  138.      =>1
  139.    Tightening the lexical rules is less useful, because it will
  140. generally make some of the builtins unavailable.  You could use it to
  141. prevent accidental call of builtins, for example:
  142.      define(`_indir', defn(`indir'))
  143.      changeword(`_[_a-zA-Z0-9]*')
  144.      esyscmd(foo)
  145.      _indir(`esyscmd',`ls')
  146.    Because `m4' constructs its words a character at a time, there is a
  147. restriction on the regular expressions that may be passed to
  148. `changeword'.  This is that if your regular expression accepts `foo',
  149. it must also accept `f' and `fo'.
  150.    `changeword' has another function.  If the regular expression
  151. supplied contains any bracketed subexpressions, then text outside the
  152. first of these is discarded before symbol lookup.  So:
  153.      changecom(`/*',`*/')
  154.      changeword(`#\([_a-zA-Z0-9]*\)')
  155.      #esyscmd(ls)
  156.    `m4' now requires a `#' mark at the beginning of every macro
  157. invocation, so one can use `m4' to preprocess shell scripts without
  158. getting `shift' commands swallowed, and plain text without losing
  159. various common words.
  160.    `m4''s macro substitution is based on text, while TeX's is based on
  161. tokens.  `changeword' can throw this difference into relief.  For
  162. example, here is the same idea represented in TeX and `m4'.  First, the
  163. TeX version:
  164.      \def\a{\message{Hello}}
  165.      \catcode`\@=0
  166.      \catcode`\\=12
  167.      =>@a
  168.      =>@bye
  169. Then, the `m4' version:
  170.      define(a,`errprint(`Hello')')
  171.      changeword(`@\([_a-zA-Z0-9]*\)')
  172.      =>@a
  173.    In the TeX example, the first line defines a macro `a' to print the
  174. message `Hello'.  The second line defines @ to be usable instead of \
  175. as an escape character.  The third line defines \ to be a normal
  176. printing character, not an escape.  The fourth line invokes the macro
  177. `a'.  So, when TeX is run on this file, it displays the message `Hello'.
  178.    When the `m4' example is passed through `m4', it outputs
  179. `errprint(Hello)'.  The reason for this is that TeX does lexical
  180. analysis of macro definition when the macro is *defined*.  `m4' just
  181. stores the text, postponing the lexical analysi