This is Info file m4.info, produced by Makeinfo-1.55 from the input
file m4.texinfo.
START-INFO-DIR-ENTRY
* m4: (m4).			A powerful macro processor.
END-INFO-DIR-ENTRY
   This file documents the GNU `m4' utility.
   Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994 Free Software
Foundation, Inc.
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: m4.info,  Node: Debug Output,  Prev: Debug Levels,  Up: Debugging
Saving debugging output
=======================
   Debug and tracing output can be redirected to files using either the
`-o' option to `m4', or with the builtin macro `debugfile':
     debugfile(opt FILENAME)
will send all further debug and trace output to FILENAME.  If FILENAME
is empty, debug and trace output are discarded and if `debugfile' is
called without any arguments, debug and trace output are sent to the
standard error output.
File: m4.info,  Node: Input Control,  Next: File Inclusion,  Prev: Debugging,  Up: Top
Input control
*************
   This chapter describes various builtin macros for controlling the
input to `m4'.
* Menu:
* Dnl::                         Deleting whitespace in input
* Changequote::                 Changing the quote characters
* Changecom::                   Changing the comment delimiters
* Changeword::                  Changing the lexical structure of words
* M4wrap::                      Saving input until end of input
File: m4.info,  Node: Dnl,  Next: Changequote,  Prev: Input Control,  Up: Input Control
Deleting whitespace in input
============================
   The builtin `dnl' reads and discards all characters, up to and
including the first newline:
     dnl
and it is often used in connection with `define', to remove the newline
that follow the call to `define'.  Thus
     define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
     foo
     =>Macro foo.
   The input up to and including the next newline is discarded, as
opposed to the way comments are treated (*note Comments::.).
   Usually, `dnl' is immediately followed by an end of line or some
other whitespace.  GNU `m4' will produce a warning diagnostic if `dnl'
is followed by an open parenthesis.  In this case, `dnl' will collect
and process all arguments, looking for a matching close parenthesis.
All predictable side effects resulting from this collection will take
place.  `dnl' will return no output.  The input following the matching
close parenthesis up to and including the next newline, on whatever
line containing it, will still be discarded.
File: m4.info,  Node: Changequote,  Next: Changecom,  Prev: Dnl,  Up: Input Control
Changing the quote characters
=============================
   The default quote delimiters can be changed with the builtin
`changequote':
     changequote(opt START, opt END)
where START is the new start-quote delimiter and END is the new
end-quote delimiter.  If any of the arguments are missing, the default
quotes (``' and `'') are used instead of the void arguments.
   The expansion of `changequote' is void.
     changequote([, ])
     =>
     define([foo], [Macro [foo].])
     =>
     foo
     =>Macro foo.
   If no single character is appropriate, START and END can be of any
length.
     changequote([[, ]])
     =>
     define([[foo]], [[Macro [[[foo]]].]])
     =>
     foo
     =>Macro [foo].
   Changing the quotes to the empty strings will effectively disable the
quoting mechanism, leaving no way to quote text.
     define(`foo', `Macro `FOO'.')
     =>
     changequote(, )
     =>
     foo
     =>Macro `FOO'.
     `foo'
     =>`Macro `FOO'.'
   There is no way in `m4' to quote a string containing an unmatched
left quote, except using `changequote' to change the current quotes.
   Neither quote string should start with a letter or `_' (underscore),
as they will be confused with names in the input.  Doing so disables
the quoting mechanism.
File: m4.info,  Node: Changecom,  Next: Changeword,  Prev: Changequote,  Up: Input Control
Changing comment delimiters
===========================
   The default comment delimiters can be changed with the builtin macro
`changecom':
     changecom(opt START, opt END)
