Modules (FWEB)

The code parts of (possibly noncontiguous) sections can be combined into modules. For FWEAVE, this is a logical combination, for purposes of cross-referencing different pieces of the code. But for FTANGLE, the combination is physical; FTANGLE’s output proceeds module by module.

Modules can be named or unnamed. There is exactly one unnamed module. The fundamental operation of FTANGLE is that

That output goes to a compilable file with an extension appropriate to the current language.

The contents of a module, either unnamed or named, consists of a mixture of code and comments. FTANGLE ignores the comments; FWEAVE treats them as TeX text. Within any TeX text, including comments, constructions delimited by ‘|...|’ signify a temporary shift into code mode. (In the present design, one cannot enclose a comment within the vertical bars.)

2.3.1 The unnamed module

The unnamed code module is introduced by the command ‘@a’. Subsequent uses of ‘@a’ accrete code to the unnamed module. To repeat, the fundamental operation of FTANGLE is that

Thus, there must be at least one ‘@a’ in the source file or FTANGLE will output nothing.

(Why is the command called ‘@a’? Historically, it was the first letter of the alphabet, as befits its prominent status. However, one can also think of it as “accrete.”)

2.3.2 Named modules

@< Arbitrary TeX text @>

Leading and trailing white space around the name text is ignored. The name text can include the ‘|...|’ construction, which tells FWEAVE to typeset a code fragment. Thus, module names can be highly explicit—for example,

@< Check that |x >= 0.0|; |abort| if not @>

To define a named module, replace the ‘@a’ that begins the unnamed code part of a section by ‘@< module name @>=’. If one uses this construction with the same name in a later section, the effect is to accrete to the contents of the module. Thus, a named module might ultimately consist of the code from sections 2, 5, and 9, for example.

To use a named module, simply use the name anywhere in a code part; FTANGLE will insert the contents of the module at the point where the name is used. For example,

@c
@ Here's how to use a named module.
@a
for(i=1; i<n; i++)
        @< Inner loop @>@;

@ Here's how to define a named module.  Definitions may occur after use.
@< Inner...@>=
{
a[i] = i;
}

There are several details to notice about the above example. First, FWEAVE considers module names to be simple expressions (such as the single identifier x). In C, expressions are made into complete statements (as is required in the body of a for statement) by appending a semicolon. In this case, a pseudo-semicolon ‘@;’ is appropriate; for more discussion of that, see AT;.

Second, after a name has appeared once in full, it may be abbreviated by a unique prefix followed by three periods, as demonstrated in the above example. By convention, a complete module name cannot be a subset of another. For example, ‘@<Test@>’ and ‘@<Test of graphics@>’ will elicit an error message.

Commonly, the first unnamed section in the code indicates its modular structure. For example, a C code might begin with

@c
@* DEMO.
@a
@<Include files@>@;
@<Typedefs@>@;
@<Function prototypes@>@;
@<Global variables@>@;

Subsequently one can accrete to the above named sections, as often as desired and in any order. This way, definitions of global variables can be introduced anywhere in the web source file as logical and pedagogical exposition dictates, but will be guaranteed to appear at the top of the code. Function prototypes could be handled this way as well; alternatively, they could all be collected into one section, perhaps at the end of the source file. (The above organization still guarantees that they will appear at the beginning of the output.) Functions could be introduced one at a time in subsequent unnamed sections.

@
@a
@< Left side @> = @< Right side @>@;

Here the intent is to construct an assignment statement. However, this will be flagged as an error because FWEB thinks one is trying to define the named module ‘@<Left side@>’, which one shouldn’t be doing while in code mode. To make it work, just put the invisible expression ‘@e’ (see ATe) before the equals sign.

2.3 Modules

2.3.1 The unnamed module

2.3.2 Named modules