![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to m4.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / pgrm / m4|
Return to m4.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / pgrm / m4 |
1.1 root 1: .\" Copyright (c) 1989, 1990 The Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" The code is derived from software contributed to Berkeley by
6: .\" Ozan Yigit.
7: .\"
8: .\" Redistribution and use in source and binary forms are permitted provided
9: .\" that: (1) source distributions retain this entire copyright notice and
10: .\" comment, and (2) distributions including binaries display the following
11: .\" acknowledgement: ``This product includes software developed by the
12: .\" University of California, Berkeley and its contributors'' in the
13: .\" documentation or other materials provided with the distribution and in
14: .\" all advertising materials mentioning features or use of this software.
15: .\" Neither the name of the University nor the names of its contributors may
16: .\" be used to endorse or promote products derived from this software without
17: .\" specific prior written permission.
18: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
19: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
20: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
21: .\"
22: .\" @(#)m4.1 6.6 (Berkeley) 7/24/90
23: .\"
24: .Dd July 24, 1990
25: .Dt M4 1
26: .Sh NAME
27: .Nm m4
28: .Nd macro language preprocessor for Ratfor and Pascal
29: .Sh SYNOPSIS
30: .Nm m4
31: .Op options
32: .Sh DESCRIPTION
33: .Nm M4
34: is a macro language
35: preprocessor
36: for Ratfor, Pascal, and similar languages which do not
37: have a built-in macro processing capability.
38: M4 reads standard input, and writes the results to the standard output.
39: .Pp
40: The options and their effects are as follows:
41: .Pp
42: .Tw _Dname[=Val]
43: .Tp Cx Fl D
44: .Ar name
45: .Op Ar \&=Val
46: .Cx
47: Defines
48: .Ar name
49: to
50: .Ar val
51: or to null in
52: the absence of
53: .Ar val .
54: .Tp Cx Fl U
55: .Ar name
56: .Cx
57: undefines
58: .Ar name .
59: .Tp
60: .Pp
61: The
62: .Nm m4
63: processor provides a kind of
64: .Nm C
65: like syntax and
66: some of the macro functions will
67: be familiar:
68: .Tw \&undiver
69: .Tp Ic define
70: .Ar define(name [, val])
71: .br
72: the second argument is installed as the value of the macro
73: whose name is the first argument. If there is no second argument,
74: the value is null.
75: Each occurrence of
76: .Cx Ic $
77: .Ar n
78: .Cx
79: in the replacement text,
80: where
81: .Ar n
82: is a digit,
83: is replaced by the
84: .Cx Ar n
85: .Cx \'th
86: .Cx
87: argument.
88: Argument 0 is the name of the macro;
89: missing arguments are replaced by the null string.
90: .Tp Ic defn
91: .Ar defn(name [, name ...])
92: .br
93: returns the quoted definition of its argument(s). Useful in renaming
94: macros.
95: .Tp Ic undefine
96: .Ar undefine(name [, name ...])
97: .br
98: removes the definition of the macro(s) named. If there is
99: more than one definition for the named macro, (due to previous use of
100: .Ic pushdef )
101: all definitions are removed.
102: .Tp Ic pushdef
103: .Ar pushdef(name [, val])
104: .br
105: like
106: .Ic define ,
107: but saves any previous definition by stacking the current definition.
108: .Tp Ic popdef
109: .Ar popdef(name [, name ...])
110: .br
111: removes current definition of its argument(s),
112: exposing the previous one if any.
113: .Tp Ic ifdef
114: .Ar ifdef(name, if-def [, ifnot-def])
115: .br
116: if the first argument is defined, the value is the second argument,
117: otherwise the third.
118: If there is no third argument, the value is null.
119: .Tp Ic shift
120: .Ar shift(arg, arg, arg, ...)
121: .br
122: returns all but its first argument.
123: The other arguments are quoted and pushed back with
124: commas in between.
125: The quoting nullifies the effect of the extra scan that
126: will subsequently be performed.
127: .Tp Ic changequote
128: .Ar changequote(lqchar, rqchar)
129: .br
130: change quote symbols to the first and second arguments.
131: With no arguments, the quotes are reset back to the default
132: characters. (i.e., \*`\\*').
133: .Tp Ic changecom
134: .Ar changecom(lcchar, rcchar)
135: .br
136: change left and right comment markers from the default
137: .Ic #
138: and
139: .Ic newline .
140: With no arguments, the comment mechanism is reset back to
141: the default characters.
142: With one argument, the left marker becomes the argument and
143: the right marker becomes newline.
144: With two arguments, both markers are affected.
145: .Tp Ic divert
146: .Ar divert(divnum)
147: .br
148: .Nm m4
149: maintains 10 output streams,
150: numbered 0-9. initially stream 0 is the current stream.
151: The
152: .Ic divert
153: macro changes the current output stream to its (digit-string)
154: argument.
155: Output diverted to a stream other than 0 through 9
156: disappears into bitbucket.
157: .Tp Ic undivert
158: .Ar undivert([divnum [, divnum ...])
159: .br
160: causes immediate output of text from diversions named as
161: argument(s), or all diversions if no argument.
162: Text may be undiverted into another diversion.
163: Undiverting discards the diverted text. At the end of input processing,
164: .Nm M4
165: forces an automatic
166: .Ic undivert ,
167: unless
168: .Ic m4wrap
169: is defined.
170: .Tp Ic divnum
171: .Ar divnum()
172: .br
173: returns the value of the current output stream.
174: .Tp Ic dnl
175: .Ar dnl()
176: .br
177: reads and discards characters up to and including the next newline.
178: .Tp Ic ifelse
179: .Ar ifelse(arg, arg, if-same [, ifnot-same \&| arg,\ arg\ ...])
180: .br
181: has three or more arguments.
182: If the first argument is the same string as the second,
183: then the value is the third argument.
184: If not, and if there are more than four arguments, the process is
185: repeated with arguments 4, 5, 6 and 7.
186: Otherwise, the value is either the fourth string, or, if it is not present,
187: null.
188: .Tp Ic incr
189: .Ar incr(num)
190: .br
191: returns the value of its argument incremented by 1.
192: The value of the argument is calculated
193: by interpreting an initial digit-string as a decimal number.
194: .Tp Ic decr
195: .Ar decr(num)
196: .br
197: returns the value of its argument decremented by 1.
198: .Tp Ic eval
199: .Ar eval(expression)
200: .br
201: evaluates its argument as a constant expression, using integer arithmetic.
202: The evaluation mechanism is very similar to that of
203: .Xr cpp
204: (#if expression).
205: The expression can involve only integer constants and character constants,
206: possibly connected by the binary operators
207: .Ds I
208: * / % + - >> << < >
209: <= >= == != & ^ &&
210: .De
211: or the unary operators
212: .Ic \&~ \&!
213: or by the ternary operator
214: .Ic \&? \&: .
215: Parentheses may be used for grouping. Octal numbers may be specified as
216: in C.
217: .Tp Ic len
218: .Ar len(string)
219: .br
220: returns the number of characters in its argument.
221: .Tp Ic index
222: .Ar index(search-string, string)
223: .br
224: returns the position in its first argument where the second argument
225: begins (zero origin),
226: or \-1 if the second argument does not occur.
227: .Tp Ic substr
228: .Ar substr(string, index [, length])
229: .br
230: returns a substring of its first argument.
231: The second argument is a zero origin
232: number selecting the first character (internally treated as an expression);
233: the third argument indicates the length of the substring.
234: A missing third argument is taken to be large enough to extend to
235: the end of the first string.
236: .Tp Ic translit
237: .Ar translit(source, from [, to])
238: .br
239: transliterates the characters in its first argument
240: from the set given by the second argument to the set given by the third.
241: If the third argument is shorter than the second, all extra characters
242: in the second argument are deleted from the first argument. If the third
243: argument is missing altogether, all characters in the second argument are
244: deleted from the first argument.
245: .Tp Ic include
246: .Ar include(filename)
247: .br
248: returns the contents of the file named in the argument.
249: .Tp Ic sinclude
250: .Ar sinclude(filename)
251: .br
252: is identical to
253: .Ic include ,
254: except that it
255: says nothing if the file is inaccessible.
256: .Tp Ic paste
257: .Ar paste(filename)
258: .br
259: returns the contents of the file named in the argument without any
260: processing, unlike
261: .Ic include .
262: .Tp Ic spaste
263: .Ar spaste(filename)
264: .br
265: is identical to
266: .Ic paste ,
267: except that it says nothing if the file is inaccessible.
268: .Tp Ic syscmd
269: .Ar syscmd(command)
270: .br
271: executes the
272: UNIX
273: command given in the first argument.
274: No value is returned.
275: .Tp Ic sysval
276: .Ar sysval()
277: .br
278: is the return code from the last call to
279: .Ic syscmd .
280: .Tp Ic maketemp
281: .Ar maketemp(string)
282: .br
283: fills in a string of
284: XXXXXX
285: in its argument with the current process
286: ID.
287: .Tp Ic m4exit
288: .Ar m4exit([exitcode])
289: .br
290: causes immediate exit from
291: .Nm m4 .
292: Argument 1, if given, is the exit code;
293: the default is 0.
294: .Tp Ic m4wrap
295: .Ar m4wrap(m4-macro-or-built-in)
296: .br
297: argument 1 will be pushed back at final
298: .Ic EOF ;
299: .Dl example: m4wrap(`dumptable()').
300: .Tp Ic errprint
301: .Ar errprint(str [, str, str, ...])
302: .br
303: prints its argument(s) on stderr. If there is more than one argument,
304: each argument is separated by a space during the output.
305: .Tp Ic dumpdef
306: .Ar dumpdef([name, name, ...])
307: .br
308: prints current names and definitions,
309: for the named items, or for all if no arguments are given.
310: .Tp
311: .Sh AUTHOR
312: Ozan S. Yigit (oz)
313: .Sh BUGS
314: A sufficiently complex M4 macro set is about as readable
315: as
316: .Ar APL .
317: .Pp
318: All complex uses of M4 require the ability to program in deep recursion.
319: Previous lisp experience is recommended.
320: .Sh EXAMPLES
321: The following macro program illustrates the type of things that
322: can be done with M4.
323: .Pp
324: .Ds I
325: changequote(<,>) define(HASHVAL,99) dnl
326: define(hash,<expr(str(substr($1,1),0)%HASHVAL)>) dnl
327: define(str,
328: <ifelse($1,",$2,
329: \t<str(substr(<$1>,1),<expr($2+'substr($1,0,1)')>)>)
330: >) dnl
331: define(KEYWORD,<$1,hash($1),>) dnl
332: define(TSTART,
333: <struct prehash {
334: char *keyword;
335: int hashval;
336: } keytab[] = {>) dnl
337: define(TEND,< "",0
338: };>)
339: dnl
340: .De
341: .Pp
342: Thus a keyword table containing the keyword string and its pre-calculated
343: hash value may be generated thus:
344: .Pp
345: .Ds I
346: TSTART
347: KEYWORD("foo")
348: KEYWORD("bar")
349: KEYWORD("baz")
350: TEND
351: .De
352: .Pp
353: which will expand into:
354: .Pp
355: .Ds I
356: struct prehash {
357: char *keyword;
358: int hashval;
359: } keytab[] = {
360: "foo",27,
361: "bar",12,
362: "baz",20,
363: "",0
364: };
365: .De
366: .Pp
367: Presumably, such a table would speed up the installation of the
368: keywords into a dynamic hash table. (Note that the above macro
369: cannot be used with
370: .Nm m4 ,
371: since
372: .Ic eval
373: does not handle character constants.)
374: .Sh SEE ALSO
375: .Xr cc 1 ,
376: .Xr cpp 1 .
377: .Xr m4 1
378: .br
379: .Em The M4 Macro Processor
380: by B. W. Kernighan and D. M. Ritchie.
381: .Sh HISTORY
382: .Nm M4
383: command appeared in Version 7 AT&T UNIX. The
384: .Nm m4
385: command this page describes is derived from code
386: contributed by Ozan S. Yigit.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.