m4

macro processor

SYNTAX
      m4 [Options...] [Macro-Definitions...] [Input-File...]

DESCRIPTION
m4 is a macro processor, in the sense that it copies its input to the output, expanding macros as it goes. Macros are either builtin or user-defined, and can take any number of arguments. Besides just doing macro expansion, `m4' has builtin functions for including named files, running UNIX commands, doing integer arithmetic, manipulating text in various ways, recursion, etc... `m4' can be used either as a front-end to a compiler, or as a macro processor in its own right.

The `m4' macro processor is widely available on all UNIXes. Usually, only a small percentage of users are aware of its existence.
However, those who do often become commited users.

Some people found `m4' to be fairly addictive. They first use `m4' for simple problems, then take bigger and bigger challenges, learning how to write complex `m4' sets of macros along the way. Once really addicted, users pursue writing of sophisticated `m4' applications even to solve simple problems, devoting more time debugging their `m4' scripts than doing real work. Beware that `m4' may be dangerous for the health of compulsive programmers.

see info m4 for the full user manual

OPTIONS
--version
     Print the version number of the program on standard output, then
     immediately exit `m4' without reading any INPUT-FILES.

--help
     Print an help summary on standard output, then immediately exit
     `m4' without reading any INPUT-FILES.

-G
--traditional
     Suppress all the extensions made in this implementation, compared
     to the System V version.

-E
--fatal-warnings
     Stop execution and exit `m4' once the first warning has been
     issued, considering all of them to be fatal.

-d FLAGS
--debug=FLAGS
     Set the debug-level according to the flags FLAGS.  The debug-level
     controls the format and amount of information presented by the
     debugging functions.  *see below for more details on the
     format and meaning of FLAGS.

-l NUM
--arglength=NUM
     Restrict the size of the output generated by macro tracing.

-o FILE
--error-output=FILE'
     Redirect debug and trace output to the named file.  Error messages
     are still printed on the standard error output.  *Note Debug
     Output:: for more details.

-I DIR
--include=DIR
     Make `m4' search DIR for included files that are not found in the
     current working directory.  *Note Search Path:: for more details.

-e
--interactive
     Makes this invocation of `m4' interactive.  This means that all
     output will be unbuffered, and interrupts will be ignored.

-s
--synclines
     Generate synchronisation lines, for use by the C preprocessor or
     other similar tools.  This is useful, for example, when `m4' is
     used as a front end to a compiler.  Source file name and line
     number information is conveyed by directives of the form `#line
     LINENUM "FILENAME"', which are inserted as needed into the middle
     of the input.  Such directives mean that the following line
     originated or was expanded from the contents of input file
     FILENAME at line LINENUM.  The `"FILENAME"' part is often omitted
     when the file name did not change from the previous directive.

     Synchronisation directives are always given on complete lines per
     themselves.  When a synchronisation discrepancy occurs in the
     middle of an output line, the associated synchronisation directive
     is delayed until the beginning of the next generated line.

-P
--prefix-builtins
     Internally modify *all* builtin macro names so they all start with
     the prefix `m4_'.  For example, using this option, one should write
     `m4_define' instead of `define', and `m4___file__' instead of
     `__file__'.

-W REGEXP
--word-regexp=REGEXP
     Use an alternative syntax for macro names.  This experimental
     option might not be present on all GNU `m4' implementations.
     (*note Changeword::.).

-H N
--hashsize=N
     Make the internal hash table for symbol lookup be N entries big.
     The number should be prime.  The default is 509 entries.  It
     should not be necessary to increase this value, unless you define
     an excessive number of macros.

-L N
--nesting-limit=N
     Artificially limit the nesting of macro calls to N levels,
     stopping program execution if this limit is ever exceeded.  When
     not specified, nesting is limited to 250 levels.

     The precise effect of this option might be more correctly
     associated with textual nesting than dynamic recursion.  It has
     been useful when some complex `m4' input was generated by
     mechanical means.  Most users would never need this option.  If
     shown to be obtrusive, this option (which is still experimental)
     might well disappear.

     This option does *not* have the ability to break endless
     rescanning loops, while these do not necessarily consume much
     memory or stack space.  Through clever usage of rescanning loops,
     one can request complex, time-consuming computations to `m4' with
     useful results.  Putting limitations in this area would break `m4'
     power.  There are many pathological cases: `define(`a', `a')a' is
     only the simplest example (but *note Compatibility::.).  Expecting
     GNU `m4' to detect these would be a little like expecting a
     compiler system to detect and diagnose endless loops: it is a
     quite *hard* problem in general, if not undecidable!

-Q
--quiet
--silent
     Suppress warnings about missing or superflous arguments in macro
     calls.

-B
-S
-T
     These options are present for compatibility with System V `m4', but
     do nothing in this implementation.

-N N
--diversions=N
     These options are present only for compatibility with previous
     versions of GNU `m4', and were controlling the number of possible
     diversions which could be used at the same time.  They do nothing,
     because there is no fixed limit anymore.

   Macro definitions and deletions can be made on the command line, by
using the `-D' and `-U' options.  They have the following format:

-D NAME
-D NAME=VALUE
--define=NAME
--define=NAME=VALUE
     This enters NAME into the symbol table, before any input files are
     read.  If `=VALUE' is missing, the value is taken to be the empty
     string.  The VALUE can be any string, and the macro can be defined
     to take arguments, just as if it was defined from within the input.

-U NAME
--undefine=NAME
     This deletes any predefined meaning NAME might have.  Obviously,
     only predefined macros can be deleted in this way.

-t NAME
--trace=NAME
     This enters NAME into the symbol table, as undefined but traced.
     The macro will consequently be traced from the point it is defined.

-F FILE
--freeze-state FILE
     Once execution is finished, write out the frozen state on the
     specified FILE (*note Frozen files::.).

-R FILE
--reload-state FILE
     Before execution starts, recover the internal state from the
     specified frozen FILE (*note Frozen files::.).

FLAGS is any of:
a show actual arguments
c show before collect, after collect and after call
e show expansion
f say current input file name
i show changes in input files
l say current input line number
p show results of path searches
q quote values as necessary, with a or e flag
t trace for all macro calls, not only traceon'ed
x add a unique macro call id, useful with
c flag
V shorthand for all of the above flags

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 `-' 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 filename `-' should only appear once on the command line.

If defined, the environment variable 'M4PATH' is a colon-separated list of directories included after any specified by '-I'.

Exit status is 0 for success, 1 for failure, 63 for frozen file version mismatch, or whatever value was passed to the m4exit macro.

"To try to understand the workings of the economy by means of macroeconomics is rather like trying to understand how a clock works by observing the movements of the hands on its face" ~ David Simpson

Related:

awk - Find and Replace text within file(s)
expr - Evaluate expressions
eval - Evaluate several commands/arguments
for - Expand words, and execute commands
grep - search file(s) for lines that match a given pattern
Equivalent Windows commands: DOSKEY - Edit command line, recall commands, and create macros


© Copyright SS64.com 1999-2014
Some rights reserved