1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
<HTML>
<!--
***********************************************************************
FUNNELWEB MANUAL WEB PAGE
=========================
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
Permission is granted to redistribute and use this manual in
any medium, with or without modification, provided that all
notices (including, without limitation, the copyright
notice, this permission notice, any record of modification,
and all legal notices) are preserved on all copies, that all
modifications are clearly marked, and that modified versions
are not represented as the original version unless all the
modifications since the manual's original release by Ross N.
Williams (www.ross.net) consist of translations or other
transformations that alter only the manual's form, not its
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
LAW THERE IS ABSOLUTELY NO WARRANTY.
***********************************************************************
-->
<HEAD>
<TITLE>4.8 Macros</TITLE>
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
</HEAD>
<BODY BACKGROUND="binary/background.gif"
BGCOLOR="#FFFFFF"
TEXT="#000000"
VLINK="#660000"
LINK="#FF0000"
ALINK="#CC0000">
<TABLE WIDTH="490">
<TR>
<TD WIDTH="130" VALIGN="top">
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
<FONT SIZE="2">
<BR>
<A HREF="http://www.ross.net/"
TARGET="rosshome"
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/rossnet_logo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="RossNet"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<A HREF="../index.shtml"
TARGET="funnelweb"
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/linklogo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="FunnelWeb"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
<A HREF="../tutorial/index.html"
TARGET="funnelwebtutorial"
onClick="window.open('','funnelwebtutorial','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
<BR>
<A HREF="../developer/index.html"
TARGET="funnelwebdeveloper"
onClick="window.open('','funnelwebdeveloper','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
<BR>
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
<A HREF="interface.html"><FONT COLOR="#FFFFFF">2 Interface</FONT></A><BR>
<A HREF="scanner.html"><FONT COLOR="#FFFFFF">3 Scanner</FONT></A><BR>
<A HREF="parser.html"><FONT COLOR="#FFFFFF">4 Parser</FONT></A><BR>
<A HREF="analyser.html"><FONT COLOR="#FFFFFF">5 Analyser</FONT></A><BR>
<A HREF="tangle.html"><FONT COLOR="#FFFFFF">6 Tangle</FONT></A><BR>
<A HREF="weave.html"><FONT COLOR="#FFFFFF">7 Weave</FONT></A><BR>
<A HREF="shell.html"><FONT COLOR="#FFFFFF">8 Shell</FONT></A><BR>
<A HREF="commands.html"><FONT COLOR="#FFFFFF">9 Commands</FONT></A><BR>
<A HREF="glossary.html"><FONT COLOR="#FFFFFF">10 Glossary</FONT></A><BR>
<A HREF="references.html"><FONT COLOR="#FFFFFF">11 References</FONT></A><BR>
<BR>
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
</FONT>
</TD></TR></TABLE>
</TD>
<TD WIDTH="360" VALIGN="top">
<FONT SIZE="3">
<A HREF="index.html"><IMG SRC="binary/title.gif"
WIDTH="316" HEIGHT="24"
BORDER="0" ALT="FunnelWeb Reference Manual"
HSPACE="0" VSPACE="0"></A>
<P><FONT SIZE="5">4.8 Macros</FONT><BR>
<P>The third category of construct appearing at the
highest syntactic level in a FunnelWeb input file is the
macro definition. A macro definition binds a unique
<STRONG>macro name</STRONG> to a <STRONG>macro body</STRONG>
containing an <STRONG>expression</STRONG> consisting of text,
calls to other macros, and formal parameters. The syntax for
a macro definition is as follows:
<P>
<PRE>
macro = ("@O" | "@$") name [formal_parameter_list]
["@Z"] ["@M"] { "@L" } ["==" | "+="]
"@{" expression "@}"
</PRE>
<P>The complexity of the macro definition syntax is mostly
to enable the user to attach various attributes to the
macro. If the user chooses
<SAMP>@O</SAMP>, then the macro cannot be called, but is
instead attached to a product file. If the user chooses
<SAMP>@$</SAMP>, then the macro is an ordinary macro definition
that is not attached to a file. Here are some example macro
definitions.
<P>
<PRE>
@O@<example.txt@>@{This is an @<ugly duckling@>.@}
@$@<ugly duckling@>@M@{swan@}
</PRE>
<P><BR><FONT SIZE="4"><STRONG>Number Of Invocations Constraint</STRONG></FONT><BR>
<P>By default, a non-file macro must be invoked exactly
once by one other macro. Macros that aren't are flagged with
errors by the FunnelWeb analyser. However, if the user uses
the <SAMP>@Z</SAMP> sequence in the macro
definition, the macro is then permitted to be invoked zero
times, as well as once. Similarly, if the user uses the
<SAMP>@M</SAMP> sequence in the macro definition,
the macro is permitted to be called many times as well as
once. If both <SAMP>@Z</SAMP> and <SAMP>@M</SAMP> are present then
the macro is permitted to be invoked zero, one, or many
times.
<P>The purpose of enforcing the default "exactly
one call" rule is to flag pieces of code that the user may
have defined in a macro but not hooked into the rest of the
program. Experience shows that this is a common error.
Similarly, it can be dangerous to multiply invoke a macro
intended to be invoked only once. For example, it may be
dangerous to invoke a scrap of non-idempotent initialization
code in two different parts of the main function of a
program! However, FunnelWeb will not generate an error if a
macro without <SAMP>@M</SAMP> is called by another macro that
is called more than once.
<P><BR><FONT SIZE="4"><STRONG>Additive Macros</STRONG></FONT><BR>
<P>If the text string <SAMP>==</SAMP> (or nothing)
follows the macro name, the expression that follows is the
entire text of the macro body. If the text string
<SAMP>+=</SAMP> follows the macro name, then more
than one such definition is allowed (but not required) in
the document and the body of the macro consists of the
concatenation of all such expressions in the order in which
they occur in the input file. Such a macro is said to be
additive and is <STRONG>additively defined</STRONG>. Thus a
macro body can either be defined in one place using one
definition (using <SAMP>==</SAMP>) or it can be
<I>distributed</I> throughout the input file in a sequence
of one or more macro definitions (using <SAMP>+=</SAMP>). If
neither <SAMP>==</SAMP> and <SAMP>+=</SAMP> are present, FunnelWeb
assumes a default of <SAMP>==</SAMP>.
<P>Macros attached to product files cannot be additively
defined. Additively defined macros can have parameter lists
and <SAMP>@Z</SAMP> and <SAMP>@M</SAMP> attributes, but these must
be specified only in the first definition of the macro.
However, <SAMP>+=</SAMP> must appear in each definition.
<P><BR><FONT SIZE="4"><STRONG>Library Macros</STRONG></FONT><BR>
<P>An ordinary macro definition can have from zero to five
<SAMP>@L</SAMP> library level markers. These define the macro
definition's library level. A macro having a particular name
may be defined up to once at each library level, and each
such definition may be multipart (additive). At tangle time,
the definition having the lowest library level is used, with
all other definitions of the same name being completely
ignored. This feature allows the creation of general-purpose
include files that contain macro definitions that can be
overridden by definitions of the same name in the including
file. Similarly, it allows the creation of include files
containing macro definitions that override definitions in
the including file. How you use the library macro feature
is up to you.
<P>In the example below, the ugly duckling macro will
be expanded to <SAMP>swan</SAMP> because the swan definition
has the lowest library level.
<P>
<PRE>
@$@<ugly duckling@>@M@L@L@{egg@}
@$@<ugly duckling@>@M@{swan@}
@$@<ugly duckling@>@M@L@{signet@}
</PRE>
<P>Note that the library macro facility imposes no
requirement on the order of appearance of the various macros
of the same name; all that matters is the library level.
This means that macros defined in an include file that is
included at the <I>end</I> of a main file can be
overridden by macros appearing earlier in the main file.
<P>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left" VALIGN="bottom"><A HREF="parser_type_emphasis.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
<TD ALIGN="center" VALIGN="bottom"><A HREF="parser.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
<TD ALIGN="right" VALIGN="bottom"><A HREF="parser_macros_name.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
</TR>
</TABLE>
<P>
<HR>
<FONT SIZE="2">
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
</FONT>
</FONT>
</TD>
</TR>
</TABLE>
</FONT>
</BODY>
<!-- *********************************************************************** -->
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
<!-- *********************************************************************** -->
</HTML>
|
