Return to m4 CVS log

Up to [MW Coherent from dump] / coherent / a / usr / man / MULTI

coherent

m4                           Command                           m4




Macro processor

mm44 [ffiillee ...]

The command m4 processes macros.  It allows you to define strings
for which m4  is to search, and strings to  replace them; m4 then
opens  file, reads  its contents,  replaces  each macro  with its
specified  replacement string,  and writes  the results  into the
standard output stream.

m4  can  also  perform  file manipulation,  conditional  decision
making, substring selection, and arithmetic.  The Introduction to
the m4 Macro Processor describes m4 in detail.

The files are read in the  order given; if no file is named, then
m4 reads the standard  input stream.  The file name `-' indicates
the standard input.

m4 copies  input to output  until it finds a  potential _m_a_c_r_o.  A
macro is  a string of  alphanumerics (letters, digits,  or under-
scores) that begins  with a non-digit character and is surrounded
by  non-alphanumerics.  If  m4 does not  recognize the  macro, it
simply copies  it to the output and  continues processing.  If m4
recognizes the macro and the next character is a left parenthesis
`(', an argument set follows:


        macro(arg1,..., argn)


The arguments are collected by processing them in the same manner
as other  text (thus, an arguments may  itself be another macro),
and resulting output text is diverted into storage.  m4 stores up
to nine arguments; any more  will be processed but not saved.  An
argument  set consists  of strings  of  text separated  by commas
(commas inside quotation marks or parentheses do not terminate an
argument), and must contain balanced parentheses that are free of
quotation marks  (i.e., that are unquoted).   m4 strips arguments
of unquoted leading space (blanks, tabs, newline characters).

m4 then removes the macro  and its optional argument set from the
input  stream, processes  them, and  replaces  them in  the input
stream  with the  resulting value.   The  value becomes  the next
piece of text to be read.

Quotation  marks, of  the form  ` ',  inhibit the  recognition of
macro.  m4  strips off one  level of quotation marks  when it en-
counters them  (quotation marks are nestable).   Thus, `_m_a_c_r_o' is
not processed, but is changed to macro and passed on.

m4 determines  the value  of a  user-defined macro by  taking the
text that  constitutes the  macro's definition and  replacing any
occurrence within that text of  `$_n' (where n is `0' through `9')
with the text  of the nth argument.  Argument 0  is the macro it-


COHERENT Lexicon                                           Page 1




m4                           Command                           m4



self.

m4 recognizes the following predefined macros:

cchhaannggeeqquuoottee[([_o_p_e_n_q_u_o_t_e],[_c_l_o_s_e_q_u_o_t_e])]
     Changes the quotation characters.  Missing arguments default
     to ` for open or ' for close.  Quotation characters will not
     nest if they are defined to be the same character.  Value is
     null.

ddeeccrr[(_n_u_m_b_e_r)]
     Decrement number  (default, 0) by one  and returns resulting
     value.

ddeeffiinnee(_m_a_c_r_o,_d_e_f_i_n_i_t_i_o_n)
     Define  or  redefine   macro.   If  a  predefined  macro  is
     redefined,  its original  definition is  irrecoverably lost.
     Value is null.

ddiivveerrtt[(_n)]
     Redirects  output to  output stream n  (default is  0).  The
     standard output is 0, and 1 through 9 are maintained as tem-
     porary files.   Any other n  results in output  being thrown
     away until the next divert macro.  Value is null.

ddiivvnnuumm
     Value is current output stream number.

ddnnll   Delete to  newline: removes all  characters from  the input
     stream up to and including the next newline.  Value is null.

dduummppddeeff[(_m_a_c_r_o_s)]
     Value  is quoted  definitions  of all  macros specified,  or
     names and definitions of all defined macros if no arguments.

eerrrrpprriinntt(_t_e_x_t)
     Print text on standard error file.  Value is null.

eevvaall(_e_x_p_r_e_s_s_i_o_n)
     Value is a number that is the value of evaluated expression.
     It  recognizes, in  order of  decreasing  precedence: paren-
     theses, **,  unary + -,  * / %,  binary + -,  relations, and
     logicals.  Arithmetic is performed in longs.

iiffddeeff(_m_a_c_r_o,_d_e_f_v_a_l_u_e,_u_n_d_e_f_v_a_l_u_e)
     Return defvalue if macro is defined, and undefvalue if not.

iiffeellssee(_a_r_g_1,_a_r_g_2,_a_r_g_3...)
     Compares arg1 and arg2.  If they are the same, returns arg3.
     If not, and arg4  is the last argument, return arg4.  Other-
     wise, the  process repeats, comparing arg4  and arg5, and so
     on.  Like other m4 macros,  this takes a maximum of nine ar-
     guments.




COHERENT Lexicon                                           Page 2




m4                           Command                           m4



iinncclluuddee(_f_i_l_e)
     Value is the entire  contents of the file argument.  If file
     is not accessible, a fatal error results.

iinnccrr[(_n_u_m_b_e_r)]
     Increments given  number (default, zero) by  one and returns
     resulting value.

iinnddeexx(_t_e_x_t,_p_a_t_t_e_r_n)
     Value is  a number corresponding  to position of  pattern in
     text.  If pattern does not occur in text, value is -1.

lleenn(_t_e_x_t)
     Value is a number that corresponds to length of text.

mmaakkeetteemmpp(_f_i_l_e_n_a_m_e_X_X_X_X_X_X)
     Value is filename  with last six characters, usually XXXXXX,
     replaced with current  process id and a single letter.  Same
     as system call mktemp.

ssiinncclluuddee(_f_i_l_e)
     Value is the entire contents of file.  If file is not acces-
     sible, return null and continue processing.

ssuubbssttrr(_t_e_x_t[,_s_t_a_r_t[,_c_o_u_n_t]])
     Value is  a substring of  text.  start may  be left-oriented
     (nonnegative) or right-oriented (negative).  count specifies
     how many  characters to  the right  (if positive) or  to the
     left (if  negative) to return.  If absent,  it is assumed to
     be  large  and of  the  same  sign as  start.   If start  is
     omitted, it  is assumed to  be zero if count  is positive or
     omitted, or -1 if count is negative.

ssyyssccmmdd(_c_o_m_m_a_n_d)
     Pass command to the  shell sh for execution.  Value is null.
     Same as system call system.

ttrraannsslliitt(_t_e_x_t,_c_h_a_r_a_c_t_e_r_s[,_r_e_p_l_a_c_e_m_e_n_t_s])
     Replaces characters  in text with  the corresponding charac-
     ters from  replacements.  If  the replacements is  absent or
     too short, replace  characters with a null character.  Value
     is text with specified replacements.

uunnddeeffiinnee(_m_a_c_r_o)
     Remove macro  definition.  Value  is null.  If  a predefined
     macro is redefined, its original definition is irrecoverably
     lost.

uunnddiivveerrtt[(_s_t_r_e_a_m[,...])]
     Dumps each specified  stream into the current output stream.
     With  no arguments,  undivert  dumps all  output streams  in
     numeric order.  m4 will  not dump any output stream into it-
     self.  At the  end of processing, m4 automatically dumps all
     diverted text to standard output in numeric order.  Value is
     null.


COHERENT Lexicon                                           Page 3




m4                           Command                           m4




***** See Also *****

commands, mktemp, system
_I_n_t_r_o_d_u_c_t_i_o_n _t_o _t_h_e _m_4 _M_a_c_r_o _P_r_o_c_e_s_s_o_r




















































COHERENT Lexicon                                           Page 4

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.