Indentation

indentationindentationnoindentationblankindentationtext

A macro call that does not appear at the left margin is called an indented macro call and seems to lead to three different alternatives for its expansion: no indentation, blank indentation, and text indentation. Here are examples of each kind of indentation. First the example problem. 

@$@<Sloth@>==@{@-
Aardvark
Walrus@}

@O@<Output@>==@{@-
Zebra@<Sloth@>
Giraffe
@}

There are three ways that the second line of the Sloth macro can be indented.

No indentation: 

     ZebraAardvark
     Walrus
     Giraffe

Blank indentation: 

     ZebraAardvark
          Walrus
     Giraffe

Text indentation: 

     ZebraAardvark
     ZebraWalrus
     Giraffe

No indentation is useful where the user wishes to deal with the output stream as a pure output stream. Blank indentation is useful when the user wishes to generate indented computer programs. Text indentation is useful where the user wishes to prefix each line of an entire macro invocation with a string. This can be useful for commenting out code (in Ada using –), and for prepending things like a dollar sign at the start of each line an a VAX VMS DCL script command file.DCL

FunnelWeb V1 provided a choice of no indentation or blank indentation. The choice was made in the command line and could not be overridden.

The design questions are as follows:

  1. Which of the three kinds of indentation should FunnelWeb support?
  2. What should be the granularity of swapping between indentation modes?
  3. Are particular indentation modes dangerous?
  4. Is the presence of particular combinations of indentation modes confusing to the user?
  5. How and when should the choice of indentation be specified?

All sorts of schemes were considered, including a finely grained system in which the user could specify at the point of call which indentation mode should be used for the called macro expansion.

After a lot of thought, the dominant factor that should affect the design was decided to be the ıclarity in the user's mind of the indentation facility and the ıdanger associated with misunderstanding it. Here are two examples that show how easily a confusion or misunderstanding of the indenting being used can cause danger. The first example shows how blank or no indentation might be misused. 

--Misuse of blank (and no) indentation.
--@<Sloth@>

Here the user has assumed that text indentation is in action and has placed an Ada comment symbol – before the invocation of the macro @<Sloth@> in the hope that the entire text of the macro would be prefixed by –. The result could be passed by the compiler which would activate all but the first statement in the expansion of macro @<Sloth@>.

The next example demonstrates how text indentation could be misused.indentationdangers 

--Misuse of text indentation:
a++; @<Sloth@>

Here the user has placed the call to @<Sloth@> after the incrementing of variable a. The result is that there is a good chance that the a++; prepended to each line of the expansion of @<Sloth@> will be passed by the compiler and will cause a to be overincremented.

These examples are not to be laughed at. It is possible that FunnelWeb will be used widely, and the problems above may cause problems in critical systems. The examples above are particularly scary because they are reflexive. One cannot simply pin the blame on one particular indentation form. A little thought reveals that the greatest danger lies in ıconfusion in the user's mind. If the user is confused between text or blank indenting, problems will arise.

There seem to be two ways to solve the problem. The first is to ban all macro calls that are preceded by non-blank text. This is not a good option because there are so many cases where it is desirable to expand more than one single line macros on the same line. A second option is to eliminate one of the two forms so as to reduce the potential for ambiguity in the user's mind. I choose the latter option. Of the two forms, the clear choice for elimination is text indenting for the following reasons:

  1. It actually introduces extra text which gives it an a priori potential for problems.
  2. It is harder to implement and would slow down Tangle.
  3. It would not be compatible with FunnelWeb V1 which uses blank indentation.

The only other decision is the level of granularity of choice between the remaining options: no indentation and blank indentation. FunnelWeb V1 allowed this choice to be made in the command line. In retrospect, this was bad design because the user might unwittingly code certain macro calls relying on one or the other mode. A better system is to allow the user to specify which mode in the input file itself. This has been done in FunnelWeb V3.

Again, to avoid confusion, it seems sensible to allow the user only one indentation mode per FunnelWeb input file. In most cases, the user will be happy with blank indentation (the default) and there will be no need for change anyway.

Decision: Implement only no indentation and blank indentation. Make the choice of indentation a static attribute of a particular FunnelWeb run that is specified in the input file. This solution is the same as FunnelWeb V1 except that the choice has been moved from the command line to the input file.