Specifying Constraints on the Number of Instantiations

Experience with FunnelWeb V1 demonstrated the need to be able to specify in macro definitions how many times it was expected that the macro would be used. FunnelWeb V1 generates an error if a macro is not used, but permits macros to be called more than once. This caused problems for macro libraries, which would be included, but whose macros were often not called.

By default, FunnelWeb V3 requires that each macro (except for the ones attached to output files) be called exactly once. However, it also provides syntax that allows the user to specify that a macro be allowed to be called zero times or many times. This allows a macro to be specified with the following permissible ranges of numbers of calls depending on the presence or absence of ``@Z'' and ``@M'':

   0..1          @$@<Sloth@>@Z==...
      1          @$@<Sloth@>==...
      1..n       @$@<Sloth@>@M==...
   0.....n       @$@<Sloth@>@Z@M==...

The only two problems with this scheme are:

  1. It is incompatible with FunnelWeb V1 files, as the default in FunnelWeb V1 is 1…n whereas the default in new FunnelWeb is 1. This is not a big problem because most macros in the old files were used exactly once. Only a few macros will have to be changed.

  2. What should the syntax be? (above is a sneak preview only!)

The initial proposal for syntax was to allow the user to insert zero, one, or both of @? and @M just after the @$ of a macro definition. However, this has the following drawbacks:

  1. It uses two sequences that are desirable to reserve (@? for conditionals and @M for macro).

  2. It stops the user from searching for the string @$@<name to find the definition of a macro.

These are significant problems. Here are some alternative ideas for where to position the modifiers in the macro definition:

@?@M@$@<Slothy dogs@>@(@5@)==@{@-
This is a short macro.
With only a line or two@}

@$@<Slothy dogs@>@?@M@(@5@)==@{@-
This is a short macro.
With only a line or two@}

@$@<Slothy dogs@>@(@5@)@?@M==@{@-
This is a short macro.
With only a line or two@

The first form puts me off because I think that it is a good visual rule to start all the macros with @$. The second form puts me off because it detaches the macro name from the parameter list, thus making it look less like a call, which is desirable syntactic resonance. The third form is messy but probably workable. Because we are right next to the tested constant string (either == or +=) we could augment it further. For example, 01== could allow a macro to be called from 0 to 1 times. The main problem with this is that we are trying to phase out == anyway!

Nevertheless, all the logic points to after the parameter list as the best place to locate this information.

After some thought, it was decided that the ``@?'' sequence be reserved for a possible future conditional facility, and so @Z was used instead.

Decision: The position is after the parameter list. The notation is @Z for zero, and @M for many.

Example of final syntax:

@$@<Slothy dogs@>@(@5@)@Z@M+=@{@-
This is a short macro.
With only a line or two@}