where START is the new start-comment delimiter and END is the new
end-comment delimiter.  If any of the arguments are void, the default
comment delimiters (`#' and newline) are used instead of the void
arguments.  The comment delimiters can be of any length.
   The expansion of `changecom' is void.
     define(`comment', `COMMENT')
     =>
     # A normal comment
     =># A normal comment
     changecom(`/*', `*/')
     =>
     # Not a comment anymore
     =># Not a COMMENT anymore
     But: /* this is a comment now */ while this is not a comment
     =>But: /* this is a comment now */ while this is not a COMMENT
   Note how comments are copied to the output, much as if they were
quoted strings.  If you want the text inside a comment expanded, quote
the start comment delimiter.
   Calling `changecom' without any arguments disables the commenting
mechanism completely.
     define(`comment', `COMMENT')
     =>
     changecom
     =>
     # Not a comment anymore
     =># Not a COMMENT anymore
File: m4.info,  Node: Changeword,  Next: M4wrap,  Prev: Changecom,  Up: Input Control
Changing the lexical structure of words
=======================================
     The macro `changeword' and all associated functionnality is
     experimental.  It is only available if the `--enable-changeword'
     option was given to `configure', at GNU `m4' installation time.
     The functionnality might change or even go away in the future.
     *Do not rely on it*.  Please direct your comments about it the
     same way you would do for bugs.
   A file being processed by `m4' is split into quoted strings, words
(potential macro names) and simple tokens (any other single character).
Initially a word is defined by the following regular expression:
     [_a-zA-Z][_a-zA-Z0-9]*
   Using `changeword', you can change this regular expression.  Relaxing
`m4''s lexical rules might be useful (for example) if you wanted to
apply translations to a file of numbers:
     changeword(`[_a-zA-Z0-9]+')
     define(1, 0)
     =>1
   Tightening the lexical rules is less useful, because it will
generally make some of the builtins unavailable.  You could use it to
prevent accidental call of builtins, for example:
     define(`_indir', defn(`indir'))
     changeword(`_[_a-zA-Z0-9]*')
     esyscmd(foo)
     _indir(`esyscmd', `ls')
   Because `m4' constructs its words a character at a time, there is a
restriction on the regular expressions that may be passed to
`changeword'.  This is that if your regular expression accepts `foo',
it must also accept `f' and `fo'.
   `changeword' has another function.  If the regular expression
supplied contains any bracketed subexpressions, then text outside the
first of these is discarded before symbol lookup.  So:
     changecom(`/*', `*/')
     changeword(`#\([_a-zA-Z0-9]*\)')
     #esyscmd(ls)
   `m4' now requires a `#' mark at the beginning of every macro
invocation, so one can use `m4' to preprocess shell scripts without
getting `shift' commands swallowed, and plain text without losing
various common words.
   `m4''s macro substitution is based on text, while TeX's is based on
tokens.  `changeword' can throw this difference into relief.  For
example, here is the same idea represented in TeX and `m4'.  First, the
TeX version:
     \def\a{\message{Hello}}
     \catcode`\@=0
     \catcode`\\=12
     =>@a
     =>@bye
Then, the `m4' version:
     define(a, `errprint(`Hello')')
     changeword(`@\([_a-zA-Z0-9]*\)')
     =>@a
   In the TeX example, the first line defines a macro `a' to print the
message `Hello'.  The second line defines @ to be usable instead of \
as an escape character.  The third line defines \ to be a normal
printing character, not an escape.  The fourth line invokes the macro
`a'.  So, when TeX is run on this file, it displays the message `Hello'.
   When the `m4' example is passed through `m4', it outputs
`errprint(Hello)'.  The reason for this is that TeX does lexical
analysis of macro definition when the macro is *defined*.  `m4' just
stores the text, postponing the lexical analysis until the macro is
*used*.
   You should note that using `changeword' will slow `m4' down by a
factor of about seven.
File: m4.info,  Node: M4wrap,  Prev: Changeword,  Up: Input Control
Saving input
============
   It is possible to `save' some text until the end of the normal input
has been seen.  Text can be saved, to be read again by `m4' when the
normal input has been exhausted.  This feature is normally used to
initiate cleanup actions before normal exit, e.g., deleting temporary
files.
   To save input text, use the builtin `m4wrap':
     m4wrap(STRING, ...)
which stores STRING and the rest of the arguments in a safe place, to
be reread when end of input is reached.
     define(`cleanup', `This is the `cleanup' actions.
     ')
     =>
     m4wrap(`cleanup')
     =>
     This is the first and last normal input line.
     =>This is the first and last normal input line.
     ^D
     =>This is the cleanup actions.
   The saved input is only reread when the end of normal input is seen,
and not if `m4exit' is used to exit `m4'.
   It is safe to call `m4wrap' from saved text, but then the order in
which the saved text is reread is undefined.  If `m4wrap' is not used
recursively, the saved pieces of text are reread in the opposite order
in which they were saved (LIFO--last in, first out).
File: m4.info,  Node: File Inclusion,  Next: Diversions,  Prev: Input Control,  Up: Top
File inclusion
**************
   `m4' allows you to include named files at any point in the input.
* Menu:
* Include::                     Including named files
* Search Path::                 Searching for include files
File: m4.info,  Node: Include,  Next: Search Path,  Prev: File Inclusion,  Up: File Inclusion
Including named files
=====================
   There are two builtin macros in `m4' for including files:
     include(FILENAME)
     sinclude(FILENAME)
both of which cause the file named FILENAME to be read by `m4'.  When
the end of the file is reached, input is resumed from the previous
input file.
   The expansion of `include' and `sinclude' is therefore the contents
of FILENAME.
   It is an error for an `include'd file not to exist.  If you do not
want error messages about non-existent files, `sinclude' can be used to
include a file, if it exists, expanding to nothing if it does not.
     include(`no-such-file')
     =>
     error-->30.include:2: m4: Cannot open no-such-file: No such file or directory
     sinclude(`no-such-file')
     =>
   Assume in the following that the file `incl.m4' contains the lines:
     Include file start
     foo
     Include file end
Normally file inclusion is used to insert the contents of a file into
the input stream.  The contents of the file will be read by `m4' and
macro calls in the file will be expanded:
     define(`foo', `FOO')
     =>
     include(`incl.m4')
     =>Include file start
     =>FOO
     =>Include file end
     =>
   The fact that `include' and `sinclude' expand to the contents of the
file can be used to define macros that operate on entire files.  Here
is an example, which defines `bar' to expand to the contents of
`incl.m4':
     define(`bar', include(`incl.m4'))
     =>
     This is `bar':  >>>bar<<<
     =>This is bar:  >>>Include file start
     =>foo
     =>Include file end
     =><<<
   This use of `include' is not trivial, though, as files can contain
quotes, commas and parentheses, which can interfere with the way the
`m4' parser works.
   The builtin macros `include' and `sinclude' are recognized only when
given arguments.
File: m4.info,  Node: Search Path,  Prev: Include,  Up: File Inclusion
Searching for include files
===========================
   GNU `m4' allows included files to be found in other directories than
the current working directory.
   If a file is not found in the current working directory, and the file
name is not absolute, the file will be looked for in a specified search
path.  First, the directories specified with the `-I' option will be
searched, in the order found on the command line.  Second, if the
`M4PATH' environment variable is set, it is expected to contain a
colon-separated list of directories, which will be searched in order.
   If the automatic search for include-files causes trouble, the `p'
debug flag (*note Debug Levels::.) can help isolate the problem.
File: m4.info,  Node: Diversions,  Next: Text handling,  Prev: File Inclusion,  Up: Top
Diverting and undiverting output
********************************
   Diversions are a way of temporarily saving output.  The output of
`m4' can at any time be diverted to a temporary file, and be reinserted
into the output stream, "undiverted", again at a later time.
   Numbered diversions are counted from 0 upwards, diversion number 0
being the normal output stream.  The number of simultaneous diversions
is limited mainly by the memory used to describe them, because GNU `m4'
tries to keep diversions in memory.  However, there is a limit to the
overall memory usable by all diversions taken altogether (512K,
currently).  When this maximum is about to be exceeded, a temporary
file is opened to receive the contents of the biggest diversion still
in memory, freeing this memory for other diversions.  So, it is
theoretically possible that the number of diversions be limited by the
number of available file descriptors.
* Menu:
* Divert::                      Diverting output
* Undivert::                    Undiverting output
* Divnum::                      Diversion numbers
* Cleardiv::                    Discarding diverted text
File: m4.info,  Node: Divert,  Next: Undivert,  Prev: Diversions,  Up: Diversions
Diverting output
================
   Output is diverted using `divert':
     divert(opt NUMBER)
where NUMBER is the diversion to be used.  If NUMBER is left out, it is
assumed to be zero.
   The expansion of `divert' is void.
   When all the `m4' input will have been processed, all existing
diversions are automatically undiverted, in numerical order.
     divert(1)
     This text is diverted.
     divert
     =>
     This text is not diverted.
     =>This text is not diverted.
     ^D
     =>
     =>This text is diverted.
   Several calls of `divert' with the same argument do not overwrite
the previous diverted text, but append to it.
   If output is diverted to a non-existent diversion, it is simply
discarded.  This can be used to suppress unwanted output.  A common
example of unwanted output is the trailing newlines after macro
definitions.  Here is how to avoid them.
     divert(-1)
     define(`foo', `Macro `foo'.')
     define(`bar', `Macro `bar'.')
     divert
     =>
   This is a common programming idiom in `m4'.
File: m4.info,  Node: Undivert,  Next: Divnum,  Prev: Divert,  Up: Diversions
Undiverting output
==================
   Diverted text can be undiverted explicitly using the builtin
`undivert':
     undivert(opt NUMBER, ...)
which undiverts the diversions given by the arguments, in the order
given.  If no arguments are supplied, all diversions are undiverted, in
numerical order.
   The expansion of `undivert' is void.
     divert(1)
     This text is diverted.
     divert
     =>
     This text is not diverted.
     =>This text is not diverted.
     undivert(1)
     =>
     =>This text is diverted.
     =>
   Notice the last two blank lines.  One of them comes from the newline
following `undivert', the other from the newline that followed the
`divert'!  A diversion often starts with a blank line like this.
   When diverted text is undiverted, it is *not* reread by `m4', but
rather copied directly to the current output, and it is therefore not
an error to undivert into a diversion.
   When a diversion has been undiverted, the diverted text is discarded,
and it is not possible to bring back diverted text more than once.
     divert(1)
     This text is diverted first.
     divert(0)undivert(1)dnl
     =>
     =>This text is diverted first.
     undivert(1)
     =>
     divert(1)
     This text is also diverted but not appended.
     divert(0)undivert(1)dnl
     =>
     =>This text is also diverted but not appended.
   Attempts to undivert the current diversion are silently ignored.
   GNU `m4' allows named files to be undiverted.  Given a non-numeric
argument, the contents of the file named will be copied, uninterpreted,
to the current output.  This complements the builtin `include' (*note
Include::.).  To illustrate the difference, assume the file `foo'
contains the word `bar':
     define(`bar', `BAR')
     =>
     undivert(`foo')
     =>bar
     =>
     include(`foo')
     =>BAR
     =>
File: m4.info,  Node: Divnum,  Next: Cleardiv,  Prev: Undivert,  Up: Diversions
Diversion numbers
=================
   The builtin `divnum':
     divnum
expands to the number of the current diversion.
     Initial divnum
     =>Initial 0
     divert(1)
     Diversion one: divnum
     divert(2)
     Diversion two: divnum
     divert
     =>
     ^D
     =>
     =>Diversion one: 1
     =>
     =>Diversion two: 2
   The last call of `divert' without argument is necessary, since the
undiverted text would otherwise be diverted itself.
File: m4.info,  Node: Cleardiv,  Prev: Divnum,  Up: Diversions
Discarding diverted text
========================
   Often it is not known, when output is diverted, whether the diverted
text is actually needed.  Since all non-empty diversion are brought back
on the main output stream when the end of input is seen, a method of
discarding a diversion is needed.  If all diversions should be
discarded, the easiest is to end the input to `m4' with `divert(-1)'
followed by an explicit `undivert':
     divert(1)
     Diversion one: divnum
     divert(2)
     Diversion two: divnum
     divert(-1)
     undivert
     ^D
No output is produced at all.
   Clearing selected diversions can be done with the following macro:
     define(`cleardivert',
     `pushdef(`_num', divnum)divert(-1)undivert($@)divert(_num)popdef(`_num')')
     =>
   It is called just like `undivert', but the effect is to clear the
diversions, given by the arguments.  (This macro has a nasty bug!  You
should try to see if you can find it and correct it.)
File: m4.info,  Node: Text handling,  Next: Arithmetic,  Prev: Diversions,  Up: Top
Macros for text handling
************************
   There are a number of builtins in `m4' for manipulating text in
various ways, extracting substrings, searching, substituting, and so on.
* Menu:
* Len::                         Calculating length of strings
* Index::                       Searching for substrings
* Regexp::                      Searching for regular expressions
* Substr::                      Extracting substrings
* Translit::                    Translating characters
* Patsubst::                    Substituting text by regular expression
* Format::                      Formatting strings (printf-like)
File: m4.info,  Node: Len,  Next: Index,  Prev: Text handling,  Up: Text handling
Calculating length of strings
=============================
   The length of a string can be calculated by `len':
     len(STRING)
which expands to the length of STRING, as a decimal number.
     len()
     =>0
     len(`abcdef')
     =>6
   The builtin macro `len' is recognized only when given arguments.
File: m4.info,  Node: Index,  Next: Regexp,  Prev: Len,  Up: Text handling
Searching for substrings
========================
   Searching for substrings is done with `index':
     index(STRING, SUBSTRING)
which expands to the index of the first occurrence of SUBSTRING in
STRING.  The first character in STRING has index 0.  If SUBSTRING does
not occur in STRING, `index' expands to `-1'.
     index(`gnus, gnats, and armadillos', `nat')
     =>7
     index(`gnus, gnats, and armadillos', `dag')
     =>-1
   The builtin macro `index' is recognized only when given arguments.
File: m4.info,  Node: Regexp,  Next: Substr,  Prev: Index,  Up: Text handling
Searching for regular expressions
=================================
   Searching for regular expressions is done with the builtin `regexp':
     regexp(STRING, REGEXP, opt REPLACEMENT)
which searches for REGEXP in STRING.  The syntax for regular
expressions is the same as in GNU Emacs.  *Note Syntax of Regular
Expressions: (emacs)Regexps.
   If REPLACEMENT is omitted, `regexp' expands to the index of the
first match of REGEXP in STRING.  If REGEXP does not match anywhere in
STRING, it expands to -1.
     regexp(`GNUs not Unix', `\<[a-z]\w+')
     =>5
     regexp(`GNUs not Unix', `\<Q\w*')
     =>-1
   If REPLACEMENT is supplied, `regexp' changes the expansion to this
argument, with `\N' substituted by the text matched by the Nth
parenthesized sub-expression of REGEXP, `\&' being the text the entire
regular expression matched.
     regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
     =>*** Unix *** nix ***
   The builtin macro `regexp' is recognized only when given arguments.
File: m4.info,  Node: Substr,  Next: Translit,  Prev: Regexp,  Up: Text handling
Extracting substrings
=====================
   Substrings are extracted with `substr':
     substr(STRING, FROM, opt LENGTH)
which expands to the substring of STRING, which starts at index FROM,
and extends for LENGTH characters, or to the end of STRING, if LENGTH
is omitted.  The starting index of a string is always 0.
     substr(`gnus, gnats, and armadillos', 6)
     =>gnats, and armadillos
     substr(`gnus, gnats, and armadillos', 6, 5)
     =>gnats
   The builtin macro `substr' is recognized only when given arguments.
File: m4.info,  Node: Translit,  Next: Patsubst,  Prev: Substr,  Up: Text handling
Translating characters
======================
   Character translation is done with `translit':
     translit(STRING, CHARS, REPLACEMENT)
which expands to STRING, with each character that occurs in CHARS
translated into the character from REPLACEMENT with the same index.
   If REPLACEMENT is shorter than CHARS, the excess characters are
deleted from the expansion.  If REPLACEMENT is omitted, all characters
in STRING, that are present in CHARS are deleted from the expansion.
   Both CHARS and REPLACEMENT can contain character-ranges, e.g., `a-z'
(meaning all lowercase letters) or `0-9' (meaning all digits).  To
include a dash `-' in CHARS or REPLACEMENT, place it first or last.
   It is not an error for the last character in the range to be `larger'
than the first.  In that case, the range runs backwards, i.e., `9-0'
means the string `9876543210'.
     translit(`GNUs not Unix', `A-Z')
     =>s not nix
     translit(`GNUs not Unix', `a-z', `A-Z')
     =>GNUS NOT UNIX
     translit(`GNUs not Unix', `A-Z', `z-a')
     =>tmfs not fnix
   The first example deletes all uppercase letters, the second converts
lowercase to uppercase, and the third `mirrors' all uppercase letters,
while converting them to lowercase.  The two first cases are by far the
most common.
   The builtin macro `translit' is recognized only when given arguments.
File: m4.info,  Node: Patsubst,  Next: Format,  Prev: Translit,  Up: Text handling
Substituting text by regular expression
=======================================
   Global substitution in a string is done by `patsubst':
     patsubst(STRING, REGEXP, opt REPLACEMENT)
which searches STRING for matches of REGEXP, and substitutes
REPLACEMENT for each match.  The syntax for regular expressions is the
same as in GNU Emacs.
   The parts of STRING that are not covered by any match of REGEXP are
copied to the expansion.  Whenever a match is found, the search
proceeds from the end of the match, so a character from STRING will
never be substituted twice.  If REGEXP matches a string of zero length,
the start position for the search is incremented, to avoid infinite
loops.
   When a replacement is to be made, REPLACEMENT is inserted into the
expansion, with `\N' substituted by the text matched by the Nth
parenthesized sub-expression of REGEXP, `\&' being the text the entire
regular expression matched.
   The REPLACEMENT argument can be omitted, in which case the text
matched by REGEXP is deleted.
     patsubst(`GNUs not Unix', `^', `OBS: ')
     =>OBS: GNUs not Unix
     patsubst(`GNUs not Unix', `\<', `OBS: ')
     =>OBS: GNUs OBS: not OBS: Unix
     patsubst(`GNUs not Unix', `\w*', `(\&)')
     =>(GNUs)() (not)() (Unix)
     patsubst(`GNUs not Unix', `\w+', `(\&)')
     =>(GNUs) (not) (Unix)
     patsubst(`GNUs not Unix', `[A-Z][a-z]+')
     =>GN not
   Here is a slightly more realistic example, which capitalizes
individual word or whole sentences, by substituting calls of the macros
`upcase' and `downcase' into the strings.
     define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl
     define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
     define(`capitalize1',
          `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
     define(`capitalize',
          `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
     capitalize(`GNUs not Unix')
     =>Gnus Not Unix
   The builtin macro `patsubst' is recognized only when given arguments.
File: m4.info,  Node: Format,  Prev: Patsubst,  Up: Text handling
Formatted output
================
   Formatted output can be made with `format':
     format(FORMAT-STRING, ...)
which works much like the C function `printf'.  The first argument is a
format string, which can contain `%' specifications, and the expansion
of `format' is the formatted string.
   Its use is best described by a few examples:
     define(`foo', `The brown fox jumped over the lazy dog')
     =>
     format(`The string "%s" is %d characters long', foo, len(foo))
     =>The string "The brown fox jumped over the lazy dog" is 38 characters long
   Using the `forloop' macro defined in *Note Loops::, this example
shows how `format' can be used to produce tabular output.
     forloop(`i', 1, 10, `format(`%6d squared is %10d
     ', i, eval(i**2))')
     =>     1 squared is	    1
     =>     2 squared is	    4
     =>     3 squared is	    9
     =>     4 squared is	   16
     =>     5 squared is	   25
     =>     6 squared is	   36
     =>     7 squared is	   49
     =>     8 squared is	   64
     =>     9 squared is	   81
     =>    10 squared is	  100
   The builtin `format' is modeled after the ANSI C `printf' function,
and supports the normal `%' specifiers: `c', `s', `d', `o', `x', `X',
`u', `e', `E' and `f'; it supports field widths and precisions, and the
modifiers `+', `-', ` ', `0', `#', `h' and `l'.  For more details on
the functioning of `printf', see the C Library Manual.
File: m4.info,  Node: Arithmetic,  Next: UNIX commands,  Prev: Text handling,  Up: Top
Macros for doing arithmetic
***************************
   Integer arithmetic is included in `m4', with a C-like syntax.  As
convenient shorthands, there are builtins for simple increment and
decrement operations.
* Menu:
* Incr::                        Decrement and increment operators
* Eval::                        Evaluating integer expressions
File: m4.info,  Node: Incr,  Next: Eval,  Prev: Arithmetic,  Up: Arithmetic
Decrement and increment operators
=================================
   Increment and decrement of integers are supported using the builtins
`incr' and `decr':
     incr(NUMBER)
     decr(NUMBER)
which expand to the numerical value of NUMBER, incremented, or
decremented, respectively, by one.
     incr(4)
     =>5
     decr(7)
     =>6
   The builtin macros `incr' and `decr' are recognized only when given
arguments.
File: m4.info,  Node: Eval,  Prev: Incr,  Up: Arithmetic
Evaluating integer expressions
==============================
   Integer expressions are evaluated with `eval':
     eval(EXPRESSION, opt RADIX, opt WIDTH)
which expands to the value of EXPRESSION.
   Expressions can contain the following operators, listed in order of
decreasing precedence.
     Unary minus
     Exponentiation
`*  /  %'
     Multiplication, division and modulo
`+  -'
     Addition and subtraction
`<<  >>'
     Shift left or right
`==  !=  >  >=  <  <='
     Relational operators
     Logical negation
     Bitwise negation
     Bitwise and
     Bitwise exclusive-or
     Bitwise or
     Logical and
     Logical or
   All operators, except exponentiation, are left associative.
   Note that many `m4' implementations use `^' as an alternate operator
for the exponentiation, while many others use `^' for the bitwise
exclusive-or.  GNU `m4' changed its behavior: it used to exponentiate
for `^', it now computes the bitwise exclusive-or.
   Numbers without special prefix are given decimal.  A simple `0'
prefix introduces an octal number.  `0x' introduces an hexadecimal
number.  `0b' introduces a binary number.  `0r' introduces a number
expressed in any radix between 1 and 36: the prefix should be
immediately followed by the decimal expression of the radix, a colon,
then the digits making the number.  For any radix, the digits are `0',
`1', `2', ....  Beyond `9', the digits are `a', `b' ... up to `z'.
Lower and upper case letters can be used interchangeably in numbers
prefixes and as number digits.
   Parentheses may be used to group subexpressions whenever needed.
For the relational operators, a true relation returns `1', and a false
relation return `0'.
   Here are a few examples of use of `eval'.
     eval(-3 * 5)
     =>-15
     eval(index(`Hello world', `llo') >= 0)
     =>1
     define(`square', `eval(($1)**2)')
     =>
     square(9)
     =>81
     square(square(5)+1)
     =>676
     define(`foo', `666')
     =>
     eval(`foo'/6)
     error-->51.eval:14: m4: Bad expression in eval: foo/6
     =>
     eval(foo/6)
     =>111
   As the second to last example shows, `eval' does not handle macro
names, even if they expand to a valid expression (or part of a valid
expression).  Therefore all macros must be expanded before they are
passed to `eval'.
   If RADIX is specified, it specifies the radix to be used in the
expansion.  The default radix is 10.  The result of `eval' is always
taken to be signed.  The WIDTH argument specifies a minimum output
width.  The result is zero-padded to extend the expansion to the
requested width.
     eval(666, 10)
     =>666
     eval(666, 11)
     =>556
     eval(666, 6)
     =>3030
     eval(666, 6, 10)
     =>0000003030
     eval(-666, 6, 10)
     =>-000003030
   Take note that RADIX cannot be larger than 36.
   The builtin macro `eval' is recognized only when given arguments.
File: m4.info,  Node: UNIX commands,  Next: Miscellaneous,  Prev: Arithmetic,  Up: Top
Running UNIX commands
*********************
   There are a few builtin macros in `m4' that allow you to run UNIX
commands from within `m4'.
* Menu:
* Syscmd::                      Executing simple commands
* Esyscmd::                     Reading the output of commands
* Sysval::                      Exit codes
* Maketemp::                    Making names for temporary files
File: m4.info,  Node: Syscmd,  Next: Esyscmd,  Prev: UNIX commands,  Up: UNIX commands
Executing simple commands
=========================
   Any shell command can be executed, using `syscmd':
     syscmd(SHELL-COMMAND)
which executes SHELL-COMMAND as a shell command.
   The expansion of `syscmd' is void, *not* the output from
SHELL-COMMAND!  Output or error messages from SHELL-COMMAND are not
read by `m4'.  *Note Esyscmd:: if you need to process the command
output.
   Prior to executing the command, `m4' flushes its output buffers.
The default standard input, output and error of SHELL-COMMAND are the
same as those of `m4'.
   The builtin macro `syscmd' is recognized only when given arguments.
File: m4.info,  Node: Esyscmd,  Next: Sysval,  Prev: Syscmd,  Up: UNIX commands
Reading the output of commands
==============================
   If you want `m4' to read the output of a UNIX command, use `esyscmd':
     esyscmd(SHELL-COMMAND)
which expands to the standard output of the shell command SHELL-COMMAND.
   Prior to executing the command, `m4' flushes its output buffers.
The default standard input and error output of SHELL-COMMAND are the
same as those of `m4'.  The error output of SHELL-COMMAND is not a part
of the expansion: it will appear along with the error output of `m4'.
   Assume you are positioned into the `checks' directory of GNU `m4'
distribution, then:
     define(`vice', `esyscmd(grep Vice ../COPYING)')
     =>
     vice
     =>  Ty Coon, President of Vice
     =>
   Note how the expansion of `esyscmd' has a trailing newline.
   The builtin macro `esyscmd' is recognized only when given arguments.
File: m4.info,  Node: Sysval,  Next: Maketemp,  Prev: Esyscmd,  Up: UNIX commands
Exit codes
==========
   To see whether a shell command succeeded, use `sysval':
     sysval
which expands to the exit status of the last shell command run with
`syscmd' or `esyscmd'.
     syscmd(`false')
     =>
     ifelse(sysval, 0, zero, non-zero)
     =>non-zero
     syscmd(`true')
     =>
     sysval
     =>0
File: m4.info,  Node: Maketemp,  Prev: Sysval,  Up: UNIX commands
Making names for temporary files
================================
   Commands specified to `syscmd' or `esyscmd' might need a temporary
file, for output or for some other purpose.  There is a builtin macro,
`maketemp', for making temporary file names:
     maketemp(TEMPLATE)
which expands to a name of a non-existent file, made from the string
TEMPLATE, which should end with the string `XXXXXX'.  The six `X''s are
then replaced, usually with something that includes the process id of
the `m4' process, in order to make the filename unique.
     maketemp(`/tmp/fooXXXXXX')
     =>/tmp/fooa07346
     maketemp(`/tmp/fooXXXXXX')
     =>/tmp/fooa07346
   As seen in the example, several calls of `maketemp' might expand to
the same string, since the selection criteria is whether the file exists
or not.  If a file has not been created before the next call, the two
macro calls might expand to the same name.
   The builtin macro `maketemp' is recognized only when given arguments.
File: m4.info,  Node: Miscellaneous,  Next: Frozen files,  Prev: UNIX commands,  Up: Top
Miscellaneous builtin macros
****************************
   This chapter describes various builtins, that do not really belong in
any of the previous chapters.
* Menu:
* Errprint::                    Printing error messages
* M4exit::                      Exiting from m4
File: m4.info,  Node: Errprint,  Next: M4exit,  Prev: Miscellaneous,  Up: Miscellaneous
Printing error messages
=======================
   You can print error messages using `errprint':
     errprint(MESSAGE, ...)
which simply prints MESSAGE and the rest of the arguments on the
standard error output.
   The expansion of `errprint' is void.
     errprint(`Illegal arguments to forloop
     ')
     error-->Illegal arguments to forloop
     =>
   A trailing newline is *not* printed automatically, so it must be
supplied as part of the argument, as in the example.  (BSD flavored
`m4''s do append a trailing newline on each `errprint' call).
   To make it possible to specify the location of the error, two
utility builtins exist:
     __file__
     __line__
which expands to the quoted name of the current input file, and the
current input line number in that file.
     errprint(`m4:'__file__:__line__: `Input error
     ')
     error-->m4:56.errprint:2: Input error
     =>
File: m4.info,  Node: M4exit,  Prev: Errprint,  Up: Miscellaneous
Exiting from `m4'
=================
   If you need to exit from `m4' before the entire input has been read,
you can use `m4exit':
     m4exit(opt CODE)
which causes `m4' to exit, with exit code CODE.  If CODE is left out,
the exit code is zero.
     define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*
     ')m4exit(1)')
     =>
     fatal_error(`This is a BAD one, buster')
     error-->m4: 57.m4exit: 5: fatal error: This is a BAD one, buster
   After this macro call, `m4' will exit with exit code 1.  This macro
is only intended for error exits, since the normal exit procedures are
not followed, e.g., diverted text is not undiverted, and saved text
(*note M4wrap::.) is not reread.
File: m4.info,  Node: Frozen files,  Next: Compatibility,  Prev: Miscellaneous,  Up: Top
Fast loading of frozen states
*****************************
   Some bigger `m4' applications may be built over a common base
containing hundreds of definitions and other costly initializations.
Usually, the common base is kept in one or more declarative files,
which files are listed on each `m4' invocation prior to the user's
input file, or else, `include''d from this input file.
   Reading the common base of a big application, over and over again,
may be time consuming.  GNU `m4' offers some machinery to speed up the
start of an application using lengthy common bases.  Presume the user
repeatedly uses:
     m4 base.m4 input.m4
with a varying contents of `input.m4', but a rather fixed contents for
`base.m4'.  Then, the user might rather execute:
     m4 -F base.m4f base.m4
once, and further execute, as often as needed:
     m4 -R base.m4f input.m4
with the varying input.  The first call, containing the `-F' option,
only reads and executes file `base.m4', so defining various application
macros and computing other initializations.  Only once the input file
`base.m4' has been completely processed, GNU `m4' produces on
`base.m4f' a "frozen" file, that is, a file which contains a kind of
snapshot of the `m4' internal state.
   Later calls, containing the `-R' option, are able to reload the
internal state of `m4''s memory, from `base.m4f', *prior* to reading
any other input files.  By this mean, instead of starting with a virgin
copy of `m4', input will be read after having effectively recovered the
effect of a prior run.  In our example, the effect is the same as if
file `base.m4' has been read anew.  However, this effect is achieved a
lot faster.
   Only one frozen file may be created or read in any one `m4'
invocation.  It is not possible to recover two frozen files at once.
However, frozen files may be updated incrementally, through using `-R'
and `-F' options simultaneously.  For example, if some care is taken,
the command:
     m4 file1.m4 file2.m4 file3.m4 file4.m4
could be broken down in the following sequence, accumulating the same
output:
     m4 -F file1.m4f file1.m4
     m4 -R file1.m4f -F file2.m4f file2.m4
     m4 -R file2.m4f -F file3.m4f file3.m4
     m4 -R file3.m4f file4.m4
   Some care is necessary because not every effort has been made for
this to work in all cases.  In particular, the trace attribute of
macros is not handled, nor the current setting of `changeword'.  Also,
interactions for some options of `m4' being used in one call and not
for the next, have not been fully analyzed yet.  On the other end, you
may be confident that stacks of `pushdef''ed definitions are handled
correctly, so are `undefine''d or renamed builtins, changed strings for
quotes or comments.
   When an `m4' run is to be frozen, the automatic undiversion which
takes place at end of execution is inhibited.  Instead, all positively
numbered diversions are saved into the frozen file.  The active
diversion number is also transmitted.
   A frozen file to be reloaded need not reside in the current
directory.  It is looked up the same way as an `include' file (*note
Search Path::.).
   Frozen files are sharable across architectures.  It is safe to write
a frozen file one one machine and read it on another, given that the
second machine uses the same, or a newer version of GNU `m4'.  These
are simple (editable) text files, made up of directives, each starting
with a capital letter and ending with a newline (NL).  Wherever a
directive is expected, the character `#' introduces a comment line,
empty lines are also ignored.  In the following descriptions, LENGTHs
always refer to corresponding STRINGs.  Numbers are always expressed in
decimal.  The directives are:
`V NUMBER NL'
     Confirms the format of the file.  NUMBER should be 1.
`C LENGTH1 , LENGTH2 NL STRING1 STRING2 NL'
     Uses STRING1 and STRING2 as the beginning comment and end comment
     strings.
`Q LENGTH1 , LENGTH2 NL STRING1 STRING2 NL'
     Uses STRING1 and STRING2 as the beginning quote and end quote
     strings.
`F LENGTH1 , LENGTH2 NL STRING1 STRING2 NL'
     Defines, through `pushdef', a definition for STRING1 expanding to
     the function whose builtin name is STRING2.
`T LENGTH1 , LENGTH2 NL STRING1 STRING2 NL'
     Defines, though `pushdef', a definition for STRING1 expanding to
     the text given by STRING2.
`D NUMBER, LENGTH NL STRING NL'
     Selects diversion NUMBER, making it current, then copy STRING in
     the current diversion.  NUMBER may be a negative number for a
     non-existing diversion.  To merely specify an active selection,
     use this command with an empty STRING.  With 0 as the diversion
     NUMBER, STRING will be issued on standard output at reload time,
     however this may not be produced from within `m4'.
File: m4.info,  Node: Compatibility,  Next: Concept index,  Prev: Frozen files,  Up: Top
Compatibility with other versions of `m4'
*****************************************
   This chapter describes the differences between this implementation of
`m4', and the implementation found under UNIX, notably System V,
Release 3.
   There are also differences in BSD flavors of `m4'.  No attempt is
made to summarize these here.
* Menu:
* Extensions::                  Extensions in GNU m4
* Incompatibilities::           Facilities in System V m4 not in GNU m4
* Other Incompat::              Other incompatibilities
File: m4.info,  Node: Extensions,  Next: Incompatibilities,  Prev: Compatibility,  Up: Compatibility
Extensions in GNU `m4'
======================
   This version of `m4' contains a few facilities, that do not exist in
System V `m4'.  These extra facilities are all suppressed by using the
`-G' command line option, unless overridden by other command line
options.
   * In the `$'N notation for macro arguments, N can contain several
     digits, while the System V `m4' only accepts one digit.  This
     allows macros in GNU `m4' to take any number of arguments, and not
     only nine (*note Arguments::.).
   * Files included with `include' and `sinclude' are sought in a user
     specified search path, if they are not found in the working
     directory.  The search path is specified by the `-I' option and the
     `M4PATH' environment variable (*note Search Path::.).
   * Arguments to `undivert' can be non-numeric, in which case the named
     file will be included uninterpreted in the output (*note
     Undivert::.).
   * Formatted output is supported through the `format' builtin, which
     is modeled after the C library function `printf' (*note Format::.).
   * Searches and text substitution through regular expressions are
     supported by the `regexp' (*note Regexp::.) and `patsubst' (*note
     Patsubst::.) builtins.
   * The output of shell commands can be read into `m4' with `esyscmd'
     (*note Esyscmd::.).
   * There is indirect access to any builtin macro with `builtin'
     (*note Builtin::.).
   * Macros can be called indirectly through `indir' (*note Indir::.).
   * The name of the current input file and the current input line
     number are accessible through the builtins `__file__' and
     `__line__' (*note Errprint::.).
   * The format of the output from `dumpdef' and macro tracing can be
     controlled with `debugmode' (*note Debug Levels::.).
   * The destination of trace and debug output can be controlled with
     `debugfile' (*note Debug Output::.).
   In addition to the above extensions, GNU `m4' implements the
following command line options: `-F', `-G', `-I', `-L', `-R', `-V',
`-W', `-d', `-l', `-o' and `-t'.  *Note Invoking m4::, for a
description of these options.
   Also, the debugging and tracing facilities in GNU `m4' are much more
extensive than in most other versions of `m4'.
File: m4.info,  Node: Incompatibilities,  Next: Other Incompat,  Prev: Extensions,  Up: Compatibility
Facilities in System V `m4' not in GNU `m4'
===========================================
   The version of `m4' from System V contains a few facilities that
have not been implemented in GNU `m4' yet.
   * System V `m4' supports multiple arguments to `defn'.  This is not
     implemented in GNU `m4'.  Its usefulness is unclear to me.
File: m4.info,  Node: Other Incompat,  Prev: Incompatibilities,  Up: Compatibility
Other incompatibilities
=======================
   There are a few other incompatibilities between this implementation
of `m4', and the System V version.
   * GNU `m4' implements sync lines differently from System V `m4',
     when text is being diverted.  GNU `m4' outputs the sync lines when
     the text is being diverted, and System V `m4' when the diverted
     text is being brought back.
     The problem is which lines and filenames should be attached to
     text that is being, or has been, diverted.  System V `m4' regards
     all the diverted text as being generated by the source line
     containing the `undivert' call, whereas GNU `m4' regards the
     diverted text as being generated at the time it is diverted.
     I expect the sync line option to be used mostly when using `m4' as
     a front end to a compiler.  If a diverted line causes a compiler
     error, the error messages should most probably refer to the place
     where the diversion were made, and not where it was inserted again.
   * GNU `m4' makes no attempt at prohiting autoreferential definitions
     like:
          define(`x', `x')
          define(`x', `x ')
     There is nothing inherently wrong with defining `x' to return `x'.
     The wrong thing is to expand `x' unquoted.  In `m4', one might
     use macros to hold strings, as we do for variables in other
     programming languages, further checking them with:
          ifelse(defn(`HOLDER'), `VALUE', ...)
     In cases like this one, an interdiction for a macro to hold its own
     name would be a useless limitation.  Of course, this leave more
     rope for the GNU `m4' user to hang himself!  Rescanning hangs may
     be avoided through careful programming, a little like for endless
     loops in traditional programming languages.
   * GNU `m4' without `-G' option will define the macro `__gnu__' to
     expand to the empty string.
     On UNIX systems, GNU `m4' without the `-G' option will define the
     macro `__unix__', otherwise the macro `unix'.  Both will expand to
     the empty string.