From f50d6be2192e3ca6193ed2208ab6a9c1c412f09c Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau <tunes@google.com> Date: Sat, 12 Apr 2014 00:28:56 -0400 Subject: [PATCH] Some readtable documentation. --- doc/asdf.texinfo | 48 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index fdfe6e63..94be38e1 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -5401,16 +5401,56 @@ to allow for such a trick. @cindex 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 @code{load} and @code{compile-file} both bind @var{*readtable*}, +so that its value is the same across the build at the start of every file +(unless overridden by some @code{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 possible to configure the lisp syntax by modifying the -currently-active readtable. Unfortunately, CL has very limited support -for controlling the readtable (e.g., there is no @code{IN-READTABLE} the -way there is @code{IN-PACKAGE}). +@itemize +@item It is forbidden to modifying any standard character or standard macro dispatch defined in the CLHS. +@item No two dependencies may assign different meanings to the same non-standard character. +@item Using any non-standard character while expecting the implementation to treat some way + counts as such an assignment of meaning. +@item libraries need to document these assignments of meaning to non-standard characters. +@item free software libraries will register these changes on: + @url{http://www.cliki.net/Macro%20Characters} +@end itemize + +If you want to use readtable modifications that cannot abide by those restrictions, +you @emph{must} create a different readtable object and set @var{*readtable*} +to temporarily bind it to your new readtable (which will be undone after processing the file). +For that, we recommend you use system @code{named-readtables} +to define or combine such readtables using @code{named-readtables:defreadtable} +and use them using @code{named-readtables:in-readtable}. + +For even more advanced syntax modification beyond what a readtable can express, +you may consider either +(1) a perform method that compiles a constant file that contains a single form + @code{#.*code-read-with-alternate-reader*} in an environment where this special variable + was bound to the code read by your alternate reader, or +(2) using the system @code{reader-interception}. + +Beware unless and until the @code{syntax-control} branch is merged, +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 @emph{must} undo any binding of @var{*readtable*} and restore the initial version +whenever you call ASDF from a REPL that isn't canonical. @subsubsection How should my system use a readtable exported by another system? +Use from the @code{named-readtables} system the macro @code{named-readtables:in-readtable}. + @subsubsection How should my library make a readtable available to other systems? +Use from the @code{named-readtables} system the macro @code{named-readtables:defreadtable}. @node ASDF development FAQs, , Issues with using and extending ASDF to define systems, FAQ @section ASDF development FAQs -- GitLab