Annotation of src/usr.bin/m4/m4.1, Revision 1.1
1.1 ! deraadt 1: .\"
! 2: .\" @(#) $Id: m4.1,v 1.3 1993/10/30 00:28:46 glass Exp $
! 3: .\"
! 4: .Dd January 26, 1993
! 5: .Dt m4 1
! 6: .Os
! 7: .Sh NAME
! 8: .Nm m4
! 9: .Nd macro language processor
! 10: .Sh SYNOPSIS
! 11: .Nm m4
! 12: .Oo
! 13: .Fl D Ns Ar name Ns Op Ar =value
! 14: .Oc
! 15: .Op Fl U Ns Ar name
! 16: .Sh DESCRIPTION
! 17: The
! 18: .Nm m4
! 19: utility is a macro processor that can be used as a front end to any
! 20: language (e.g., C, ratfor, fortran, lex, and yacc).
! 21: .Nm m4
! 22: reads from the standard input and writes
! 23: the processed text to the standard output.
! 24: .Pp
! 25: Macro calls have the form name(argument1[, argument2, ...,] argumentN).
! 26: .Pp
! 27: There cannot be any space following the macro name and the open
! 28: parentheses '('. If the macro name is not followed by an open
! 29: parentheses it is processed with no arguments.
! 30: .Pp
! 31: Macro names consist of a leading alphabetic or underscore
! 32: possibly followed by alphanumeric or underscore characters, therefore
! 33: valid macro names match this pattern [a-zA-Z_][a-zA-Z0-9_]*.
! 34: .Pp
! 35: In arguments to macros, leading unquoted space, tab and newline
! 36: characters are ignored. To quote strings use left and right single
! 37: quotes (e.g., ` this is a string with a leading space'). You can change
! 38: the quote characters with the changequote built-in macro.
! 39: .Pp
! 40: The options are as follows:
! 41: .Bl -tag -width "-Dname[=value]xxx"
! 42: .It Fl D Ns Ar name Ns Oo
! 43: .Ar =value
! 44: .Oc
! 45: Define the symbol
! 46: .Ar name
! 47: to have some value (or NULL).
! 48: .It Fl "U" Ns Ar "name"
! 49: Undefine the symbol
! 50: .Ar name .
! 51: .El
! 52: .Sh SYNTAX
! 53: .Nm m4
! 54: provides the following built-in macros. They may be
! 55: redefined, loosing their original meaning.
! 56: Return values are NULL unless otherwise stated.
! 57: .Bl -tag -width changequotexxx
! 58: .It changecom
! 59: Change the start and end comment sequences. The default is
! 60: the pound sign `#' and the newline character. With no arguments
! 61: comments are turned off. The maximum length for a comment marker is
! 62: five characters.
! 63: .It changequote
! 64: Defines the quote symbols to be the first and second arguments.
! 65: The symbols may be up to five characters long. If no arguments are
! 66: given it restores the default open and close single quotes.
! 67: .It decr
! 68: Decrements the argument by 1. The argument must be a valid numeric string.
! 69: .It define
! 70: Define a new macro named by the first argument to have the
! 71: value of the second argument. Each occurrence of $n (where n
! 72: is 0 through 9) is replaced by the n'th argument. $0 is the name
! 73: of the calling macro. Undefined arguments are replaced by a
! 74: NULL string. $# is replaced by the number of arguments; $*
! 75: is replaced by all arguments comma separated; $@ is the same
! 76: as $* but all arguments are quoted against further expansion.
! 77: .It defn
! 78: Returns the quoted definition for each argument. This can be used to rename
! 79: macro definitions (even for built-in macros).
! 80: .It divert
! 81: There are 10 output queues (numbered 0-9).
! 82: At the end of processing
! 83: .Nm m4
! 84: concatenates all the queues in numerical order to produce the
! 85: final output. Initially the output queue is 0. The divert
! 86: macro allows you to select a new output queue (an invalid argument
! 87: passed to divert causes output to be discarded).
! 88: .It divnum
! 89: Returns the current output queue number.
! 90: .It dnl
! 91: Discard input characters up to and including the next newline.
! 92: .It dumpdef
! 93: Prints the names and definitions for the named items, or for everything
! 94: if no arguments are passed.
! 95: .It errprint
! 96: Prints the first argument on the standard error output stream.
! 97: .It eval
! 98: Computes the first argument as an arithmetic expression using 32-bit
! 99: arithmetic. Operators are the standard C ternary, arithmetic, logical,
! 100: shift, relational, bitwise, and parentheses operators. You can specify
! 101: octal, decimal, and hexadecimal numbers as in C. The second argument (if
! 102: any) specifies the radix for the result and the third argument (if
! 103: any) specifies the minimum number of digits in the result.
! 104: .It expr
! 105: This is an alias for eval.
! 106: .It ifdef
! 107: If the macro named by the first argument is defined then return the second
! 108: argument, otherwise the third. If there is no third argument,
! 109: the value is NULL. The word `unix' is predefined.
! 110: .It ifelse
! 111: If the first argument matches the second argument then ifelse returns
! 112: the third argument. If the match fails the three arguments are
! 113: discarded and the next three arguments are used until there is
! 114: zero or one arguments left, either this last argument or NULL is
! 115: returned if no other matches were found.
! 116: .It include
! 117: Returns the contents of the file specified in the first argument.
! 118: Include aborts with an error message if the file cannot be included.
! 119: .It incr
! 120: Increments the argument by 1. The argument must be a valid numeric string.
! 121: .It index
! 122: Returns the index of the second argument in the first argument (e.g.,
! 123: index(the quick brown fox jumped, fox) returns 16). If the second
! 124: argument is not found index returns -1.
! 125: .It len
! 126: Returns the number of characters in the first argument. Extra arguments
! 127: are ignored.
! 128: .It m4exit
! 129: Immediately exits with the return value specified by the first argument,
! 130: 0 if none.
! 131: .It m4wrap
! 132: Allows you to define what happens at the final EOF, usually for cleanup
! 133: purposes (e.g., m4wrap("cleanup(tempfile)") causes the macro cleanup to
! 134: invoked after all other processing is done.)
! 135: .It maketemp
! 136: Translates the string XXXXX in the first argument with the current process
! 137: ID leaving other characters alone. This can be used to create unique
! 138: temporary file names.
! 139: .It paste
! 140: Includes the contents of the file specified by the first argument without
! 141: any macro processing. Aborts with an error message if the file cannot be
! 142: included.
! 143: .It popdef
! 144: Restores the pushdef'ed definition for each argument.
! 145: .It pushdef
! 146: Takes the same arguments as define, but it saves the definition on a
! 147: stack for later retrieval by popdef.
! 148: .It shift
! 149: Returns all but the first argument, the remaining arguments are
! 150: quoted and pushed back with commas in between. The quoting
! 151: nullifies the effect of the extra scan that will subsequently be
! 152: performed.
! 153: .It sinclude
! 154: Similar to include, except it ignores any errors.
! 155: .It spaste
! 156: Similar to spaste, except it ignores any errors.
! 157: .It substr
! 158: Returns a substring of the first argument starting at the offset specified
! 159: by the second argument and the length specified by the third argument.
! 160: If no third argument is present it returns the rest of the string.
! 161: .It syscmd
! 162: Passes the first argument to the shell. Nothing is returned.
! 163: .It sysval
! 164: Returns the return value from the last syscmd.
! 165: .It translit
! 166: Transliterate the characters in the first argument from the set
! 167: given by the second argument to the set given by the third. You cannot
! 168: use
! 169: .Xr tr 1
! 170: style abbreviations.
! 171: .It undefine
! 172: Removes the definition for the macro specified by the first argument.
! 173: .It undivert
! 174: Flushes the named output queues (or all queues if no arguments).
! 175: .It unix
! 176: A pre-defined macro for testing the OS platform.
! 177: .El
! 178: .Sh AUTHOR
! 179: Ozan Yigit <oz@sis.yorku.ca> and Richard A. O'Keefe (ok@goanna.cs.rmit.OZ.AU)
![[BACK]](/icons/back.gif){kind=icon}
Return to m4.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / m4