home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / cug / softt-7.lbr / MACRO.DQC / MACRO.DOC
Text File  |  1984-07-05  |  7KB  |  319 lines
  1. .bp 1
  2. .in 0
  3. .he 'MACRO (1)'10/1/79'MACRO (1)'
  4. .in 3
  5. .ti -3
  6. NAME
  7. .br
  8. macro - general-purpose macro processor
  9. .sp
  10. .ti -3
  11. SYNOPSIS
  12. .br
  13. macro [-0] [files...]
  14. .sp
  15. .ti -3
  16. DESCRIPTION
  17. .br
  18. Macro is a general-purpose macro processor.
  19. Macro reads the files and writes onto the standard output
  20. a new file with the macro definitions deleted and the macro
  21. references expanded.
  22. If no files are given, or the file "-" is specified, the standard
  23. input is read.
  24. .sp
  25. Macros permit the definition of
  26. symbolic constants so that subsequent
  27. occurrences of the constant are replaced by the defining
  28. string of characters.
  29. The general form of a macro definition is
  30. .sp
  31. .ce
  32. define(name,replacement text)
  33. .sp
  34. All subsequent occurrences of "name" in the file will be replaced
  35. by "replacement text".
  36. The placement of blanks in definitions is significant;
  37. they should only appear in the replacement
  38. text where desired.
  39. Upper and lower case letters are also significant.
  40. The replacement text may be more than one
  41. line long.
  42. However, when an entire macro definition is followed
  43. immediately by a newline,
  44. the newline is discarded.  This prevents extraneous blank lines
  45. from appearing in the output.
  46. .sp
  47. Nesting of definitions is allowed, as is recursion.
  48. .sp
  49. An elementary example of a macro is:
  50. .sp
  51. .ce
  52. define(EOF,-1)
  53. .sp
  54. Thereafter, all occurrences of "EOF" in the file would be replaced
  55. by "-1".
  56. .sp
  57. Macros with arguments may also be specified.
  58. Any occurrence in
  59. the replacement text of "$n", where n is between 1 and 9,
  60. will be replaced by the nth argument when the macro is actually
  61. called.
  62. For example,
  63. .sp
  64. .ti +10
  65. define(copen,$3 = open($1,$2)
  66. .ti +18
  67. if ($3 == ERR)
  68. .ti +21
  69. call cant($1)
  70. )
  71. .sp
  72. would define a macro that, when called
  73. by
  74. .sp
  75. .ce
  76. copen(name, READ, fd)
  77. .sp
  78. would expand into
  79. .in +10
  80. .nf
  81. fd = open(name,READ)
  82. if (fd == ERR)
  83. .ti +3
  84. call cant(name)
  85. .sp
  86. .fi
  87. .in -10
  88. If a macro definition refers to an argument that wasn't supplied,
  89. the "$n" will be ignored.
  90. "$0" refers to the name of the macro itself.
  91. If a character other
  92. than a digit follows "$",
  93. the "$" is taken literally.
  94. .sp
  95. Macros can be nested, and any macros encountered during argument
  96. collection are expanded immediately, unless they are surrounded
  97. by brackets "[]".
  98. That is, input surrounded by brackets is
  99. left absolutely alone, except that one level of [ and ] is
  100. stripped off.
  101. Thus it is possible to write the macro "d" as
  102. .sp
  103. .ce
  104. define(d,[define($1,$2)])
  105. .sp
  106. The replacement text for "d", protected by the brackets is
  107. literally "define($1,$2)" so one could say
  108. .sp
  109. .ce
  110. d(a,bc)
  111. .sp
  112. to define "a" as "bc".
  113. Brackets must also be used when it is desired to redefine
  114. a macro, e.g.
  115. .sp
  116. .in +25
  117. define(x,y)
  118. .br
  119. define(x,z)
  120. .sp
  121. .in -25
  122. would define "y" in the second line, instead of redefining "x".
  123. To avoid redefining "y", the operation must be expressed as
  124. .sp
  125. .in +25
  126. define(x,y)
  127. .br
  128. define([x],z)
  129. .sp
  130. .in -25
  131. Normally, brackets appearing outside any macro calls
  132. ("level 0" brackets) are
  133. .ul
  134. not
  135. removed, unless the -0 option is specified.
  136. .sp 2
  137. The following built-in macros are provided:
  138. .sp
  139. define(a,b)
  140. .br
  141. .in +5
  142. defines a to be b and returns the null string.
  143. .in -5
  144. .sp
  145. ifelse(a,b,c,d)
  146. .br
  147. .in +5
  148. returns c if a is identical to b and d otherwise.
  149. .in -5
  150. .sp
  151. incr(a)
  152. .br
  153. .in +5
  154. interprets a as an integer and returns a+1.
  155. .in -5
  156. .sp
  157. substr(a,b,c)
  158. .br
  159. .in +5
  160. returns a substring of "a" starting at character number
  161. b and extending for c characters.
  162. .in -5
  163. .sp
  164. len(a)
  165. .br
  166. .in +5
  167. returns the length of a.
  168. .in -5
  169. .sp
  170. includ(a)
  171. .br
  172. .in +5
  173. returns the contents of file a.
  174. .in -5
  175. .sp
  176. expr(a)
  177. .br
  178. .in +5
  179. returns the result of evaluating infix expression a.
  180. Operators in increasing order of precedence are
  181. as follows.  Parentheses may be used as usual.
  182. .br
  183. .sp
  184. .in +5
  185. .nf
  186. | &             logical OR and AND
  187. !               unary logical NOT
  188. == ^= <= < > >= arithmetic comparison (!= and ~= are
  189. .ti +16
  190. equivalent to ^=)
  191. + -             addition and subtraction
  192. * / %           multiplication, division, modulo (remainder)
  193. **              exponentiation
  194. + -             unaryáplus and negation
  195. .fi
  196. .sp
  197. .in -5
  198. Logical operators return 0 or 1 (false or true).
  199. .in -5
  200. .sp
  201. .ti -3
  202. FILES
  203. .br
  204. None
  205. .sp
  206. .ti -3
  207. SEE ALSO
  208. .br
  209. Kernighan and Plauger's "Software Tools", pages. 251-283
  210. .br
  211. ratfor
  212. .sp
  213. .ti -3
  214. DIAGNOSTICS
  215. .br
  216. arith evaluation stack overflow
  217. .in +5
  218. The max level of nested arithmetic expressions has been exceeded.
  219. The size is set by the MAXSTACK definition in the source code.
  220. .sp
  221. .in -5
  222. arg stack overflow
  223. .br
  224. .in +5
  225. The maximum number of total arguments has been exceeded;
  226. the size is set by the ARGSIZE definition in the source code.
  227. .in -5
  228. .sp
  229. call stack overflow
  230. .br
  231. .in +5
  232. The maximum level of nesting of definitions has been exceeded.
  233. The size is set by the CALLSIZE definition in the source code.
  234. .in -5
  235. .sp
  236. EOF in string
  237. .br
  238. .in +5
  239. An end-of-file has been encountered before a bracketed string has
  240. been terminated.
  241. .in -5
  242. .sp
  243. evaluation stack overflow
  244. .br
  245. .in +5
  246. The total number of characters permitted for
  247. name, definition, and arguments
  248. has been exceeded.
  249. Set by the EVALSIZE definition in the source code.
  250. .in -5
  251. .sp
  252. unexpected EOF
  253. .br
  254. .in +5
  255. An end-of-file was reached before the macro definition was terminated.
  256. .in -5
  257. .sp
  258. filename: can't open
  259. .br
  260. .in +5
  261. The indicated file could not be opened.
  262. .in -5
  263. .sp
  264. filename: can't includ
  265. .br
  266. .in +5
  267. The indicated file could not be included via the includ builtin.
  268. .in -5
  269. .sp
  270. includs nested too deeply
  271. .br
  272. .in +5
  273. Includ builtins were nested deeper than the system would
  274. allow.
  275. The number is determined by the MAXOFILES definition in the
  276. general symbols definition file.
  277. .in -5
  278. .sp
  279. expression: invalid infix expression
  280. .br
  281. .in +5
  282. There is a syntax error in the indicated infix expression as
  283. passed to the expr builtin.
  284. .in -5
  285. .sp
  286. too many characters pushed back
  287. .br
  288. .in +5
  289. A macro expansion is too large to be rescanned.
  290. The size is set by the BUFSIZE definition in the source code.
  291. .in -5
  292. .sp
  293. name: too many definitions
  294. .br
  295. .in +5
  296. The table space for macro definitions has been exhausted; this
  297. occurred upon the definition of the indicated macro.
  298. .in -5
  299. .sp
  300. token too long
  301. .br
  302. .in +5
  303. A name or symbol in the input was longer than the token buffer.
  304. Size is determined by the MAXTOK definition in the source code.
  305. .in -5
  306. .sp
  307. .ti -3
  308. AUTHORS
  309. .br
  310. Original by Kernighan and Plauger, with enhancements by
  311. David Hanson and friends (U. of Arizona) and Philip
  312. Scherrer (Stanford U.)
  313. .sp
  314. .ti -3
  315. BUGS/DEFICIENCIES
  316. .br
  317. This macro processor is incompatible with the one included
  318. in the ratfor preprocessor.
  319.