4
***********************************************************************
5
FUNNELWEB MANUAL WEB PAGE
6
=========================
7
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
9
Permission is granted to redistribute and use this manual in
10
any medium, with or without modification, provided that all
11
notices (including, without limitation, the copyright
12
notice, this permission notice, any record of modification,
13
and all legal notices) are preserved on all copies, that all
14
modifications are clearly marked, and that modified versions
15
are not represented as the original version unless all the
16
modifications since the manual's original release by Ross N.
17
Williams (www.ross.net) consist of translations or other
18
transformations that alter only the manual's form, not its
19
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
20
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
21
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
22
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
23
LAW THERE IS ABSOLUTELY NO WARRANTY.
25
***********************************************************************
29
<TITLE>2.2 Number of Times Called</TITLE>
30
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
32
<BODY BACKGROUND="binary/background.gif"
41
<TD WIDTH="130" VALIGN="top">
42
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
47
<A HREF="http://www.ross.net/"
49
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
51
<IMG SRC="binary/rossnet_logo.gif"
52
WIDTH="64" HEIGHT="32"
53
BORDER="0" ALT="RossNet"
54
HSPACE="0" VSPACE="1"></A><BR>
57
<A HREF="../index.shtml"
59
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
61
<IMG SRC="binary/linklogo.gif"
62
WIDTH="64" HEIGHT="32"
63
BORDER="0" ALT="FunnelWeb"
64
HSPACE="0" VSPACE="1"></A><BR>
66
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
67
<A HREF="../reference/index.html"
68
TARGET="funnelwebreference"
69
onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
70
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
72
<A HREF="../developer/index.html"
73
TARGET="funnelwebdeveloper"
74
onClick="window.open('','funnelwebdeveloper','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
75
><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
77
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
78
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
79
<A HREF="macro.html"><FONT COLOR="#FFFFFF">2 Macros</FONT></A><BR>
80
<A HREF="type.html"><FONT COLOR="#FFFFFF">3 Typesetting</FONT></A><BR>
81
<A HREF="example.html"><FONT COLOR="#FFFFFF">4 Example</FONT></A><BR>
82
<A HREF="hints.html"><FONT COLOR="#FFFFFF">5 Hints</FONT></A><BR>
83
<A HREF="examples.html"><FONT COLOR="#FFFFFF">6 Examples</FONT></A><BR>
84
<A HREF="web.html"><FONT COLOR="#FFFFFF">7 Webmaking</FONT></A><BR>
87
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
93
<TD WIDTH="360" VALIGN="top">
97
<A HREF="../reference/index.html"><IMG SRC="binary/title.gif"
98
WIDTH="302" HEIGHT="24"
99
BORDER="0" ALT="FunnelWeb Tutorial Manual"
100
HSPACE="0" VSPACE="0"></A>
101
<P><FONT SIZE="5">2.2 Number of Times Called</FONT><BR>
105
<P>So far we have seen only tiny, degenerate input files.
106
The next example moves up to the level of "trivial",
107
but starts to convey the flavour of the way FunnelWeb can be
108
used in practice. Normally, there would be documentation
109
text appearing between the macros, but this has been omitted
110
so as to keep the focus on the macros themselves. Although
111
the next example is much longer than the previous example,
112
the only new construct is <SAMP>@-</SAMP> which can appear
113
only at the end of a line, and suppresses
114
it, preventing it from appearing
115
in the text. The <SAMP>@-</SAMP> construct allows
116
the text of a macro to be aligned at the left margin, rather
117
than having the first line hanging at the end of the
118
<SAMP>@{</SAMP>. FunnelWeb could have been set up so that
119
this end of line marker was suppressed. However, it would
120
have been a special case that would have broken the very
121
memorable rule "the text of a macro is the text
122
appearing between the <SAMP>@{</SAMP> and <SAMP>@}</SAMP>".
124
<P>Type the following text into the file
125
<SAMP>hello.fw</SAMP> and run it through FunnelWeb. The file
126
contains some intentional errors so be sure to type it in
127
exactly and worry only if FunnelWeb <I>doesn't</I>
128
generate some errors.
132
@O@<hello.c@>==@{@-
133
@<Include Files@>
134
@<Include Files@>
135
@<Main Program@>
138
@$@<Main Program@>==@{@-
145
@$@<Subroutine@>==@{@-
149
for (i=0;i<10;i++)
156
@$@<Print@>==@{@-
157
printf("Hello World!");
160
@$@<Scan@>==@{scanf@}
162
@$@<Include Files@>==@{@-
163
#include <stdio.h>
164
#include <stdlib.h>@}
167
<P>What happened? Well, if you haven't typed the file in
168
properly, you may get some miscellaneous syntax errors. Fix
169
these before continuing. If the file has been correctly
170
typed, you should be faced with some error messages to do
171
with the number of times some of the macros are called.
173
<P>By default, FunnelWeb insists that each macro defined
174
is invoked exactly once. However, the file above defines
175
macros that are used more than once and a macro that is not
176
used at all. Let us examine the errors.
178
<P>First, we see that FunnelWeb has alerted us to the fact
179
that the <SAMP>Include Files</SAMP> macro has been called
180
twice. Once alerted to this, a quick look at the program
181
convinces us that calling the macro twice is a mistake, and
182
that one of the calls should be deleted.
184
<P>Second, we note that FunnelWeb has alerted us to the
185
fact that the <SAMP>@<subroutine@></SAMP> macro
186
is never called. Again, a quick look at the program tells us
187
that this is a mistake (and a very common one in the use of
188
FunnelWeb), and that a call to the
189
<SAMP>@<subroutine@></SAMP> macro should be
190
inserted just above the call to the <SAMP>@<Main
191
Program@></SAMP> macro in the definition of
192
<SAMP>@<hello.c@></SAMP>.
194
<P>These two cases demonstrate why these checks have been
195
placed in FunnelWeb. It is nearly always acceptable for a
196
macro to be called once. However, if a macro is not called
197
at all, or called more than once, this is often a sign that
198
the user has made a mistake.
200
<P>These checks have a dark side too. In addition to the
201
errors mentioned above, FunnelWeb has generated two similar
202
errors that do not help us.
204
<P>First, we are alerted to the fact that the
205
<SAMP>@<print@></SAMP> macro has been called
206
twice. Clearly, in this case, this is not a problem, and so
207
here FunnelWeb's fussiness is a nuisance.
209
<P>Second, we are alerted to the fact that the
210
<SAMP>@<scan@></SAMP> macro has never been
211
called. Like the <SAMP>@<print@></SAMP> macro,
212
this macro was defined as a notational convenience, and
213
clearly it does not matter here if it is not used. Again,
214
FunnelWeb is being a nuisance.
216
<P>The four cases above demonstrate the light and dark
217
side of FunnelWeb's insistence that each macro be called
218
exactly once. To resolve the conflict without reducing the
219
strength of the checking, FunnelWeb provides two special
220
sequences <SAMP>@Z</SAMP> (for <STRONG>Z</STRONG>ero) and <SAMP>@M</SAMP>
221
(for <STRONG>M</STRONG>any) that can be attached to macro definitions.
222
Presence of the <SAMP>@Z</SAMP> tag
223
allows the designated macro to be called zero times.
224
Presence of the <SAMP>@M</SAMP> tag
225
allows the designated macro to be called more than once. A
226
single macro may carry both tags. It is always true that all
227
macros are allowed to be called exactly once.
229
<P>Here is the revised program with the errors fixed, by
230
eliminating or adding macro calls, or by adding tags. Try
231
processing the file now. There should be no errors.
235
@O@<hello.c@>==@{@-
236
@<Include Files@>
238
@<Main Program@>
241
@$@<Main Program@>==@{@-
248
@$@<Function@>==@{@-
252
for (i=0;i<10;i++)
259
@$@<Print@>@M==@{@-
260
printf("Hello World!");
263
@$@<Scan@>@Z==@{scanf@}
265
@$@<Include Files@>==@{@-
266
#include <stdio.h>
267
#include <stdlib.h>@}
274
<TD ALIGN="left" VALIGN="bottom"><A HREF="macro_simple.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
275
<TD ALIGN="center" VALIGN="bottom"><A HREF="macro.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
276
<TD ALIGN="right" VALIGN="bottom"><A HREF="macro_indent.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
284
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
285
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
296
<!-- *********************************************************************** -->
297
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
298
<!-- *********************************************************************** -->
added
removed
tutorial/macro_times.html
