[BACK]Return to m4.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / m4

Diff for /src/usr.bin/m4/m4.1 between version 1.35 and 1.36

version 1.35, 2004/02/17 19:28:31 version 1.36, 2004/05/25 18:41:17
Line 148 
Line 148 
 provides the following built-in macros.  provides the following built-in macros.
 They may be redefined, losing their original meaning.  They may be redefined, losing their original meaning.
 Return values are null unless otherwise stated.  Return values are null unless otherwise stated.
 .Bl -tag -width changequotexxx  .Bl -tag -width changequote
 .It Ic builtin  .It Fn builtin name
 Calls a built-in by its name, overriding possible redefinitions.  Calls a built-in by its
 .It Ic changecom  .Fa name ,
   overriding possible redefinitions.
   .It Fn changecom startcomment endcomment
 Change the start and end comment sequences.  Change the start and end comment sequences.
 The default is the pound sign  The default is the pound sign
 .Pq Sq #  .Pq Sq #
 and the newline character.  and the newline character.
 With no arguments comments are turned off.  With no arguments comments are turned off.
 The maximum length for a comment marker is five characters.  The maximum length for a comment marker is five characters.
 .It Ic changequote  .It Fn changequote beginquote endquote
 Defines the quote symbols to be the first and second arguments.  Defines the quote symbols to be the first and second arguments.
 The symbols may be up to five characters long.  The symbols may be up to five characters long.
 If no arguments are  If no arguments are
 given it restores the default open and close single quotes.  given it restores the default open and close single quotes.
 .It Ic decr  .It Fn decr arg
 Decrements the argument by 1.  Decrements the argument
 The argument must be a valid numeric string.  .Fa arg
 .It Ic define  by 1.
 Define a new macro named by the first argument to have the  The argument
 value of the second argument.  .Fa arg
   must be a valid numeric string.
   .It Fn define name value
   Define a new macro named by the first argument
   .Fa name
   to have the
   value of the second argument
   .Fa value .
 Each occurrence of  Each occurrence of
 .Sq $n  .Sq $n
 (where  (where
Line 187 
Line 196 
 is the same as  is the same as
 .Sq $*  .Sq $*
 but all arguments are quoted against further expansion.  but all arguments are quoted against further expansion.
 .It Ic defn  .It Fn defn name ...
 Returns the quoted definition for each argument.  Returns the quoted definition for each argument.
 This can be used to rename  This can be used to rename
 macro definitions (even for built-in macros).  macro definitions (even for built-in macros).
 .It Ic divert  .It Fn divert num
 There are 10 output queues (numbered 0-9).  There are 10 output queues (numbered 0-9).
 At the end of processing  At the end of processing
 .Nm m4  .Nm m4
Line 205 
Line 214 
 Returns the current output queue number.  Returns the current output queue number.
 .It Ic dnl  .It Ic dnl
 Discard input characters up to and including the next newline.  Discard input characters up to and including the next newline.
 .It Ic dumpdef  .It Fn dumpdef name ...
 Prints the names and definitions for the named items, or for everything  Prints the names and definitions for the named items, or for everything
 if no arguments are passed.  if no arguments are passed.
 .It Ic errprint  .It Fn errprint msg
 Prints the first argument on the standard error output stream.  Prints the first argument on the standard error output stream.
 .It Ic esyscmd  .It Fn esyscmd cmd
 Passes its first argument to a shell and returns the shell's standard output.  Passes its first argument to a shell and returns the shell's standard output.
 Note that the shell shares its standard input and standard error with  Note that the shell shares its standard input and standard error with
 .Nm m4 .  .Nm m4 .
 .It Ic eval  .It Fn eval expr
 Computes the first argument as an arithmetic expression using 32-bit  Computes the first argument as an arithmetic expression using 32-bit
 arithmetic.  arithmetic.
 Operators are the standard C ternary, arithmetic, logical,  Operators are the standard C ternary, arithmetic, logical,
Line 224 
Line 233 
 The second argument (if any)  The second argument (if any)
 specifies the radix for the result and the third argument (if any)  specifies the radix for the result and the third argument (if any)
 specifies the minimum number of digits in the result.  specifies the minimum number of digits in the result.
 .It Ic expr  .It Fn expr expr
 This is an alias for  This is an alias for
 .Ic eval .  .Ic eval .
 .It Ic ifdef  .It Fn ifdef name yes no
 If the macro named by the first argument is defined then return the second  If the macro named by the first argument is defined then return the second
 argument, otherwise the third.  argument, otherwise the third.
 If there is no third argument, the value is  If there is no third argument, the value is
Line 235 
Line 244 
 The word  The word
 .Qq unix  .Qq unix
 is predefined.  is predefined.
 .It Ic ifelse  .It Fn ifelse a b yes ...
 If the first argument matches the second argument then  If the first argument
 .Ic ifelse  .Fa a
   matches the second argument
   .Fa b
   then
   .Fn ifelse
 returns  returns
 the third argument.  the third argument
   .Fa yes .
 If the match fails the three arguments are  If the match fails the three arguments are
 discarded and the next three arguments are used until there is  discarded and the next three arguments are used until there is
 zero or one arguments left, either this last argument or  zero or one arguments left, either this last argument or
 .Dv NULL  .Dv NULL
 is returned if no other matches were found.  is returned if no other matches were found.
 .It Ic include  .It Fn include name
 Returns the contents of the file specified in the first argument.  Returns the contents of the file specified in the first argument.
 If the file is not found as is, look through the include path:  If the file is not found as is, look through the include path:
 first the directories specified with  first the directories specified with
Line 254 
Line 268 
 .Ev M4PATH ,  .Ev M4PATH ,
 as a colon-separated list of directories.  as a colon-separated list of directories.
 Include aborts with an error message if the file cannot be included.  Include aborts with an error message if the file cannot be included.
 .It Ic incr  .It Fn incr arg
 Increments the argument by 1.  Increments the argument by 1.
 The argument must be a valid numeric string.  The argument must be a valid numeric string.
 .It Ic index  .It Fn index string substring
 Returns the index of the second argument in the first argument (e.g.,  Returns the index of the second argument in the first argument (e.g.,
 .Ic index(the quick brown fox jumped, fox)  .Ic index(the quick brown fox jumped, fox)
 returns 16).  returns 16).
 If the second  If the second
 argument is not found index returns \-1.  argument is not found index returns \-1.
 .It Ic indir  .It Fn indir macro arg1 ...
 Indirectly calls the macro whose name is passed as the first argument,  Indirectly calls the macro whose name is passed as the first argument,
 with the remaining arguments passed as first, ... arguments.  with the remaining arguments passed as first, ... arguments.
 .It Ic len  .It Fn len arg
 Returns the number of characters in the first argument.  Returns the number of characters in the first argument.
 Extra arguments  Extra arguments
 are ignored.  are ignored.
 .It Ic m4exit  .It Fn m4exit code
 Immediately exits with the return value specified by the first argument,  Immediately exits with the return value specified by the first argument,
 0 if none.  0 if none.
 .It Ic m4wrap  .It Fn m4wrap todo
 Allows you to define what happens at the final  Allows you to define what happens at the final
 .Dv EOF ,  .Dv EOF ,
 usually for cleanup purposes (e.g.,  usually for cleanup purposes (e.g.,
 .Ic m4wrap("cleanup(tempfile)")  .Ic m4wrap("cleanup(tempfile)")
 causes the macro cleanup to be  causes the macro cleanup to be
 invoked after all other processing is done).  invoked after all other processing is done).
 .It Ic maketemp  .It Fn maketemp template
 Invokes  Invokes
 .Xr mkstemp 3  .Xr mkstemp 3
 on the first argument, and returns the modified string.  on the first argument, and returns the modified string.
 This can be used to create unique  This can be used to create unique
 temporary file names.  temporary file names.
 .It Ic paste  .It Fn paste file
 Includes the contents of the file specified by the first argument without  Includes the contents of the file specified by the first argument without
 any macro processing.  any macro processing.
 Aborts with an error message if the file cannot be  Aborts with an error message if the file cannot be
 included.  included.
 .It Ic patsubst  .It Fn patsubst string regexp replacement
 Substitutes a regular expression in a string with a replacement string.  Substitutes a regular expression in a string with a replacement string.
 Usual substitution patterns apply: an ampersand  Usual substitution patterns apply: an ampersand
 .Pq Sq \&&  .Pq Sq \&&
Line 301 
Line 315 
 where  where
 .Sq #  .Sq #
 is a digit, is replaced by the corresponding back-reference.  is a digit, is replaced by the corresponding back-reference.
 .It Ic popdef  .It Fn popdef arg ...
 Restores the  Restores the
 .Ic pushdef Ns ed  .Ic pushdef Ns ed
 definition for each argument.  definition for each argument.
 .It Ic pushdef  .It Fn pushdef macro def
 Takes the same arguments as  Takes the same arguments as
 .Ic define ,  .Ic define ,
 but it saves the definition on a  but it saves the definition on a
 stack for later retrieval by  stack for later retrieval by
 .Ic popdef .  .Fn popdef .
 .It Ic regexp  .It Fn regexp string regexp replacement
 Finds a regular expression in a string.  Finds a regular expression in a string.
 If no further arguments are given,  If no further arguments are given,
 it returns the first match position or \-1 if no match.  it returns the first match position or \-1 if no match.
 If a third argument  If a third argument
 is provided, it returns the replacement string, with sub-patterns replaced.  is provided, it returns the replacement string, with sub-patterns replaced.
 .It Ic shift  .It Fn shift arg1 ...
 Returns all but the first argument, the remaining arguments are  Returns all but the first argument, the remaining arguments are
 quoted and pushed back with commas in between.  quoted and pushed back with commas in between.
 The quoting  The quoting
 nullifies the effect of the extra scan that will subsequently be  nullifies the effect of the extra scan that will subsequently be
 performed.  performed.
 .It Ic sinclude  .It Fn sinclude file
 Similar to  Similar to
 .Ic include ,  .Ic include ,
 except it ignores any errors.  except it ignores any errors.
 .It Ic spaste  .It Fn spaste file
 Similar to  Similar to
 .Ic paste ,  .Fn paste ,
 except it ignores any errors.  except it ignores any errors.
 .It Ic substr  .It Fn substr string offset length
 Returns a substring of the first argument starting at the offset specified  Returns a substring of the first argument starting at the offset specified
 by the second argument and the length specified by the third argument.  by the second argument and the length specified by the third argument.
 If no third argument is present it returns the rest of the string.  If no third argument is present it returns the rest of the string.
 .It Ic syscmd  .It Fn syscmd cmd
 Passes the first argument to the shell.  Passes the first argument to the shell.
 Nothing is returned.  Nothing is returned.
 .It Ic sysval  .It Ic sysval
 Returns the return value from the last  Returns the return value from the last
 .Ic syscmd .  .Ic syscmd .
 .It Ic traceon  .It Fn traceon arg ...
 Enables tracing of macro expansions for the given arguments, or for all  Enables tracing of macro expansions for the given arguments, or for all
 macros if no argument is given.  macros if no argument is given.
 .It Ic traceoff  .It Fn traceoff arg ...
 Disables tracing of macro expansions for the given arguments, or for all  Disables tracing of macro expansions for the given arguments, or for all
 macros if no argument is given.  macros if no argument is given.
 .It Ic translit  .It Fn translit string mapfrom mapto
 Transliterate the characters in the first argument from the set  Transliterate the characters in the first argument from the set
 given by the second argument to the set given by the third.  given by the second argument to the set given by the third.
 You cannot use  You cannot use
 .Xr tr 1  .Xr tr 1
 style abbreviations.  style abbreviations.
 .It Ic undefine  .It Fn undefine name1 ...
 Removes the definition for the macros specified by its arguments.  Removes the definition for the macros specified by its arguments.
 .It Ic undivert  .It Fn undivert arg ...
 Flushes the named output queues (or all queues if no arguments).  Flushes the named output queues (or all queues if no arguments).
 .It Ic unix  .It Ic unix
 A pre-defined macro for testing the OS platform.  A pre-defined macro for testing the OS platform.
Legend:
Removed from v.1.35  
changed lines
  Added in v.1.36