1 12/02/85  pl1_macro, pmac
  2 
  3 Syntax as a command:  pmac in_path {out_path} {-control_args}
  4 
  5 
  6 Function: invokes the stand-alone pl1 macro processor to translate a
  7 segment in accordance with the defined pl1 macro language.
  8 
  9 
 10 Arguments:
 11 in_path
 12    is the pathname of the source segment.  The source segment name must
 13    have at least three components, a suffix of "pmac", and a
 14    penultimate component of "pl1" or "cds" or "rd".  If you don't
 15    supply the suffix, it is assumed.  The star convention is not
 16    supported.
 17 out_path
 18    is the pathname of the macro processed output segment.  If you
 19    haven't used -print or -process_dir, then the name of the inpath
 20    less the suffix is assumed if not given.  The outpath cannot be the
 21    same segment as the inpath.  The equal convention is not supported.
 22    This argument is incompatible with -print and -process_dir.
 23 
 24 
 25 Control arguments:
 26 -arguments STRs, -ag STRs
 27    passes the strings as command line arguments.  It must be the last
 28    control argument, and at least one STR must follow.  These arguments
 29    are used in conjuntion with the %isarg macro construct (see "Notes
 30    on command line argument testing" below).
 31 -call STR
 32    calls STR as a command after the translation is complete if the
 33    macro processor does not discover an error.
 34 -no_version, -nver
 35    does not print the version of pl1_macro.
 36 
 37 
 38 -parameter IDENTIFIER VALUE, -pm IDENTIFIER VALUE
 39    sets the value of macro replacement identifiers on the command line.
 40    IDENTIFIER must be a pl1 identifier; VALUE, a decimal integer, a bit
 41    string constant, a character constant, or an identifier.  (See
 42    "Notes on command line constants and their defaults.")
 43 -print, -pr
 44    prints the macro processed output on user_output rather than place
 45    it in a segment.
 46 -process_dir, -pd
 47    places the macro processed output in the process directory rather
 48    than in your working directory.
 49 
 50 
 51 -target STR, -tgt STR
 52    makes the macro processor interpret STR as a target machine and sets
 53    the %target builtin (see "Notes on code for different target
 54    machines").
 55 -version, -ver
 56    prints the version of pl1_macro.  (Default)
 57 
 58 
 59 List of macro constructs and builtin variables:
 60 %INCLUDE <identifier>;
 61    provides an expansion time include file feature.
 62 %INCLUDE <quoted-string>;
 63    provides an expansion time include file feature.
 64 %abort <char_string>;
 65    allows you to send messages to user_output at macro time and sets
 66    the minimum value of pl1_macro_severity_ to four.
 67 %default <identifier> to <constant-expression>;
 68    is ignored if the identifier has been used in a parameter statement;
 69    otherwise, causes the same substitution behavior as %replace.
 70 %error <char_string>;
 71    allows you to send messages to user_output at macro time and sets
 72    the minimum value of pl1_macro_severity_ to three.
 73 
 74 
 75 %if <constant-expression> %then <token-string>
 76    where <token-string> is a possibly null string of tokens and the
 77    <constant-expression>'s must evaluate to a bit_string constant.
 78 %isarg (<char_string>)
 79    is a macro builtin function that returns a value of data type bit
 80    (1).
 81 %isarg (<pl1-token>)
 82    is a macro builtin function that returns a value of data type bit
 83    (1).
 84 %isdef (<identifier>)
 85    is a macro builtin function that returns a value of data type bit
 86    (1).
 87 %print <char_string>;
 88    allows you to send messages to user_output at macro time and sets
 89    the minimum value of pl1_macro_severity_ to zero.
 90 
 91 
 92 %replace <identifier> by <constant-expression>
 93    where <constant-expression> is an expression whose operands are
 94    either constants or identifiers previously defined in other
 95    statements or on the command line.
 96 %set <identifier> to <constant-expression>
 97    is like %replace in the way it deals with replacement activity and
 98    constant expression evaluation, conflicts with parameters, etc.
 99 %target (<identifier>)
100    is a replacement identifier of data type bit (1) whose value is
101    true only if the value of the <identifier> is equal to the value of
102    the identifier given as the argument of -target on the command
103    line.
104 
105 
106 %warn <char_string>;
107    allows you to send messages to user_output at macro time and sets
108    the minimum value of pl1_macro_severity_ to one.
109 [%else <token-string>] %endif
110    where <token-string> is a possibly null string of tokens.
111 [%elseif <constant-expression> %then <token-string>]...
112    where <token-string> is a possibly null string of tokens and the
113    <constant-expression>'s must evaluate to a bit_string constant.
114 
115 
116 Notes on basic replacement construct: To facilitate the use of named
117 constants in places where internal static options (constant) don't
118 work (e.g., label arrays and functions of named constant), there are
119 three ways of defining replacement identifiers--pl1_identifiers that
120 are transformed at lex level to their defined values--by the %replace
121 statement, by the %set statement, and, on the command line, by the
122 %default statement.
123 
124 
125 Notes on macro time constants:
126    %replace <identifier> by <constant-expression>
127 where <constant-expression> is an expression whose operands are either
128 constants or identifiers previously defined in other statements or on
129 the command line.  The valid operators are the arithmetic ones (+, -,
130 *, and /) the concatenation operator (||), the logical operators (^, &,
131 and |), and the relational operators (=, ^=, <, <=, >, >=, ^>, and ^<).
132 Arithmetic values are represented internally as fixed binary (71).
133 Parentheses can be in all expressions.  The usual semantics of
134 expression evaluation apply, and pl1-like conversions are not done
135 implicitly.
136 
137 
138 Semantic Rules--
139    1. All replacement identifiers must be lexically declared by a
140       replace statement prior to use.
141    2. A replacement identifier may not appear lexically prior to its
142       declaration in a replace statement.  This is to insure that its
143       meaning remains constant throught the compilation unit.
144    3. Once declared, a replacement identifier may not be redefined to
145       have a different value by a replace statement, nor is there any
146       way to "undefine" a replacement identifier; however, to
147       facilitate replacement identifiers being used in a variety of
148       include files, redeclaration to the same value is permitted.
149 
150 
151    4. After its declaration, the replacement identifier is replaced
152       where it appears as a token in the lexed source by the value
153       defined in the replace statement.
154    5. Replacement identifiers have four data types: arithmetic, bit,
155       character, and identifier.  For all data types, operands must
156       agree with their operators.  The identifier data type is
157       associated with no operator except the = and ^= comparison.
158 
159 
160 Notes on macro time variables:
161    %set <identifier> to <constant-expression>
162 
163 The %set statement is like the %replace statement in the way it deals
164 with replacement activity and constant expression evaluation, conflicts
165 with parameters, etc.  The only difference is that the placement
166 identifier declared in an %set statement may appear in another %set
167 statement with a different value.  Its replacement rule is that it uses
168 the value set in the last %set statement (in the lexical sense).  The
169 use of variables in any two of %default, %replace, and %set statements
170 is not allowed.
171 
172 
173 Notes on command line constants and their defaults: The -parameter
174 control argument allows the virtual equivalent of a replacement
175 identifier declaration on the command line.
176 
177 The macro processor uses the replacement identifiers as though they had
178 been declared in %replace statements, with two important differences:
179 (1) these parameters must not be declared in the source in a %replace
180 statement, even to the same value; (2) they must be declared in a
181 %default statement.  If the same identifier appears in more than one
182 instance of a "-pm IDENTIFIER VALUE" triplet, the last such triplet
183 takes effect.
184 
185    %default <identifier> to <constant-expression>;
186 
187 
188 If the identifier has been used in a parameter statement, this
189 statement is ignored except to check that the data type of the constant
190 given in the command line and the data type of the expression in the
191 statement agree; otherwise, this statement causes the same substitution
192 behavior as a %replace statement.
193 
194 
195 Notes on macro variable declaration builtin:
196    %isdef (<identifier>)
197 is a macro builtin function that returns a value of data type bit (1).
198 Its value is true only if the argument is a macro replacement
199 identifier that you have lexically declared either in a %default, %set,
200 or %replace construct prior to using %isdef or as a command line
201 parameter.
202 
203 
204 Notes on command line argument testing:
205    %isarg (<pl1-token>)
206    %isarg (<char_string>)
207 is a macro builtin function that returns a value of data type bit (1).
208 Its value is true only if the argument is one of the character strings
209 following -arguments on the command line.
210 
211 The character string form of the argument is necessary if a command
212 line argument is a string according to the command processor, but is
213 not a pl1 token (e.g., 34xy).  If the argument to %isarg is a character
214 string, it is dequoted and the dequoted value is used in the test; for
215 example, if the command line has -ag 34xy, the test in the source must
216 be phrased as %isarg ("34xy"), rather than %isarg (34xy) because the
217 macro processor works on pl1 tokens.  So use only identifiers as
218 command line arguments, to facilitate more reasonable-looking code.
219 
220 
221 Notes on conditional compilation:
222    %if <constant-expression> %then <token-string>
223    [%elseif <constant-expression> %then <token-string>]...
224    [%else <token-string>] %endif
225 where <token-string> is a possibly null string of tokens and the
226 <constant-expression>'s must evaluate to a bit_string constant.
227 Semantic Rules--
228    1. The usual semantics of if-then-elseif-then-else statements apply.
229       If the boolean expression in the test clause equals ""b, then the
230       condition is false, otherwise it is true.  The %elseif and %else
231       terms are optional, but the %then and %endif keywords are
232       required.
233    2. The conditional compilation construct is invalid if all the
234       constant expressions do not evaluate to proper logical values.
235 
236 
237    3. There is no restriction on what may appear as the object
238       token-string of a then or else clause.  In particular it may be
239       standard pl1 tokens or further macro constructs such as %replace,
240       %include, etc.
241    4. In order to facilitate the maintainability of code, use the
242       conditional compilation facility to construct token strings that
243       comprise entire pl1 statments, rather than code fragments.
244 
245 
246 Notes on code for different target machines: there is a strategy for
247 informing translators which machine they should generate code for.
248 The macro processor also uses this same strategy for use in
249 conditional compilation.
250 
251    %target (<identifier>)
252 is a replacement identifier of data type bit (1) whose value is true
253 only if the value of the <identifier> is equal to the value of the
254 identifier given as the argument of -target on the command line.  If
255 you use %target without -target, a default value is supplied and an
256 error of severity 2 indicated.  If you don't use %target, then you need
257 supply no information on the command line about the target machine.
258 
259 
260 There are currently two flavors of target machines.  The names l68,
261 6180, and dps8 are cannonically equivalent and refer to the standard
262 Multics cpu's.
263 
264 
265 Notes on expansion time include files:
266    %INCLUDE <identifier>;
267    %INCLUDE <quoted-string>;
268 provides an expansion time include file feature.  Include files are
269 found through the translator search rules and have the same naming
270 conventions as compile time include files.  You are permitted a maximum
271 of 255 include files in one expansion, and you can nest them 64 deep.
272 This differs from %include in that the macro processor merely checks to
273 see that the %include statement is syntactically correct and outputs
274 the statement.
275 
276 
277 Notes on user-generated messages:
278    %print <char_string>;
279    %warn <char_string>;
280    %error <char_string>;
281    %abort <char_string>;
282 
283 The macro processor sets a severity, an external fixed binary (35)
284 variable, called pl1_macro_severity_.  These four constructs allow you
285 to send messages to user_output at macro time and set the minimum value
286 of pl1_macro_severity_ to zero, one, three, and four respectively.  The
287 %abort construct immediately aborts the macro_processor.  The
288 char_string can be generated as a result of macro time activity.
289 
290 
291 Notes on skip and page macros: These are features that the pl1
292 compiler accepts.  The macro processor checks them for syntactic
293 correctness and passes the statement through.