![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to m4.ms CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 17.m4|
Return to m4.ms CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 17.m4 |
1.1 ! root 1: .\" @(#)m4 6.1 (Berkeley) 5/8/86 ! 2: .\" ! 3: .EH 'PS1:17-%''The M4 Macro Processor' ! 4: .OH 'The M4 Macro Processor''PS1:17-%' ! 5: .if n .ls 2 ! 6: .tr _\(em ! 7: .tr *\(** ! 8: .de UC ! 9: \&\\$3\s-1\\$1\\s0\&\\$2 ! 10: .. ! 11: .de IT ! 12: .if n .ul ! 13: \&\\$3\f2\\$1\fP\&\\$2 ! 14: .. ! 15: .de UL ! 16: .if n .ul ! 17: \&\\$3\f3\\$1\fP\&\\$2 ! 18: .. ! 19: .de P1 ! 20: .DS I 3n ! 21: .if n .ls 2 ! 22: .nf ! 23: .if n .ta 5 10 15 20 25 30 35 40 45 50 55 60 ! 24: .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 ! 25: .if t .tr -\(mi|\(bv'\(fm^\(no*\(** ! 26: .tr `\(ga'\(aa ! 27: .if t .tr _\(ul ! 28: .ft 3 ! 29: .lg 0 ! 30: .. ! 31: .de P2 ! 32: .ps \\n(PS ! 33: .vs \\n(VSp ! 34: .ft R ! 35: .if n .ls 2 ! 36: .tr --||''^^!! ! 37: .if t .tr _\(em ! 38: .fi ! 39: .lg ! 40: .DE ! 41: .if t .tr _\(em ! 42: .. ! 43: .hw semi-colon ! 44: .hw estab-lished ! 45: .hy 14 ! 46: . \"2=not last lines; 4= no -xx; 8=no xx- ! 47: . \"special chars in programs ! 48: . \" start of text ! 49: .\".RP ! 50: .....TR 59 ! 51: .....TM 77-1273-6 39199 39199-11 ! 52: .ND "July 1, 1977" ! 53: .TL ! 54: The M4 Macro Processor ! 55: .AU "MH 2C-518" 6021 ! 56: Brian W. Kernighan ! 57: .AU "MH 2C-517" 3770 ! 58: Dennis M. Ritchie ! 59: .AI ! 60: .MH ! 61: .AB ! 62: .PP ! 63: M4 is a macro processor available on ! 64: .UX ! 65: and ! 66: .UC GCOS . ! 67: Its primary use has been as a ! 68: front end for Ratfor for those ! 69: cases where parameterless macros ! 70: are not adequately powerful. ! 71: It has also been used for languages as disparate as C and Cobol. ! 72: M4 is particularly suited for functional languages like Fortran, PL/I and C ! 73: since macros are specified in a functional notation. ! 74: .PP ! 75: M4 provides features seldom found even in much larger ! 76: macro processors, ! 77: including ! 78: .IP " \(bu" ! 79: arguments ! 80: .IP " \(bu" ! 81: condition testing ! 82: .IP " \(bu" ! 83: arithmetic capabilities ! 84: .IP " \(bu" ! 85: string and substring functions ! 86: .IP " \(bu" ! 87: file manipulation ! 88: .LP ! 89: .PP ! 90: This paper is a user's manual for M4. ! 91: .AE ! 92: .CS 6 0 6 0 0 1 ! 93: .if t .2C ! 94: .SH ! 95: Introduction ! 96: .PP ! 97: A macro processor is a useful way to enhance a programming language, ! 98: to make it more palatable ! 99: or more readable, ! 100: or to tailor it to a particular application. ! 101: The ! 102: .UL #define ! 103: statement in C ! 104: and the analogous ! 105: .UL define ! 106: in Ratfor ! 107: are examples of the basic facility provided by ! 108: any macro processor _ ! 109: replacement of text by other text. ! 110: .PP ! 111: The M4 macro processor is an extension of a macro processor called M3 ! 112: which was written by D. M. Ritchie ! 113: for the AP-3 minicomputer; ! 114: M3 was in turn based on a macro processor implemented for [1]. ! 115: Readers unfamiliar with the basic ideas of macro processing ! 116: may wish to read some of the discussion there. ! 117: .PP ! 118: M4 is a suitable front end for Ratfor and C, ! 119: and has also been used successfully with Cobol. ! 120: Besides the straightforward replacement of one string of text by another, ! 121: it provides ! 122: macros with arguments, ! 123: conditional macro expansion, ! 124: arithmetic, ! 125: file manipulation, ! 126: and some specialized string processing functions. ! 127: .PP ! 128: The basic operation of M4 ! 129: is to copy its input to its output. ! 130: As the input is read, however, each alphanumeric ``token'' ! 131: (that is, string of letters and digits) is checked. ! 132: If it is the name of a macro, ! 133: then the name of the macro is replaced by its defining text, ! 134: and the resulting string is pushed back onto the ! 135: input to be rescanned. ! 136: Macros may be called with arguments, in which case the arguments are collected ! 137: and substituted into the right places in the defining text ! 138: before it is rescanned. ! 139: .PP ! 140: M4 provides a collection of about twenty built-in ! 141: macros ! 142: which perform various useful operations; ! 143: in addition, the user can define new macros. ! 144: Built-ins and user-defined macros work exactly the same way, except that ! 145: some of the built-in macros have side effects ! 146: on the state of the process. ! 147: .SH ! 148: Usage ! 149: .PP ! 150: On ! 151: .UC UNIX , ! 152: use ! 153: .P1 ! 154: m4 [files] ! 155: .P2 ! 156: Each argument file is processed in order; ! 157: if there are no arguments, or if an argument ! 158: is `\-', ! 159: the standard input is read at that point. ! 160: The processed text is written on the standard output, ! 161: which may be captured for subsequent processing with ! 162: .P1 ! 163: m4 [files] >outputfile ! 164: .P2 ! 165: On ! 166: .UC GCOS , ! 167: usage is identical, but the program is called ! 168: .UL \&./m4 . ! 169: .SH ! 170: Defining Macros ! 171: .PP ! 172: The primary built-in function of M4 ! 173: is ! 174: .UL define , ! 175: which is used to define new macros. ! 176: The input ! 177: .P1 ! 178: define(name, stuff) ! 179: .P2 ! 180: causes the string ! 181: .UL name ! 182: to be defined as ! 183: .UL stuff . ! 184: All subsequent occurrences of ! 185: .UL name ! 186: will be replaced by ! 187: .UL stuff . ! 188: .UL name ! 189: must be alphanumeric and must begin with a letter ! 190: (the underscore \(ul counts as a letter). ! 191: .UL stuff ! 192: is any text that contains balanced parentheses; ! 193: it may stretch over multiple lines. ! 194: .PP ! 195: Thus, as a typical example, ! 196: .P1 ! 197: define(N, 100) ! 198: ... ! 199: if (i > N) ! 200: .P2 ! 201: defines ! 202: .UL N ! 203: to be 100, and uses this ``symbolic constant'' in a later ! 204: .UL if ! 205: statement. ! 206: .PP ! 207: The left parenthesis must immediately follow the word ! 208: .UL define , ! 209: to signal that ! 210: .UL define ! 211: has arguments. ! 212: If a macro or built-in name is not followed immediately by `(', ! 213: it is assumed to have no arguments. ! 214: This is the situation for ! 215: .UL N ! 216: above; ! 217: it is actually a macro with no arguments, ! 218: and thus when it is used there need be no (...) following it. ! 219: .PP ! 220: You should also notice that a macro name is only recognized as such ! 221: if it appears surrounded by non-alphanumerics. ! 222: For example, in ! 223: .P1 ! 224: define(N, 100) ! 225: ... ! 226: if (NNN > 100) ! 227: .P2 ! 228: the variable ! 229: .UL NNN ! 230: is absolutely unrelated to the defined macro ! 231: .UL N , ! 232: even though it contains a lot of ! 233: .UL N 's. ! 234: .PP ! 235: Things may be defined in terms of other things. ! 236: For example, ! 237: .P1 ! 238: define(N, 100) ! 239: define(M, N) ! 240: .P2 ! 241: defines both M and N to be 100. ! 242: .PP ! 243: What happens if ! 244: .UL N ! 245: is redefined? ! 246: Or, to say it another way, is ! 247: .UL M ! 248: defined as ! 249: .UL N ! 250: or as 100? ! 251: In M4, ! 252: the latter is true _ ! 253: .UL M ! 254: is 100, so even if ! 255: .UL N ! 256: subsequently changes, ! 257: .UL M ! 258: does not. ! 259: .PP ! 260: This behavior arises because ! 261: M4 expands macro names into their defining text as soon as it possibly can. ! 262: Here, that means that when the string ! 263: .UL N ! 264: is seen as the arguments of ! 265: .UL define ! 266: are being collected, it is immediately replaced by 100; ! 267: it's just as if you had said ! 268: .P1 ! 269: define(M, 100) ! 270: .P2 ! 271: in the first place. ! 272: .PP ! 273: If this isn't what you really want, there are two ways out of it. ! 274: The first, which is specific to this situation, ! 275: is to interchange the order of the definitions: ! 276: .P1 ! 277: define(M, N) ! 278: define(N, 100) ! 279: .P2 ! 280: Now ! 281: .UL M ! 282: is defined to be the string ! 283: .UL N , ! 284: so when you ask for ! 285: .UL M ! 286: later, you'll always get the value of ! 287: .UL N ! 288: at that time ! 289: (because the ! 290: .UL M ! 291: will be replaced by ! 292: .UL N ! 293: which will be replaced by 100). ! 294: .SH ! 295: Quoting ! 296: .PP ! 297: The more general solution is to delay the expansion of ! 298: the arguments of ! 299: .UL define ! 300: by ! 301: .ul ! 302: quoting ! 303: them. ! 304: Any text surrounded by the single quotes \(ga and \(aa ! 305: is not expanded immediately, but has the quotes stripped off. ! 306: If you say ! 307: .P1 ! 308: define(N, 100) ! 309: define(M, `N') ! 310: .P2 ! 311: the quotes around the ! 312: .UL N ! 313: are stripped off as the argument is being collected, ! 314: but they have served their purpose, and ! 315: .UL M ! 316: is defined as ! 317: the string ! 318: .UL N , ! 319: not 100. ! 320: The general rule is that M4 always strips off ! 321: one level of single quotes whenever it evaluates ! 322: something. ! 323: This is true even outside of ! 324: macros. ! 325: If you want the word ! 326: .UL define ! 327: to appear in the output, ! 328: you have to quote it in the input, ! 329: as in ! 330: .P1 ! 331: `define' = 1; ! 332: .P2 ! 333: .PP ! 334: As another instance of the same thing, which is a bit more surprising, ! 335: consider redefining ! 336: .UL N : ! 337: .P1 ! 338: define(N, 100) ! 339: ... ! 340: define(N, 200) ! 341: .P2 ! 342: Perhaps regrettably, the ! 343: .UL N ! 344: in the second definition is ! 345: evaluated as soon as it's seen; ! 346: that is, it is ! 347: replaced by ! 348: 100, so it's as if you had written ! 349: .P1 ! 350: define(100, 200) ! 351: .P2 ! 352: This statement is ignored by M4, since you can only define things that look ! 353: like names, but it obviously doesn't have the effect you wanted. ! 354: To really redefine ! 355: .UL N , ! 356: you must delay the evaluation by quoting: ! 357: .P1 ! 358: define(N, 100) ! 359: ... ! 360: define(`N', 200) ! 361: .P2 ! 362: In M4, ! 363: it is often wise to quote the first argument of a macro. ! 364: .PP ! 365: If \` and \' are not convenient for some reason, ! 366: the quote characters can be changed with the built-in ! 367: .UL changequote : ! 368: .P1 ! 369: changequote([, ]) ! 370: .P2 ! 371: makes the new quote characters the left and right brackets. ! 372: You can restore the original characters with just ! 373: .P1 ! 374: changequote ! 375: .P2 ! 376: .PP ! 377: There are two additional built-ins related to ! 378: .UL define . ! 379: .UL undefine ! 380: removes the definition of some macro or built-in: ! 381: .P1 ! 382: undefine(`N') ! 383: .P2 ! 384: removes the definition of ! 385: .UL N . ! 386: (Why are the quotes absolutely necessary?) ! 387: Built-ins can be removed with ! 388: .UL undefine , ! 389: as in ! 390: .P1 ! 391: undefine(`define') ! 392: .P2 ! 393: but once you remove one, you can never get it back. ! 394: .PP ! 395: The built-in ! 396: .UL ifdef ! 397: provides a way to determine if a macro is currently defined. ! 398: In particular, M4 has pre-defined the names ! 399: .UL unix ! 400: and ! 401: .UL gcos ! 402: on the corresponding systems, so you can ! 403: tell which one you're using: ! 404: .P1 ! 405: ifdef(`unix', `define(wordsize,16)' ) ! 406: ifdef(`gcos', `define(wordsize,36)' ) ! 407: .P2 ! 408: makes a definition appropriate for the particular machine. ! 409: Don't forget the quotes! ! 410: .PP ! 411: .UL ifdef ! 412: actually permits three arguments; ! 413: if the name is undefined, the value of ! 414: .UL ifdef ! 415: is then the third argument, as in ! 416: .P1 ! 417: ifdef(`unix', on UNIX, not on UNIX) ! 418: .P2 ! 419: .SH ! 420: Arguments ! 421: .PP ! 422: So far we have discussed the simplest form of macro processing _ ! 423: replacing one string by another (fixed) string. ! 424: User-defined macros may also have arguments, so different invocations ! 425: can have different results. ! 426: Within the replacement text for a macro ! 427: (the second argument of its ! 428: .UL define ) ! 429: any occurrence of ! 430: .UL $n ! 431: will be replaced by the ! 432: .UL n th ! 433: argument when the macro ! 434: is actually used. ! 435: Thus, the macro ! 436: .UL bump , ! 437: defined as ! 438: .P1 ! 439: define(bump, $1 = $1 + 1) ! 440: .P2 ! 441: generates code to increment its argument by 1: ! 442: .P1 ! 443: bump(x) ! 444: .P2 ! 445: is ! 446: .P1 ! 447: x = x + 1 ! 448: .P2 ! 449: .PP ! 450: A macro can have as many arguments as you want, ! 451: but only the first nine are accessible, ! 452: through ! 453: .UL $1 ! 454: to ! 455: .UL $9 . ! 456: (The macro name itself is ! 457: .UL $0 , ! 458: although that is less commonly used.) ! 459: Arguments that are not supplied are replaced by null strings, ! 460: so ! 461: we can define a macro ! 462: .UL cat ! 463: which simply concatenates its arguments, like this: ! 464: .P1 ! 465: define(cat, $1$2$3$4$5$6$7$8$9) ! 466: .P2 ! 467: Thus ! 468: .P1 ! 469: cat(x, y, z) ! 470: .P2 ! 471: is equivalent to ! 472: .P1 ! 473: xyz ! 474: .P2 ! 475: .UL $4 ! 476: through ! 477: .UL $9 ! 478: are null, since no corresponding arguments were provided. ! 479: .PP ! 480: .PP ! 481: Leading unquoted blanks, tabs, or newlines that occur during argument collection ! 482: are discarded. ! 483: All other white space is retained. ! 484: Thus ! 485: .P1 ! 486: define(a, b c) ! 487: .P2 ! 488: defines ! 489: .UL a ! 490: to be ! 491: .UL b\ \ \ c . ! 492: .PP ! 493: Arguments are separated by commas, but parentheses are counted properly, ! 494: so a comma ``protected'' by parentheses does not terminate an argument. ! 495: That is, in ! 496: .P1 ! 497: define(a, (b,c)) ! 498: .P2 ! 499: there are only two arguments; ! 500: the second is literally ! 501: .UL (b,c) . ! 502: And of course a bare comma or parenthesis can be inserted by quoting it. ! 503: .SH ! 504: Arithmetic Built-ins ! 505: .PP ! 506: M4 provides two built-in functions for doing arithmetic ! 507: on integers (only). ! 508: The simplest is ! 509: .UL incr , ! 510: which increments its numeric argument by 1. ! 511: Thus to handle the common programming situation ! 512: where you want a variable to be defined as ``one more than N'', ! 513: write ! 514: .P1 ! 515: define(N, 100) ! 516: define(N1, `incr(N)') ! 517: .P2 ! 518: Then ! 519: .UL N1 ! 520: is defined as one more than the current value of ! 521: .UL N . ! 522: .PP ! 523: The more general mechanism for arithmetic is a built-in ! 524: called ! 525: .UL eval , ! 526: which is capable of arbitrary arithmetic on integers. ! 527: It provides the operators ! 528: (in decreasing order of precedence) ! 529: .DS ! 530: unary + and \(mi ! 531: ** or ^ (exponentiation) ! 532: * / % (modulus) ! 533: + \(mi ! 534: == != < <= > >= ! 535: ! (not) ! 536: & or && (logical and) ! 537: \(or or \(or\(or (logical or) ! 538: .DE ! 539: Parentheses may be used to group operations where needed. ! 540: All the operands of ! 541: an expression given to ! 542: .UL eval ! 543: must ultimately be numeric. ! 544: The numeric value of a true relation ! 545: (like 1>0) ! 546: is 1, and false is 0. ! 547: The precision in ! 548: .UL eval ! 549: is ! 550: 32 bits on ! 551: .UC UNIX ! 552: and 36 bits on ! 553: .UC GCOS . ! 554: .PP ! 555: As a simple example, suppose we want ! 556: .UL M ! 557: to be ! 558: .UL 2**N+1 . ! 559: Then ! 560: .P1 ! 561: define(N, 3) ! 562: define(M, `eval(2**N+1)') ! 563: .P2 ! 564: As a matter of principle, it is advisable ! 565: to quote the defining text for a macro ! 566: unless it is very simple indeed ! 567: (say just a number); ! 568: it usually gives the result you want, ! 569: and is a good habit to get into. ! 570: .SH ! 571: File Manipulation ! 572: .PP ! 573: You can include a new file in the input at any time by ! 574: the built-in function ! 575: .UL include : ! 576: .P1 ! 577: include(filename) ! 578: .P2 ! 579: inserts the contents of ! 580: .UL filename ! 581: in place of the ! 582: .UL include ! 583: command. ! 584: The contents of the file is often a set of definitions. ! 585: The value ! 586: of ! 587: .UL include ! 588: (that is, its replacement text) ! 589: is the contents of the file; ! 590: this can be captured in definitions, etc. ! 591: .PP ! 592: It is a fatal error if the file named in ! 593: .UL include ! 594: cannot be accessed. ! 595: To get some control over this situation, the alternate form ! 596: .UL sinclude ! 597: can be used; ! 598: .UL sinclude ! 599: (``silent include'') ! 600: says nothing and continues if it can't access the file. ! 601: .PP ! 602: It is also possible to divert the output of M4 to temporary files during processing, ! 603: and output the collected material upon command. ! 604: M4 maintains nine of these diversions, numbered 1 through 9. ! 605: If you say ! 606: .P1 ! 607: divert(n) ! 608: .P2 ! 609: all subsequent output is put onto the end of a temporary file ! 610: referred to as ! 611: .UL n . ! 612: Diverting to this file is stopped by another ! 613: .UL divert ! 614: command; ! 615: in particular, ! 616: .UL divert ! 617: or ! 618: .UL divert(0) ! 619: resumes the normal output process. ! 620: .PP ! 621: Diverted text is normally output all at once ! 622: at the end of processing, ! 623: with the diversions output in numeric order. ! 624: It is possible, however, to bring back diversions ! 625: at any time, ! 626: that is, to append them to the current diversion. ! 627: .P1 ! 628: undivert ! 629: .P2 ! 630: brings back all diversions in numeric order, and ! 631: .UL undivert ! 632: with arguments brings back the selected diversions ! 633: in the order given. ! 634: The act of undiverting discards the diverted stuff, ! 635: as does diverting into a diversion ! 636: whose number is not between 0 and 9 inclusive. ! 637: .PP ! 638: The value of ! 639: .UL undivert ! 640: is ! 641: .ul ! 642: not ! 643: the diverted stuff. ! 644: Furthermore, the diverted material is ! 645: .ul ! 646: not ! 647: rescanned for macros. ! 648: .PP ! 649: The built-in ! 650: .UL divnum ! 651: returns the number of the currently active diversion. ! 652: This is zero during normal processing. ! 653: .SH ! 654: System Command ! 655: .PP ! 656: You can run any program in the local operating system ! 657: with the ! 658: .UL syscmd ! 659: built-in. ! 660: For example, ! 661: .P1 ! 662: syscmd(date) ! 663: .P2 ! 664: on ! 665: .UC UNIX ! 666: runs the ! 667: .UL date ! 668: command. ! 669: Normally ! 670: .UL syscmd ! 671: would be used to create a file ! 672: for a subsequent ! 673: .UL include . ! 674: .PP ! 675: To facilitate making unique file names, the built-in ! 676: .UL maketemp ! 677: is provided, with specifications identical to the system function ! 678: .ul ! 679: mktemp: ! 680: a string of XXXXX in the argument is replaced ! 681: by the process id of the current process. ! 682: .SH ! 683: Conditionals ! 684: .PP ! 685: There is a built-in called ! 686: .UL ifelse ! 687: which enables you to perform arbitrary conditional testing. ! 688: In the simplest form, ! 689: .P1 ! 690: ifelse(a, b, c, d) ! 691: .P2 ! 692: compares the two strings ! 693: .UL a ! 694: and ! 695: .UL b . ! 696: If these are identical, ! 697: .UL ifelse ! 698: returns ! 699: the string ! 700: .UL c ; ! 701: otherwise it returns ! 702: .UL d . ! 703: Thus we might define a macro called ! 704: .UL compare ! 705: which compares two strings and returns ``yes'' or ``no'' ! 706: if they are the same or different. ! 707: .P1 ! 708: define(compare, `ifelse($1, $2, yes, no)') ! 709: .P2 ! 710: Note the quotes, ! 711: which prevent too-early evaluation of ! 712: .UL ifelse . ! 713: .PP ! 714: If the fourth argument is missing, it is treated as empty. ! 715: .PP ! 716: .UL ifelse ! 717: can actually have any number of arguments, ! 718: and thus provides a limited form of multi-way decision capability. ! 719: In the input ! 720: .P1 ! 721: ifelse(a, b, c, d, e, f, g) ! 722: .P2 ! 723: if the string ! 724: .UL a ! 725: matches the string ! 726: .UL b , ! 727: the result is ! 728: .UL c . ! 729: Otherwise, if ! 730: .UL d ! 731: is the same as ! 732: .UL e , ! 733: the result is ! 734: .UL f . ! 735: Otherwise the result is ! 736: .UL g . ! 737: If the final argument ! 738: is omitted, the result is null, ! 739: so ! 740: .P1 ! 741: ifelse(a, b, c) ! 742: .P2 ! 743: is ! 744: .UL c ! 745: if ! 746: .UL a ! 747: matches ! 748: .UL b , ! 749: and null otherwise. ! 750: .SH ! 751: String Manipulation ! 752: .PP ! 753: The built-in ! 754: .UL len ! 755: returns the length of the string that makes up its argument. ! 756: Thus ! 757: .P1 ! 758: len(abcdef) ! 759: .P2 ! 760: is 6, and ! 761: .UL len((a,b)) ! 762: is 5. ! 763: .PP ! 764: The built-in ! 765: .UL substr ! 766: can be used to produce substrings of strings. ! 767: .UL substr(s,\ i,\ n) ! 768: returns the substring of ! 769: .UL s ! 770: that starts at the ! 771: .UL i th ! 772: position ! 773: (origin zero), ! 774: and is ! 775: .UL n ! 776: characters long. ! 777: If ! 778: .UL n ! 779: is omitted, the rest of the string is returned, ! 780: so ! 781: .P1 ! 782: substr(`now is the time', 1) ! 783: .P2 ! 784: is ! 785: .P1 ! 786: ow is the time ! 787: .P2 ! 788: If ! 789: .UL i ! 790: or ! 791: .UL n ! 792: are out of range, various sensible things happen. ! 793: .PP ! 794: .UL index(s1,\ s2) ! 795: returns the index (position) in ! 796: .UL s1 ! 797: where the string ! 798: .UL s2 ! 799: occurs, or \-1 ! 800: if it doesn't occur. ! 801: As with ! 802: .UL substr , ! 803: the origin for strings is 0. ! 804: .PP ! 805: The built-in ! 806: .UL translit ! 807: performs character transliteration. ! 808: .P1 ! 809: translit(s, f, t) ! 810: .P2 ! 811: modifies ! 812: .UL s ! 813: by replacing any character found in ! 814: .UL f ! 815: by the corresponding character of ! 816: .UL t . ! 817: That is, ! 818: .P1 ! 819: translit(s, aeiou, 12345) ! 820: .P2 ! 821: replaces the vowels by the corresponding digits. ! 822: If ! 823: .UL t ! 824: is shorter than ! 825: .UL f , ! 826: characters which don't have an entry in ! 827: .UL t ! 828: are deleted; as a limiting case, ! 829: if ! 830: .UL t ! 831: is not present at all, ! 832: characters from ! 833: .UL f ! 834: are deleted from ! 835: .UL s . ! 836: So ! 837: .P1 ! 838: translit(s, aeiou) ! 839: .P2 ! 840: deletes vowels from ! 841: .UL s . ! 842: .PP ! 843: There is also a built-in called ! 844: .UL dnl ! 845: which deletes all characters that follow it up to ! 846: and including the next newline; ! 847: it is useful mainly for throwing away ! 848: empty lines that otherwise tend to clutter up M4 output. ! 849: For example, if you say ! 850: .P1 ! 851: define(N, 100) ! 852: define(M, 200) ! 853: define(L, 300) ! 854: .P2 ! 855: the newline at the end of each line is not part of the definition, ! 856: so it is copied into the output, where it may not be wanted. ! 857: If you add ! 858: .UL dnl ! 859: to each of these lines, the newlines will disappear. ! 860: .PP ! 861: Another way to achieve this, due to J. E. Weythman, ! 862: is ! 863: .P1 ! 864: divert(-1) ! 865: define(...) ! 866: ... ! 867: divert ! 868: .P2 ! 869: .SH ! 870: Printing ! 871: .PP ! 872: The built-in ! 873: .UL errprint ! 874: writes its arguments out on the standard error file. ! 875: Thus you can say ! 876: .P1 ! 877: errprint(`fatal error') ! 878: .P2 ! 879: .PP ! 880: .UL dumpdef ! 881: is a debugging aid which ! 882: dumps the current definitions of defined terms. ! 883: If there are no arguments, you get everything; ! 884: otherwise you get the ones you name as arguments. ! 885: Don't forget to quote the names! ! 886: .SH ! 887: Summary of Built-ins ! 888: .PP ! 889: Each entry is preceded by the ! 890: page number where it is described. ! 891: .DS ! 892: .tr '\'`\` ! 893: .ta .25i ! 894: 3 changequote(L, R) ! 895: 1 define(name, replacement) ! 896: 4 divert(number) ! 897: 4 divnum ! 898: 5 dnl ! 899: 5 dumpdef(`name', `name', ...) ! 900: 5 errprint(s, s, ...) ! 901: 4 eval(numeric expression) ! 902: 3 ifdef(`name', this if true, this if false) ! 903: 5 ifelse(a, b, c, d) ! 904: 4 include(file) ! 905: 3 incr(number) ! 906: 5 index(s1, s2) ! 907: 5 len(string) ! 908: 4 maketemp(...XXXXX...) ! 909: 4 sinclude(file) ! 910: 5 substr(string, position, number) ! 911: 4 syscmd(s) ! 912: 5 translit(str, from, to) ! 913: 3 undefine(`name') ! 914: 4 undivert(number,number,...) ! 915: .DE ! 916: .SH ! 917: Acknowledgements ! 918: .PP ! 919: We are indebted to Rick Becker, John Chambers, ! 920: Doug McIlroy, ! 921: and especially Jim Weythman, ! 922: whose pioneering use of M4 has led to several valuable improvements. ! 923: We are also deeply grateful to Weythman for several substantial contributions ! 924: to the code. ! 925: .SG ! 926: .SH ! 927: References ! 928: .LP ! 929: .IP [1] ! 930: B. W. Kernighan and P. J. Plauger, ! 931: .ul ! 932: Software Tools, ! 933: Addison-Wesley, Inc., 1976.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.