1 10/17/84 pl1 Macro Language
2
3 Basic replacement construct: To facilitate the use of named constants
4 in places where internal static options constant don't work e.g.
5 label arrays and functions of named constant, there are three ways of
6 defining replacement identifiers--pl1_identifiers that are transformed
7 at lex level to their defined values--by the %replace statement, by the
8 %set statement, and, on the command line, by the %default statement.
9
10
11 Macro time constants:
12 %replace <identifier> by <constant-expression>
13 where <constant-expression> is an expression whose operands are either
14 constants or identifiers previously defined in other statements or on
15 the command line. The valid operators are the arithmetic ones + -
16 * and / the concatenation operator ||, the logical operators ^ &
17 and |, and the relational operators = ^= < <= > >= ^> and ^<.
18 arithmetic values are represented internally as fixed binary 71.
19 Parentheses can be in all expressions. The usual semantics of
20 expression evaluation apply, and pl1-like conversions are not done
21 implicitly.
22
23
24 Semantic rules--
25 1. All replacement identifiers must be lexically declared by a replace
26 statement prior to use.
27 2. A replacement identifier may not appear lexically prior to its
28 declaration in a replace statement. This is to insure that its
29 meaning remains constant throught the compilation unit.
30 3. Once declared, a replacement identifier may not be redefined to have
31 a different value by a replace statement, nor is there any way to
32 "undefine" a replacement identifier; however, to facilitate
33 replacement identifiers being used in a variety of include files,
34 redeclaration to the same value is permitted.
35
36
37 4. After its declaration, the replacement identifier is replaced where
38 it appears as a token in the lexed source by the value defined in
39 the replace statement.
40 5. Replacement identifiers have four data types: arithmetic, bit,
41 character, and identifier. For all data types, operands must agree
42 with their operators. The identifier data type is associated with
43 no operator except the = and ^= comparison.
44
45
46 Macro time variables:
47 %set <identifier> to <constant-expression>
48 The %set statement is like the %replace statement in the way it deals
49 with replacement activity and constant expression evaluation, conflicts
50 with parameters, etc. The only difference is that the placement
51 identifier declared in an %set statement may appear in another %set
52 statement with a different value. Its replacement rule is that it uses
53 the value set in the last %set statement in the lexical sense. The
54 use of variables in any two of %default, %replace, and %set statements
55 is not allowed.
56
57
58 Command line constants and their defaults: The -parameter control
59 argument allows the virtual equivalent of a replacement identifier
60 declaration on the command line.
61
62 The macro processor uses the replacement identifiers as though they
63 had been declared in %replace statements, with two important
64 differences: 1 these parameters must not be declared in the source
65 in a %replace statement, even to the same value; 2 they must be
66 declared in a %default statement. If the same identifier appears in
67 more than one instance of a "-pm identifier value" triplet, the last
68 such triplet takes effect.
69
70
71 %default <identifier> to <constant-expression>;
72 If the identifier has been used in a parameter statement, this
73 statement is ignored except to check that the data type of the
74 constant given in the command line and the data type of the expression
75 in the statement agree; otherwise, this statement causes the same
76 substitution behavior as a %replace statement.
77
78
79 Macro variable declaration builtin:
80 %isdef <identifier>
81 is a macro builtin function that returns a value of data type bit 1.
82 Its value is true only if the argument is a macro replacement
83 identifier that you have lexically declared either in a %default, %set,
84 or %replace construct prior to using %isdef or as a command line
85 parameter.
86
87
88 Command line argument testing:
89 %isarg <pl1-token>
90 %isarg <char_string>
91 is a macro builtin function that returns a value of data type bit 1.
92 Its value is true only if the argument is one of the character strings
93 following -arguments on the command line.
94
95 The character string form of the argument is necessary if a command
96 line argument is a string according to the command processor, but is
97 not a pl1 token e.G. 34xy. If the argument to %isarg is a character
98 string, it is dequoted and the dequoted value is used in the test; for
99 example, if the command line has -ag 34xy, the test in the source must
100 be phrased as %isarg "34xy", rather than %isarg 34xy because the
101 macro processor works on pl1 tokens. So use only identifiers as
102 command line arguments, to facilitate more reasonable-looking code.
103
104
105 Conditional compilation:
106 Syntax:
107 %if <constant-expression> %then <token-string>
108 %elseif <constant-expression> %then <token-string>...
109 %else <token-string> %endif
110 where <token-string> is a possibly null string of tokens and the
111 <constant-expression>'s must evaluate to a bit_string constant.
112
113
114 Semantic rules--
115 1. The usual semantics of if-then-elseif-then-else statements apply.
116 If the boolean expression in the test clause equals ""b, then the
117 condition is false, otherwise it is true. The %elseif and %else
118 terms are optional, but the %then and %endif keywords are required.
119 2. The conditional compilation construct is invalid if all the constant
120 expressions do not evaluate to proper logical values.
121 3. There is no restriction on what may appear as the object
122 token-string of a then or else clause. In particular it may be
123 garden-variety pl1 tokens or further macro constructs such as
124 %replace, %include, etc.
125 4. In order to facilitate the maintainability of code, use the
126 conditional compilation facility to construct token strings that
127 comprise entire pl1 statments, rather than code fragments.
128
129
130 Code for different target machines: There is a strategy for informing
131 translators which machine they should generate code for. The macro
132 processor also uses this same strategy for use in conditional
133 compilation.
134 %target <identifier>
135 is a replacement identifier of data type bit 1 whose value is true
136 only if the value of the <identifier> is equal to the value of the
137 identifier given as the argument of -target on the command line.
138
139 If you use %target without -target, a default value is supplied and an
140 error of severity 2 indicated.
141
142 If you don't use %target, then you need supply no information on the
143 command line about the target machine.
144
145
146 There are currently two flavors of target machines. The names l68,
147 6180, and dps8 are cannonically equivalent and refer to the
148 garden-variety multics cpu's. The names adp and orion are
149 cannonically equivalent and refer to the new, next-generation cpu.
150 These names are case insensitive.
151
152
153 Expansion time include files:
154 %INCLUDE <identifier>;
155 %INCLUDE <quoted-string>;
156 provides an expansion time include file feature. Include files are
157 found through the translator search rules and have the same naming
158 conventions as compile time include files. You are permitted a
159 maximum of 255 include files in one expansion, and you can nest them
160 64 deep. This differs from %include in that the macro processor
161 merely checks to see that the %include statement is syntactically
162 correct and outputs the statement.
163
164
165 User-generated messages:
166 %print <char_string>;
167 %warn <char_string>;
168 %error <char_string>;
169 %abort <char_string>;
170 The macro processor sets a severity, an external fixed binary 35
171 variable, called pl1_macro_severity_. These four constructs allow you
172 to send messages to user_output at macro time and set the minimum
173 value of pl1_macro_severity_ to zero, one, three, and four
174 respectively. The %abort construct immediately aborts the
175 macro_processor. The char_string can be generated as a result of
176 macro time activity.
177
178
179 Skip and page macros: These are features that the pl1 compiler
180 accepts. The macro processor checks them for syntactic correctness
181 and passes the statement through.