do-xxx-symbols

[Rob MacLachlan <RAM@CMU-CS-C.ARPA>]

    Date: Sunday, 3 March 1985  21:43-EST
    From: Charles Hedrick <HEDRICK at RUTGERS.ARPA>
    To:   ram
    Re:   do-xxx-symbols

    The definition of DO-SYMBOLS says that it iterates over all symbols
    accessible in the specified package, and that it does each once.  The
    term "accessible in" is ambiguous. The code I have from Spice simply
    iterates over the externals and internals of that package. One could
    also interpret that as including packages used by the specified package.
    In that case, some interesting code would be needed to prevent a given
    symbol from being used more than once, since if IMPORT was done, a
    symbol could appear in several packages.  Does Spice still make the
    interpretation that DO-SYMBOLS looks only at the package specified?

    Similarly, APROPOS talks about symbols "available in" a given  package.
    The wording talks about inheritance paths, so the implication seems
    fairly clear that APROPOS does look at used packages.

Even after staring at the manual, I was unable to determine what the
intent was.  It is unfortunate that after spending N pages developing
the theory and terminology, the actual function description blows it.
The two possibilities are to iterate over all symbols available in the
package, or only over those present in the package.

If Do-Symbols is supposed to iterate over all symbols available in the
package, then it is clearly impractical to guarantee that each symbol
is only done once, so there probably should be a caveat similar to
that for Do-All-Symbols in the Do-Symbols description.  I think that
with some imagination, one could read the statement that each symbol
is done once to mean that each symbol is done at least once.

There is another problem with this interpretation, though.  Before you
can iterate over any symbol for a used package, you must check to see
if the symbol is shadowed in the inheriting package.  This could cause
a substantial performance penalty in Do-Symbols, since it would be
forced to do a hashtable lookup for each inherited symbol iterated
over.  This means that doing an apropos in any package using the lisp
package would require doing 1000 hashtable lookups.

On the other hand, the word accessible could be replaced with
present, and everyone would be happy.  Apropos would have to be
changed to do a Do-External-Symbols on each used package, and would
ignore details such as shadowed symbols.

  Rob