\input texinfo  @c -*- Texinfo -*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename m4.info
@settitle m4
@c @setchapternewpage odd
@comment %**end of header (This is for running Texinfo on a region.)

@iftex
@finalout
@end iftex

@ifinfo
This file documents the GNU m4 utility.

Copyright (C) 1989, 1990 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.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also 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.
@end ifinfo

@c $Revision: 0.5 $ $Date: 90/01/22 22:22:02 $
@titlepage
@null
@sp 10
@center @titlefont{GNU m4}
@sp 2
@center A simple macro processor
@sp 2
@center by Rene' Seindal
@sp 3
@center Edition 0.05.
@sp 1
@center last updated 22 Jan 1990,
@sp 1
@center for @code{m4}, Version 0.50.
@page
@null
@vskip 0pt plus 1filll
Copyright @copyright{} 1989, 1990 Free Software Foundation, Inc.
@sp 2

This is Edition 0.05 Beta of the @cite{GNU m4 Manual}, @*
last updated 22 Jan 1990, @*
for @code{m4} Version 0.50.

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 also 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.
@end titlepage
@page

@node Top, Intro, , (dir)
@comment  node-name,  next,  previous,  up

@menu
* Intro::                       Introduction to m4
* Manual::                      How to use this manual
* Bugs::                       	Reporting bugs in m4

* Invoking m4::                 How to run the program
* Syntax::                      Lexical and syntatic conventions

* Macros::                      How to invoke macros
* Definitions::                 How to define new macros
* Conditionals::                Conditionals and loops

* File inclusion::              File inclusion
* Diversions::                  Diverting and undiverting output

* Debugging::                   How to debug macros and input

* Text handling::               Macros for text handling
* Arithmetic::                  Macros for doing arithmetic
* Unix commands::               Macros for running Unix commands
* Miscellaneous::               Miscellaneous builtin macros

* Compatibility::               Compatibility with other wersions of m4

* Concept index::               Index over used concepts
* Macro index::                 Index over predefined macros
@end menu

@comment  node-name,  next,  previous,  up
@node Intro, Manual, Top, Top
@chapter Introduction to m4

@code{M4} is a macro processor, in the sense that in copies its input to
the output, expanding macros as it goes.  Macros can be either builtin
or user-defined, and can take any number of arguments.  Besides just
doing macro expansion, @code{m4} has builtin functions for such things
as including named files, running Unix commands, it supports integer
arithmetic, various forms of text manipulation, recursive macros,
etc@dots{}

@code{M4} can be used either as a front-end to a compiler (this is the
traditional use), or as a macro processor in its own right.

GNU @code{m4} is mostly compatible with the System V, release 3 version,
except for some minor differences.  @xref{Compatibility} for more
details.

@comment  node-name,  next,  previous,  up
@node Manual, Bugs, Intro, Top
@chapter Using this manual

This is a draft of the GNU @code{m4} manual.  Neither the program, nor
this manual should be regarded as finished, so comments and bug reports
are always welcome.  You will find the addresses to write to in the file
@file{README} in the source distribution.

This manual contains a number of examples of @code{m4} input and output,
and a simple notation is used to destinguish input, output and error
messages from @code{m4}.  Examples are set out from the normal text, and
shown in a fixed width font, like this

@comment ignore
@example
This is an example of an example!
@end example

To destinguish input from output, all output from @code{m4} are prefixed
by the string @samp{=>}, and all error messages by the string @samp{*>}.
Thus

@comment ignore
@example
Example of input line
=>Output line from m4
*>and an error message
@end example

If somebody has a better idea for this, I would very much like to hear
about it.

@node Bugs, Invoking m4, Manual, Top
@chapter Problems and Bugs

If you have problems with GNU @code{m4} or think you've found a bug,
please report it to Rene' Seindal; he doesn't promise to do anything
but he might well want to fix it.

Before reporting a bug, make sure you've actually found a real bug.
Carefully reread the documentation and see if it really says you can do
what you're trying to do.  If it's not clear whether you should be able
to do something or not, report that too; it's a bug in the documentation!

Before reporting a bug or trying to fix it yourself, try to isolate it
to the smallest possible input file that reproduces the problem.  Then
send us the input file and the exact results @code{m4} gave you.  Also
say what you expected to occur; this will help us decide whether the
problem was really in the documentation.

Once you've got a precise problem, send email to (Internet)
@samp{bug-gnu-utils@@prep.ai.mit.edu} or (UUCP)
@samp{mit-eddie!prep.ai.mit.edu!bug-gnu-utils}.  Please include the
version number of @code{m4} you are using.  You can get this information
with the command @samp{m4 -V /dev/null}.@refill

Non-bug suggestions are always welcome as well.  If you have questions
about things that are unclear in the documentation or are just obscure
features, ask Rene' Seindal; he'll be happy to help you out (but no
promises).  You can send him electronic mail at Internet address
@samp{seindal@@diku.dk}.

@comment  node-name,  next,  previous,  up
@node Invoking m4, Syntax, Bugs, Top
@chapter Invoking m4

The format of the @code{m4} command is:

@comment ignore
@example
m4 [@var{options}] [@var{macro-definition}] [@var{input-files}]
@end example

@cindex Command line, options
@cindex Options, command line
All options begin with @samp{-}.  GNU @code{m4} currently understands the
following options:

@table @code

@item -e
Makes this invocation of @code{m4} interactive.  This means that all
output will be unbuffered, and interupts will be ignored.@refill

