Issue: DO-SYMBOLS-DUPLICATES (Version 2)

[Masinter.pa@Xerox.COM]

Status:  I merged in various comments. Ready for release? [use ballot]

Issue:        DO-SYMBOLS-DUPLICATES
References:   Do-Symbols, Page 187
Category:     Clarification
Edit history: Revision 1 by SEF 17-Apr-87
              Version 2 by Masinter, add other options

Problem Description:

CLtL specifies that Do-Symbols executes the body once for each symbol
accessible in the package.  It does not say whether it is permissible
for the body to be executed more than once for some accessible symbols.
The term "accessible" is defined on page 172 to include symbols
inherited from other packages (not including any symbols that may be
shadowed).  It is very expensive in some implementations to eliminate
duplications that occur because the same symbol is inherited from
multiple packages.

Proposal: DO-SYMBOLS-DUPLICATES:ALLOWED

Add to the specification of DO-SYMBOLS a note that it may execute the
body more than once for some symbols.

Rationale:

Most uses of DO-PACKAGE would not be harmed by the presence of
duplicates.  For these applications it is unreasonable to force users to
pay the high cost of filtering out the duplications.  Users who really
want the duplicates to be removed can add additional code to do this job.

Current Practice:

Many implementations have always produced duplicate values.

Adoption Cost:

None.  Implemenations would still be free to eliminate the duplications,
though code will not be assuming that this has been done.

Benefits:

Clarification of a situation that is currently ambiguous.

Conversion Cost:

Users who have been assuming that DO-SYMBOLS eliminates duplications
will have to be modified, but such code would run on few existing Common
Lisp systems.

Aesthetics:

It would be cleaner to present each symbol exactly once.  This is a
clear case of choosing efficiency over elegance.

Discussion:

This issue was discussed on the Common Lisp mailing list in 1985, and
the solution proposed here seems to have been informally agreed to at
the time -- there was no formal decision-making process in place then.

The need for do-symbols to be efficient is questionable, however; for 
many applications (e.g., global package manipulation), duplicate values
would create havoc. 

For some implementations, the performance penalty would be well over 
a factor of two.

Proposal: DO-SYMBOLS-DUPLICATES:ADD-KEYWORDS

Add a keyword argument to the DO-SYMBOLS macro :ALLOW-DUPLICATES (default
value T) which would make the choice explicit. E.g., 

 (DO-SYMBOLS (SYMBOL (FIND-PACKAGE "FRED") NIL
	       :ALLOW-DUPLICATES T
	       :EXTERNAL-ONLY NIL)
   ...)

Rationale:

This proposal allows applications which need to be careful the 
opportunity to do so.

Current Practice:

No current implementation has this feature.

Adoption Cost:

Implementations which currently can produce duplicates would have
to keep track of symbols which were previously in the macro expansion.

Benefits:

The default case would run efficiently, and yet users could also have
code that guaranteed that there were no duplicates.

Conversion Cost:

Users who have been assuming that DO-SYMBOLS eliminates duplications
would only have to add a :ALLOW-DUPLICATES T.

Aesthetics:

This proposal makes the language slightly more complex, but allows 
for both efficiency and accuracy. 

Discussion:

Should the default value of :allow-duplicates be nil instead?