3.2 Special Sequences

The scanner scans the input file from top to bottom, left to right, treating the input as ordinary text (to be handed directly to the parser as a text token) unless it encounters the special character which introduces a special sequence. Thus, the scanner partitions the input file into ordinary text and special sequences. (Note: This sort of character is often referred to as the "escape character" or the "control character" in other systems. However, as there is great potential to confuse these names with the "escape" character (ASCII 27) and ASCII "control" characters, the term "special" has been chosen instead. This results in the terms special character  and special sequence .

input_file = { ordinary_text | special_sequence }

Upon startup, the special character is @, but it can be changed using the <special>=<new_special> special sequence. Rather than using <special> whenever the special character appears, this document uses the default special character "@" to represent the current special character. More importantly, FunnelWeb's error messages all use the default special character in examples, even if the special character has been changed.

An occurrence of the special character in the input file introduces a special sequence. The kind of special sequence is determined by the character following the special character. Only printable characters can follow the special character.

The following list gives all the possible characters that can follow the special character, and the legality of each sequence. The first column gives the ASCII number of each ASCII character. The second column gives the special sequence for that character. The next column contains one of three characters: "-" means that the sequence is illegal. "S" indicates that the sequence is a simple sequence (with no attributes or side effects) that appears exactly as shown and is converted directly into a token and fed to the parser. Finally, "C" indicates that the special sequence is complex, possibly having a following syntax or producing funny side effects.

ASC  SEQ  COMMENT
-----------------
000       \
016        | Unprintable chars (illegal specials).
031       /
032  @    - Illegal (space).
033  @!   C Comment.
034  @"   S Parameter delimeter.
035  @#   C Short name sequence.
036  @$   S Start of macro definition.
037  @%   - Illegal.
038  @&   - Illegal.
039  @'   - Illegal.
040  @(   S Open parameter list.
041  @)   S Close parameter list.
042  @*   - Illegal.
043  @+   C Insert newline.
044  @,   S Parameter separator.
045  @-   C Suppress end of line marker.
046  @.   - Illegal.
047  @/   S Open or close emphasised text.
048  @0   - Illegal.
049  @1   S Formal parameter 1.
050  @2   S Formal parameter 2.
051  @3   S Formal parameter 3.
052  @4   S Formal parameter 4.
053  @5   S Formal parameter 5.
054  @6   S Formal parameter 6.
055  @7   S Formal parameter 7.
056  @8   S Formal parameter 8.
057  @9   S Formal parameter 9.
058  @:   - Illegal.
059  @;   - Illegal.
060  @<   S Open macro name.
061  @=   C Set special character.
062  @>   S Close macro name.
063  @?   - Illegal. Reserved for future use.
064  @@   C Insert special character into text.
065  @A   S New section (level 1).
066  @B   S New section (level 2).
067  @C   S New section (level 3).
068  @D   S New section (level 4).
069  @E   S New section (level 5).
070  @F   - Illegal.
071  @G   - Illegal.
072  @H   - Illegal.
073  @I   C Include file.
074  @J   - Illegal.
075  @K   - Illegal.
076  @L   S Macro is library macro.
077  @M   S Macro may be called many times.
078  @N   - Illegal.
079  @O   S Macro is attached to product file.
080  @P   C Pragma.
081  @Q   - Illegal.
082  @R   - Illegal.
083  @S   - Illegal.
084  @T   C Typesetter directive.
085  @U   - Illegal.
086  @V   - Illegal.
087  @W   - Illegal.
088  @X   - Illegal.
089  @Y   - Illegal.
090  @Z   S Macro may be called zero times.
091  @[   - Illegal. Reserved for future use.
092  @\   - Illegal.
093  @]   - Illegal. Reserved for future use.
094  @^   C Insert control character into text
095  @_   - Illegal.
096  @`   - Illegal.
097  @a   \
109  @m    | Identical to @A..@Z.
122  @z   /
123  @{   S Open macro body/Open literal directive.
124  @|   - Illegal.
125  @}   S Close macro body/Close literal directive.
126  @~   - Illegal.
127 to 255 - Illegal specials (as non-standard ASCII).

The most important thing to remember about the scanner is that nothing happens unless the special character is seen.  There are no funny sequences that will cause strange things to happen. The best way to view a FunnelWeb document at the scanner level is as a body of text punctuated by special sequences that serve to structure the text at a higher level.

The remaining description of the scanner consists of a detailed description of the effect of each complex special sequence.