File: macro_include.html

package info (click to toggle)
funnelweb-doc 3.2d-5
links: PTS, VCS
area: main
in suites: forky, sid
size: 3,740 kB
sloc: perl: 241; makefile: 23
file content (238 lines) | stat: -rw-r--r-- 7,637 bytes
parent folder | download | duplicates (6)

<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.8 Include Files</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.8 Include Files</FONT><BR>



<P>FunnelWeb provides a nested include file facility that
can be used for a number of purposes. When FunnelWeb runs
into a single line containing the special sequence
<SAMP>@i</SAMP> followed by a blank, followed by a
file name, it reads in the designated file and replaces the
line containing the command (including the end of line
marker at the end of the line) with the entire contents of
the designated file. For example, if there was a file called
<SAMP>camera.txt</SAMP> containing the two
lines:

<P>
<PRE>
'Cos I shoot with a camera instead of a gun.
The animals flock to be petted and fed,
</PRE>

<P>and another file called <SAMP>poem.fw</SAMP>
containing the following four lines

<P>
<PRE>
I like to go shooting, it's a whole lot of fun,
@i camera.txt
Cos they know my camera isn't loaded with lead.
- RNW, 04-Jan-1991.
</PRE>

<P>Then, if FunnelWeb were to process <SAMP>poem.fw</SAMP>,
the result would be as if FunnelWeb had read in:

<P>
<PRE>
I like to go shooting, it's a whole lot of fun,
'Cos I shoot with a camera instead of a gun.
The animals flock to be petted and fed,
'Cos they know my camera isn't loaded with lead.
- RNW, 04-Jan-1991.
</PRE>

<P>FunnelWeb expands include files before it starts
scanning and parsing the included text. The result is that
include files can contain anything that can be found in a
FunnelWeb file. The following example illustrates the level
at which the include mechanism operates. If
<SAMP>main.fw</SAMP> contains

<P>
<PRE>
@O@&lt;output.dat@&gt;==@{@-
@i inc.fw
This is the text of the sloth macro.
@}
</PRE>

<P>and inc.fw contains

<P>
<PRE>
@&lt;Sloth@&gt;
@}

@$@&lt;Sloth@&gt;==@{@-
</PRE>

<P>Then if FunnelWeb were applied to <SAMP>main.fw</SAMP>, it would see:

<P>
<PRE>
@O@&lt;output.dat@&gt;==@{@-
@&lt;Sloth@&gt;
@}

@$@&lt;Sloth@&gt;==@{@-
This is the text of the sloth macro.
@}
</PRE>

<P>which it would process in the normal manner. The only
special sequence processing that takes place at a level
lower than include files is the processing of the
<SAMP>&lt;special&gt;=&lt;newspecial&gt;</SAMP>
sequence which changes the special character.

<P>A few other facts about include files are worth
mentioning here. Include files inherit the directory
specification supplied using the <SAMP>+I</SAMP> command line
option. The special character is saved at the start of each
include file and restored to its previous value at the end
of each include file. Include files can be nested up to ten
levels. Recursive included files will always cause an infinite recursion
as there is no bottoming out mechanism available. Include
files must contain an integer number of lines (i.e. the
last line must be terminated with an end of line marker).
Once FunnelWeb has seen "<TT>@i&nbsp;</TT>" at the start of a
line, it will grab the rest of the line raw and treat it as
a file name. There is no place on the line for things like
FunnelWeb comments (see later) or extraneous text.

<P>Include files can be used for many purposes, but are
particularly useful for hauling in macro
libraries.


<P>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"   VALIGN="bottom"><A HREF="macro_expansion.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.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></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>