Named Readtables Manual
Table of Contents
- 1 named-readtables ASDF System Details
- 2 Introduction
- 3 Overview
- 4 Reference
[in package EDITOR-HINTS.NAMED-READTABLES]
1 named-readtables ASDF System Details
- Version: 0.9
- Description: Library that creates a namespace for named readtable akin to the namespace of packages.
- Licence: BSD, see LICENSE
- Author: Tobias C. Rittweiler firstname.lastname@example.org
- Maintainer: Gábor Melis
- Mailto: email@example.com
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-cin 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.
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.
3.1 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
3.2 Important API idiosyncrasies
There are three major differences between the API of Named-Readtables, and the API of packages.
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-MYSQL:SQL-SYNTAXcan happily coexist next to each other. Or, taken to an extreme,
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.
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.)
DEFREADTABLEdoes 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
IN-READTABLEfor 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.
DEFREADTABLEhad compile-time effects, you'd have to wrap each definition of a reader-macro function in an
EVAL-WHENto make its definition available at compile-time. Because that's simply not the common case,
DEFREADTABLEdoes not have a compile-time effect.
If you want to use a readtable within the same file as its definition, wrap the
DEFREADTABLEand the reader-macro function definitions in an explicit
3.3 Preregistered Readtables
:COMMON-LISPdesignate the standard readtable.
:MODERNdesignates a case-preserving standard-readtable.
:CURRENTdesignates the current readtable.
(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) ...
[macro] 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
Merge the readtables designated into the new readtable being defined as per
:MERGEclause is given, an empty readtable is used. See
Error conditions of type
READER-MACRO-CONFLICTthat are signaled during the merge operation will be silently continued. It follows that reader macros in earlier entries will be overwritten by later ones. For backward compatibility,
:FUZEis accepted as an alias of
(:DISPATCH-MACRO-CHAR MACRO-CHAR SUB-CHAR FUNCTION)
Define a new sub character
SUB-CHARfor the dispatching macro character
SET-DISPATCH-MACRO-CHARACTER. You probably have to define
MACRO-CHARas 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
FUNCTIONis the keyword
MACRO-CHARis made a dispatching macro character, per
(:SYNTAX-FROM FROM-READTABLE-DESIGNATOR FROM-CHAR TO-CHAR)
Set the character syntax of
TO-CHARin the readtable being defined to the same syntax as
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:
:DISPATCH-MACRO-CHAR(one group), finally
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
DEFREADTABLEform in an explicit
On redefinition, the target readtable is made empty first before it's refilled according to the clauses.
:CURRENTare preregistered readtable names.
[macro] IN-READTABLE NAME
*READTABLE*to the readtable referred to by the symbol
[function] MAKE-READTABLE &OPTIONAL (NAME NIL NAME-SUPPLIED-P) &KEY MERGE
Creates and returns a new readtable under the specified
MERGEtakes a list of NAMED-READTABLE-DESIGNATORS and specifies the readtables the new readtable is created from. (See the
NIL, an empty readtable is used instead.
NAMEis not given, an anonymous empty readtable is returned.
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.
[function] MERGE-READTABLES-INTO RESULT-READTABLE &REST NAMED-READTABLES
Copy the contents of each readtable in
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
[function] FIND-READTABLE NAME
Looks for the readtable specified by
NAMEand returns it if it is found. Returns
[function] ENSURE-READTABLE NAME &OPTIONAL (DEFAULT NIL DEFAULT-P)
Looks up the readtable specified by
NAMEand returns it if it's found. If it is not found, it registers the readtable designated by
DEFAULTunder the name represented by NAME; or if no default argument is given, it signals an error of type
[function] RENAME-READTABLE OLD-NAME NEW-NAME
Replaces the associated name of the readtable designated by
NEW-NAME. If a readtable is already registered under
NEW-NAME, an error of type
[function] READTABLE-NAME NAMED-READTABLE
Returns the name of the readtable designated by
[function] REGISTER-READTABLE NAME READTABLE
NAME. Returns the readtable.
[function] UNREGISTER-READTABLE NAMED-READTABLE
Remove the association of
[function] COPY-NAMED-READTABLE NAMED-READTABLE
COPY-READTABLEbut takes a
Returns a list of all registered readtables. The returned list is guaranteed to be fresh, but may contain duplicates.
Either a symbol or a readtable itself.
[condition] READER-MACRO-CONFLICT READTABLE-ERROR
This condition is signaled during the merge process if a reader macro (be it a macro character or the sub character of a dispatch macro character) is present in the both source and the target readtable and the two respective reader macro functions differ.
[condition] READTABLE-DOES-ALREADY-EXIST READTABLE-ERROR
- [condition] READTABLE-DOES-NOT-EXIST READTABLE-ERROR