FunnelWeb Notation

 

 

As we mentioned earlier, a literate programming (LP) tool allows the user to interleave documentation and code in whatever order is most appropriate for presentation. However, the tool must be able to extract and reorder the code ``chunks'' properly for the compiler. Like other LP tools, FunnelWeb accomplishes this feat with macros and automatic cross-referencing.

Each macro may contain some code as well as references to other macros. During the code extraction phase, FunnelWeb, starting at the ``root'' macro, extracts any code from the macro and expands all references to other macros. The process continues until there are no more references to expand and all of the code is extracted. The macros and their cross-references also appear in the typeset documentation so the reader can see how the code chunks fit together.

We use two types of FunnelWeb macros:

Simple Macro: The simple macro, by far the most common, has the following format. (The typographical conventions are consistent with FunnelWeb's output.)

   macro name¯  [definition number]  

  		 The code to be processed appears here 

  		   call to another macro  
        [called macro's definition number]

  This macro is invoked in definition n.

The letters M and Z may follow the definition number, indicating that the macro may be called many times or zero times, respectively. The numbers of the definitions that use a macro are listed in the last line. Macros that are invoked in a macro that is not defined in this document are invoked in external files as described by Section 3 of Chapter 13.

Here is an example of a simple macro.

   procI<>edure example  [5]  

  		 procTedure example is

  		 		   Constants  [4]

  		 begin

  		 		 for iT in 1..n loop

  		 		 		   Write out first p powers of i  [8]

  		 		 end loop;

  		 end example;

  This macro is invoked in definition 7.

Additive Macro: This macro is like the simple macro except that its definition may be distributed throughout the document. Each extension of an additive macro has the same name. The only syntactic difference between an additive macro and a simple macro is that is replaced with .

Parameterized Macro: As its name implies, the parameterized macro accepts one or more parameters for its definition. While not widely used in this report, this facility is useful in certain cases. Here is a simple example.

   add¯  [6]
     (  2)M  

  		   1 +   2

  This macro is invoked in definitions 3, 4 and 9.

This macro takes two parameters and the second is added to the first. The small diamonds ( ) distinguish the quantity of parameters and the parameter numbers from the definition numbers and ordinary code. Since it makes little sense to define a parameterized macro to be invoked only once, the M will usually appear after the definition number. An invocation of add is illustrated below in the definition of another parameterized macro! The parameter list is enclosed in parentheses and the individual parameters are enclosed in single quotes and delimited by commas.

   double¯  [3](  1)M  

  		   add  [6](`  1',`  1')

  This macro is invoked in definitions 10 and 11.