Hello,

After some discussion on comp.lang.lisp a few weeks ago, I asked Pascal Costanza whether a CDR document could specify that implementations of the document's interface should push features to advertise purported conformance with the CDR document. He encouraged me to send a draft here for comment.

The writeup is in apprxomately the form of the cl-cleanup committee's issues, since I expect everybody will be familiar with that structure, though it doesnt actually propose any changes to ANSI. I'll mark it up in LaTeX later, if people think it's worth submitting to the editors.

Comments?

-- RmK

* Issue

CDR-FEATURES-CONVENTION

* References

Pitman, K.M. (1991). Issue COMMON-FEATURES. Issue 56, X3J13, ANSI. http://www.lisp.org/HyperSpec/Issues/iss056-writeup.html

Pitman, K. and Chapman, K., editors (1994). Information Technology ­ Programming Language ­ Common Lisp. Number 226­1994 in INCITS. ANSI.

Rhodes, Christope. (2004). "Maintaining Portable Lisp Programs" http://www-jcsu.jesus.cam.ac.uk/~csr21/papers/features.pdf

* Related Issues

ANSI Issue 56, more or less.

* Category

Recommendation ; "Recommendation wasn't a category in the cl-cleanup ;committee, but the CDR process isn't really the same ;thing.

* Problem Description

A document in the Common Lisp Document Repository (CDR) may describe programmers' interfaces or propose emendations or extensions to the ANSI Common Lisp standard. Such a document should specify one or more features so that programs may easily distinguish environments that may be expected to conform to the document's specification.

* Proposal

We propose a convention for naming symbols meant to be included in *FEATURES* for the purpose of advertising purported conformance with a CDR document's specifications, and encourage CDR document authors, Common Lisp implementors, and library authors to follow such conventions when providing purported implementations of such specifications.

CDR documents that describe programmers' interfaces should enumerate a set of symbols in the KEYWORD package whose names begin with a prefix consisting of the string "CDR-" followed by the decimal representation of the number of the CDR document with no leading zeroes. If the CDR document defines only one level of conformance with the document's specifications (e.g., the document specifies no subsets), then the enumeration of keyword symbols should contain the symbol whose name is the prefix. If the CDR document defines levels of conformance of its total specification (such as subsets, or even mutually incompatible interfaces), then for each defined level of conformance, the enumeration of keyword symbols should should contain a symbol whose name begins with the prefix, followed by a hyphen, followed by some descriptive name for the subset.

Implementors of an interface described in a CDR document that enumerates a set of keyword symbols as above should ensure that the appropriate symbols occur in the *FEATURES* list when the Lisp environment has been configured to behave in conformance with the specification. Configuring the Lisp environment might involve loading files, invoking functions, etc.; or the environment may conform to the specification when the host Lisp is initialized, in which case the implementation should include the appropriate symbols in *FEATURES* as early as initialization time. If, after configuring the Lisp environment to conform to the CDR document's specification, it should be possible to reconfigure the Lisp environment to fail to conform to the specification, whether the corresponding symbol remains in the *FEATURES* list after so reconfiguring is not defined by this proposal, but may be defined by a CDR document or an implementation of a CDR document's interface.

Implementations of Lisps that provide non-standard lettercase customs in their symbol names are permitted to vary the lettercase of the names of the enumerated keyword symbols as necessary to furnish the appropriate effects on those implementations.

Finally, programmers are discouraged from adding keyword symbols to *FEATURES* whose names begin with "CDR-" except as part of implementations of interfaces described in CDR documents.

* Examples

** Example 1

Suppose CDR document number 42 defines no subsets of its specification; in this case, the document might include text such as the following:

"Implementations of the interface described in this document should ensure that the symbol :CDR-42 occurs in the *FEATURES* list when the Lisp environment is configured to behave as described in this document."

Next, suppose that Lisp implementation BAR only conforms in case the user calls the function ENABLE-CDR-42-API, and that Lisp implementation QUUX only conforms in case a particular file is loaded. In this case, a program that can work only in environments conforming to CDR 42's specification might begin with

#+(and bar (not cdr-42)) (eval-when (:compile-toplevel :load-toplevel) (enable-cdr-42-api)) #+(and quux (not cdr-42)) (eval-when (:compile-toplevel :load-toplevel) (load "sys:source;cdr-42")) ;; If, after all that, CDR-42 still isn't present, bail out. #-cdr-42 (eval-when (:compile-toplevel :load-toplevel) (error "Can't run this program in a non-CDR-42 environment."))

