.if n .ls 2.tr _\(em.tr *\(**.de UC\&\\$3\s-1\\$1\\s0\&\\$2...de IT.if n .ul\&\\$3\f2\\$1\fP\&\\$2...de UL.if n .ul\&\\$3\f3\\$1\fP\&\\$2...de P1.DS I 3n.if n .ls 2.nf.if n .ta 5 10 15 20 25 30 35 40 45 50 55 60.if t .ta .4i .8i 1.2i 1.6i 2i 2.4i 2.8i 3.2i 3.6i 4i 4.4i 4.8i 5.2i 5.6i.if t .tr -\(mi|\(bv'\(fm^\(no*\(**.tr `\(ga'\(aa.if t .tr _\(ul.ft 3.lg 0...de P2.ps \\n(PS.vs \\n(VSp.ft R.if n .ls 2.tr --||''^^!!.if t .tr _\(em.fi.lg.DE.if t .tr _\(em...hw semi-colon.hw estab-lished.hy 14.		\"2=not last lines; 4= no -xx; 8=no xx-.		\"special chars in programs.	\" start of text.RP.....TR 59.....TM 77-1273-6 39199 39199-11.ND "July 1, 1977".TLThe M4 Macro Processor.AU "MH 2C-518" 6021Brian W. Kernighan.AU "MH 2C-517" 3770Dennis M. Ritchie.AI.MH.AB.PPM4 is a macro processor available on.UXand.UC GCOS .Its primary use has been as afront end for Ratfor for thosecases where parameterless macros are not adequately powerful.It has also been used for languages as disparate as C and Cobol.M4 is particularly suited for functional languages like Fortran, PL/I and Csince macros are specified in a functional notation..PPM4 provides features seldom found even in much largermacro processors, including.IP "  \(bu"arguments.IP "  \(bu"condition testing.IP "  \(bu"arithmetic capabilities.IP "  \(bu"string and substring functions.IP "  \(bu"file manipulation.LP.PPThis paper is a user's manual for M4..AE.CS 6 0 6 0 0 1.if t .2C.SHIntroduction.PPA macro processor is a useful way to enhance a programming language,to make it more palatableor more readable,or to tailor it to a particular application.The.UL #definestatement in Cand the analogous.UL definein Ratforare examples of the basic facility provided byany macro processor _replacement of text by other text..PPThe M4 macro processor is an extension of a macro processor called M3which was written by D. M. Ritchiefor the AP-3 minicomputer;M3 was in turn based on a macro processor implemented for [1].Readers unfamiliar with the basic ideas of macro processingmay wish to read some of the discussion there..PPM4 is a suitable front end for Ratfor and C,and has also been used successfully with Cobol.Besides the straightforward replacement of one string of text by another,it providesmacros with arguments,conditional macro expansion,arithmetic,file manipulation,and some specialized string processing functions..PPThe basic operation of M4is to copy its input to its output.As the input is read, however, each alphanumeric ``token''(that is, string of letters and digits) is checked.If it is the name of a macro,then the name of the macro is replaced by its defining text,and the resulting string is pushed back onto theinput to be rescanned.Macros may be called with arguments, in which case the arguments are collectedand substituted into the right places in the defining textbefore it is rescanned..PPM4 provides a collection of about twenty built-inmacroswhich perform various useful operations;in addition, the user can define new macros.Built-ins and user-defined macros work exactly the same way, except thatsome of the built-in macros have side effectson the state of the process..SHUsage.PPOn.UC UNIX ,use.P1m4 [files].P2Each argument file is processed in order;if there are no arguments, or if an argumentis `\-',the standard input is read at that point.The processed text is written on the standard output,which may be captured for subsequent processing with.P1m4 [files] >outputfile.P2On.UC GCOS ,usage is identical, but the program is called.UL \&./m4 ..SHDefining Macros.PPThe primary built-in function of M4is.UL define ,which is used to define new macros.The input.P1define(name, stuff).P2causes the string.UL nameto be defined as.UL stuff .All subsequent occurrences of.UL namewill be replaced by.UL stuff ..UL namemust be alphanumeric and must begin with a letter(the underscore \(ul counts as a letter)..UL stuffis any text that contains balanced parentheses;it may stretch over multiple lines..PPThus, as a typical example,.P1define(N, 100) ...if (i > N).P2defines.UL Nto be 100, and uses this ``symbolic constant'' in a later.UL ifstatement..PPThe left parenthesis must immediately follow the word.UL define ,to signal that.UL definehas arguments.If a macro or built-in name is not followed immediately by `(',it is assumed to have no arguments.This is the situation for.UL Nabove;it is actually a macro with no arguments,and thus when it is used there need be no (...) following it..PPYou should also notice that a macro name is only recognized as suchif it appears surrounded by non-alphanumerics.For example, in.P1define(N, 100) ...if (NNN > 100).P2the variable .UL NNNis absolutely unrelated to the defined macro.UL N ,even though it contains a lot of.UL N 's..PPThings may be defined in terms of other things.For example,.P1define(N, 100)define(M, N).P2defines both M and N to be 100..PPWhat happens if.UL Nis redefined?Or, to say it another way, is.UL M defined as.UL Nor as 100?In M4,the latter is true _.UL Mis 100, so even if.UL N subsequently changes,.UL Mdoes not..PPThis behavior arises becauseM4 expands macro names into their defining text as soon as it possibly can.Here, that means that when the string.UL Nis seen as the arguments of.UL defineare being collected, it is immediately replaced by 100;it's just as if you had said.P1define(M, 100).P2in the first place..PPIf this isn't what you really want, there are two ways out of it.The first, which is specific to this situation,is to interchange the order of the definitions:.P1define(M, N)define(N, 100).P2Now.UL Mis defined to be the string.UL N ,so when you ask for .UL Mlater, you'll always get the value of.UL N at that time(because the.UL Mwill be replaced by.UL Nwhich will be replaced by 100)..SHQuoting.PPThe more general solution is to delay the expansion ofthe arguments of.UL define by.ulquotingthem.Any text surrounded by the single quotes \(ga and \(aais not expanded immediately, but has the quotes stripped off.If you say.P1define(N, 100)define(M, `N').P2the quotes around the.UL Nare stripped off as the argument is being collected,but they have served their purpose, and .UL Mis defined asthe string.UL N ,not 100.The general rule is that M4 always strips offone level of single quotes whenever it evaluatessomething.This is true even outside ofmacros.If you want the word.UL defineto appear in the output,you have to quote it in the input,as in.P1	`define' = 1;.P2.PPAs another instance of the same thing, which is a bit more surprising,consider redefining.UL N :.P1define(N, 100) ...define(N, 200).P2Perhaps regrettably, the.UL Nin the second definition isevaluated as soon as it's seen;that is, it isreplaced by100, so it's as if you had written.P1define(100, 200).P2This statement is ignored by M4, since you can only define things that looklike names, but it obviously doesn't have the effect you wanted.To really redefine .UL N ,you must delay the evaluation by quoting:.P1define(N, 100) ...define(`N', 200).P2In M4,it is often wise to quote the first argument of a macro..PPIf \` and \' are not convenient for some reason,the quote characters can be changed with the built-in.UL changequote :.P1changequote([, ]).P2makes the new quote characters the left and right brackets.You can restore the original characters with just.P1changequote.P2.PPThere are two additional built-ins related to.UL define ..UL undefineremoves the definition of some macro or built-in:.P1undefine(`N').P2removes the definition of.UL N .(Why are the quotes absolutely necessary?)Built-ins can be removed with .UL undefine ,as in.P1undefine(`define').P2but once you remove one, you can never get it back..PPThe built-in .UL ifdefprovides a way to determine if a macro is currently defined.In particular, M4 has pre-defined the names.UL unixand.UL gcoson the corresponding systems, so you cantell which one you're using:.P1ifdef(`unix', `define(wordsize,16)' )ifdef(`gcos', `define(wordsize,36)' ).P2makes a definition appropriate for the particular machine.Don't forget the quotes!.PP.UL ifdefactually permits three arguments;if the name is undefined, the value of.UL ifdefis then the third argument, as in.P1ifdef(`unix', on UNIX, not on UNIX).P2.SHArguments.PPSo far we have discussed the simplest form of macro processing _replacing one string by another (fixed) string.User-defined macros may also have arguments, so different invocationscan have different results.Within the replacement text for a macro(the second argument of its.UL define )any occurrence of.UL $nwill be replaced by the .UL n thargument when the macrois actually used.Thus, the macro.UL bump ,defined as.P1define(bump, $1 = $1 + 1).P2generates code to increment its argument by 1:.P1bump(x).P2is.P1x = x + 1.P2.PPA macro can have as many arguments as you want,but only the first nine are accessible,through.UL $1to.UL $9 .(The macro name itself is.UL $0 ,although that is less commonly used.)Arguments that are not supplied are replaced by null strings,sowe can define a macro.UL catwhich simply concatenates its arguments, like this:.P1define(cat, $1$2$3$4$5$6$7$8$9).P2Thus.P1cat(x, y, z)