13.6.7 How do I work with readtables?

It is possible to configure the lisp syntax by modifying the currently-active readtable. However, this same readtable is shared globally by all software being compiled by ASDF, especially since load and compile-file both bind *readtable*, so that its value is the same across the build at the start of every file (unless overridden by some perform :around method), even if a file locally binds it to a different readtable during the build.

Therefore, the following hygiene restrictions apply. If you don’t abide by these restrictions, there will be situations where your output files will be corrupted during an incremental build. We are not trying to prescribe new restrictions for the sake of good style: these restrictions have always applied implicitly, and we are simply describing what they have always been.

• It is forbidden to modifying any standard character or standard macro dispatch defined in the CLHS.
• No two dependencies may assign different meanings to the same non-standard character.
• Using any non-standard character while expecting the implementation to treat some way counts as such an assignment of meaning.
• libraries need to document these assignments of meaning to non-standard characters.
• free software libraries will register these changes on: http://www.cliki.net/Macro%20Characters

If you want to use readtable modifications that cannot abide by those restrictions, you must create a different readtable object and set *readtable* to temporarily bind it to your new readtable (which will be undone after processing the file).

For that, we recommend you use system named-readtables to define or combine such readtables using named-readtables:defreadtable and use them using named-readtables:in-readtable. Equivalently, you can use system cl-syntax, that itself uses named-readtables, but may someday do more with, e.g. *print-pprint-dispatch*.

For even more advanced syntax modification beyond what a readtable can express, you may consider either:

• a perform method that compiles a constant file that contains a single form #.*code-read-with-alternate-reader* in an environment where this special variable was bound to the code read by your alternate reader, or
• using the system reader-interception.

Beware that it is unsafe to use ASDF from the REPL to compile or load systems while the readtable isn’t the shared readtable previously used to build software. You must manually undo any binding of *readtable* at the REPL and restore its initial value whenever you call operate (via e.g. load-system, test-system or require) from a REPL that is using a different readtable.

13.6.7.1 How should my system use a readtable exported by another system?

Use from the named-readtables system the macro named-readtables:in-readtable.

If the other system fails to use named-readtables, fix it and send a patch upstream. In the day and age of Quicklisp and clbuild, there is little reason to eschew using such an important library anymore.

13.6.7.2 How should my library make a readtable available to other systems?

Use from the named-readtables system the macro named-readtables:defreadtable.