** Example 2

Suppose that CDR 704 defines two subsets of its specification, called "BASIC" and "BELLS-N-WHISTLES"; in this case the document might include text such as the following:

"Implementations of the interface identified in this document as BASIC should ensure the symbol :CDR-704-BASIC occurs in the *FEATURES* list when the Lisp environment is configured to behave in conformance with the BASIC interface. Implementations of the interface identified in this document as BELLS-N-WHISTLES should ensure that the symbol CDR-704-BELLS-N-WHISTLES occur in the *FEATURES* list when the Lisp environment is configured to behave in conformance with the BELLS-N-WHISTLES interface."

Now suppose a program needs a function FROB that's in BELLS-N-WHISTLES but not in BASIC, but that can be defined portably (albeit perhaps not maximally efficiently), given BASIC. Then the program might begin with

#+(and cdr-704-basic (not cdr-704-bells-n-whistles)) (eval-when (:compile-toplevel :load-toplevel) (defun frob ...)) #-cdr-704-basic (eval-when (:compile-toplevel :load-toplevel) (error "Can't run this program without BASIC CDR 704~ compliance."))

* Rationale

Since CDR documents are not constrained to describe only those interfaces that can be implemented in portable Common Lisp, an individual document may define what is in effect a new dialect that's slightly different from ANSI Common Lisp. Thus, by the logic of ANSI Issue 56,

"Users need this to get a foothold as they try to port between dialects in transition."

In particular, it is not possible in general to programmatically investigate the semantics of a new dialect. For example, a CDR document might specify some behavior for an operator that has undefined consequences in ANSI Common Lisp; a program that exercised the operator to test for conformance with the CDR document might crash a Lisp implementation that conforms to ANSI but not to the CDR document's specification.

Even for interfaces that could be programmatically detected safely (interfaces that can be implemented in "modules" or "libraries"), it may nonetheless be desirable to distinguish the environment's purported conformance to an interface from the presence of a particular implementation of the interface. For example, it may be desirable from time to time for one library to supersede another while providing an upwardly compatible interface (perhaps modulo package names), or for an implementor to provide an implementation of an interface with extensions or optimizations that can't be written portably. In such cases, it may be difficult to detect all the ways that the environment might conform to the interface, and so an advertisement by the provider of the interface should simplify programs that depend on the interface.

* Current practice

As of Aug 2007, no existing CDR document does as this document describes. It is unlikely that anyone is already using keywords of the form :CDR-<NN> in their *FEATURES*.

* Cost to Implementors

Negligible. CDR document authors are encouraged to add a bit of boilerplate to their documents, and authors of programs that purport to conform to CDR document standards will have to arrange to push some symbols onto *FEATURES*.

* Cost to Users

Negligible, if any.

* Cost of non-adoption

It can be difficult to take advantage of interfaces described in the Common Lisp Document Repository, even when these interfaces are implemented.

* Performance Impact

None.

* Benefits

The CDR project might be more effective at spurring progress in Common Lisp.

Users who desire to write programs that produce equivalent results and observable side effects on a subset of possible implementations might face an easier task if implementations advertised their purported conformance with defined, if non-ANSI, interfaces.

* Esthetics

It's slightly ugly to call for symbols such :CDR-<nn>-FOO-BAR-BAZ to be members of *FEATURES*, but alternatives are bad or worse. Specifically,, it's inconvenient to use read-time conditionals to check for anything other than the presence of keyword symbols in *FEATURES*, and it seemed like overkill to call for a package (say, "CDR") solely for the names of CDR document interfaces.

* Notes

Rhodes (2004) provides many examples of the pitfalls of read-time feature conditionals as a means for maintaining portable programs; this document does not dispute any of Rhodes's observations or suggestions. However, while Rhodes suggests various ways to organize implementation-specific code to minimize the use of read-time conditionals, it is hoped that the conventions detailed above will promote convergence of implementations in areas ANSI leaves implementation-specific or does not address, thereby reducing the amount of such implementation-specific code in programs intended for use in different Lisp environments.

Note that this document does not constrain CDR documents from calling for elements of *FEATURES* other than those that follow the conventions proposed here, nor constrain implementors from providing symbols other than ones that follow the conventions proposed here.

* Discussion

It is not intended that identifiers of the form CDR-<NN> supplant descriptive, mnemonic names for interfaces, libraries, packages, systems, etc.