2.8 Include Files

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 @i 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 camera.txt containing the two lines:

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

and another file called poem.fw containing the following four lines

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.

Then, if FunnelWeb were to process poem.fw, the result would be as if FunnelWeb had read in:

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.

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 main.fw contains

@O@<output.dat@>==@{@-
@i inc.fw
This is the text of the sloth macro.
@}

and inc.fw contains

@<Sloth@>
@}

@$@<Sloth@>==@{@-

Then if FunnelWeb were applied to main.fw, it would see:

@O@<output.dat@>==@{@-
@<Sloth@>
@}

@$@<Sloth@>==@{@-
This is the text of the sloth macro.
@}

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 <special>=<newspecial> sequence which changes the special character.

A few other facts about include files are worth mentioning here. Include files inherit the directory specification supplied using the +I 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 "@i " 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.

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