Commit 507f09ee authored by Tobias C. Rittweiler's avatar Tobias C. Rittweiler
Browse files

Fix download & repository url in documentation. Fix :version in .ASD.

Ignore-this: 592a96b5eb2ef35050811e9624b5b6fe

darcs-hash:20091105144458-f5546-7f5a420c77c39900862fca0b52fc65da031de86e.gz
parent 3b0aca72
......@@ -3,8 +3,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>EDITOR-HINTS.NAMED-READTABLES</title>
<style type="text/css">
<title>EDITOR-HINTS.NAMED-READTABLES - 0.9</title><style type="text/css">
pre { padding:5px; background-color:#e0e0e0 }
h3, h4 { text-decoration: underline; }
a { text-decoration: none; padding: 1px 2px 1px 2px; }
......@@ -25,16 +24,21 @@
<body bgcolor=white>
<h2> EDITOR-HINTS.NAMED-READTABLES</h2>
<h2> EDITOR-HINTS.NAMED-READTABLES - 0.9</h2>
<h5>&nbsp;&nbsp;&nbsp;&nbsp; by Tobias C Rittweiler </h5>
<font color=red>Download:</font> <br>&nbsp;<br>
<font color=red>Repository:</font> <br>&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;
<code>darcs get http://common-lisp.net/~trittweiler/darcs/editor-hints/named-readtables/</code> (to be changed)
<code>darcs get darcs get http://common-lisp.net/project/editor-hints/darcs/named-readtables/</code>
<br>&nbsp;<br>
<br>&nbsp;<br><h3><a class=none name="contents">Contents</a></h3>
<font color=red>Download:</font> <br>&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;
<a href="http://common-lisp.net/project/editor-hints/releases/named-readtables-0.9.tar.gz">editor-hints.named-readtables-0.9.tar.gz </a><br>&nbsp;<br><h3><a class=none name="contents">Contents</a></h3>
<ol>
<li> <a href="#what_are_named-readtables?">What are Named-Readtables?</a>
<li> <a href="#notes_on_the_api">Notes on the API</a>
......@@ -68,64 +72,64 @@
&nbsp; &nbsp; Named-Readtables is a library that provides a namespace for readtables akin to the <br> &nbsp; &nbsp; already-existing namespace of packages. In particular:
<ul>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <li>you can associate readtables with names, and retrieve readtables by names;</li>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <li>you can associate source files with readtable names, and be sure that the <br> right readtable is active when compiling/loading the file;</li>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <li>similiarly, your development environment now has a chance to automatically <br> determine what readtable should be active while processing source forms on <br> interactive commands. (E.g. think of `C-c C-c&#039; in Slime [yet to be done])</li>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <li>you can associate source files with readtable names, and be sure that the right readtable is <br> active when compiling/loading the file;</li>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <li>similiarly, your development environment now has a chance to automatically determine what <br> readtable should be active while processing source forms on interactive commands. (E.g. think <br> of `C-c C-c&#039; in Slime [yet to be done])</li>
</ul>
&nbsp; &nbsp; Additionally, it also attempts to become a facility for using readtables in a <br> &nbsp; &nbsp; <u>modular</u> way. In particular:
&nbsp; &nbsp; Additionally, it also attempts to become a facility for using readtables in a <u>modular</u> way. In <br> &nbsp; &nbsp; particular:
<ul>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <li>it provides a macro to specify the content of a readtable at a glance;</li>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <li>it makes it possible to use multiple inheritance between readtables.</li>
</ul>
<br>&nbsp;<br><h3><a class=none name="notes_on_the_api">Notes on the API</a></h3>
&nbsp; &nbsp; The <code>API</code> heavily imitates the <code>API</code> of packages. This has the nice property that any <br> &nbsp; &nbsp; experienced Common Lisper will take it up without effort.
&nbsp; &nbsp; The <code>API</code> heavily imitates the <code>API</code> of packages. This has the nice property that any experienced <br> &nbsp; &nbsp; Common Lisper will take it up without effort.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_defpkg.htm"><code>DEFPACKAGE</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_defpkg.htm"><code>DEFPACKAGE</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#In-Readtable"><code>IN-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_in_pkg.htm"><code>IN-PACKAGE</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#IN-READTABLE"><code>IN-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_in_pkg.htm"><code>IN-PACKAGE</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Merge-Readtables-Into"><code>MERGE-READTABLES-INTO</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_use_pk.htm"><code>USE-PACKAGE</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#MERGE-READTABLES-INTO"><code>MERGE-READTABLES-INTO</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_use_pk.htm"><code>USE-PACKAGE</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Make-Readtable"><code>MAKE-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_mk_pkg.htm"><code>MAKE-PACKAGE</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#MAKE-READTABLE"><code>MAKE-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_mk_pkg.htm"><code>MAKE-PACKAGE</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Unregister-Readtable"><code>UNREGISTER-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_del_pk.htm"><code>DELETE-PACKAGE</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#UNREGISTER-READTABLE"><code>UNREGISTER-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_del_pk.htm"><code>DELETE-PACKAGE</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Rename-Readtable"><code>RENAME-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_rn_pkg.htm"><code>RENAME-PACKAGE</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#RENAME-READTABLE"><code>RENAME-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_rn_pkg.htm"><code>RENAME-PACKAGE</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Find-Readtable"><code>FIND-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_find_p.htm"><code>FIND-PACKAGE</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#FIND-READTABLE"><code>FIND-READTABLE</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_find_p.htm"><code>FIND-PACKAGE</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Readtable-Name"><code>READTABLE-NAME</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_pkg_na.htm"><code>PACKAGE-NAME</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#READTABLE-NAME"><code>READTABLE-NAME</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_pkg_na.htm"><code>PACKAGE-NAME</code></a></code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#List-All-Named-Readtables"><code>LIST-ALL-NAMED-READTABLES</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_list_a.htm"><code>LIST-ALL-PACKAGES</code></a></code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#LIST-ALL-NAMED-READTABLES"><code>LIST-ALL-NAMED-READTABLES</code></a></code> - <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_list_a.htm"><code>LIST-ALL-PACKAGES</code></a></code>
<br>&nbsp;<br><h3><a class=none name="important_api_idiosyncrasies">Important API idiosyncrasies</a></h3>
&nbsp; &nbsp; There are three major differences between the <code>API</code> of Named-Readtables, and the <code>API</code> <br> &nbsp; &nbsp; of packages.
&nbsp; &nbsp; There are three major differences between the <code>API</code> of Named-Readtables, and the <code>API</code> of packages.
<br><br>
&nbsp; &nbsp; &nbsp; <code>1.</code> Readtable names are symbols not strings.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Time has shown that the fact that packages are named by strings causes severe <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; headache because of the potential of package names colliding with each other.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Time has shown that the fact that packages are named by strings causes severe headache because of <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; the potential of package names colliding with each other.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Hence, readtables are named by symbols lest to make the situation worse than it <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; already is. Consequently, readtables named <code>CL-ORACLE:SQL-SYNTAX</code> and <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code>CL-MYSQL:SQL-SYNTAX</code> can happily coexist next to each other. Or, taken to an extreme, <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code>SCHEME:SYNTAX</code> and <code>ELISP:SYNTAX.</code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Hence, readtables are named by symbols lest to make the situation worse than it already is. <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Consequently, readtables named <code>CL-ORACLE:SQL-SYNTAX</code> and <code>CL-MYSQL:SQL-SYNTAX</code> can happily coexist <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; next to each other. Or, taken to an extreme, <code>SCHEME:SYNTAX</code> and <code>ELISP:SYNTAX.</code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If, for example to duly signify the importance of your cool readtable hack, you <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; really think it deserves a global name, you can always resort to keywords.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If, for example to duly signify the importance of your cool readtable hack, you really think it <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; deserves a global name, you can always resort to keywords.
<br><br>
&nbsp; &nbsp; &nbsp; <code>2.</code> The inheritance is resolved statically, not dynamically.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; A package that uses another package will have access to all the other <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; package&#039;s exported symbols, even to those that will be added after its <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; definition. I.e. the inheritance is resolved at run-time, that is dynamically.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; A package that uses another package will have access to all the other package&#039;s exported <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; symbols, even to those that will be added after its definition. I.e. the inheritance is resolved at <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; run-time, that is dynamically.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Unfortunately, we cannot do the same for readtables in a portable manner.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Therefore, we do not talk about &quot;using&quot; another readtable but about <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &quot;merging&quot; the other readtable&#039;s definition into the readtable we are <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; going to define. I.e. the inheritance is resolved once at definition time, that is <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; statically.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Therefore, we do not talk about &quot;using&quot; another readtable but about &quot;merging&quot; <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; the other readtable&#039;s definition into the readtable we are going to define. I.e. the <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; inheritance is resolved once at definition time, that is statically.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; (Such merging can more or less be implemented portably albeit at a certain cost. <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Most of the time, this cost manifests itself at the time a readtable is defined, <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; i.e. once at compile-time, so it may not bother you. Nonetheless, we provide extra <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; support for Sbcl, ClozureCL, and AllegroCL at the moment. Patches for your <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; implementation of choice are welcome, of course.)
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; (Such merging can more or less be implemented portably albeit at a certain cost. Most of the time, <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; this cost manifests itself at the time a readtable is defined, i.e. once at compile-time, so it may <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; not bother you. Nonetheless, we provide extra support for Sbcl, ClozureCL, and AllegroCL at the <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; moment. Patches for your implementation of choice are welcome, of course.)
<br><br>
&nbsp; &nbsp; &nbsp; <code>3.</code> <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> does not have compile-time effects.
&nbsp; &nbsp; &nbsp; <code>3.</code> <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> does not have compile-time effects.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If you define a package via <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_defpkg.htm"><code>DEFPACKAGE</code></a>,</code> you can make that package the currently <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; active package for the subsequent compilation of the same file via <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_in_pkg.htm"><code>IN-PACKAGE</code></a>.</code> The <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; same is, however, not true for <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> and <code><a href="#In-Readtable"><code>IN-READTABLE</code></a></code> for the following <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; reason:
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If you define a package via <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_defpkg.htm"><code>DEFPACKAGE</code></a>,</code> you can make that package the currently active package for <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; the subsequent compilation of the same file via <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/m_in_pkg.htm"><code>IN-PACKAGE</code></a>.</code> The same is, however, not true for <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> and <code><a href="#IN-READTABLE"><code>IN-READTABLE</code></a></code> for the following reason:
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; It&#039;s unlikely that the need for special reader-macros arises for a problem <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; which can be solved in just one file. Most often, you&#039;re going to define the <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; reader macro functions, and set up the corresponding readtable in an extra file.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; It&#039;s unlikely that the need for special reader-macros arises for a problem which can be <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; solved in just one file. Most often, you&#039;re going to define the reader macro functions, and <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; set up the corresponding readtable in an extra file.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> had compile-time effects, you&#039;d have to wrap each definition <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; of a reader-macro function in an <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a></code> to make its definition available at <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; compile-time. Because that&#039;s simply not the common case, <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> does not <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; have a compile-time effect.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> had compile-time effects, you&#039;d have to wrap each definition of a <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; reader-macro function in an <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a></code> to make its definition available at compile-time. Because <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; that&#039;s simply not the common case, <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> does not have a compile-time effect.
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If you want to use a readtable within the same file as its definition, wrap the <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> and the reader-macro function definitions in an explicit <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a>.</code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If you want to use a readtable within the same file as its definition, wrap the <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> and <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; the reader-macro function definitions in an explicit <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a>.</code>
<br>&nbsp;<br><h3><a class=none name="preregistered_readtables">Preregistered Readtables</a></h3>
&nbsp; &nbsp; &nbsp; &nbsp; - <code>NIL,</code> <code>:STANDARD,</code> and <code>:COMMON-LISP</code> designate the <i><a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_s.htm#standard_readtable">standard readtable</a></i>.
<br><br>
......@@ -163,7 +167,7 @@
<br>&nbsp;<br><h3><a class=none name="acknowledgements">Acknowledgements</a></h3>
&nbsp; &nbsp; Thanks to Robert Goldman for making me want to write this library.
<br><br>
&nbsp; &nbsp; Thanks to Stephen Compall, Ariel Badichi, David Lichteblau, Bart Botta, David <br> &nbsp; &nbsp; Crawford, and Pascal Costanza for being early adopters, providing comments and <br> &nbsp; &nbsp; bugfixes.
&nbsp; &nbsp; Thanks to Stephen Compall, Ariel Badichi, David Lichteblau, Bart Botta, David Crawford, and Pascal <br> &nbsp; &nbsp; Costanza for being early adopters, providing comments and bugfixes.
<br>&nbsp;<br>
<br>&nbsp;<br><h3><a class=none name="dictionary">Dictionary</a></h3>
......@@ -175,7 +179,7 @@
SYMBOL)</code></blockquote><blockquote><i>result</i>: <code>READTABLE</code></blockquote>&nbsp;&nbsp;Description:
<blockquote>
Like <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_cp_rdt.htm"><code>COPY-READTABLE</code></a></code> but takes a <code><a href="#Named-Readtable-Designator"><code>NAMED-READTABLE-DESIGNATOR</code></a></code> as argument.
Like <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_cp_rdt.htm"><code>COPY-READTABLE</code></a></code> but takes a <code><a href="#NAMED-READTABLE-DESIGNATOR"><code>NAMED-READTABLE-DESIGNATOR</code></a></code> as argument.
</blockquote>
......@@ -188,47 +192,47 @@ Like <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_cp_rdt.h
<p><br>[Macro]<br><a class=none name='DEFREADTABLE'><b>defreadtable</b> <i>name &amp;body options</i> =&gt; <i>result</i></a><br><br>&nbsp;&nbsp;Description:
<blockquote>
Define a new named readtable, whose name is given by the symbol <i>name</i>. Or, if <br> a readtable is already registered under that name, redefine that one.
Define a new named readtable, whose name is given by the symbol <i>name</i>. Or, if a readtable is <br> already registered under that name, redefine that one.
<br><br>
The readtable can be populated using the following <i>options</i>:
<br><br>
&nbsp; &nbsp; <code>(:MERGE</code> <i>readtable-designators</i>+)
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Merge the readtables designated into the new readtable being defined as per <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="#Merge-Readtables-Into"><code>MERGE-READTABLES-INTO</code></a>.</code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Merge the readtables designated into the new readtable being defined as per <code><a href="#MERGE-READTABLES-INTO"><code>MERGE-READTABLES-INTO</code></a>.</code>
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If no <code>:MERGE</code> clause is given, an empty readtable is used. See <code><a href="#Make-Readtable"><code>MAKE-READTABLE</code></a>.</code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; If no <code>:MERGE</code> clause is given, an empty readtable is used. See <code><a href="#MAKE-READTABLE"><code>MAKE-READTABLE</code></a>.</code>
<br><br>
&nbsp; &nbsp; <code>(:FUZE</code> <i>readtable-designators</i>+)
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Like <code>:MERGE</code> except:
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Error conditions of type <code><a href="#Reader-Macro-Conflict"><code>READER-MACRO-CONFLICT</code></a></code> that are signaled during the merge <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; operation will be silently <u>continued</u>. It follows that reader macros in earlier <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; entries will be overwritten by later ones.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Error conditions of type <code><a href="#READER-MACRO-CONFLICT"><code>READER-MACRO-CONFLICT</code></a></code> that are signaled during the merge operation will <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; be silently <u>continued</u>. It follows that reader macros in earlier entries will be overwritten by <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; later ones.
<br><br>
&nbsp; &nbsp; <code>(:DISPATCH-MACRO-CHAR</code> <i>macro-char</i> <i>sub-char</i> <i>function</i>)
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Define a new sub character <i>sub-char</i> for the dispatching macro character <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>macro-char</i>, per <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_set__1.htm"><code>SET-DISPATCH-MACRO-CHARACTER</code></a>.</code> You probably have to define <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>macro-char</i> as a dispatching macro character by the following option first.
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Define a new sub character <i>sub-char</i> for the dispatching macro character <i>macro-char</i>, <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; per <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_set__1.htm"><code>SET-DISPATCH-MACRO-CHARACTER</code></a>.</code> You probably have to define <i>macro-char</i> as a dispatching <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; macro character by the following option first.
<br><br>
&nbsp; &nbsp; <code>(:MACRO-CHAR</code> <i>macro-char</i> <i>function</i> [<i>non-terminating-p</i>])
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Define a new macro character in the readtable, per <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_set_ma.htm"><code>SET-MACRO-CHARACTER</code></a>.</code> If <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>function</i> is the keyword <code>:DISPATCH,</code> <i>macro-char</i> is made a dispatching <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; macro character, per <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_mk_dis.htm"><code>MAKE-DISPATCH-MACRO-CHARACTER</code></a>.</code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Define a new macro character in the readtable, per <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_set_ma.htm"><code>SET-MACRO-CHARACTER</code></a>.</code> If <i>function</i> is the <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; keyword <code>:DISPATCH,</code> <i>macro-char</i> is made a dispatching macro character, per <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_mk_dis.htm"><code>MAKE-DISPATCH-MACRO-CHARACTER</code></a>.</code>
<br><br>
&nbsp; &nbsp; <code>(:SYNTAX-FROM</code> <i>from-readtable-designator</i> <i>from-char</i> <i>to-char</i>)
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Set the character syntax of <i>to-char</i> in the readtable being defined to the <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; same syntax as <i>from-char</i> as per <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_set_sy.htm"><code>SET-SYNTAX-FROM-CHAR</code></a>.</code>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Set the character syntax of <i>to-char</i> in the readtable being defined to the same syntax as <br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>from-char</i> as per <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/f_set_sy.htm"><code>SET-SYNTAX-FROM-CHAR</code></a>.</code>
<br><br>
&nbsp; &nbsp; <code>(:CASE</code> <i>case-mode</i>)
<br><br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Defines the <i><a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#case_sensitivity_mode">case sensitivity mode</a></i> of the resulting readtable.
<br><br>
Any number of option clauses may appear. The options are grouped by their type, but <br> in each group the order the options appeared textually is preserved. The following <br> groups exist and are executed in the following order: <code>:MERGE</code> and <code>:FUZE</code> (one group), <br> <code>:CASE,</code> <code>:MACRO-CHAR</code> and <code>:DISPATCH-MACRO-CHAR</code> (one group), finally <code>:SYNTAX-FROM.</code>
Any number of option clauses may appear. The options are grouped by their type, but in each group <br> the order the options appeared textually is preserved. The following groups exist and are executed <br> in the following order: <code>:MERGE</code> and <code>:FUZE</code> (one group), <code>:CASE,</code> <code>:MACRO-CHAR</code> and <code>:DISPATCH-MACRO-CHAR</code> <br> (one group), finally <code>:SYNTAX-FROM.</code>
<br><br>
Notes:
<br><br>
&nbsp; &nbsp; The readtable is defined at load-time. If you want to have it available at <br> &nbsp; &nbsp; compilation time <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/a__.htm"><code>-</code></a>-</code> say to use its reader-macros in the same file as its definition <br> &nbsp; &nbsp; <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/a__.htm"><code>-</code></a>-</code> you have to wrap the <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> form in an explicit <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a>.</code>
&nbsp; &nbsp; The readtable is defined at load-time. If you want to have it available at compilation time <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/a__.htm"><code>-</code></a>-</code> say <br> &nbsp; &nbsp; to use its reader-macros in the same file as its definition <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/a__.htm"><code>-</code></a>-</code> you have to wrap the <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> <br> &nbsp; &nbsp; form in an explicit <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a>.</code>
<br><br>
&nbsp; &nbsp; On redefinition, the target readtable is made empty first before it&#039;s refilled <br> &nbsp; &nbsp; according to the clauses.
&nbsp; &nbsp; On redefinition, the target readtable is made empty first before it&#039;s refilled according to <br> &nbsp; &nbsp; the clauses.
<br><br>
&nbsp; &nbsp; <code>NIL,</code> <code>:STANDARD,</code> <code>:COMMON-LISP,</code> <code>:MODERN,</code> and <code>:CURRENT</code> are preregistered readtable <br> &nbsp; &nbsp; names.
&nbsp; &nbsp; <code>NIL,</code> <code>:STANDARD,</code> <code>:COMMON-LISP,</code> <code>:MODERN,</code> and <code>:CURRENT</code> are preregistered readtable names.
</blockquote>
......@@ -245,7 +249,7 @@ Notes:
SYMBOL)</code></blockquote><blockquote><i>result</i>: <code>READTABLE</code></blockquote>&nbsp;&nbsp;Description:
<blockquote>
Looks up the readtable specified by <i>name</i> and returns it if it&#039;s found. <br> If it is not found, it registers the readtable designated by <i>default</i> under <br> the name represented by <i>name</i>; or if no default argument is given, it signals <br> an error of type <code><a href="#Readtable-Does-Not-Exist"><code>READTABLE-DOES-NOT-EXIST</code></a></code> instead.
Looks up the readtable specified by <i>name</i> and returns it if it&#039;s found. If it is not <br> found, it registers the readtable designated by <i>default</i> under the name represented by <br> <i>name</i>; or if no default argument is given, it signals an error of type <br> <code><a href="#READTABLE-DOES-NOT-EXIST"><code>READTABLE-DOES-NOT-EXIST</code></a></code> instead.
</blockquote>
......@@ -262,7 +266,7 @@ Looks up the readtable specified by <i>name</i> and returns it if it&#039;s foun
NULL)</code></blockquote>&nbsp;&nbsp;Description:
<blockquote>
Looks for the readtable specified by <i>name</i> and returns it if it is found. <br> Returns <code>NIL</code> otherwise.
Looks for the readtable specified by <i>name</i> and returns it if it is found. Returns <code>NIL</code> <br> otherwise.
</blockquote>
......@@ -288,7 +292,7 @@ Set <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/v_rdtabl.ht
<p><br>[Function]<br><a class=none name='LIST-ALL-NAMED-READTABLES'><b>list-all-named-readtables</b> <i></i> =&gt; <i>result</i></a><br><br>&nbsp;&nbsp;Argument and Values:<blockquote><i>result</i>: <code>LIST</code></blockquote>&nbsp;&nbsp;Description:
<blockquote>
Returns a list of all registered readtables. The returned list is guaranteed to be <br> fresh, but may contain duplicates.
Returns a list of all registered readtables. The returned list is guaranteed to be fresh, but may <br> contain duplicates.
</blockquote>
......@@ -305,7 +309,7 @@ Returns a list of all registered readtables. The returned list is guaranteed to
Creates and returns a new readtable under the specified <i>name</i>.
<br><br>
<i>merge</i> takes a list of <code><a href="#Named-Readtable-Designators"><code>NAMED-READTABLE-DESIGNATORS</code></a></code> and specifies the <br> readtables the new readtable is created from. (See the <code>:MERGE</code> clause of <code><a href="#Defreadtable"><code>DEFREADTABLE</code></a></code> <br> for details.)
<i>merge</i> takes a list of <code><a href="#NAMED-READTABLE-DESIGNATORS"><code>NAMED-READTABLE-DESIGNATORS</code></a></code> and specifies the readtables the new <br> readtable is created from. (See the <code>:MERGE</code> clause of <code><a href="#DEFREADTABLE"><code>DEFREADTABLE</code></a></code> for details.)
<br><br>
If <i>merge</i> is <code>NIL,</code> an empty readtable is used instead.
<br><br>
......@@ -313,7 +317,7 @@ If <i>name</i> is not given, an anonymous empty readtable is returned.
<br><br>
Notes:
<br><br>
&nbsp; &nbsp; An empty readtable is a readtable where each character&#039;s syntax is the same as <br> &nbsp; &nbsp; in the <i><a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_s.htm#standard_readtable">standard readtable</a></i> except that each macro character has been made a <br> &nbsp; &nbsp; constituent. Basically: whitespace stays whitespace, everything else is constituent.
&nbsp; &nbsp; An empty readtable is a readtable where each character&#039;s syntax is the same as in the <br> &nbsp; &nbsp; <i><a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_s.htm#standard_readtable">standard readtable</a></i> except that each macro character has been made a constituent. Basically: <br> &nbsp; &nbsp; whitespace stays whitespace, everything else is constituent.
</blockquote>
......@@ -330,9 +334,9 @@ Notes:
SYMBOL)</code></blockquote><blockquote><i>result</i>: <code>READTABLE</code></blockquote>&nbsp;&nbsp;Description:
<blockquote>
Copy the contents of each readtable in <i>named-readtables</i> into <br> <i>result-table</i>.
Copy the contents of each readtable in <i>named-readtables</i> into <i>result-table</i>.
<br><br>
If a macro character appears in more than one of the readtables, i.e. if a conflict <br> is discovered during the merge, an error of type <code><a href="#Reader-Macro-Conflict"><code>READER-MACRO-CONFLICT</code></a></code> is signaled.
If a macro character appears in more than one of the readtables, i.e. if a conflict is discovered <br> during the merge, an error of type <code><a href="#READER-MACRO-CONFLICT"><code>READER-MACRO-CONFLICT</code></a></code> is signaled.
</blockquote>
......@@ -360,7 +364,7 @@ Either a symbol or a readtable itself.
Continuable.
<br><br>
This condition is signaled during the merge process if a) a reader macro (be it a <br> macro character or the sub character of a dispatch macro character) is both present <br> in the source as well as the target readtable, and b) if and only if the two <br> respective reader macro functions differ.
This condition is signaled during the merge process if a) a reader macro (be it a macro character <br> or the sub character of a dispatch macro character) is both present in the source as well as the <br> target readtable, and b) if and only if the two respective reader macro functions differ.
</blockquote>
......@@ -428,7 +432,7 @@ Associate <i>readtable</i> with <i>name</i>. Returns the readtable.
SYMBOL)</code></blockquote><blockquote><i>new-name</i>: <code>SYMBOL</code></blockquote><blockquote><i>result</i>: <code>READTABLE</code></blockquote>&nbsp;&nbsp;Description:
<blockquote>
Replaces the associated name of the readtable designated by <i>old-name</i> with <br> <i>new-name</i>. If a readtable is already registered under <i>new-name</i>, an <br> error of type <code><a href="#Readtable-Does-Already-Exist"><code>READTABLE-DOES-ALREADY-EXIST</code></a></code> is signaled.
Replaces the associated name of the readtable designated by <i>old-name</i> with <i>new-name</i>. <br> If a readtable is already registered under <i>new-name</i>, an error of type <br> <code><a href="#READTABLE-DOES-ALREADY-EXIST"><code>READTABLE-DOES-ALREADY-EXIST</code></a></code> is signaled.
</blockquote>
......@@ -440,11 +444,12 @@ Replaces the associated name of the readtable designated by <i>old-name</i> with
<p><br>[Function]<br><a class=none name='UNREGISTER-READTABLE'><b>unregister-readtable</b> <i>named-readtable</i> =&gt; <i>result</i></a><br><br>&nbsp;&nbsp;Argument and Values:<blockquote><i>named-readtable</i>: <code>(OR
READTABLE
SYMBOL)</code></blockquote><blockquote><i>result</i>: <code>(MEMBER T
NIL)</code></blockquote>&nbsp;&nbsp;Description:
SYMBOL)</code></blockquote><blockquote><i>result</i>: <code>(MEMBER
T
NIL)</code></blockquote>&nbsp;&nbsp;Description:
<blockquote>
Remove the association of <i>named-readtable</i>. Returns <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/a_t.htm"><code>T</code></a></code> if successfull, <code>NIL</code> <br> otherwise.
Remove the association of <i>named-readtable</i>. Returns <code><a href="http://www.lispworks.com/reference/HyperSpec/Body/a_t.htm"><code>T</code></a></code> if successfull, <code>NIL</code> otherwise.
</blockquote>
......@@ -454,7 +459,7 @@ Remove the association of <i>named-readtable</i>. Returns <code><a href="http://
<hr>
<p>
This documentation was generated on 2009-9-29 from a Lisp image using some home-brewn,
This documentation was generated on 2009-11-5 from a Lisp image using some home-brewn,
duct-taped, <br> evolutionary hacked extension of Edi Weitz'
<a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a>.
</p>
......
......@@ -14,7 +14,7 @@
(asdf:defsystem :named-readtables
:description "Library that creates a namespace for named readtable akin to the namespace of packages."
:author "Tobias C. Rittweiler <trittweiler@common-lisp.net>"
:version "1.0 (unpublished so far)"
:version "0.9"
:licence "BSD"
:default-component-class asdf::named-readtables-source-file
:components
......@@ -47,4 +47,11 @@
(c (eql (asdf:find-system
:named-readtables-test))))
(let ((*package* (find-package :named-readtables-test)))
(funcall (intern (string '#:do-tests) *package*))))
\ No newline at end of file
(funcall (intern (string '#:do-tests) *package*))))
;; (documentation-template:create-template
;; :named-readtables
;; :target "/home/tcr/src/contributing/named-readtables/doc/named-readtables.html"
;; :version (asdf:component-version (asdf:find-system :named-readtables))
;; :repository "darcs get http://common-lisp.net/project/editor-hints/darcs/named-readtables/"
;; :download-url "http://common-lisp.net/project/editor-hints/releases/named-readtables-0.9.tar.gz")
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment