home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / sigm / vol280 / macro55.lbr / MACRO55.DOC < prev   
Encoding:
Text File  |  1986-06-11  |  8.8 KB  |  196 lines
  1. MACRO version 5.5, 26-May-85
  2.  
  3. Specifications:
  4.  
  5.      This macro processor resembles somewhat the one in Kernighan and Plauger's
  6. book Software Tools in Pascal.  However, some additions and modifications have
  7. been made to allow it to be used with text files as well as programs.  Many
  8. details of operation and implementation are also different.
  9.  
  10.      The macro processor scans its input file looking for macros.  A macro
  11. is defined by a command of the form:
  12.  
  13. %define(name,replacement)
  14.  
  15.      "Name" must contain only alphanumeric characters, and it must start with
  16. either a letter or a special character defined as MACROCHAR in the source
  17. (currently set to "%").  "Name" must not contain any embedded blanks.  Whenever
  18. "name" is encountered in the input file, separated from other text by blanks or
  19. by non-alphabetic characters, it will be replaced by the string "replacement".
  20.  
  21.      Macros are allowed to have up to ten arguments, which may be included in
  22. the replacement text by specifying them as $1, $2, etc. (a la Kernighan and
  23. Plauger).  If a carriage return immediately follows the end of a built-in that
  24. does not produce any output (such as %define) then the carriage return will not
  25. be written to the output file.  Thus, lines containing only %define or similar
  26. statements produce no output.  Text within special "quote" characters is copied
  27. literally to the output, without any macro expansions (the quote characters are
  28. stripped off).  The default quote characters are "{" and "}".
  29.  
  30.      If the statement "%capsok(on)" appears in the source before the definition
  31. of a macro, then the macro processor will recognize the macro regardless of
  32. whether the first letter of its name is lower- or upper-case. If the macro name
  33. is found in the input file with an initial capital letter, then the replacement
  34. text will also be made to have an initial capital letter.  If the macro appears
  35. with a small initial letter, the replacement text will also have a small
  36. initial letter.  Without the "%capsok" option, macro names in the source must
  37. exactly match the name in the definition (including case of all letters) in
  38. order for replacement to occur.  Note that the %capsok option is set at
  39. definition time, not at the time the macro is being evaluated.  This option can
  40. be selectively disabled for some some macros by setting "%capsok(off)".
  41.  
  42.      Other built-ins:
  43.  
  44. %append(filename)
  45.  
  46.      Following this command, all output from MACRO is tacked onto the end of
  47. the named file, instead of going to the normal output file. The file must
  48. already exist on the disk.
  49.  
  50. %divert(filename)
  51.  
  52.      Following this command, all output from MACRO is written to the file name
  53. given. If the file does not already exist on the disk, it is created.
  54.  
  55. %enddivert
  56.  
  57.      Marks the end of a diversion begun with %divert or %append, resumes
  58. writing to the standard output file.
  59.  
  60. %expr(expr)
  61.  
  62.      Causes the current value of "expr" to be written to the output
  63. file as a decimal number.  "Expr" is an expression consisting of
  64. register variables and/or integers (see %register for details).
  65.  
  66. %fill(on) or %fill(off)
  67.  
  68.      Allows or disables filling of text (default is off).  If filling is on, as
  69. many words are packed into output lines as will fit within the right and
  70. left margins (default 0 and 79).  MACRO is fairly sophisticated in its handling
  71. of hyphens, slashes etc.  "Hard hyphen" and "ghost hyphen" characters are
  72. recognized and treated appropriately (these can be changed with the %spchars
  73. built-in).  Lines beginning with a space or a word-processor command character
  74. (user-settable) will be output without filling.
  75.  
  76. %ifelse(a,b,c,d)
  77.  
  78.     If a=b, expands to c, otherwise expands to d.  The carriage return
  79. following this statement is suppressed if it produces no output.
  80.  
  81. %include(filename)
  82. %source(filename)
  83.  
  84.      Starts reading from "filename" instead of the original input file. Reading
  85. resumes from the input file after the end of file on "filename". "%source" is a
  86. synonym for "%include".
  87.  
  88. %macros(on) or %macros(off)
  89.  
  90.      Turns on and off expansion of macros.  Default is on.  If %macros(off)
  91. is specified, built-ins are still evaluated, but macros defined with
  92. %define statements are treated as text and output without replacement.
  93.  
  94. %margins(left,right)
  95.  
  96.      sets right and left margins
  97.  
  98. %quotes(char1,char2)
  99.  
  100.      sets quote characters to char1 (left) and char2 (right).
  101.  
  102. %register(#n,expr)
  103.  
  104.      Sets one of ten register variables (#0 to #9) to the value of "expr",
  105. which may be any expression containing register variables (prefixed by #),
  106. integer constants and the operations +, -, \ (integer division), *, and %
  107. (modulus).
  108.  
  109. %spchars(macrochar,argsym,sepsym,wcmdchar,hardhy,ghosthy)
  110.  
  111.      sets MACRO to recognize the following special characters:
  112.  
  113. macrochar       non-alphanumeric character, can start a macro name
  114.                 (default "%")
  115. argsym          identifies a macro argument in the replacement portion
  116.                 of a "%define" macro.  Default "$".
  117. sepsym          separator, can be used to set off a macro embedded within
  118.                 a word.  It will not be copied to the output.  Default "\".
  119. wcmdchar        word-processor command character.  Lines beginning with this
  120.                 character are not filled.  Default "^".
  121. hardhy          hard hyphen character, cannot be removed during filling as
  122.                 a regular hyphen can.  Default is Control-Underline.
  123. ghosthy         "ghost hyphen", may be embedded in words, is ignored by
  124.                 MACRO (but will be copied to the output, unless the word
  125.                 of which it is a part is a macro).  Default "&".
  126.  
  127. %trace(on) or %trace(off)
  128.  
  129.      If on, shows the expansion of each macro on the screen, plus other stats.
  130. Default is off.
  131.  
  132. %translit(char1,char2)
  133.  
  134.      Causes char1 to be replaced by char2 everywhere in the output. Ranges of
  135. characters can be specified for both char1 and char2: for example,
  136. "%translit(a-z,A-Z)" maps all lower-case characters to upper-case.  Trans-
  137. literation is always done after macro expansion.  Consequently, using %translit
  138. to redefine any of the special characters, such as argsym or sepsym (see under
  139. %spchars for list) does not affect the operation of MACRO-- the same
  140. characters are still recognized as special, and will be transliterated
  141. only if they are inside quotes or are otherwise part of a string that would
  142. normally appear in the output file.  If you want to specify the quote
  143. characters for either char1 or char2, I recommend the following way:
  144.  
  145. %quotes(",')       (set new quote characters)
  146. %translit("{',[)   (translit { to [)
  147. %quotes({,})       (reset old quote characters)
  148.  
  149. Known bugs/limitations:
  150.  
  151. 1.   A command of the form %define(x,x) or even %define(x,something x) causes
  152. an infinite loop.  To avoid this, if the replacement string contains the name
  153. string as a substring, enclose the replacement string in 2 layers of quotes
  154. (the first gets stripped off during definition, the second gets stripped off at
  155. evaluation time).  E.g.:
  156.  
  157. %define(very,{{very, very}})
  158.  
  159. 2.   Because macros are evaluated immediately as they are encountered, be
  160. careful about using built-ins inside of an %ifelse macro. E.g. the statement:
  161.  
  162. %ifelse(draft,true,%include(outline.txt))
  163.  
  164.      may cause an "argument too long" error, because MACRO will evaluate the
  165. %include macro and try to store the whole contents of "outline.txt" in its
  166. argument buffer (before even checking to see if draft=true!).  This problem can
  167. be avoided by putting quote characters around the %include macro. Similarly, a
  168. statement like:
  169.  
  170. %ifelse(draft,true,%trace(on))
  171.  
  172.      will always turn tracing on (because %trace is evaluated before %ifelse),
  173. unless the %trace macro is enclosed in quotes.
  174.  
  175. 3.   MACRO does not currently support nested %source, %divert or %append
  176. commands, but this may be added in a future version.  The hooks are in the
  177. program, it is just not implemented (or tested).
  178.  
  179. 4.   Tab characters (^I) in the input are copied directly to the output.  This
  180. will result in improperly spaced output if filling is enabled and the input
  181. file contains tabs.  It is recommended that input files not contain tabs if
  182. filling is to be used.
  183.  
  184. 5.   The input file should be in ASCII format (i.e. lines should end with a
  185. carriage return or line feed or both).  MACRO doesn't (yet) know what to do
  186. with WordStar-style "soft" carriage returns.
  187.  
  188. 6.   The text of all macros (name and replacement) is currently limited to
  189. 5500 characters.  The total length of all arguments in a single macro
  190. call must not exceed 500 characters.  Macros can be nested 15 deep.
  191. Input lines may be up to 132 characters long; output lines may be up to
  192. 160 characters.  All of these limitations are set by constants defined
  193. in file "MACRO1.PAS".
  194.  
  195.  
  196.