[cdr-discuss] Re: [RfC] WITH-READTABLE-ITERATOR

[Tobias C. Rittweiler]

The updated specification of WITH-READTABLE-ITERATOR looks now as
follows.

  -T.


  -- Macro: with-readtable-iterator 
                (name readtable &rest macro-char-types) declaration* form*                                  
              => results

Arguments and Values
....................

NAME
     A symbol.

READTABLE
     A form, evaluated once to produce a readtable designator.

MACRO-CHAR-TYPE
     One of the symbols `:macro-char', or `:dispatch-macro-char'.

DECLARATION
     A `declare' expression; not evaluated.

FORMS
     An implicit progn.

RESULTS
     The values of the FORMS.


Description
...........

Within the lexical scope of the body FORMS, the NAME is defined via `macrolet'
such that successive invocations of `(name)' will return the macro characters,
one by one, from the READTABLE. The order of the macro characters returned is
implementation-dependent.

The variable MACRO-CHAR-TYPES controls which macro characters are returned:

`:macro-char'
     All macro characters in READTABLE that are _not_ dispatch macro
     characters.

`:dispatch-macro-char'
     All dispatch macro characters in READTABLE.

Multiple occurences of the same symbol are allowed in MACRO-CHAR-TYPES.  If
MACRO-CHAR-TYPES is null, both `:macro-char' and `:dispatch-macro-char' is
assumed.

An invocation of `(name)' returns the following five values:

  1. A generalized boolean that is true if a macro character is returned.

  2. A macro character that is defined in READTABLE.

  3. A reader macro function of the macro character returned.

  4. A generalized boolean that is true if the macro character is a dispatch
     macro character.

  5. An association list between the "sub-characters" of the dispatch macro
     character and their reader macro functions.


After all macro characters have been returned by successive invocations of
`(name)', only one value is returned, namely `nil'.

Consequences are undefined if the association list returned as fifth value is
modified.

Consequences are undefined if READTABLE is modified in a way that might affect
an ongoing traversal operation. Yet conforming programs may modify the current
macro character in the readtable under traversal by means of
`set-macro-character', and `set-dispatch-macro-character'. [This does not
entail the permission to modify the standard readtable; CLHS 2.1.1.2 prevails.]

It is unspecified what happens if any of the implicit interior state of an
iteration is returned outside the dynamic extent of the
`with-readtable-iterator' form such as by returning some closure over the
invocation form.

Any number of invocations of `with-readtable-iterator' can be nested, and the
body of the innermost one can invoke all of the locally established macros,
provided all those macros have distinct names.

Exceptional Situations
......................

Signals an error of type `program-error' if a MACRO-CHAR-TYPE is supplied that
is not recognized by the implementation.

An error of type `type-error' is signalled if READTABLE does not evaluate to a
readtable designator.

See Also
........

Readtables (CLHS 2.1.1), Traversal Rules and Side Effects (CLHS 3.6)

Notes
.....

Implementations may extend the syntax of `with-readtable-iterator' by
recognizing additional macro character types.