Annotation of src/usr.bin/m4/m4.1, Revision 1.21
1.21 ! aaron 1: .\" @(#) $OpenBSD: m4.1,v 1.20 2000/11/09 17:52:20 aaron Exp $
1.1 deraadt 2: .\"
3: .\"
4: .Dd January 26, 1993
1.5 aaron 5: .Dt M4 1
1.1 deraadt 6: .Os
7: .Sh NAME
8: .Nm m4
9: .Nd macro language processor
10: .Sh SYNOPSIS
11: .Nm m4
1.12 espie 12: .Op Fl g
1.1 deraadt 13: .Oo
14: .Fl D Ns Ar name Ns Op Ar =value
15: .Oc
16: .Op Fl U Ns Ar name
1.7 espie 17: .Op Fl I Ar dirname
1.1 deraadt 18: .Sh DESCRIPTION
19: The
20: .Nm m4
21: utility is a macro processor that can be used as a front end to any
22: language (e.g., C, ratfor, fortran, lex, and yacc).
23: .Nm m4
24: reads from the standard input and writes
25: the processed text to the standard output.
26: .Pp
1.8 espie 27: Macro calls have the form name(argument1[, argument2, ..., argumentN]).
1.1 deraadt 28: .Pp
29: There cannot be any space following the macro name and the open
1.10 aaron 30: parenthesis
31: .Pq Ql ( .
32: If the macro name is not followed by an open
1.5 aaron 33: parenthesis it is processed with no arguments.
1.1 deraadt 34: .Pp
35: Macro names consist of a leading alphabetic or underscore
1.9 espie 36: possibly followed by alphanumeric or underscore characters, e.g.,
1.10 aaron 37: valid macro names match the pattern
38: .Dq [a-zA-Z_][a-zA-Z0-9_]* .
1.1 deraadt 39: .Pp
1.10 aaron 40: In arguments to macros, leading unquoted space, tab, and newline
41: .Pq Ql \en
42: characters are ignored.
43: To quote strings, use left and right single
44: quotes (e.g.,
45: .Sq \ this is a string with a leading space ) .
46: You can change the quote characters with the
1.5 aaron 47: .Ic changequote
48: built-in macro.
1.9 espie 49: .Pp
1.12 espie 50: Most built-ins don't make any sense without arguments, and hence are not
1.9 espie 51: recognized as special when not followed by an open parenthesis.
1.1 deraadt 52: .Pp
53: The options are as follows:
1.20 aaron 54: .Bl -tag -width Ds
1.1 deraadt 55: .It Fl D Ns Ar name Ns Oo
56: .Ar =value
57: .Oc
58: Define the symbol
59: .Ar name
1.10 aaron 60: to have some value (or
61: .Dv NULL ) .
1.1 deraadt 62: .It Fl "U" Ns Ar "name"
63: Undefine the symbol
64: .Ar name .
1.7 espie 65: .It Fl I Ar "dirname"
1.15 aaron 66: Add directory
1.7 espie 67: .Ar dirname
68: to the include path.
1.12 espie 69: .It Fl g
1.13 aaron 70: Activate GNU-m4 compatibility mode.
1.15 aaron 71: In this mode, changequote with
1.12 espie 72: two empty parameters deactivates quotes, translit handles simple character
1.19 espie 73: ranges (e.g., a-z), regular expressions mimic emacs behavior,
74: and the number of diversions is unlimited.
1.17 aaron 75: .El
1.1 deraadt 76: .Sh SYNTAX
77: .Nm m4
1.10 aaron 78: provides the following built-in macros.
79: They may be redefined, losing their original meaning.
80: Return values are null unless otherwise stated.
1.1 deraadt 81: .Bl -tag -width changequotexxx
1.11 espie 82: .It Ic builtin
83: Calls a built-in by its name, overriding possible redefinitions.
1.5 aaron 84: .It Ic changecom
1.10 aaron 85: Change the start and end comment sequences.
86: The default is the pound sign
87: .Pq Ql #
88: and the newline character.
89: With no arguments comments are turned off.
90: The maximum length for a comment marker is five characters.
1.5 aaron 91: .It Ic changequote
1.1 deraadt 92: Defines the quote symbols to be the first and second arguments.
1.10 aaron 93: The symbols may be up to five characters long.
94: If no arguments are
1.1 deraadt 95: given it restores the default open and close single quotes.
1.5 aaron 96: .It Ic decr
1.10 aaron 97: Decrements the argument by 1.
98: The argument must be a valid numeric string.
1.5 aaron 99: .It Ic define
1.1 deraadt 100: Define a new macro named by the first argument to have the
1.10 aaron 101: value of the second argument.
102: Each occurrence of
103: .Ql $n
104: (where
105: .Ar n
106: is 0 through 9) is replaced by the
107: .Ar n Ns 'th
108: argument.
109: .Ql $0
110: is the name of the calling macro.
111: Undefined arguments are replaced by a null string.
112: .Ql $#
113: is replaced by the number of arguments;
114: .Ql $*
115: is replaced by all arguments comma separated;
116: .Ql $@
117: is the same as
118: .Ql $*
119: but all arguments are quoted against further expansion.
1.5 aaron 120: .It Ic defn
1.10 aaron 121: Returns the quoted definition for each argument.
122: This can be used to rename
1.1 deraadt 123: macro definitions (even for built-in macros).
1.5 aaron 124: .It Ic divert
1.1 deraadt 125: There are 10 output queues (numbered 0-9).
126: At the end of processing
127: .Nm m4
128: concatenates all the queues in numerical order to produce the
1.10 aaron 129: final output.
130: Initially the output queue is 0.
131: The divert
1.1 deraadt 132: macro allows you to select a new output queue (an invalid argument
133: passed to divert causes output to be discarded).
1.5 aaron 134: .It Ic divnum
1.1 deraadt 135: Returns the current output queue number.
1.5 aaron 136: .It Ic dnl
1.1 deraadt 137: Discard input characters up to and including the next newline.
1.5 aaron 138: .It Ic dumpdef
1.1 deraadt 139: Prints the names and definitions for the named items, or for everything
140: if no arguments are passed.
1.5 aaron 141: .It Ic errprint
1.1 deraadt 142: Prints the first argument on the standard error output stream.
1.18 espie 143: .It Ic esyscmd
144: Pass its first argument to a shell and returns the shell's standard output.
145: Note that the shell shares its standard input and standard error with
146: .Nm
1.5 aaron 147: .It Ic eval
1.1 deraadt 148: Computes the first argument as an arithmetic expression using 32-bit
1.10 aaron 149: arithmetic.
150: Operators are the standard C ternary, arithmetic, logical,
151: shift, relational, bitwise, and parentheses operators.
152: You can specify
153: octal, decimal, and hexadecimal numbers as in C.
154: The second argument (if any)
155: specifies the radix for the result and the third argument (if any)
156: specifies the minimum number of digits in the result.
1.5 aaron 157: .It Ic expr
158: This is an alias for
159: .Ic eval .
160: .It Ic ifdef
1.1 deraadt 161: If the macro named by the first argument is defined then return the second
1.10 aaron 162: argument, otherwise the third.
163: If there is no third argument, the value is
164: .Dv NULL .
165: The word
166: .Qq unix
167: is predefined.
1.5 aaron 168: .It Ic ifelse
169: If the first argument matches the second argument then
170: .Ic ifelse
171: returns
1.10 aaron 172: the third argument.
173: If the match fails the three arguments are
1.1 deraadt 174: discarded and the next three arguments are used until there is
1.10 aaron 175: zero or one arguments left, either this last argument or
176: .Dv NULL
177: is returned if no other matches were found.
1.5 aaron 178: .It Ic include
1.1 deraadt 179: Returns the contents of the file specified in the first argument.
1.7 espie 180: If the file is not found as is, look through the include path:
181: first the directories specified with
182: .Fl I
183: on the command line, then the environment variable
1.10 aaron 184: .Ev M4PATH ,
1.7 espie 185: as a colon-separated list of directories.
1.1 deraadt 186: Include aborts with an error message if the file cannot be included.
1.5 aaron 187: .It Ic incr
1.10 aaron 188: Increments the argument by 1.
189: The argument must be a valid numeric string.
1.5 aaron 190: .It Ic index
1.1 deraadt 191: Returns the index of the second argument in the first argument (e.g.,
1.10 aaron 192: .Ic index(the quick brown fox jumped, fox)
193: returns 16).
194: If the second
195: argument is not found index returns \-1.
1.11 espie 196: .It Ic indir
197: Indirectly calls the macro whose name is passed as the first arguments,
198: with the remaining arguments passed as first, ... arguments.
1.5 aaron 199: .It Ic len
1.10 aaron 200: Returns the number of characters in the first argument.
201: Extra arguments
1.1 deraadt 202: are ignored.
1.5 aaron 203: .It Ic m4exit
1.1 deraadt 204: Immediately exits with the return value specified by the first argument,
205: 0 if none.
1.5 aaron 206: .It Ic m4wrap
1.10 aaron 207: Allows you to define what happens at the final
208: .Dv EOF ,
209: usually for cleanup purposes (e.g.,
210: .Ic m4wrap("cleanup(tempfile)")
211: causes the macro cleanup to be
1.16 aaron 212: invoked after all other processing is done).
1.5 aaron 213: .It Ic maketemp
1.10 aaron 214: Translates the string
1.15 aaron 215: .Dq XXXXX
1.10 aaron 216: in the first argument with the current process
217: ID leaving other characters alone.
218: This can be used to create unique
1.1 deraadt 219: temporary file names.
1.5 aaron 220: .It Ic paste
1.1 deraadt 221: Includes the contents of the file specified by the first argument without
1.10 aaron 222: any macro processing.
223: Aborts with an error message if the file cannot be
1.1 deraadt 224: included.
1.11 espie 225: .It Ic patsubst
226: Substitutes a regular expression in a string with a replacement string.
227: Usual substitution patterns apply: an ampersand
1.15 aaron 228: .Pq Ql &
1.11 espie 229: is replaced by the string matching the regular expression.
230: The string
231: .Ql \e# ,
232: where
233: .Ql #
234: is a digit, is replaced by the corresponding back-reference.
1.5 aaron 235: .It Ic popdef
236: Restores the
237: .Ic pushdef Ns ed
238: definition for each argument.
239: .It Ic pushdef
240: Takes the same arguments as
241: .Ic define ,
242: but it saves the definition on a
243: stack for later retrieval by
244: .Ic popdef .
1.11 espie 245: .It Ic regexp
1.13 aaron 246: Finds a regular expression in a string.
247: If no further arguments are given,
1.14 aaron 248: it returns the first match position or \-1 if no match.
249: If a third argument
1.11 espie 250: is provided, it returns the replacement string, with sub-patterns replaced.
1.5 aaron 251: .It Ic shift
1.1 deraadt 252: Returns all but the first argument, the remaining arguments are
1.10 aaron 253: quoted and pushed back with commas in between.
254: The quoting
1.1 deraadt 255: nullifies the effect of the extra scan that will subsequently be
256: performed.
1.5 aaron 257: .It Ic sinclude
258: Similar to
259: .Ic include ,
260: except it ignores any errors.
261: .It Ic spaste
262: Similar to
263: .Ic paste ,
264: except it ignores any errors.
265: .It Ic substr
1.1 deraadt 266: Returns a substring of the first argument starting at the offset specified
267: by the second argument and the length specified by the third argument.
268: If no third argument is present it returns the rest of the string.
1.5 aaron 269: .It Ic syscmd
1.10 aaron 270: Passes the first argument to the shell.
271: Nothing is returned.
1.5 aaron 272: .It Ic sysval
273: Returns the return value from the last
274: .Ic syscmd .
275: .It Ic translit
1.1 deraadt 276: Transliterate the characters in the first argument from the set
1.10 aaron 277: given by the second argument to the set given by the third.
1.21 ! aaron 278: You cannot use
1.1 deraadt 279: .Xr tr 1
280: style abbreviations.
1.5 aaron 281: .It Ic undefine
1.1 deraadt 282: Removes the definition for the macro specified by the first argument.
1.5 aaron 283: .It Ic undivert
1.1 deraadt 284: Flushes the named output queues (or all queues if no arguments).
1.5 aaron 285: .It Ic unix
1.1 deraadt 286: A pre-defined macro for testing the OS platform.
1.11 espie 287: .It Ic __line__
288: Returns the current file's line number.
289: .It Ic __file__
290: Returns the current file's name.
1.1 deraadt 291: .El
1.21 ! aaron 292: .Sh AUTHORS
1.11 espie 293: Ozan Yigit <oz@sis.yorku.ca> and Richard A. O'Keefe (ok@goanna.cs.rmit.OZ.AU).
294: GNU-m4 compatibility extensions by Marc Espie <espie@cvs.openbsd.org>.
![[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