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