2.1 Simple Macros

The original "Hello World" program consisted of a single macro definition.

@O@<hello.txt@>@{Hello World@+@}

In fact, this is a rather exceptional macro, as it causes its expansion to be written to a product file. The @O (for Output) signals this. In FunnelWeb, most macros are defined using @$. This results in a macro that does not generate a product file, but which can be called in other macros (including @O macros). Let us expand the hello world program to include some other macros.

@O@<hello.txt@>@{@<Greetings@>@+@}

@$@<H@>==@{Hello@}
@$@<W@>==@{World@}

@$@<Greetings@>==@{@<H@> @<W@>@}

Type in the file and run it through FunnelWeb using the command:

fw hello

The product file (result.out) should look like this:

Hello World

This short program illustrates some of the features of ordinary macros in FunnelWeb. Consider the @O macro. Instead of containing straight text ("Hello World"), it now contains the macro call @<Greetings@>. A FunnelWeb macro can be called from within the body of another macro just by giving the macro name delimited in @< and @>.

At the bottom of the file is the definition of the @<Greetings@> macro. The definition is similar to the definition of hello.txt except that it starts with @$ to indicate that no product file is desired from this macro (directly). It also employs the optional == syntax which has no semantic impact, but can be used to make definitions clearer. The body of the @<Greetings@> macro consists of calls to the H and W macros which are defined immediately above.

Note that the macros are not constrained to be defined in any particular order. One of the main features of literate programming tools is that they allow the different parts of the text document being developed (usually a computer program) to be layed out in any order. So long as there is a definition somewhere in the input file for every macro call, FunnelWeb will sort it all out.

In fact, FunnelWeb's macro facility is very simple. Unlike many macro preprocessors which allow macros to define other macros, FunnelWeb completely finishes parsing and analysing the macros in the input file before it starts expanding them into product files. Other preprocessors allow macros to be redefined like variables (as in, say, TeX) taking on many different values as the macro pre-processor travels through the input file. In contrast, FunnelWeb has no concept of "different times" and treats the input as one huge static orderless, timeless, collection of definitions. In FunnelWeb, there is only ever one time, and so there can only ever be one value/definition for each macro.