Return to m4.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / pgrm / m4

Annotation of 43BSDReno/pgrm/m4/m4.1, revision 1.1

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.