@item -s
Generate sync lines, for use by the C preprocessor.  This is useful, if
@code{m4} is being used as a front end to a compiler.  The lines have
the format @samp{#line @var{lineno} "@var{file}"}, as described in the
manual for the C preprocessor.

@item -H@var{n}
Make the internal hash table for symbol lookup be @var{n} entries big.
The number should be a prime.  The default is 509 entries.  It should
not be necessary to increase this value, unless you define an excessive
number of macros.@refill

@item -d@var{n}
Set the debug-level to @var{n}.  The debug-level controls the format and
amount of information presented by the macros for debugging.
@xref{Debugging} for more details.@refill

@item -V
Print the version number of the program.  To see only the version
number, use the command @samp{m4 -V /dev/null}.@refill

@item -G
Suppress all the extensions made in this implementation, compared to the
System V version.  For a list of these, @pxref{Compatibility}.@refill

@item -B
@itemx -S
@itemx -T
These options are present for compatibility with System V @code{m4}, but
does nothing in this implementation.@refill
@end table

@cindex Macro definitions, on the command line
@cindex Command line, macro definitions on the
Macro definitions can be made on the command line, by using the
@samp{-D} and @samp{-U} switches.  They have the following format:

@table @code

@item -D@var{name}
@itemx -D@var{name}=@var{value}
This enters @var{name} into the symbol table, before any input files are
read.  If @samp{=@var{value}} is missing, the value is taken to be the
empty string.  The @var{value} can be any string, and the macro can be
defined to take arguments, just as if it was defined from within the
input.@refill

@item -U@var{name}
This deletes any predefined meaning @var{name} might have had.
Obviously, only predefined macros can be deleted in this way.

@end table

All macro definitions and deletions must appear @emph{after} the other
options.

@cindex Command line, file names on the
@cindex File names, on the command line
The remaining arguments on the command line are taken to be input file
names.  If no names are present, the standard input is read.  A file
name of @file{-} is taken to mean the standard input.

The input files are read in the sequence given.  The standard input can
only be read once, so the file name @file{-} should only appear once on
the command line.

@comment  node-name,  next,  previous,  up
@node Syntax, Macros, Invoking m4, Top
@chapter Lexical and syntatic conventions

@cindex Input tokens
@cindex Tokens
When @code{m4} scans its input, it separates it into @dfn{tokens}.  A token is
either a name, a quoted string, or any single character, that is not a
part of one of a name or a string.  Input to @code{m4} can also contain
comments.

@section Names

@cindex Names
A name is any sequence of letters, digits, and the character @kbd{_}
(underbar), where the first is not a digit.  If a name has a macro
definition, it will be subject to macro expansion (@pxref{Macros} for
more details).

@section Quoted strings

@cindex Quoted string
A quoted string is a sequence of characters surrounded by the quotes
@kbd{`} and @kbd{'}, where the number of start and end quotes within the
string balances.  The value of a string token is the text, with one
level of quotes stripped off.  Thus

@comment ignore
@example
`'
@end example

is the empty string, and

@comment ignore
@example
``quoted''
@end example

is the string

@comment ignore
@example
`quoted'
@end example

The quote characters can be changed at any time, using the builtin macro
@code{changequote}.  @xref{Miscellaneous} for more information.

@section Other tokens

Any character, that is neither a part of a name, nor of a quoted string,
is a token by itself.

@section Comments

@cindex Comments
Comments in @code{m4} are normally delimited by the characters @kbd{#}
and newline.  All characters between the comment delimiters are ignored.
The begin comment character can be included in the input by quoting it.

The comment delimiter can be changed at any time, using the builtin
macro @code{changecom}.  @xref{Miscellaneous} for more information.

@comment  node-name,  next,  previous,  up
@node Macros, Definitions, Syntax, Top
@chapter How to invoke macros

@cindex Macro invokation
Macro invokations has one of the forms

@comment ignore
@example
name
@end example

which is a macro invokation without any arguments, and

@comment ignore
@example
name(arg1, arg2, ..., argn)
@end example

@noindent
which is a macro invokation with @var{n} arguments.  The opening
parenthesis @emph{must} follow the @var{name} directly, with no spaces
in between.  Macros can have any number of arguments.

@section Macro arguments

@cindex Macro, arguments to
@cindex Arguments to macros
When a name is seen, and it has a macro definition, it will be expanded
as a macro.  If the name is not followed immediately by an opening
parenthesis, the macro will be called with no arguments.

If the name is followed by an opening parenthesis, the arguments will be
collected, and the macro called.  If too few arguments are supplied, the
missing arguments are taken to be the empty string.  If there are too
many arguments, the excess arguments are ignored.  Normally @code{m4} will
issue warnings if a macro is called with an inappropriate number of
arguments.

Macros are expanded normally during argument collection, and whatever
commas and parentheses that might show up in the resulting expanded text
will serve to separate arguments as well.  Thus, if @var{foo} expands to
@samp{,b,c}, the macro call

@comment ignore
@example
bar(a foo,d)
@end example

is a macro call with four arguments, which are @samp{a }, @samp{b},
@samp{c} and @samp{d}.

@section Quoting macro arguments

@cindex Quoted macro arguments
@cindex Macros, quoted arguments to
@cindex Arguments, quoted macro
Each argument has leading unquoted whitespace removed.  Within each
argument, all unquoted parentheses must match.  For example, if
@var{foo} is a macro,

@comment ignore
@example
foo(() (`(') `(')
@end example

is a macro call, with one argument, whose value is @samp{()(()(}.

It is common practice to quote all arguments to macros, unless you are
sure you want the arguments expanded.  Thus, in the above
example with the parentheses, the `right' way to do it is like this:

@comment ignore
@example
foo(`() (() (')
@end example

It is, however, in certain cases necessary to leave out quotes for some
arguments, and there is nothing wrong in doing it.  It just makes life a
bit harder, if you are not careful.

@section Macro expansion

@cindex Macros, expansion of
@cindex Expansion of macros
When the arguments, if any, to a macro call have been collected, the
expansion text are pushed back onto the input (unquoted), and reread.
The expansion text from one macro call might therefore result in more
macros being called, if the calls are included, completely or partially,
in the first macros expansion text.

Taking a very simple example, if @var{foo} expands to @samp{bar}, and
@var{bar} expands to @samp{Hello world}, the input

@comment ignore
@example
foo
@end example

@noindent
will expand first to @samp{bar}, and when this is being reread and
expanded, into @samp{Hello world}.

@comment  node-name,  next,  previous,  up
@node Definitions, Conditionals, Macros, Top
@chapter How to define new macros

@cindex Macros, how to define new
@cindex Defining new macros
Macros can be defined, redefined and deleted in several different ways.
Also, it is possible to redefine a macro, without losing a previous
value, which can be brought back at a later time.

@section Defining a macro

@findex define
The normal way to define or redefine macros is to use the builtin
@code{define}, which takes two arguments, the first being the macro
name, and the second the expansion text.

The following example defines the macro @var{foo} to expand to the text
@samp{Hello World.}.

@example
define(`foo', `Hello world.')
=>
foo
=>Hello world.
@end example

The empty line in the output is there because the newline is not a part
of the macro definition, and it is consequently copied to the output.
This can be avoided by use of the builtin @code{dnl}
(@pxref{Miscellaneous} for details).

@cindex Macros, arguments to
@cindex Arguments to macros
Macros can have arguments.  The @var{n}th argument are denoted by
@code{$n} in the expansion text, and are replaced by the @var{n}th
actual argument, when the macro is expanded.  Here is a simple example
of a macro with arguments.  It simply exchanges the order of the two
arguments.

@example
define(`exch', `$2, $1')
=>
exch(arg1, arg2)
=>arg2, arg1
@end example

This can for example be used, if you like the arguments to @code{define}
to be reversed.

@example
define(`exch', `$2, $1')
=>
define(exch(``expansion text'', ``macro''))
=>
macro
=>expansion text
@end example

For an explanation of the double quotes, @pxref{Syntax}.

@cindex GNU extensions
GNU @code{m4} allows the number following the @samp{$} to consist of one
or more digits, allowing macros to have any number of arguments.

If you want quoted text to appear as part of the expansion text,
remember that quotes can be nested in quoted strings.  Thus, in

@example
define(`foo', `This is macro `foo'.')
=>
foo
=>This is macro foo.
@end example

@noindent
the @samp{foo} in the expansion text is @emph{not} expanded.

@cindex Special arguments to macros
@cindex Macros, special arguments to
@cindex Arguments to macros, special
There is a special notation for the number of actual arguments supplied,
and for all the actual arguments.

The number of actual arguments in a macro call is denoted by @code{$#}
in the expansion text.  Thus, a simple macro to display the number of
arguments given, can be

@example
define(`nargs', `$#')
=>
nargs
=>0
nargs()
=>1
nargs(arg1, arg2, arg3)
=>3
@end example

The notation @code{$*} can be used in the expansion text to denote all
the actual arguments, with commas in between.  For example

@example
define(`echo', `$*')
=>
echo(arg1,    arg2, arg3 , arg4)
=>arg1, arg2, arg3 , arg4
@end example

Often each argument should be quoted, and the notation @code{$@@} handles
that.  It is just like @code{$*}, except that it quotes each argument.
A simple example of that is:

@example
define(`echo', `$@@')
=>
echo(arg1,    arg2, arg3 , arg4)
=>arg1, arg2, arg3 , arg4
@end example

Where did the quotes go?  Of course, they were eaten, when the expanded
text were reread by @code{m4}.  To show the difference, try

@example
define(`echo1', `$*')
=>
define(`echo2', `$@@')
=>
define(`foo', `This is macro `foo'.')
=>
echo1(foo)
=>This is macro This is macro foo..
echo2(foo)
=>This is macro foo.
@end example

If you don't understand this, @pxref{Debugging}.

A @samp{$} sign in the expansion text, that isn't followed by anything
@code{m4} understands, is simply copied to the macro expansion.

@example
define(`foo', `$$$ hello $$$')
=>
foo
=>$$$ hello $$$
@end example

If you want a macro to expand to something like @samp{$12}, put a pair
of quotes after the @code{$}.  This will prevent @code{m4} from
interpreting the @code{$} sign as a reference to an argument.

@section Deleting a macro

@cindex Macros, how to delete
@cindex Deleting macros
@cindex Undefining macros
@findex undefine
A macro definition can be removed with the builtin @code{undefine}.  It
takes one argument, which is the name of the macro to be removed.  It is
best illustrated by an example

@example
foo
=>foo
define(`foo', `expansion text')
=>
foo
=>expansion text
undefine(`foo')
=>
foo
=>foo
@end example

It is not an error to try to undefine an already undefined name.

@section Renaming macros

@cindex Macros, how to rename
@cindex Renaming macros
@findex defn
It is possible to rename an already defined macro, with the builtin
@code{defn}.  It returns the @emph{quoted definition} of its first
argument.  If the argument is not a defined macro, the expansion is
empty.

If the argument is the name of a user defined macro, the quoted
definition is simply the quoted expansion.  If, instead, it is a
builtin, the expansion can be seen as a special token, which points to
the builtins definition.  This last case is best understood through an
example.

@example
define(`zap', defn(`undefine'))
=>
zap(`undefine')
=>
undefine(`zap')
=>undefine(zap)
@end example

In this way, @code{defn} can be used to copy macro definitions, even
builtins definitions.  Even if the original macro is removed, the other
name can still be used to access the definition.

@section Temporarily redefining macros

@cindex Macros, temporary redefinition of
@cindex Temporary redefinition of macros
@cindex Redefinition of macros, temporary
It is possible to redefine a macro temporarily, reverting to the
previous definition at a later time.
@findex popdef
@findex pushdef
This is done with the builtins @code{pushdef} and @code{popdef}.  These
macros work in a stack-like fashion.@refill

Macros are temporarily redefined with @code{pushdef}, which is called
exactly like @code{define}, but instead of replacing an existing
definition, the previous definition is saved, before the new one is
installed.  If there is no previous definition, @code{pushdef} behaves
exactly like @code{define}.

If a macro has several definitions (of which only one is accessible),
the topmost definition can be removed with @code{popdef}, which is
called just like @code{undefine}. If there is no previous definition,
@code{popdef} does nothing.

@example
define(`foo', `Expansion one.')
=>
foo
=>Expansion one.
pushdef(`foo', `Expansion two.')
=>
foo
=>Expansion two.
popdef(`foo')
=>
foo
=>Expansion one.
popdef(`foo')
=>
foo
=>foo
@end example

If a macro has several definitions, and its name is given to
@code{define}, the topmost definition is @emph{replaced} with the new
definition.

If a macro has several definitions, and its name is given to
@code{undefine}, @emph{all} the definitions are removed, not only the
topmost one.  

@example
define(`foo', `Expansion one.')
=>
foo
=>Expansion one.
pushdef(`foo', `Expansion two.')
=>
foo
=>Expansion two.
define(`foo', `Second expansion two.')
=>
foo
=>Second expansion two.
undefine(`foo')
=>
foo
=>foo
@end example

It is naturally possible to temporarily redefine a builtin with
@code{pushdef} and @code{defn}.

@comment  node-name,  next,  previous,  up
@node Conditionals, Debugging, Definitions, Top
@chapter Conditionals, loops and recursion

Macros, expanding to plain text, perhaps with arguments, are not quite
enough.  We would like to have macros expand to different things, based
on decisions taken at run-time, e.g., we need some kind of conditionals.
Also, we would like to have some kind of loop construct, so we could do
something a number of times, or while some condition is true.

@section Conditionals

@cindex Conditionals
@findex ifdef
There are two different builtin conditionals in @code{m4}.  The first is
@code{ifdef}, which makes it possible to test for whether a macro is
defined or not.  The first argument to @code{ifdef} is the name of a
macro, and if the macro is defined, @code{ifdef} expands to the second
arguments, else to the third argument.  If the third argument is
omitted, it is taken to be the empty string (according to the normal
rules).

@example
ifdef(`foo', ``foo' is defined', ``foo' is not defined')
=>foo is not defined
define(`foo', `')
=>
ifdef(`foo', ``foo' is defined', ``foo' is not defined')
=>foo is defined
@end example

@findex ifelse
The other conditional, @code{ifelse}, is much more powerful.  It takes
three or more arguments.  If called with three or four arguments,
@code{ifelse} expands into the third argument, if the first and second
arguments are the same, otherwise into the fourth argument (which is
taken to be the empty string, if omitted).  Thus

@example
ifelse(foo, bar, `true')
=>
ifelse(foo, foo, `true')
=>true
ifelse(foo, bar, `true', `false')
=>false
ifelse(foo, foo, `true', `false')
=>true
@end example

@cindex Multibranches
Now, @code{ifelse} can take more than four arguments.  If given more
than four arguments, @code{ifelse} works like a multibranch.  If the
first and the second arguments are equal, it expands into the third
argument, else the procedure are repeated with the first three arguments
discarded, for example

@example
ifelse(foo, bar, `third', gnu, gnats, `sixth', `seventh')
=>seventh
@end example

Naturally, the normal case will be slightly more advanced that these
examples.  A common use of @code{ifelse} is in macros, used for loops.

@section Loops and recursion

@cindex Recursive macros
@cindex Macros, recursive
There is no direct support for loops in @code{m4}, but macros can be
recursive.  There is no limit on the number of recursion levels, other
than those you hardware and operating systems enforces.

@cindex Loops
Loops can be programmed using recursion and the conditionals described
previously.

@findex shift
There is a builtin macro, @code{shift}, which can, among other things,
be used for iterating through the actual arguments to a macro.  It takes
any number of arguments, and expands to all but the first argument,
separated by commas, with each argument quoted.  Thus

@example
shift(bar)
=>
shift(foo, bar, baz)
=>bar, baz
@end example

A simple example of use of @code{shift}, is this macro, which
concatenates all its arguments, separated by commas.

@example
define(`concat', `ifelse($2, , `$1', `$1,concat(shift($@@))')')
=>
concat(foo)
=>foo
concat(foo, bar, gnats,and gnus)
=>foo,bar,gnats,and gnus
@end example


@cindex Forloops
@cindex Loops, counting
@cindex Counting loops
Another example is a looping macro, that implements a simple forloop.
It can for example be used for simple counting.

@comment ignore
@example
forloop(`i', 1, 8, `i ')
=>1 2 3 4 5 6 7 8
@end example

The arguments are a name for the iteration variable, the starting value,
the final value, and the text to be expanded for each iteration.  With
this macro, the macro @code{i} is defined only within the loop.  After
the loop, it retains whatever value it might have had before.

For-loops can be nested, like

@comment ignore
@example
forloop(`i', 1, 4, `forloop(`j', 1, 8, `(i, j) ')
')
=>(1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8)
=>(2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8)
=>(3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8)
=>(4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8)
=>
@end example

The implementation of the @code{forloop} macro is fairly
straightforward.  The @code{forloop} macro itself is simply a wrapper,
which saves the previous definition of the first argument, calls the
internal macro @code{_forloop}, and restablishes the saved definition of
the first argument.

The macro @code{_forloop} expands the fourth argument once, and tests to
see if it is finished.  If it has not finished, it increments the
iteration variable (using the predefined macro @code{incr}
(@pxref{Arithmetic} for details)), and recurses.

Here is the actual implementation of @code{forloop}:

@comment ignore
@example
define(`forloop',
       `pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')popdef(`$1')')
define(`_forloop',
       `$4`'ifelse($1, `$3', ,
                   `define(`$1', incr($1))_forloop(`$1', `$2', `$3', `$4')')')
@end example

Notice the careful use of quotes.  Only three macro arguments are
unquoted, each for its own reason.  Try to find out @emph{why} these
three arguments are left unquoted, and see what happens, if they are
quoted.

Now, even though these two macros are useful, they are still not robust
enough for general use. They lack even basic error handling, of cases
like start value less than final value, and the first argument not being
a name.  Correcting these errors is left as an exercise to the reader.


@comment  node-name,  next,  previous,  up
@node Debugging, File inclusion, Conditionals, Top
@chapter How to debug macros and input

When writing macros for @code{m4}, most of the times they don't work
as intended (as is the case with most programming languages).  There is
a little support for macro debugging in @code{m4}.

The @samp{-d} option is supposed to control the amount of details
presented, when using the macros described in the following sections,
but it is not implemented in the current version of GNU @code{m4}.

@section Displaying macro definitions

@cindex Displaying macro definitions
@cindex Macros, displaying definitions
@cindex Definitions, displaying macro
@findex dumpdef
If you want to see what a name expands into, you can use the builtin
@code{dumpdef}.  It can be called with any number of arguments.  If
called with zero arguments, it displays the definitions of all known
names, otherwise it displays the definitions of the names given.  The
output is printed directly on the standard error output.  For example

@example
define(`foo', `Hello world.')
=>
dumpdef(`foo')
*>foo:    `Hello world.'
=>
dumpdef(`define')
*>define: <define>
=>
@end example

The last example shows how builtin macros definitions are displayed.

@section Tracing macro calls

@cindex Tracing macro expansion
@cindex Macro expansion, tracing
@cindex Expansion, tracing macro
@findex traceon
@findex traceoff
It is possible to trace macro calls and expansions through the builtins
@code{traceon} and @code{traceoff}.  Both builtins can be called with any
number of arguments.  If called without any arguments, they will turn
tracing on resp. off for all known macros, otherwise only the named
macros are affected.

Whenever a traced macro is called and the arguments collected, the call
is displayed.  If the expansion is non-null, the expansion is displayed
after the call.  The output is printed directly on the standard error
output.  For example

@example
define(`foo', `Hello World.')
=>
define(`echo', `$@@')
=>
traceon(`foo', `echo')
=>
foo
*>m4 trace (1): foo -> `Hello World.'
=>Hello World.
echo(gnus, and gnats)
*>m4 trace (1): echo( `gnus', `and gnats' ) -> ``gnus', `and gnats''
=>gnus, and gnats
@end example

Tracing normally quotes all arguments and the expansion, in case they
contain whitespace.

The number in parentheses is the depth of the expansion.  It is one most
of the time, signifying an expansion at the outermost level, but it
increases, when macro arguments contains unquoted macro calls.

@comment  node-name,  next,  previous,  up
@node File inclusion, Diversions, Debugging, Top
@chapter File inclusion

@cindex File inclusion
@cindex Inclusion, of files
@findex include
The builtin macro @code{include} takes one argument, which is a file
name of a file to be read by @code{m4}.  Subsequent input will be read from the
named file.  When the end of file is reached, input is resumed from the
previous input file.

@findex sinclude
It is an error for an @code{include}d file not to exist.  If you don't
want error messages about non-existent files, the builtin
@code{sinclude} can be used to silently include a file, if it exists.
If the file does not exist, @code{sinclude} expands to nothing.

Some examples are needed here!

@comment  node-name,  next,  previous,  up
@node Diversions, Text handling, File inclusion, Top
@chapter Diverting and undiverting output

Diversions are a way of temporarily saving output, which can be brought
back at a later time.

@section Diverting output

@cindex Diverting output to files
@cindex Output, diverting to files
@cindex Files, diverting output to
@findex divert
Output can be saved temporarily by diverting it.  Up to ten numbered
diversions (numbered from 0 to 9) are supported in @code{m4}.  Diversion
number 0 is the normal output stream.  Output are diverted using the
builtin @code{divert}.  It takes zero or one argument, which is the
diversion number, or 0 if not supplied.

Diverted data, that haven't been explicitly undiverted, will be brought
back when all other input have been processed.

@example
divert(1)
This text is diverted.
divert
=>
This text is not diverted
=>This text is not diverted
^D
=>This text is diverted.
@end example

Several calls of @code{divert} with the same argument does not overwrite
the previous diveretd text, but rather appends to it.

If output are diverted to an non-existing divertion, 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.

@example
divert(-1)
define(`foo', `Macro `foo'.')
define(`bar', `Macro `bar'.')
divert
=>
@end example

This is a common programming ideom in @code{m4}.

@section Undiverting output

@findex undivert
Diverted text can be brought back explicitly using the builtin
@code{undivert}, which brings back the diversions given as arguments, in
the order given.  If no arguments are supplied, all diversions are
brought back, in numerical order.

@example
divert(1)
This text is diverted.
divert
=>
This text is not diverted
=>This text is not diverted
undivert(1)
=>
=>This text is diverted.
=>
@end example

Notice the last two blank lines.  One of them comes from the newline
following @code{undivert}, the other from the newline that followed the
@code{divert}!  A diversion often starts with a blank line like this.

When diverted text is brought back, it is @emph{not} reread by
@code{m4}, but rather copied directly to the current output.  It is not
an error to undivert into a diversion.  When a diversion has been
brought back, the diverted text is discarded.  It is therefore not
possible to bring back diverted text more than once.

@section Diversion numbers

@cindex Diversion numbers
@findex divnum
The current diversion number is returned by the builtin @code{divnum}.
Thus

@example
Initial divnum
=>Initial 0
divert(1)
Diversion one: divnum
divert(2)
Diversion two: divnum
divert
=>
^D
=>Diversion one: 1
=>
=>Diversion two: 2
@end example

The last @code{divert} without argument is necessary, since the
undiverted text would otherwise be diverted itself.

@section Discarding diverted text

@cindex Discarding diverted text
@cindex Diverted text, discarding
Often it is not known, when output is diverted, whether the diverted
text is actually needed.  Since all non-empty diversion are brought back
when the end of input is seen, a method of discarding a diversion is
needed.

This is done very easy, using a macro like this.

@example
define(`cleardivert',
`pushdef(`_divnum', divnum)divert(-1)undivert($@@)divert(_divnum)popdef(`_divnum')')
=>
@end example

It is called just like @code{undivert}, but the effect is to clear the
diversions, given by the arguments.

@comment  node-name,  next,  previous,  up
@node Text handling, Arithmetic, Diversions, Top
@chapter Macros for text handling

There is a number of builtins in @code{m4} for manipulating strings of text.

@section Length of strings

@cindex Length of strings
@cindex Strings, length of
@findex len
The builtin @code{len} takes one argument, and returns the length of the
string.  For example

@example
len(`')
=>0
len(`abcdef')
=>6
@end example

@section The index function

@findex index
The builtin @code{index} takes two arguments, and returns the index of
the first occurence of the second argument in the first.  The first
character has index 0.  If the second argument does not occur in the
first argument, it returns -1.  Thus

@example
index(`gnus, gnats, and armadillos', `nat')
=>7
index(`gnus, gnats, and armadillos', `dag')
=>-1
@end example

@section Extracting substrings

@cindex Extracting substrings
@cindex Substrings, extracting
@findex substr
Substrings can be extracted using the builtin @code{substr}.  It takes
two or three arguments.  The first argument is the string, from which
the substring is taken, the second argument is the index of the first
charater of the substring, and the third argument is length of the
substring.  If the last argument is omitted, the substring extends to
the end of the input string.

@example
substr(`gnus, gnats, and armadillos', 6)
=>gnats, and armadillos
substr(`gnus, gnats, and armadillos', 6, 5)
=>gnats
@end example


@section Translating characters

@cindex Translating characters
@cindex Characters, translating
@findex translit
There is a builtin, @code{translit}, for character translation.  The
first argument is the string to be worked upon and the second is the
characters to be translated.

Each character in the first argument, that also occurs in the second
argument, is translated into the character with the same index from the
third argument.  If the third argument is shorter than the second, the
excess characters are deleted.  If the third argument is omitted, all
characters in the first, that are also present in the second, are
deleted.

@example
translit(`abcdefghijklmnopqrstuvwxyz', `aeiou', `01234')
=>0bcd1fgh2jklmn3pqrst4vwxyz
translit(`abcdefghijklmnopqrstuvwxyz', `aeiou', `AEI')
=>AbcdEfghIjklmnpqrstvwxyz
translit(`abcdefghijklmnopqrstuvwxyz', `aeiou')
=>bcdfghjklmnpqrstvwxyz
@end example

If you think this resembles the Unix program @code{tr}, you are quite
right.  The @code{translit} macro does @emph{not}, however, allow
shorthands like @samp{a-z} to mean all lowercase letters.

@comment  node-name,  next,  previous,  up
@node Arithmetic, Unix commands, Text handling, Top
@chapter Macros for doing arithmetic

@cindex Arithmetic
@cindex Integer arithmetic
Integer arithmetic is included in @code{m4}, with a C like syntax.  As
convenient shorthands, there are builtins for simple increment and
decrement operations.

@section Decrement and increment operators

@cindex Decrement operator
@cindex Increment operator
@findex incr
@findex decr
Increment and decrement of integers are supported using the builtins
@code{incr} and @code{decr}.  Each macro takes one argument, and returns
the numerical value, incremented, resp. decremented by one.

@example
incr(4)
=>5
decr(7)
=>6
@end example

@section Evaluating integer expressions

@cindex Integer expression evaluation
@cindex Evaluation, of integer expressions
@cindex Expressions, evaluation of integer
@findex eval
The builtin @code{eval} evaluates general integer expressions.
Expressions can contain the following operators, listed in decreasing
precedence.

@table @code
@item -
Unany minus
@item **  ^
Exponentation
@item *  /  %
Multiplication, division and modulo
@item +  -
Addition and subtraction
@item ==  !=  >  >=  <  <=
Relational operators
@item !
Logical negation
@item &
Bitwise and
@item |
Bitwise or
@item &&
Logical and
@item ||
Logical or
@end table

All operators, but exponentation, are left associative.

Numbers can be given in decimal, octal (starting with @code{0}), or
hexadecimal (starting with @code{0x}).

Parentheses may be use to group subexpressions whenever needed.  For the
relational operators, a true relation returns @code{1}, and a false
relation return @code{0}.

Here is a few examples of use of @code{eval}.

@example
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)
*>examples/arithmetic.2: 14: bad expression in eval: foo/6
=>
eval(foo/6)
=>111
@end example

As the second last example shows @code{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 @code{eval}.

A second argument to @code{eval} can be used to specify the radix to be
used in the output.  The default radix is 10.  If the specified radix is
different from 10, the result of @code{eval} is taken to be unsigned,
otherwise it is signed.  A third argument specifies a minimum output
width.  The result is then zero-padded to match the requested width.

@example
eval(666, 10)
=>666
eval(666, 11)
=>556
eval(666, 6)
=>3030
eval(666, 6, 10)
=>0000003030
eval(-16, 16)
=>fffffff0
@end example

@comment  node-name,  next,  previous,  up
@node Unix commands, Miscellaneous, Arithmetic, Top
@chapter Running Unix commands

@cindex Executing Unix commands
@cindex Running Unix commands
@cindex Unix commands, running
@cindex Commands, running Unix
There is a few builtin macros to interface to the operating system.  It
allows you to run Unix commands from within @code{m4}.

@findex syscmd
Any shell command can be run, using the builtin @code{syscmd}.  It takes
one argument, which is the command to run.

The expansion of @code{syscmd} is always empty.  It is @emph{not} the
output from the command!  Instead the standard input, output and error
of the shell command are the same as those of @code{m4}.  This means
that output or error messages from the shell commands are not read by
@code{m4}, and might get mixed up with the normal output from @code{m4}.
This can produce unexpected results.  It is therefore a good habit to
always redirect the input and output of shell commands.

@cindex Exit code from Unix commands
@cindex Unix commands, exit code from
@cindex Commands, exit code from Unix
@findex sysval
To test whether the shell command succeeded, the builtin @code{sysval}
can be used.  It returns the exit status of the last shell command run
with @code{syscmd}.

@example
syscmd(`false')
=>
sysval
=>1
syscmd(`true')
=>
sysval
=>0
@end example

@cindex Temporary file names
@cindex Files, names of temporary
@cindex Names, temporary file
@findex maketemp
There is a builtin macro, @code{maketemp}, for making temporary file
names, for use with @code{syscmd}.  It takes one argument, which is a
file name template, ending with the string @samp{XXXXXX}.  The six
@code{X}'s are then replaced, usually with something that includes the
process id of the @code{m4} process, as to make the file name unique.

@comment ignore
@example
maketemp(`/tmp/fooXXXXXX')
=>/tmp/fooa07346
maketemp(`/tmp/fooXXXXXX')
=>/tmp/fooa07346
@end example

As seen in the example, several calls of @code{maketemp} might return
the same string, since the selection criteria is whether the file exists
or not.  If the file returned by the first call has not been created
before the second call, the same name might be returned.

@cindex Output from Unix Commands
@cindex Unix commands, output from
@cindex Commands, output from Unix
If you want to capture the output of a shell command, run with
@code{syscmd}, you must make a name of an unused temporary file with the
builtin @code{maketemp}, and redirect the shell commands output to it.
If the shell command succeeds, the file can be included.

@comment ignore
@example
define(`tmpfile', maketemp(`/tmp/fooXXXXXX'))
=>
syscmd(`who >' tmpfile)
=>
ifelse(sysval, 0, `include(tmpfile)')
=>herskind ttyp0   Dec 18 19:49   (tau)
=>seindal  ttyp5   Dec 18 11:54   (vale:0.0)
=>carllp   ttyp8   Dec 18 11:58   (vigrid:0.0)
=>seindal  ttype   Dec 18 12:36   (vale:0.0)
=>kaiip    ttypf   Dec 18 15:41   (gamma)
=>sigfried ttyq0   Dec 18 13:11   (rimfaxe)
=>
@end example

Of course, you should remove the temporary file afterwards.

@comment  node-name,  next,  previous,  up
@node Miscellaneous, Compatibility, Unix commands, Top
@chapter Miscellaneous builtin macros

This chaper describes various builtins, that doesn't really belong in
any of the previous chapters.

@section Deleting whitespace in input

@cindex Deleting whitespace in input
@findex dnl
The builtin @code{dnl} reads and discards all characters, upto and
including the first newline.  It is often used in connection with
@code{define}, to remove the newline that follow the call to
@code{define}.  Thus

@example
define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
foo
=>Macro foo.
@end example

@section Changing the quote characters

@cindex Changing the quote characters
@cindex Quote characters, changing the 
@findex changequote

The default quote characters can be changed with the builtin
@code{changequote}.  It takes up to two arguments, specifying the left
resp. the right quote.  Only the first character from each argument is
used.

@example
changequote([,])
=>
define([foo], [Macro [foo].])
=>
foo
=>Macro foo.
@end example

There is no way in @code{m4} to make a string containing a single left quote,
less of using @code{changequote} to change the current quotes.

If @code{changequote} is called with too few arguments, the default
quote characters (@code{`'}) are used instead of the missing arguments.

@section Changing comment delimeters

@cindex Changing comment delimeters
@cindex Comment delimeters, changing
@findex changecom
The default comment delimeters can be changed with the builtin
@code{changecom}.  It takes up to two arguments, specifying the start
resp. the end comment delimeter.  Only the first character from each
argument is used.

@example
define(`comment', `COMMENT')
=>
# A normal comment
=># A normal comment
changecom(`@@', `*')
=>
# Not a comment anymore
=># Not a COMMENT anymore
But: @@ this is now a comment *
=>But: @@ this is now a comment *
@end example

@cindex Comments, copied to output
Note how comments are copied to the output, much as it they were quoted
strings.  If you want the text inside a comment expanded, simply quote
the start comment delimeter.

@section Printing error messages

@cindex Printing error messages
@cindex Error messages, printing
@cindex Messages, printing error
@findex errprint
You can print error messages using the builtin @code{errprint}, which
simply prints all its arguments on the standard error output.

@example
errprint(`Illegal arguments to forloop
')
*>Illegal arguments to forloop
=>
@end example

A trailing newline is @emph{not} printed automatically, so it must be
supplied as part of the argument, as in the example.

@section Exiting from @code{m4}

@cindex Exiting from m4
@findex m4exit
If you need to exit from @code{m4} before the entire input has been read, you
can use the builtin @code{m4exit}.  It causes @code{m4} to exit, with exit code
as supplied by the first argument.  If no arguments are given, the exit
code is zero.

@example
define(`fatal_error', `errprint(`m4: fatal error: $*
')m4exit(1)')
=>
fatal_error(`This is a BAD one, buster')
*>m4: fatal error: This is a BAD one, buster
@end example

After this input, @code{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 are not brought back, and saved text (see
next section) are not reread.

@section Saving input

@cindex Saving input
@cindex Input, saving
@findex m4wrap
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 @code{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 @code{m4wrap}, which takes any
number of arguments.  Thus

@example
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.
@end example

The saved input is only reread when the end of normal input is seen, and
not if @code{m4exit} is used to exit @code{m4}.

It is safe to call @code{m4wrap} from saved text, but then the order the
saved text is reread is undefined.  If @code{m4wrap} isn't used
recursively, the saved pieces of text are reread in the opposite order
in which they were saved.

@section Indirect call of builtins

@cindex Indirect call of builtins
@cindex Call of builtins, indirect
@cindex Builtins, indirect call of
@cindex GNU extensions
@findex builtin
The builtin @code{builtin} can be used to call builtins indirectly.  The
builtin given by the first argument is called with the rest of the
arguments.

@comment  node-name,  next,  previous,  up
@node Compatibility, Concept index, Miscellaneous, Top
@chapter Compatibility with other wersions of m4

@cindex Compatibility
This chapter describes the differences between this implementation of
@code{m4}, and the implementation found in System V, release 3.

@section Facilites in System V @code{m4} not in GNU @code{m4}

The version of @code{m4} from System V contains a few facilities, that have not
been implemented in GNU @code{m4} yet.

@itemize @bullet
@item
Multicharacter comment delimiters are not supported in GNU @code{m4}.  System V
@code{m4} supports comment delimiters of upto 5 characters.
@item
Multicharacter quote delimiters are not supported in GNU @code{m4}.  System V
@code{m4} supports quote delimiters of upto 5 characters.
@item
System V @code{m4} supports multiple arguments to @code{defn}.  This is
not implemented in GNU @code{m4}.  Its usefulness is unclear to me.
@end itemize

@section Facilites in GNU @code{m4} not in System V @code{m4}

@cindex GNU extensions
This version of @code{m4} contains a few facilities, that does not exist
in System V @code{m4}.  These extra facilities are suppressed by using
the @samp{-G} command line switch.

@itemize @bullet
@item
@code{m4wrap} takes several arguments, whereas the System V @code{m4} only
takes one.
@item
@code{errprint} takes several arguments, whereas the System V @code{m4} only
takes one.
@item
In the @code{$}@var{n} notation for macro arguments, @var{n} can contain
several digits, while the System V @code{m4} only accepts one digit.  This
allows macros in GNU @code{m4} to take any number of arguments, and not only
nine.
@end itemize

@section Other incompatibilities

There are a few other incompatibilities between this implementation of
@code{m4}, and the System V version.

@itemize @bullet
@item
GNU @code{m4} implements the builtins @code{incr} and @code{decr} as
ordinary macros, expanding to @samp{eval(($1)+1)} resp.
@samp{eval(($1)-1)}.  This causes error messages, if the arguments to
@code{incr} and @code{decr} are ill-formed expressions.  System V
@code{m4} only looks at a numerical prefix to the argument.
Consequently, the input @samp{incr(3foo)} fails in GNU @code{m4}, and
not in System V @code{m4}.@refill
@item
GNU @code{m4} implements sync lines differently that System V @code{m4},
when text is being diverted.  GNU @code{m4} outputs the sync lines when
the text is being diverted, and System V @code{m4} when the diverted
text is being brought back.

The problem is which lines and file names that should be attached to
text that are being, or have been, diverted.  System V @code{m4} regards
all the diverted text as being generated by the source line containing
the @code{undivert} call, whereas GNU @code{m4} regards the diverted
text as being generated at the time it is diverted.
@end itemize

@node Concept Index, Macro Index, Compatibility, Top

@unnumbered Concept index
@printindex cp

@node Macro Index, , Concept Index, Top

@unnumbered Macro index
@printindex fn

@contents
@bye
