File: macro_times.html

package info (click to toggle)
funnelweb-doc 3.2d-4.2
links: PTS
area: main
in suites: forky, sid, trixie
size: 3,744 kB
sloc: perl: 241; makefile: 23
file content (300 lines) | stat: -rw-r--r-- 9,825 bytes
parent folder | download | duplicates (5)

<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>2.2 Number of Times Called</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="../reference/index.html"
 TARGET="funnelwebreference"
 onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Reference</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>Tutorial</B></FONT></A><BR>
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
<A HREF="macro.html"><FONT COLOR="#FFFFFF">2 Macros</FONT></A><BR>
<A HREF="type.html"><FONT COLOR="#FFFFFF">3 Typesetting</FONT></A><BR>
<A HREF="example.html"><FONT COLOR="#FFFFFF">4 Example</FONT></A><BR>
<A HREF="hints.html"><FONT COLOR="#FFFFFF">5 Hints</FONT></A><BR>
<A HREF="examples.html"><FONT COLOR="#FFFFFF">6 Examples</FONT></A><BR>
<A HREF="web.html"><FONT COLOR="#FFFFFF">7 Webmaking</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="../reference/index.html"><IMG SRC="binary/title.gif"
 WIDTH="302" HEIGHT="24"
 BORDER="0" ALT="FunnelWeb Tutorial Manual"
 HSPACE="0" VSPACE="0"></A>
<P><FONT SIZE="5">2.2 Number of Times Called</FONT><BR>



<P>So far we have seen only tiny, degenerate input files.
The next example moves up to the level of "trivial",
but starts to convey the flavour of the way FunnelWeb can be
used in practice. Normally, there would be documentation
text appearing between the macros, but this has been omitted
so as to keep the focus on the macros themselves. Although
the next example is much longer than the previous example,
the only new construct is <SAMP>@-</SAMP> which can appear
only at the end of a line, and suppresses
it, preventing it from appearing
in the text. The <SAMP>@-</SAMP> construct allows
the text of a macro to be aligned at the left margin, rather
than having the first line hanging at the end of the
<SAMP>@{</SAMP>. FunnelWeb could have been set up so that
this end of line marker was suppressed. However, it would
have been a special case that would have broken the very
memorable rule "the text of a macro is the text
                appearing between the <SAMP>@{</SAMP> and <SAMP>@}</SAMP>".

<P>Type the following text into the file
<SAMP>hello.fw</SAMP> and run it through FunnelWeb. The file
contains some intentional errors so be sure to type it in
exactly and worry only if FunnelWeb <I>doesn't</I>&nbsp;
generate some errors.

<P>
<PRE>
@O@&lt;hello.c@&gt;==@{@-
@&lt;Include Files@&gt;
@&lt;Include Files@&gt;
@&lt;Main Program@&gt;
@}

@$@&lt;Main Program@&gt;==@{@-
main()
{
 doit();
}
@}

@$@&lt;Subroutine@&gt;==@{@-
void doit()
{
 int i;
 for (i=0;i&lt;10;i++)
   {
    @&lt;Print@&gt;
    @&lt;Print@&gt;
   }
}@}

@$@&lt;Print@&gt;==@{@-
printf("Hello World!");
printf("\n");@}

@$@&lt;Scan@&gt;==@{scanf@}

@$@&lt;Include Files@&gt;==@{@-
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;@}
</PRE>

<P>What happened? Well, if you haven't typed the file in
properly, you may get some miscellaneous syntax errors. Fix
these before continuing. If the file has been correctly
typed, you should be faced with some error messages to do
with the number of times some of the macros are called.

<P>By default, FunnelWeb insists that each macro defined
is invoked exactly once. However, the file above defines
macros that are used more than once and a macro that is not
used at all. Let us examine the errors.

<P>First, we see that FunnelWeb has alerted us to the fact
that the <SAMP>Include Files</SAMP> macro has been called
twice. Once alerted to this, a quick look at the program
convinces us that calling the macro twice is a mistake, and
that one of the calls should be deleted.

<P>Second, we note that FunnelWeb has alerted us to the
fact that the <SAMP>@&lt;subroutine@&gt;</SAMP> macro
is never called. Again, a quick look at the program tells us
that this is a mistake (and a very common one in the use of
FunnelWeb), and that a call to the
<SAMP>@&lt;subroutine@&gt;</SAMP> macro should be
inserted just above the call to the <SAMP>@&lt;Main
                                          Program@&gt;</SAMP> macro in the definition of
<SAMP>@&lt;hello.c@&gt;</SAMP>.

<P>These two cases demonstrate why these checks have been
placed in FunnelWeb. It is nearly always acceptable for a
macro to be called once. However, if a macro is not called
at all, or called more than once, this is often a sign that
the user has made a mistake.

<P>These checks have a dark side too. In addition to the
errors mentioned above, FunnelWeb has generated two similar
errors that do not help us.

<P>First, we are alerted to the fact that the
<SAMP>@&lt;print@&gt;</SAMP> macro has been called
twice. Clearly, in this case, this is not a problem, and so
here FunnelWeb's fussiness is a nuisance.

<P>Second, we are alerted to the fact that the
<SAMP>@&lt;scan@&gt;</SAMP> macro has never been
called. Like the <SAMP>@&lt;print@&gt;</SAMP> macro,
this macro was defined as a notational convenience, and
clearly it does not matter here if it is not used. Again,
FunnelWeb is being a nuisance.

<P>The four cases above demonstrate the light and dark
side of FunnelWeb's insistence that each macro be called
exactly once. To resolve the conflict without reducing the
strength of the checking, FunnelWeb provides two special
sequences <SAMP>@Z</SAMP> (for <STRONG>Z</STRONG>ero) and <SAMP>@M</SAMP>
(for <STRONG>M</STRONG>any) that can be attached to macro definitions.
Presence of the <SAMP>@Z</SAMP> tag
allows the designated macro to be called zero times.
Presence of the <SAMP>@M</SAMP> tag
allows the designated macro to be called more than once. A
single macro may carry both tags. It is always true that all
macros are allowed to be called exactly once.

<P>Here is the revised program with the errors fixed, by
eliminating or adding macro calls, or by adding tags. Try
processing the file now. There should be no errors.

<P>
<PRE>
@O@&lt;hello.c@&gt;==@{@-
@&lt;Include Files@&gt;
@&lt;Function@&gt;
@&lt;Main Program@&gt;
@}

@$@&lt;Main Program@&gt;==@{@-
main()
{
 doit();
}
@}

@$@&lt;Function@&gt;==@{@-
void doit()
{
 int i;
 for (i=0;i&lt;10;i++)
   {
    @&lt;Print@&gt;
    @&lt;Print@&gt;
   }
}@}

@$@&lt;Print@&gt;@M==@{@-
printf("Hello World!");
printf("\n");@}

@$@&lt;Scan@&gt;@Z==@{scanf@}

@$@&lt;Include Files@&gt;==@{@-
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;@}
</PRE>


<P>
<TABLE WIDTH="100%">
<TR>
<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>
<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>
<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>
</TR>
</TABLE>



<HR>
<FONT SIZE="2">
<A HREF="mailto:webmaster@ross.net">Webmaster</A>&nbsp;&nbsp;&nbsp;
<A HREF="copyright.html">Copyright &copy; Ross N. Williams 1992,1999. All rights reserved.</A><BR>
</FONT>

</FONT>
</TD>
</TR>
</TABLE>


</BODY>

<!-- *********************************************************************** -->
<!--      End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/)       -->
<!-- *********************************************************************** -->

</HTML>