Common Lisp Package: EDITOR-HINTS.NAMED-READTABLES

* What are Named-Readtables? Named-Readtables is a library that provides a namespace for readtables akin to the already-existing namespace of packages. In particular: * you can associate readtables with names, and retrieve readtables by names; * you can associate source files with readtable names, and be sure that the right readtable is active when compiling/loading the file; * similiarly, your development environment now has a chance to automatically determine what readtable should be active while processing source forms on interactive commands. (E.g. think of `C-c C-c' in Slime [yet to be done]) It follows that Named-Readtables is a facility for using readtables in a localized way. Additionally, it also attempts to become a facility for using readtables in a _modular_ way. In particular: * it provides a macro to specify the content of a readtable at a glance; * it makes it possible to use multiple inheritance between readtables. * Notes on the API The API heavily imitates the API of packages. This has the nice property that any experienced Common Lisper will take it up without effort. DEFREADTABLE - DEFPACKAGE IN-READTABLE - IN-PACKAGE MERGE-READTABLES-INTO - USE-PACKAGE MAKE-READTABLE - MAKE-PACKAGE UNREGISTER-READTABLE - DELETE-PACKAGE RENAME-READTABLE - RENAME-PACKAGE FIND-READTABLE - FIND-PACKAGE READTABLE-NAME - PACKAGE-NAME LIST-ALL-NAMED-READTABLES - LIST-ALL-PACKAGES * Important API idiosyncrasies There are three major differences between the API of Named-Readtables, and the API of packages. 1. Readtable names are symbols not strings. Time has shown that the fact that packages are named by strings causes severe headache because of the potential of package names colliding with each other. Hence, readtables are named by symbols lest to make the situation worse than it already is. Consequently, readtables named CL-ORACLE:SQL-SYNTAX and CL-MYSQL:SQL-SYNTAX can happily coexist next to each other. Or, taken to an extreme, SCHEME:SYNTAX and ELISP:SYNTAX. If, for example to duly signify the importance of your cool readtable hack, you really think it deserves a global name, you can always resort to keywords. 2. The inheritance is resolved statically, not dynamically. A package that uses another package will have access to all the other package's exported symbols, even to those that will be added after its definition. I.e. the inheritance is resolved at run-time, that is dynamically. Unfortunately, we cannot do the same for readtables in a portable manner. Therefore, we do not talk about "using" another readtable but about "merging" the other readtable's definition into the readtable we are going to define. I.e. the inheritance is resolved once at definition time, that is statically. (Such merging can more or less be implemented portably albeit at a certain cost. Most of the time, this cost manifests itself at the time a readtable is defined, i.e. once at compile-time, so it may not bother you. Nonetheless, we provide extra support for Sbcl, ClozureCL, and AllegroCL at the moment. Patches for your implementation of choice are welcome, of course.) 3. DEFREADTABLE does not have compile-time effects. If you define a package via DEFPACKAGE, you can make that package the currently active package for the subsequent compilation of the same file via IN-PACKAGE. The same is, however, not true for DEFREADTABLE and IN-READTABLE for the following reason: It's unlikely that the need for special reader-macros arises for a problem which can be solved in just one file. Most often, you're going to define the reader macro functions, and set up the corresponding readtable in an extra file. If DEFREADTABLE had compile-time effects, you'd have to wrap each definition of a reader-macro function in an EVAL-WHEN to make its definition available at compile-time. Because that's simply not the common case, DEFREADTABLE does not have a compile-time effect. If you want to use a readtable within the same file as its definition, wrap the DEFREADTABLE and the reader-macro function definitions in an explicit EVAL-WHEN. * Preregistered Readtables - NIL, :STANDARD, and :COMMON-LISP designate the /standard readtable/. - :MODERN designates a _case-preserving_ /standard-readtable/. - :CURRENT designates the /current readtable/. * Examples > (defreadtable elisp:syntax > (:merge :standard) > (:macro-char #\? #'elisp::read-character-literal t) > (:macro-char #\[ #'elisp::read-vector-literal t) > ... > (:case :preserve)) > > (defreadtable scheme:syntax > (:merge :standard) > (:macro-char #\[ #'(lambda (stream char) > (read-delimited-list #\] stream))) > (:macro-char #\# :dispatch) > (:dispatch-macro-char #\# #\t #'scheme::read-#t) > (:dispatch-macro-char #\# #\f #'scheme::read-#f) > ... > (:case :preserve)) > > (in-readtable elisp:syntax) > > ... > > (in-readtable scheme:syntax) > > ... * Acknowledgements Thanks to Robert Goldman for making me want to write this library. Thanks to Stephen Compall, Ariel Badichi, David Lichteblau, Bart Botta, David Crawford, and Pascal Costanza for being early adopters, providing comments and bugfixes.

README:

FUNCTION

Public

COPY-NAMED-READTABLE (NAMED-READTABLE)

Like COPY-READTABLE but takes a NAMED-READTABLE-DESIGNATOR as argument.

ENSURE-READTABLE (NAME &OPTIONAL (DEFAULT NIL DEFAULT-P))

Looks up the readtable specified by `name' and returns it if it's found. If it is not found, it registers the readtable designated by `default' under the name represented by `name'; or if no default argument is given, it signals an error of type READTABLE-DOES-NOT-EXIST instead.

FIND-READTABLE (NAME)

Looks for the readtable specified by `name' and returns it if it is found. Returns NIL otherwise.

LIST-ALL-NAMED-READTABLES

Returns a list of all registered readtables. The returned list is guaranteed to be fresh, but may contain duplicates.

MAKE-READTABLE (&OPTIONAL (NAME NIL NAME-SUPPLIED-P) &KEY MERGE)

Creates and returns a new readtable under the specified `name'. `merge' takes a list of NAMED-READTABLE-DESIGNATORS and specifies the readtables the new readtable is created from. (See the :MERGE clause of DEFREADTABLE for details.) If `merge' is NIL, an empty readtable is used instead. If `name' is not given, an anonymous empty readtable is returned. Notes: An empty readtable is a readtable where each character's syntax is the same as in the /standard readtable/ except that each macro character has been made a constituent. Basically: whitespace stays whitespace, everything else is constituent.

MERGE-READTABLES-INTO (RESULT-READTABLE &REST NAMED-READTABLES)

Copy the contents of each readtable in `named-readtables' into `result-table'. If a macro character appears in more than one of the readtables, i.e. if a conflict is discovered during the merge, an error of type READER-MACRO-CONFLICT is signaled.

READTABLE-NAME (NAMED-READTABLE)

Returns the name of the readtable designated by `named-readtable', or NIL.

REGISTER-READTABLE (NAME READTABLE)

Associate `readtable' with `name'. Returns the readtable.

RENAME-READTABLE (OLD-NAME NEW-NAME)

Replaces the associated name of the readtable designated by `old-name' with `new-name'. If a readtable is already registered under `new-name', an error of type READTABLE-DOES-ALREADY-EXIST is signaled.

UNREGISTER-READTABLE (NAMED-READTABLE)

Remove the association of `named-readtable'. Returns T if successfull, NIL otherwise.

Private

%ASSOCIATE-NAME-WITH-READTABLE (NAME READTABLE)

Associate NAME with READTABLE for FIND-READTABLE to work.

%ASSOCIATE-READTABLE-WITH-NAME (NAME READTABLE)

Associate READTABLE with NAME for READTABLE-NAME to work.

%CLEAR-READTABLE (READTABLE)

Make all macro characters in READTABLE be constituents.

%FIND-READTABLE (NAME)

Return the readtable named NAME.

%GET-DISPATCH-MACRO-CHARACTER (CHAR SUBCHAR RT)

Ensure ANSI behaviour for GET-DISPATCH-MACRO-CHARACTER.

%GET-MACRO-CHARACTER (CHAR RT)

Ensure ANSI behaviour for GET-MACRO-CHARACTER.

%LIST-ALL-READTABLE-NAMES

Return a list of all available readtable names.

%READTABLE-NAME (READTABLE)

Return the name associated with READTABLE.

%STANDARD-READTABLE

Return the standard readtable.

%UNASSOCIATE-NAME-FROM-READTABLE (NAME READTABLE)

Remove the association between NAME and READTABLE

%UNASSOCIATE-READTABLE-FROM-NAME (NAME READTABLE)

Remove the association between READTABLE and NAME.

DISPATCH-MACRO-CHAR-P (CHAR RT)

Is CHAR a dispatch macro character in RT?

ENSURE-FUNCTION (FUNCTION-DESIGNATOR)

Returns the function designated by FUNCTION-DESIGNATOR: if FUNCTION-DESIGNATOR is a function, it is returned, otherwise it must be a function name and its FDEFINITION is returned.

ENSURE-LIST (LIST)

If LIST is a list, it is returned. Otherwise returns the list designated by LIST.

FUNCTION= (FN1 FN2)

Are reader-macro function-designators FN1 and FN2 the same?

PARSE-BODY (BODY &KEY DOCUMENTATION WHOLE)

Parses BODY into (values remaining-forms declarations doc-string). Documentation strings are recognized only if DOCUMENTATION is true. Syntax errors in body are signalled and WHOLE is used in the signal arguments when given.

PARSE-ORDINARY-LAMBDA-LIST (LAMBDA-LIST)

Parses an ordinary lambda-list, returning as multiple values: 1. Required parameters. 2. Optional parameter specifications, normalized into form (NAME INIT SUPPLIEDP) where SUPPLIEDP is NIL if not present. 3. Name of the rest parameter, or NIL. 4. Keyword parameter specifications, normalized into form ((KEYWORD-NAME NAME) INIT SUPPLIEDP) where SUPPLIEDP is NIL if not present. 5. Boolean indicating &ALLOW-OTHER-KEYS presence. 6. &AUX parameter specifications, normalized into form (NAME INIT). Signals a PROGRAM-ERROR is the lambda-list is malformed.

REQUIRED-ARGUMENT (&OPTIONAL NAME)

Signals an error for a missing argument of NAME. Intended for use as an initialization form for structure and class-slots, and a default value for required keyword arguments.

Undocumented

%FROB-SWANK-READTABLE-ALIST (PACKAGE READTABLE)

%MAKE-READTABLE-ITERATOR (READTABLE)

CHECK-READER-MACRO-CONFLICT (FROM TO CHAR &OPTIONAL SUBCHAR)

CONSTANT-STANDARD-READTABLE-EXPRESSION-P (THING)

ENSURE-DISPATCH-MACRO-CHARACTER (CHAR &OPTIONAL NON-TERMINATING-P (READTABLE *READTABLE*))

FIND-RESERVED-READTABLE (RESERVED-NAME)

RESERVED-READTABLE-NAME-P (NAME)

SIGNAL-SUSPICIOUS-REGISTRATION-WARNING (NAME-EXPR READTABLE-EXPR)

SIMPLE-PROGRAM-ERROR (MESSAGE &REST ARGS)

SIMPLE-STYLE-WARN (FORMAT-CONTROL &REST FORMAT-ARGS)

MACRO

Public

DEFREADTABLE (NAME &BODY OPTIONS)

Define a new named readtable, whose name is given by the symbol `name'. Or, if a readtable is already registered under that name, redefine that one. The readtable can be populated using the following `options': (:MERGE `readtable-designators'+) Merge the readtables designated into the new readtable being defined as per MERGE-READTABLES-INTO. If no :MERGE clause is given, an empty readtable is used. See MAKE-READTABLE. (:FUZE `readtable-designators'+) Like :MERGE except: Error conditions of type READER-MACRO-CONFLICT that are signaled during the merge operation will be silently _continued_. It follows that reader macros in earlier entries will be overwritten by later ones. (:DISPATCH-MACRO-CHAR `macro-char' `sub-char' `function') Define a new sub character `sub-char' for the dispatching macro character `macro-char', per SET-DISPATCH-MACRO-CHARACTER. You probably have to define `macro-char' as a dispatching macro character by the following option first. (:MACRO-CHAR `macro-char' `function' [`non-terminating-p']) Define a new macro character in the readtable, per SET-MACRO-CHARACTER. If `function' is the keyword :DISPATCH, `macro-char' is made a dispatching macro character, per MAKE-DISPATCH-MACRO-CHARACTER. (:SYNTAX-FROM `from-readtable-designator' `from-char' `to-char') Set the character syntax of `to-char' in the readtable being defined to the same syntax as `from-char' as per SET-SYNTAX-FROM-CHAR. (:CASE `case-mode') Defines the /case sensitivity mode/ of the resulting readtable. Any number of option clauses may appear. The options are grouped by their type, but in each group the order the options appeared textually is preserved. The following groups exist and are executed in the following order: :MERGE and :FUZE (one group), :CASE, :MACRO-CHAR and :DISPATCH-MACRO-CHAR (one group), finally :SYNTAX-FROM. Notes: The readtable is defined at load-time. If you want to have it available at compilation time -- say to use its reader-macros in the same file as its definition -- you have to wrap the DEFREADTABLE form in an explicit EVAL-WHEN. On redefinition, the target readtable is made empty first before it's refilled according to the clauses. NIL, :STANDARD, :COMMON-LISP, :MODERN, and :CURRENT are preregistered readtable names.

IN-READTABLE (NAME)

Set *READTABLE* to the readtable referred to by the symbol `name'.

Private

DESTRUCTURE-CASE (VALUE &REST PATTERNS)

Dispatch VALUE to one of PATTERNS. A cross between `case' and `destructuring-bind'. The pattern syntax is: ((HEAD . ARGS) . BODY) The list of patterns is searched for a HEAD `eq' to the car of VALUE. If one is found, the BODY is executed with ARGS bound to the corresponding values in the CDR of VALUE.

DO-READTABLE ((ENTRY-DESIGNATOR READTABLE &OPTIONAL RESULT) &BODY BODY)

Iterate through a readtable's macro characters, and dispatch macro characters.

Undocumented

DEFINE-API (NAME LAMBDA-LIST TYPE-LIST &BODY BODY)

DEFINE-CRUFT (NAME LAMBDA-LIST &BODY (DOCSTRING . ALTERNATIVES))

WITH-READTABLE-ITERATOR ((NAME READTABLE) &BODY BODY)

WITHOUT-PACKAGE-LOCK ((&REST PACKAGE-NAMES) &BODY BODY)

GENERIC-FUNCTION

Private

Undocumented

CONFLICTING-DISPATCH-SUB-CHAR (CONDITION)

SETFCONFLICTING-DISPATCH-SUB-CHAR (NEW-VALUE CONDITION)

CONFLICTING-MACRO-CHAR (CONDITION)

SETFCONFLICTING-MACRO-CHAR (NEW-VALUE CONDITION)

EXISTING-READTABLE-NAME (CONDITION)

SETFEXISTING-READTABLE-NAME (NEW-VALUE CONDITION)

FROM-READTABLE (CONDITION)

SETFFROM-READTABLE (NEW-VALUE CONDITION)

MISSING-READTABLE-NAME (CONDITION)

SETFMISSING-READTABLE-NAME (NEW-VALUE CONDITION)

TO-READTABLE (CONDITION)

SETFTO-READTABLE (NEW-VALUE CONDITION)

VARIABLE

Private

Undocumented

*CASE-PRESERVING-STANDARD-READTABLE*

*EMPTY-READTABLE*

*NAMED-READTABLES*

*READTABLE-NAMES*

*RESERVED-READTABLE-NAMES*

*STANDARD-READTABLE*

CONDITION

Public

READER-MACRO-CONFLICT

Continuable. This condition is signaled during the merge process if a) a reader macro (be it a macro character or the sub character of a dispatch macro character) is both present in the source as well as the target readtable, and b) if and only if the two respective reader macro functions differ.

READTABLE-DOES-ALREADY-EXIST

Continuable.

Undocumented

READTABLE-DOES-NOT-EXIST

Private

Undocumented

READTABLE-ERROR

SIMPLE-PROGRAM-ERROR (MESSAGE &REST ARGS)

SIMPLE-STYLE-WARNING