diff options
Diffstat (limited to 'static/inferno/man1/m4.1')
| -rw-r--r-- | static/inferno/man1/m4.1 | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/static/inferno/man1/m4.1 b/static/inferno/man1/m4.1 new file mode 100644 index 00000000..748aa275 --- /dev/null +++ b/static/inferno/man1/m4.1 @@ -0,0 +1,291 @@ +.TH M4 1 +.SH NAME +m4 \- macro processor +.SH SYNOPSIS +.B m4 +[ +.BI -p prefix +] +[ +.B -t +] +[ +.BI -D name = value +] [ +.BI -Q name = value +] [ +.BI -U name +] [ +.I file +\&... +] +.SH DESCRIPTION +.I M4 +is a general-purpose macro processor. +It copies text from each of the input +.I files +in order (or standard input by default), and writes the processed text to the standard output. +.PP +Macro calls +have the form +.IP +.IB name ( arg1,\ arg2,\ ...,\ argn ) +.PP +The `(' must immediately follow the name of the macro. +If a defined macro name is not followed by a `(', +it is deemed to have no arguments. +Leading unquoted blanks, tabs, and newlines are ignored while collecting arguments. +A comma within a nested parenthesis is part of an argument value, not an argument separator. +Potential macro names consist of alphabetic letters, Unicode characters, +digits, and underscore `\_', where the first character is not a digit. +.PP +Comments begin with the +.B # +character and extend to the end of that line; the characters in a comment are copied to the current +output stream unchanged. +The comment start and end sequences may be changed using the +.B changecom +call described below. +.PP +The left and right single quotes (ie, grave and acute accents \`\|\' ) are used to quote strings. +Because the left and right quotes are distinct, quoted strings may nest. +The value of a quoted string is the string stripped of the outermost quotes. +The left and right quote characters may be changed using the +.B changequote +call described below. +.PP +When +.I m4 +recognises a macro name, followed by a `(', it collects arguments up to a matching right parenthesis. +Macro evaluation proceeds normally during this collection, and the text produced by those macro calls +is interpreted exactly as if it had been in the original input stream (in place of the corresponding macro call). +Thus, any commas or right parentheses within the value of a nested +call are as effective as those in the original input text. +(Remember however that commas within +.I nested +parentheses are not argument separators.) +After argument collection, +the value of the macro is pushed back onto the input stream +and rescanned. +.PP +.I M4 +makes available the following built-in macros. +They may be redefined, but once this is done the original meaning is lost. +Their values are null unless otherwise stated. +.TF changequote +.TP +changecom +Change the starting and ending delimiters for subsequent comments to the first and second arguments. +If the second argument is missing or an empty string, comments will be ended by newline. +If there are no arguments, there are no comments. +.TP +changequote +Change quote characters to the first and second arguments. +.I Changequote +without arguments restores the original values of +.BR `\|' . +.TP +copydef +The second argument is installed with the value of the macro +named by the first argument, +which may be a built-in macro. +Typically both arguments are quoted to prevent too early expansion. +A macro can be renamed using +.B copydef +followed by +.BR undefine . +.TP +define +The second argument is installed as the value of the macro +named by the first argument. +When the macro is later called (expanded), +each occurrence in the replacement text of +.BI $ n, +where +.I n +is a digit, +is replaced by the +.IR n -th +argument of that macro call. +Argument 0 is the name of the macro; +missing arguments are replaced by the null string. +If the macro value is the same as its name, or the value is +.BR $0 , +the result is the macro name. +To prevent expansion of a name when redefining a macro, quote the first argument. +.TP +divert +.I M4 +maintains 10 output streams, +numbered 0-9. +The final output is the concatenation of the streams +in numerical order; +initially stream 0 is the current stream. +The +.I divert +macro changes the current output stream to its (digit-string) +argument. +Output diverted to a stream other than 0 through 9 +is discarded. +.TP +divnum +Returns the value of the current output stream. +.TP +dnl +Reads and discards characters up to and including the next newline. +.TP +dumpdef +Prints current names and definitions, +for the named items, or for all if no arguments are given. +.TP +errprint +Prints its argument +on the diagnostic output file. +.TP +eval +Evaluates its argument as an arithmetic expression, using 64-bit arithmetic, +and returns the result as a signed decimal integer. +The only literals are decimal integers. +Operators are those of Limbo: the binary operators +.BR || , +.BR && , +.BR | , +.BR ^ , +.BR & , +.BR "== !=" , +.BR "< > >= <=" , +.B "<< >>" +(arithmetic shifts), +.BR "+ -" , +.BR "* / %" , +.BR "**" " (power)"; +the unary operators +.BR + , +.BR - , +.BR ~ , +.BR ! ; +and parenthesis. +Operator precedence is the same as in Limbo. +Right shifts are signed. +.TP +ifdef +If the first argument is defined, the value is the second argument, otherwise the third. +If there is no third argument, the value is null. +The word +.B inferno +is predefined with +.RB ` inferno ' +as its replacement text. +.TP +ifelse +Has three or more arguments. +If the first argument is the same string as the second, +then the value is the third argument. +If not, the process is repeated with arguments 4, 5, 6 and so on, in groups of three. +If no match is found, the result is the remaining argument (not part of a group of three), +or null if none is present. +.TP +include +Returns the contents of the file named in the argument. +.TP +incr +Returns the value of its argument incremented by 1. +The value of the argument is calculated +by interpreting an initial digit-string as a decimal number. +.TP +index +Returns the position in its first argument where the second argument begins (zero origin), +or \-1 if the second argument does not occur. +.TP +len +Returns the number of characters in its argument. +.TP +maketemp +Returns its first argument after replacing any trailing XXXs by the current host name, process ID, and a unique letter. +Normally used to create unique temporary file names. +.TP +sinclude +The same as +.I include, +except that it +says nothing if the file is inaccessible. +.TP +substr +Returns a substring of its first argument. +The second argument is a zero origin +number selecting the first character; +the third argument indicates the length of the substring. +A missing third argument is taken to be large enough to extend to +the end of the first string. +.TP +syscmd +Runs the first argument as an +.IR sh (1) +command. +No value is returned. +Note that the output of a command can be redirected to a temporary file named by +.BR maketemp , +included, and then removed. +.TP +translit +Transliterates the characters in its first argument +from the set given by the second argument to the set given by the third. +No abbreviations are permitted. +.TP +undefine +Removes the definition of the macro named in its argument. +.TP +undivert +Causes immediate output of text from diversions named as +arguments, or all diversions if no argument. +Text may be undiverted into another diversion. +Undiverting discards the diverted text. +.PD +.PP +The +.B -p +option causes +.I m4 +to add the given prefix character to the names of predefined macros; +typically the +.I prefix +is a Unicode character, to reduce the chance of a clash with macro names in the input text. +The +.B -t +option produces a trace on standard error. +.PP +.I M4 +otherwise +interprets its command line options after installing the predefined macro set. +The +.B -D +option defines +.I name +as a macro with the given +.IR value ; +.B -Q +defines +.I name +as a macro with the given +.IR value +that is regarded as always quoted (ie, is never rescanned). +Neither +.B -D +nor +.B -Q +may change a predefined macro. +The +.B -U +option +.I undefines +the given macro +.IR name , +which may be one of the predefined macros. +.PP +.I M4 +in Inferno is more closely related to the original +.I m4 +in Seventh Edition UNIX than its more elaborate relatives in System V and POSIX. +.SH "SEE ALSO" +B. W. Kernighan and D. M. Ritchie, +.I The M4 Macro Processor |