klisp

an open source interpreter for the Kernel Programming Language.
git clone http://git.hanabi.in/repos/klisp.git
Log | Files | Refs | README

commit b4fef6372f6691b4baf598a4eb6414f696155bc6
parent a0140f0fc439e3e62838788e9c8f54190330158a
Author: Andres Navarro <canavarro82@gmail.com>
Date:   Tue, 31 May 2011 13:16:05 -0300

Added symbol module to the manual. Changed to double spaces after periods.

Diffstat:
Mmanual/html/A-Sample-Applicative-Description.html | 12++++++------
Mmanual/html/Acknowledgements.html | 2+-
Mmanual/html/Caveats.html | 8++++----
Mmanual/html/Conventions.html | 2+-
Mmanual/html/Error-Messages.html | 4++--
Mmanual/html/Evaluation-Notation.html | 4++--
Mmanual/html/Format-of-Descriptions.html | 2+-
Mmanual/html/Index.html | 10++++++++--
Mmanual/html/Introduction.html | 28++++++++++++++--------------
Mmanual/html/Kernel-History.html | 14+++++++-------
Mmanual/html/Printing-Notation.html | 4++--
Mmanual/html/Some-Terms.html | 4++--
Mmanual/html/index.html | 3++-
Mmanual/klisp.info | 196+++++++++++++++++++++++++++++++++++++++++++++++--------------------------------
Mmanual/src/Makefile | 2+-
Mmanual/src/booleans.texi | 30+++++++++++++++---------------
Mmanual/src/equivalence.texi | 6+++---
Mmanual/src/index.texi | 2+-
Mmanual/src/intro.texi | 84++++++++++++++++++++++++++++++++++++++++----------------------------------------
Mmanual/src/klisp.texi | 2++
Amanual/src/symbols.texi | 41+++++++++++++++++++++++++++++++++++++++++
21 files changed, 274 insertions(+), 186 deletions(-)

diff --git a/manual/html/A-Sample-Applicative-Description.html b/manual/html/A-Sample-Applicative-Description.html @@ -34,9 +34,9 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Format-of-Descriptions.html#Format-of-D <p><a name="index-applicative-descriptions-8"></a><a name="index-operative-descriptions-9"></a><a name="index-object-descriptions-10"></a> In an applicative description, the name of the applicative being -described appears first. It is followed on the same line by an +described appears first. It is followed on the same line by an applicative combination that includes the name of the applicative and -the arguments, as would appear in a program. The names used for the +the arguments, as would appear in a program. The names used for the arguments are also used in the body of the description. <p>Here is a description of an imaginary applicative <code>foo</code>: @@ -59,13 +59,13 @@ then adds all the rest of the arguments to the result. <p>Any parameter whose name contains the name of a type (e.g., <var>integer</var>, <var>integer1</var> or <var>continuation</var>) is expected to be of that -type. A plural of a type (such as <var>numbers</var>) often means a list of -objects of that type. Parameters named <var>object</var> may be of any +type. A plural of a type (such as <var>numbers</var>) often means a list of +objects of that type. Parameters named <var>object</var> may be of any type. <!-- TODO add xref types of objects --> (XXX Types of Lisp Object XXX, for a list of Kernel object types.) Parameters with other sorts of names are -discussed specifically in the description of the combiner. In some +discussed specifically in the description of the combiner. In some sections, features common to parameters of several combiners are described at the beginning. @@ -73,7 +73,7 @@ described at the beginning. <!-- TODO clean this up a little --> <p>Operative descriptions have the same format, but the word `Applicative' is replaced by `Operative', and `Argument' is replaced -by `Operand'. Also Operatives always have an environment parameter +by `Operand'. Also Operatives always have an environment parameter (that can be #ignore or a symbol). </body></html> diff --git a/manual/html/Acknowledgements.html b/manual/html/Acknowledgements.html @@ -35,7 +35,7 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introdu <p>This manual was written by Andres Navarro. <p>The structure and some text for this introductory section were -borrowed from the Elisp Manual by the Free Sofware Foundation. This +borrowed from the Elisp Manual by the Free Sofware Foundation. This manual also borrows freely from both the Kernel Report and the Scheme Reports. diff --git a/manual/html/Caveats.html b/manual/html/Caveats.html @@ -34,17 +34,17 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introdu <h3 class="section">1.1 Caveats</h3> -<p>This is the first draft of this manual. It will be incomplete for -some time. It will also evolve, together with klisp and the Kernel +<p>This is the first draft of this manual. It will be incomplete for +some time. It will also evolve, together with klisp and the Kernel Programming Language, both of which, right now, are in a quite fluid state. <!-- this is below, in history --> <p>The main reference on Kernel is the preliminary report: -<cite>Revised(-1) Report on the Kernel Programming Language</cite>. Some +<cite>Revised(-1) Report on the Kernel Programming Language</cite>. Some sections of the report are still incomplete, so both klisp and this manual will use specifications from other languages in these sections, -trying to follow the Kernel spirit. These instances will be documented +trying to follow the Kernel spirit. These instances will be documented throughout the manual. <p>Please mail comments and corrections to diff --git a/manual/html/Conventions.html b/manual/html/Conventions.html @@ -35,7 +35,7 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introdu <h3 class="section">1.3 Conventions</h3> <p>This section explains the notational conventions that are used in this -manual. You may want to skip this section and refer back to it later. +manual. You may want to skip this section and refer back to it later. <ul class="menu"> <li><a accesskey="1" href="Some-Terms.html#Some-Terms">Some Terms</a>: Explanation of terms we use in this manual. diff --git a/manual/html/Error-Messages.html b/manual/html/Error-Messages.html @@ -35,11 +35,11 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventio <h4 class="subsection">1.3.4 Error Messages</h4> <p><a name="index-error-message-notation-6"></a> - Some examples cause errors to be signaled. The report doesn't + Some examples cause errors to be signaled. The report doesn't specify what objects are passed to the error continuation, but in klisp, objects passed to the error continuation are encapsulated error objects that have at least a message and possibly some additional -objects and context informations (such as source code location). In +objects and context informations (such as source code location). In the examples, the error message is shown on a line starting with &lsquo;<samp><span class="samp">error--&gt;</span></samp>&rsquo;. diff --git a/manual/html/Evaluation-Notation.html b/manual/html/Evaluation-Notation.html @@ -35,7 +35,7 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventio <h4 class="subsection">1.3.2 Evaluation Notation</h4> <p><a name="index-evaluation-notation-3"></a><a name="index-documentation-notation-4"></a> - When you evaluate a piece of Kernel code, it produces a result. In the + When you evaluate a piece of Kernel code, it produces a result. In the examples in this manual, this is indicated with &lsquo;<samp><span class="samp">&rArr;</span></samp>&rsquo;: <pre class="example"> (car (cons 1 2)) @@ -45,7 +45,7 @@ examples in this manual, this is indicated with &lsquo;<samp><span class="samp"> <p>The semantics of a language feature are sometimes clarified, or even defined, in its entry by specifying that two expressions are -equivalent. This is notated with &lsquo;<samp><span class="samp">==</span></samp>&rsquo;. For example, the +equivalent. This is notated with &lsquo;<samp><span class="samp">==</span></samp>&rsquo;. For example, the semantics of applicative list* can be defined by following equivalences: <pre class="example"> (list* arg1) == arg1 diff --git a/manual/html/Format-of-Descriptions.html b/manual/html/Format-of-Descriptions.html @@ -34,7 +34,7 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventio <p><a name="index-description-format-7"></a> Applicatives, operatives, and other objects are described in this manual -in a uniform format. The first line of a description contains the +in a uniform format. The first line of a description contains the name of the item followed by its operands or arguments, if any. The description follows on succeeding lines, sometimes with examples. diff --git a/manual/html/Index.html b/manual/html/Index.html @@ -5,7 +5,7 @@ <meta name="description" content="klisp Reference Manual"> <meta name="generator" content="makeinfo 4.13"> <link title="Top" rel="start" href="index.html#Top"> -<link rel="prev" href="Equivalence.html#Equivalence" title="Equivalence"> +<link rel="prev" href="Symbols.html#Symbols" title="Symbols"> <link rel="next" href="../index.html#dir" title="(dir)"> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> <meta http-equiv="Content-Style-Type" content="text/css"> @@ -26,7 +26,7 @@ <a name="Index"></a> <p> Next:&nbsp;<a rel="next" accesskey="n" href="../index.html#dir">(dir)</a>, -Previous:&nbsp;<a rel="previous" accesskey="p" href="Equivalence.html#Equivalence">Equivalence</a>, +Previous:&nbsp;<a rel="previous" accesskey="p" href="Symbols.html#Symbols">Symbols</a>, Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a> <hr> </div> @@ -56,6 +56,10 @@ Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a> <li><a href="A-Sample-Applicative-Description.html#index-operative-descriptions-9">operative descriptions</a>: <a href="A-Sample-Applicative-Description.html#A-Sample-Applicative-Description">A Sample Applicative Description</a></li> <li><a href="Booleans.html#index-or_003f-16"><code>or?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li> <li><a href="Printing-Notation.html#index-printing-notation-5">printing notation</a>: <a href="Printing-Notation.html#Printing-Notation">Printing Notation</a></li> +<li><a href="Symbols.html#index-string_002d_003esymbol-25"><code>string-&gt;symbol</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li> +<li><a href="Symbols.html#index-symbol_002d_003estring-24"><code>symbol-&gt;string</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li> +<li><a href="Symbols.html#index-symbol_003f-23"><code>symbol?</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li> +<li><a href="Symbols.html#index-symbols-22">symbols</a>: <a href="Symbols.html#Symbols">Symbols</a></li> </ul><!-- Print the tables of contents --> <div class="shortcontents"> @@ -65,6 +69,7 @@ Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a> <li><a href="Index.html#toc_Introduction">1 Introduction</a></li> <li><a href="Index.html#toc_Booleans">2 Booleans</a></li> <li><a href="Index.html#toc_Equivalence">3 Equivalence</a></li> +<li><a href="Index.html#toc_Symbols">4 Symbols</a></li> <li><a href="Index.html#toc_Index">Index</a></li> </ul> </div> @@ -92,6 +97,7 @@ Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a> </li></ul> <li><a name="toc_Booleans" href="Booleans.html#Booleans">2 Booleans</a> <li><a name="toc_Equivalence" href="Equivalence.html#Equivalence">3 Equivalence</a> +<li><a name="toc_Symbols" href="Symbols.html#Symbols">4 Symbols</a> <li><a name="toc_Index" href="Index.html#Index">Index</a> </li></ul> </div> diff --git a/manual/html/Introduction.html b/manual/html/Introduction.html @@ -34,29 +34,29 @@ Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a> <h2 class="chapter">1 Introduction</h2> <p>klisp is an open source interpreter for the Kernel Programming -Language. It aims at being comprehensive and robust as specified in +Language. It aims at being comprehensive and robust as specified in the <cite>Revised(-1) Report on the Kernel Programming Language</cite>, but -that probably won't happen for some time. It is written in C99 under -the MIT license. It draws heavily from the Lua interpreter source -code &amp; file structure. It uses the IMath library for arbitrary sized +that probably won't happen for some time. It is written in C99 under +the MIT license. It draws heavily from the Lua interpreter source +code &amp; file structure. It uses the IMath library for arbitrary sized integers and rationals. <p>The Kernel programming language is a statically scoped and properly -tail-recursive dialect of Lisp, descended from Scheme. It is designed +tail-recursive dialect of Lisp, descended from Scheme. It is designed to be simpler and more general than Scheme, with an exceptionally clear, simple, and versatile semantics, only one way to form compound expressions, and no inessential restrictions on the power of that one -compound form. Imperative, functional, and message-passing programming +compound form. Imperative, functional, and message-passing programming styles (to name a few) may be conveniently expressed in Kernel. <p>An important property of Kernel is that all manipulable entities in -Kernel are first-class objects. In particular, Kernel has no +Kernel are first-class objects. In particular, Kernel has no second-class combiners; instead, the roles of special forms and macros are subsumed by operatives, which are first-class, statically scoped -combiners that act directly on their unevaluated operands. Kernel +combiners that act directly on their unevaluated operands. Kernel also has a second type of combiners, applicatives, which act on their -evalu- ated arguments. Applicatives are roughly equivalent to Scheme -procedures. However, an applicative is nothing more than a wrapper to +evalu- ated arguments. Applicatives are roughly equivalent to Scheme +procedures. However, an applicative is nothing more than a wrapper to induce operand evaluation, around an underlying operative (or, in principle, around another applicative, though that isn’t usually done); applicatives themselves are mere facilitators to computation. @@ -65,17 +65,17 @@ done); applicatives themselves are mere facilitators to computation. <a href="http://web.cs.wpi.edu/~jshutt/kernel.html">http://web.cs.wpi.edu/~jshutt/kernel.html</a>. <p>klisp is freely available for both academic and commercial purposes. -See LICENSE for details. it can be downloaded at +See LICENSE for details. it can be downloaded at <a href="http://www.bitbucket.org/AndresNavarro/klisp">http://www.bitbucket.org/AndresNavarro/klisp</a> <p>klisp is developed by Andres Navarro, a Computer Science -undergraduate at Buenos Aires University (UBA). You can reach him at +undergraduate at Buenos Aires University (UBA). You can reach him at <a href="mailto:canavarro82@gmail.com">canavarro82@gmail.com</a>. <p>This manual describes klisp version 0.1, presuming some familiarity with the Lisp family of languages in general, and with the Kernel -Programming Language in particular. There are frequent references to -the Kernel Programming Language Report. Unlike in the report, no +Programming Language in particular. There are frequent references to +the Kernel Programming Language Report. Unlike in the report, no rationale is provided for any feature, only a description of the implemented functionality. diff --git a/manual/html/Kernel-History.html b/manual/html/Kernel-History.html @@ -35,29 +35,29 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introdu <h3 class="section">1.2 Kernel History</h3> <p><a name="index-Kernel-history-1"></a> - The Kernel Programming Language is a work in progress. It is being + The Kernel Programming Language is a work in progress. It is being developed by John N. Shutt, Ph.D, who created it while studying at the -Worcester Polytechnic Institute (I think about 2002, or so... ASK). It +Worcester Polytechnic Institute (I think about 2002, or so... ASK). It is descended from scheme, with the idea that all objects should be -first class values. In particular, Kernel replaces macros with +first class values. In particular, Kernel replaces macros with operatives (kinda like statically scoped fexprs and fsubrs) and has -first class environments. Kernel also has the notion of encapsulated +first class environments. Kernel also has the notion of encapsulated objects which limits the ammount of information an implementation can share with a Kernel program (e.g. There is no way in Kernel to get the parents or a complete list of bindings of an environment object). <!-- this is repeated above, in caveats --> <p>The main reference on Kernel is the preliminary report: -<cite>Revised(-1) Report on the Kernel Programming Language</cite>. Some +<cite>Revised(-1) Report on the Kernel Programming Language</cite>. Some sections of the report are still incomplete, so both klisp and this manual will use specifications from other languages in these sections, -trying to follow the Kernel spirit. These instances will be documented +trying to follow the Kernel spirit. These instances will be documented throughout the manual. <p>You can read all about Kernel at John's homepage at WPI <a href="http://www.cs.wpi.edu/~jshutt/">http://www.cs.wpi.edu/~jshutt/</a>, including the preliminary report on the language and his doctoral dissertation which gives a -theorethical frame for fexprs. You can contact him at +theorethical frame for fexprs. You can contact him at <a href="mailto:jshutt@cs.wpi.edu">jshutt@cs.wpi.edu</a>. </body></html> diff --git a/manual/html/Printing-Notation.html b/manual/html/Printing-Notation.html @@ -36,8 +36,8 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventio <p><a name="index-printing-notation-5"></a> Many of the examples in this manual print text when they are -evaluated. In examples that print text, the printed text is indicated with -&lsquo;<samp><span class="samp">-|</span></samp>&rsquo;. The value returned by evaluating the form (here +evaluated. In examples that print text, the printed text is indicated with +&lsquo;<samp><span class="samp">-|</span></samp>&rsquo;. The value returned by evaluating the form (here <code>#t</code>) follows on a separate line. <pre class="example"> ($sequence (write 1) (write 2) #t) diff --git a/manual/html/Some-Terms.html b/manual/html/Some-Terms.html @@ -38,12 +38,12 @@ Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventio printer&rdquo; are used to refer to those routines in Lisp that convert textual representations of Kernel objects into actual objects, and <!-- TODO xref to printed representations --> -vice versa. XXX Printed Representation XXX, for more details. You, the +vice versa. XXX Printed Representation XXX, for more details. You, the person reading this manual, are assumed to be &ldquo;the programmer&rdquo; or &ldquo;the user&rdquo;. <p><a name="index-fonts-2"></a> Examples of Kernel code appear in this font or form: <code>(list 1 2 -3)</code>. Names that represent arguments or metasyntactic variables appear +3)</code>. Names that represent arguments or metasyntactic variables appear in this font or form: <var>first-number</var>. </body></html> diff --git a/manual/html/index.html b/manual/html/index.html @@ -40,8 +40,9 @@ Up:&nbsp;<a rel="up" accesskey="u" href="../index.html#dir">(dir)</a> <li><a accesskey="3" href="Booleans.html#Booleans">Booleans</a>: Boolean module features. <li><a accesskey="4" href="Equivalence.html#Equivalence">Equivalence</a>: Equivalence under mutation &amp; Equivalence up to mutation module features. +<li><a accesskey="5" href="Symbols.html#Symbols">Symbols</a>: Symbol module features. <!-- TODO complete --> -<li><a accesskey="5" href="Index.html#Index">Index</a>: Index including concepts, functions, variables, +<li><a accesskey="6" href="Index.html#Index">Index</a>: Index including concepts, functions, variables, and other terms. <!-- Appendices --> diff --git a/manual/klisp.info b/manual/klisp.info @@ -29,6 +29,7 @@ in part. * Booleans:: Boolean module features. * Equivalence:: Equivalence under mutation & Equivalence up to mutation module features. +* Symbols:: Symbol module features. * Index:: Index including concepts, functions, variables, and other terms. @@ -78,29 +79,29 @@ File: klisp.info, Node: Introduction, Next: Booleans, Prev: License, Up: Top ************** klisp is an open source interpreter for the Kernel Programming -Language. It aims at being comprehensive and robust as specified in the -`Revised(-1) Report on the Kernel Programming Language', but that -probably won't happen for some time. It is written in C99 under the MIT -license. It draws heavily from the Lua interpreter source code & file -structure. It uses the IMath library for arbitrary sized integers and -rationals. +Language. It aims at being comprehensive and robust as specified in +the `Revised(-1) Report on the Kernel Programming Language', but that +probably won't happen for some time. It is written in C99 under the +MIT license. It draws heavily from the Lua interpreter source code & +file structure. It uses the IMath library for arbitrary sized integers +and rationals. The Kernel programming language is a statically scoped and properly -tail-recursive dialect of Lisp, descended from Scheme. It is designed +tail-recursive dialect of Lisp, descended from Scheme. It is designed to be simpler and more general than Scheme, with an exceptionally clear, simple, and versatile semantics, only one way to form compound expressions, and no inessential restrictions on the power of that one -compound form. Imperative, functional, and message-passing programming +compound form. Imperative, functional, and message-passing programming styles (to name a few) may be conveniently expressed in Kernel. An important property of Kernel is that all manipulable entities in -Kernel are first-class objects. In particular, Kernel has no +Kernel are first-class objects. In particular, Kernel has no second-class combiners; instead, the roles of special forms and macros are subsumed by operatives, which are first-class, statically scoped -combiners that act directly on their unevaluated operands. Kernel also +combiners that act directly on their unevaluated operands. Kernel also has a second type of combiners, applicatives, which act on their evalu- -ated arguments. Applicatives are roughly equivalent to Scheme -procedures. However, an applicative is nothing more than a wrapper to +ated arguments. Applicatives are roughly equivalent to Scheme +procedures. However, an applicative is nothing more than a wrapper to induce operand evaluation, around an underlying operative (or, in principle, around another applicative, though that isn’t usually done); applicatives themselves are mere facilitators to computation. @@ -109,17 +110,17 @@ applicatives themselves are mere facilitators to computation. `http://web.cs.wpi.edu/~jshutt/kernel.html'. klisp is freely available for both academic and commercial purposes. -See LICENSE for details. it can be downloaded at +See LICENSE for details. it can be downloaded at `http://www.bitbucket.org/AndresNavarro/klisp' klisp is developed by Andres Navarro, a Computer Science -undergraduate at Buenos Aires University (UBA). You can reach him at +undergraduate at Buenos Aires University (UBA). You can reach him at <canavarro82@gmail.com>. This manual describes klisp version 0.1, presuming some familiarity with the Lisp family of languages in general, and with the Kernel -Programming Language in particular. There are frequent references to -the Kernel Programming Language Report. Unlike in the report, no +Programming Language in particular. There are frequent references to +the Kernel Programming Language Report. Unlike in the report, no rationale is provided for any feature, only a description of the implemented functionality. @@ -138,16 +139,16 @@ File: klisp.info, Node: Caveats, Next: Kernel History, Prev: Introduction, U 1.1 Caveats =========== -This is the first draft of this manual. It will be incomplete for some -time. It will also evolve, together with klisp and the Kernel +This is the first draft of this manual. It will be incomplete for some +time. It will also evolve, together with klisp and the Kernel Programming Language, both of which, right now, are in a quite fluid state. The main reference on Kernel is the preliminary report: `Revised(-1) -Report on the Kernel Programming Language'. Some sections of the report -are still incomplete, so both klisp and this manual will use +Report on the Kernel Programming Language'. Some sections of the +report are still incomplete, so both klisp and this manual will use specifications from other languages in these sections, trying to follow -the Kernel spirit. These instances will be documented throughout the +the Kernel spirit. These instances will be documented throughout the manual. Please mail comments and corrections to <canavarro82@gmail.com>. @@ -161,28 +162,28 @@ File: klisp.info, Node: Kernel History, Next: Conventions, Prev: Caveats, Up 1.2 Kernel History ================== -The Kernel Programming Language is a work in progress. It is being +The Kernel Programming Language is a work in progress. It is being developed by John N. Shutt, Ph.D, who created it while studying at the -Worcester Polytechnic Institute (I think about 2002, or so... ASK). It +Worcester Polytechnic Institute (I think about 2002, or so... ASK). It is descended from scheme, with the idea that all objects should be -first class values. In particular, Kernel replaces macros with +first class values. In particular, Kernel replaces macros with operatives (kinda like statically scoped fexprs and fsubrs) and has -first class environments. Kernel also has the notion of encapsulated +first class environments. Kernel also has the notion of encapsulated objects which limits the ammount of information an implementation can share with a Kernel program (e.g. There is no way in Kernel to get the parents or a complete list of bindings of an environment object). The main reference on Kernel is the preliminary report: `Revised(-1) -Report on the Kernel Programming Language'. Some sections of the report -are still incomplete, so both klisp and this manual will use +Report on the Kernel Programming Language'. Some sections of the +report are still incomplete, so both klisp and this manual will use specifications from other languages in these sections, trying to follow -the Kernel spirit. These instances will be documented throughout the +the Kernel spirit. These instances will be documented throughout the manual. You can read all about Kernel at John's homepage at WPI `http://www.cs.wpi.edu/~jshutt/', including the preliminary report on the language and his doctoral dissertation which gives a theorethical -frame for fexprs. You can contact him at <jshutt@cs.wpi.edu>. +frame for fexprs. You can contact him at <jshutt@cs.wpi.edu>.  File: klisp.info, Node: Conventions, Next: Acknowledgements, Prev: Kernel History, Up: Introduction @@ -191,7 +192,7 @@ File: klisp.info, Node: Conventions, Next: Acknowledgements, Prev: Kernel His =============== This section explains the notational conventions that are used in this -manual. You may want to skip this section and refer back to it later. +manual. You may want to skip this section and refer back to it later. * Menu: @@ -210,7 +211,7 @@ File: klisp.info, Node: Some Terms, Next: Evaluation Notation, Prev: Conventi Throughout this manual, the phrases "the Kernel reader" and "the Kernel printer" are used to refer to those routines in Lisp that convert textual representations of Kernel objects into actual objects, and vice -versa. XXX Printed Representation XXX, for more details. You, the +versa. XXX Printed Representation XXX, for more details. You, the person reading this manual, are assumed to be "the programmer" or "the user". @@ -224,7 +225,7 @@ File: klisp.info, Node: Evaluation Notation, Next: Printing Notation, Prev: S 1.3.2 Evaluation Notation ------------------------- -When you evaluate a piece of Kernel code, it produces a result. In the +When you evaluate a piece of Kernel code, it produces a result. In the examples in this manual, this is indicated with `=>': (car (cons 1 2)) @@ -234,7 +235,7 @@ You can read this as "`(car (cons 1 2))' evaluates to 1". The semantics of a language feature are sometimes clarified, or even defined, in its entry by specifying that two expressions are -equivalent. This is notated with `=='. For example, the semantics of +equivalent. This is notated with `=='. For example, the semantics of applicative list* can be defined by following equivalences: (list* arg1) == arg1 (list* arg1 . more-args) == (cons arg1 (list* . more-args)) @@ -261,11 +262,11 @@ File: klisp.info, Node: Error Messages, Next: Format of Descriptions, Prev: P 1.3.4 Error Messages -------------------- -Some examples cause errors to be signaled. The report doesn't specify +Some examples cause errors to be signaled. The report doesn't specify what objects are passed to the error continuation, but in klisp, objects passed to the error continuation are encapsulated error objects that have at least a message and possibly some additional objects and -context informations (such as source code location). In the examples, +context informations (such as source code location). In the examples, the error message is shown on a line starting with `error-->'. (+ 23 #t) @@ -278,7 +279,7 @@ File: klisp.info, Node: Format of Descriptions, Prev: Error Messages, Up: Con ---------------------------- Applicatives, operatives, and other objects are described in this manual -in a uniform format. The first line of a description contains the name +in a uniform format. The first line of a description contains the name of the item followed by its operands or arguments, if any. The category--operative, applicative, or whatever--appears at the beginning of the line. The description follows on succeeding lines, sometimes @@ -295,9 +296,9 @@ File: klisp.info, Node: A Sample Applicative Description, Prev: Format of Desc ........................................ In an applicative description, the name of the applicative being -described appears first. It is followed on the same line by an +described appears first. It is followed on the same line by an applicative combination that includes the name of the applicative and -the arguments, as would appear in a program. The names used for the +the arguments, as would appear in a program. The names used for the arguments are also used in the body of the description. Here is a description of an imaginary applicative `foo': @@ -316,8 +317,8 @@ arguments are also used in the body of the description. (+ (- X W) Y...) Any parameter whose name contains the name of a type (e.g., INTEGER, -INTEGER1 or CONTINUATION) is expected to be of that type. A plural of a -type (such as NUMBERS) often means a list of objects of that type. +INTEGER1 or CONTINUATION) is expected to be of that type. A plural of +a type (such as NUMBERS) often means a list of objects of that type. Parameters named OBJECT may be of any type. (XXX Types of Lisp Object XXX, for a list of Kernel object types.) Parameters with other sorts of names are discussed specifically in the description of the combiner. @@ -326,7 +327,7 @@ described at the beginning. Operative descriptions have the same format, but the word `Applicative' is replaced by `Operative', and `Argument' is replaced -by `Operand'. Also Operatives always have an environment parameter +by `Operand'. Also Operatives always have an environment parameter (that can be #ignore or a symbol).  @@ -338,7 +339,7 @@ File: klisp.info, Node: Acknowledgements, Prev: Conventions, Up: Introduction This manual was written by Andres Navarro. The structure and some text for this introductory section were -borrowed from the Elisp Manual by the Free Sofware Foundation. This +borrowed from the Elisp Manual by the Free Sofware Foundation. This manual also borrows freely from both the Kernel Report and the Scheme Reports. @@ -354,8 +355,8 @@ There are no possible mutations of either of these two values, and the boolean type is encapsulated. -- Applicative: boolean? (boolean? . objects) - The primitive type predicate for type boolean. `boolean?' returns - true iff all the objects in list are of type boolean. + The primitive type predicate for type boolean. `boolean?' returns + true iff all the objects in `objects' are of type boolean. -- Applicative: not? (not? boolean) Applicative `not?' is a predicate that returns the logical @@ -371,40 +372,40 @@ boolean type is encapsulated. -- Operative: $and? ($and? . list) The `$and?' operative performs a "short-circuit and" of its - operands. It evaluates them from left to right, until either an - operand evaluates to false, or the end of the list is reached. If + operands. It evaluates them from left to right, until either an + operand evaluates to false, or the end of the list is reached. If the end of the list is reached (which is immediate if `list' is - `nil'), the operative returns true. If an operand evaluates to + `nil'), the operative returns true. If an operand evaluates to false, no further operand evaluations are performed, and the - operative returns false. If `list' is acyclic, and the last - operand is evaluated, it is evaluated as a tail context. If `list' - is cyclic, an unbounded number of operand evaluations may be - performed. If any of the operands evaluates to a non-boolean + operative returns false. If `list' is acyclic, and the last + operand is evaluated, it is evaluated as a tail context. If + `list' is cyclic, an unbounded number of operand evaluations may be + performed. If any of the operands evaluates to a non-boolean value, an error is signaled (even if it's the last one). -- Operative: $or? ($or? . list) The `$or?' operative performs a "short-circuit or" of its - operands. It evaluates them from left to right, until either an - operand evaluates to true, or the end of the list is reached. If + operands. It evaluates them from left to right, until either an + operand evaluates to true, or the end of the list is reached. If the end of the list is reached (which is immediate if `list' is - `nil'), the operative returns false. If an operand evaluates to + `nil'), the operative returns false. If an operand evaluates to true, no further operand evaluations are performed, and the - operative returns true. If `list' is acyclic, and the last operand - is evaluated, it is evaluated as a tail context. If `list' is - cyclic, an unbounded number of operand evaluations may be - performed. If any of the operands evaluates to a non-boolean + operative returns true. If `list' is acyclic, and the last + operand is evaluated, it is evaluated as a tail context. If + `list' is cyclic, an unbounded number of operand evaluations may be + performed. If any of the operands evaluates to a non-boolean value, an error is signaled (even if it's the last one).  -File: klisp.info, Node: Equivalence, Next: Index, Prev: Booleans, Up: Top +File: klisp.info, Node: Equivalence, Next: Symbols, Prev: Booleans, Up: Top 3 Equivalence ************* Kernel has two general-purpose equivalence predicates (whereas R5RS -Scheme has three). The two Kernel predicates correspond to the abstract -notions of equivalence up to mutation (`equal') and equivalence in the -presence of mutation (`eq?'). +Scheme has three). The two Kernel predicates correspond to the +abstract notions of equivalence up to mutation (`equal') and +equivalence in the presence of mutation (`eq?'). -- Applicative: eq? (eq? . objects) Predicate `eq?' returns true iff all of `objects' are effectively @@ -412,12 +413,44 @@ presence of mutation (`eq?'). -- Applicative: equal? (equal? . objects) Predicate `equal?' returns true iff all of `objects' "look" the - same as long as nothing is mutated. This is a weaker predicate + same as long as nothing is mutated. This is a weaker predicate than `eq?'; that is, `equal?' must return true whenever `eq?' would return true.  -File: klisp.info, Node: Index, Next: (dir), Prev: Equivalence, Up: Top +File: klisp.info, Node: Symbols, Next: Index, Prev: Equivalence, Up: Top + +4 Symbols +********* + +Two symbols are eq? iff they have the same external representation. +Symbols are immutable, and the symbol type is encapsulated. The +external representations of symbols are usually identifiers. However, +symbols with other external representations may be created. + + -- Applicative: symbol? (symbol? . objects) + The primitive type predicate for type symbol. `symbol?' returns + true iff all the objects in `objects' are of type symbol. + + -- Applicative: symbol->string (symbol->string symbol) + Applicative `symbol->string' returns the name of `symbol' as a + string. The string returned is immutable. + + -- Applicative: string->symbol (string->symbol string) + Applicative `string->symbol' returns the symbol with name + `string'. The symbol is always interned, which means, that it is + always the case that: + (eq? <symbol> (string->symbol (symbol->string <symbol>))) + => #t + `string->symbol' can create symbols whose external + representation aren't identifiers. Right now klisp uses an + output-only representation, but in the near future it will + probably include some kind of escaping mechanism to allow + arbitrary symbols to have readable external representations as in + R7RS Scheme. + + +File: klisp.info, Node: Index, Next: (dir), Prev: Symbols, Up: Top Index ***** @@ -451,25 +484,30 @@ Index (line 6) * or?: Booleans. (line 24) * printing notation: Printing Notation. (line 6) +* string->symbol: Symbols. (line 20) +* symbol->string: Symbols. (line 16) +* symbol?: Symbols. (line 12) +* symbols: Symbols. (line 6)  Tag Table: Node: Top302 -Node: License1025 -Node: Introduction2696 -Node: Caveats5505 -Node: Kernel History6287 -Node: Conventions7725 -Node: Some Terms8395 -Node: Evaluation Notation9064 -Node: Printing Notation9805 -Node: Error Messages10281 -Node: Format of Descriptions10927 -Node: A Sample Applicative Description11490 -Node: Acknowledgements13146 -Node: Booleans13531 -Node: Equivalence16039 -Node: Index16828 +Node: License1077 +Node: Introduction2748 +Node: Caveats5571 +Node: Kernel History6357 +Node: Conventions7802 +Node: Some Terms8473 +Node: Evaluation Notation9144 +Node: Printing Notation9888 +Node: Error Messages10364 +Node: Format of Descriptions11012 +Node: A Sample Applicative Description11576 +Node: Acknowledgements13236 +Node: Booleans13622 +Node: Equivalence16148 +Node: Symbols16941 +Node: Index18304  End Tag Table diff --git a/manual/src/Makefile b/manual/src/Makefile @@ -2,7 +2,7 @@ # some of this is from the elisp manual srcs = klisp.texi intro.texi \ - index.texi + index.texi booleans.texi equivalence.texi symbols.texi #TODO add dvi/pdf output #TODO check what happens with xrefs diff --git a/manual/src/booleans.texi b/manual/src/booleans.texi @@ -9,13 +9,13 @@ The boolean data type consists of two values, which are called true and false, and have respectively external representations @code{#t} -and @code{#f}. There are no possible mutations of either of these two +and @code{#f}. There are no possible mutations of either of these two @c add encapsulated cross ref values, and the boolean type is encapsulated. @deffn Applicative boolean? (boolean? . objects) - The primitive type predicate for type boolean. @code{boolean?} -returns true iff all the objects in list are of type boolean. + The primitive type predicate for type boolean. @code{boolean?} +returns true iff all the objects in @code{objects} are of type boolean. @end deffn @deffn Applicative not? (not? boolean) @@ -35,31 +35,31 @@ or more of its arguments are true. @deffn Operative $and? ($and? . list) The @code{$and?} operative performs a ``short-circuit and'' of its -operands. It evaluates them from left to right, until either an -operand evaluates to false, or the end of the list is reached. If the +operands. It evaluates them from left to right, until either an +operand evaluates to false, or the end of the list is reached. If the end of the list is reached (which is immediate if @code{list} is -@code{nil}), the operative returns true. If an operand evaluates to +@code{nil}), the operative returns true. If an operand evaluates to false, no further operand evaluations are performed, and the operative -returns false. If @code{list} is acyclic, and the last operand is +returns false. If @code{list} is acyclic, and the last operand is @c TODO cross ref tail-contect -evaluated, it is evaluated as a tail context. If @code{list} is +evaluated, it is evaluated as a tail context. If @code{list} is cyclic, an unbounded number of operand evaluations may be -performed. If any of the operands evaluates to a non-boolean value, an +performed. If any of the operands evaluates to a non-boolean value, an error is signaled (even if it's the last one). @end deffn @deffn Operative $or? ($or? . list) The @code{$or?} operative performs a ``short-circuit or'' of its -operands. It evaluates them from left to right, until either an -operand evaluates to true, or the end of the list is reached. If the +operands. It evaluates them from left to right, until either an +operand evaluates to true, or the end of the list is reached. If the end of the list is reached (which is immediate if @code{list} is -@code{nil}), the operative returns false. If an operand evaluates to +@code{nil}), the operative returns false. If an operand evaluates to true, no further operand evaluations are performed, and the operative -returns true. If @code{list} is acyclic, and the last operand is +returns true. If @code{list} is acyclic, and the last operand is @c TODO cross ref tail-contect -evaluated, it is evaluated as a tail context. If @code{list} is +evaluated, it is evaluated as a tail context. If @code{list} is cyclic, an unbounded number of operand evaluations may be -performed. If any of the operands evaluates to a non-boolean value, an +performed. If any of the operands evaluates to a non-boolean value, an error is signaled (even if it's the last one). @end deffn diff --git a/manual/src/equivalence.texi b/manual/src/equivalence.texi @@ -1,14 +1,14 @@ @c -*-texinfo-*- @setfilename ../src/equivalence -@node Equivalence, Index, Booleans, Top +@node Equivalence, Symbols, Booleans, Top @comment node-name, next, previous, up @chapter Equivalence @cindex equivalence Kernel has two general-purpose equivalence predicates (whereas R5RS -Scheme has three). The two Kernel predicates correspond to the +Scheme has three). The two Kernel predicates correspond to the abstract notions of equivalence up to mutation (@code{equal}) and equivalence in the presence of mutation (@code{eq?}). @@ -20,7 +20,7 @@ effectively the same object, even in the presence of mutation. @deffn Applicative equal? (equal? . objects) Predicate @code{equal?} returns true iff all of @code{objects} -``look'' the same as long as nothing is mutated. This is a weaker +``look'' the same as long as nothing is mutated. This is a weaker predicate than @code{eq?}; that is, @code{equal?} must return true whenever @code{eq?} would return true. @c todo maybe add more content here, specifical to klisp diff --git a/manual/src/index.texi b/manual/src/index.texi @@ -2,7 +2,7 @@ @setfilename ../src/index @c TODO correct prev node -@node Index, (dir), Equivalence, Top +@node Index, (dir), Symbols, Top @c this is from the elisp manual... Should read a little about this. @unnumbered Index diff --git a/manual/src/intro.texi b/manual/src/intro.texi @@ -46,29 +46,29 @@ THE SOFTWARE. @chapter Introduction klisp is an open source interpreter for the Kernel Programming -Language. It aims at being comprehensive and robust as specified in +Language. It aims at being comprehensive and robust as specified in the @cite{Revised(-1) Report on the Kernel Programming Language}, but -that probably won't happen for some time. It is written in C99 under -the MIT license. It draws heavily from the Lua interpreter source -code & file structure. It uses the IMath library for arbitrary sized +that probably won't happen for some time. It is written in C99 under +the MIT license. It draws heavily from the Lua interpreter source +code & file structure. It uses the IMath library for arbitrary sized integers and rationals. The Kernel programming language is a statically scoped and properly -tail-recursive dialect of Lisp, descended from Scheme. It is designed +tail-recursive dialect of Lisp, descended from Scheme. It is designed to be simpler and more general than Scheme, with an exceptionally clear, simple, and versatile semantics, only one way to form compound expressions, and no inessential restrictions on the power of that one -compound form. Imperative, functional, and message-passing programming +compound form. Imperative, functional, and message-passing programming styles (to name a few) may be conveniently expressed in Kernel. An important property of Kernel is that all manipulable entities in -Kernel are first-class objects. In particular, Kernel has no +Kernel are first-class objects. In particular, Kernel has no second-class combiners; instead, the roles of special forms and macros are subsumed by operatives, which are first-class, statically scoped -combiners that act directly on their unevaluated operands. Kernel +combiners that act directly on their unevaluated operands. Kernel also has a second type of combiners, applicatives, which act on their -evalu- ated arguments. Applicatives are roughly equivalent to Scheme -procedures. However, an applicative is nothing more than a wrapper to +evalu- ated arguments. Applicatives are roughly equivalent to Scheme +procedures. However, an applicative is nothing more than a wrapper to induce operand evaluation, around an underlying operative (or, in principle, around another applicative, though that isn’t usually done); applicatives themselves are mere facilitators to computation. @@ -77,17 +77,17 @@ done); applicatives themselves are mere facilitators to computation. @url{http://web.cs.wpi.edu/~jshutt/kernel.html}. klisp is freely available for both academic and commercial purposes. -See LICENSE for details. it can be downloaded at +See LICENSE for details. it can be downloaded at @url{http://www.bitbucket.org/AndresNavarro/klisp} klisp is developed by Andres Navarro, a Computer Science -undergraduate at Buenos Aires University (UBA). You can reach him at +undergraduate at Buenos Aires University (UBA). You can reach him at @email{canavarro82@@gmail.com}. This manual describes klisp version 0.1, presuming some familiarity with the Lisp family of languages in general, and with the Kernel -Programming Language in particular. There are frequent references to -the Kernel Programming Language Report. Unlike in the report, no +Programming Language in particular. There are frequent references to +the Kernel Programming Language Report. Unlike in the report, no rationale is provided for any feature, only a description of the implemented functionality. @@ -103,17 +103,17 @@ implemented functionality. @node Caveats, Kernel History, Introduction, Introduction @section Caveats - This is the first draft of this manual. It will be incomplete for -some time. It will also evolve, together with klisp and the Kernel + This is the first draft of this manual. It will be incomplete for +some time. It will also evolve, together with klisp and the Kernel Programming Language, both of which, right now, are in a quite fluid state. @c this is below, in history The main reference on Kernel is the preliminary report: -@cite{Revised(-1) Report on the Kernel Programming Language}. Some +@cite{Revised(-1) Report on the Kernel Programming Language}. Some sections of the report are still incomplete, so both klisp and this manual will use specifications from other languages in these sections, -trying to follow the Kernel spirit. These instances will be documented +trying to follow the Kernel spirit. These instances will be documented throughout the manual. Please mail comments and corrections to @@ -128,36 +128,36 @@ Please mail comments and corrections to @section Kernel History @cindex Kernel history - The Kernel Programming Language is a work in progress. It is being + The Kernel Programming Language is a work in progress. It is being developed by John N. Shutt, Ph.D, who created it while studying at the -Worcester Polytechnic Institute (I think about 2002, or so... ASK). It +Worcester Polytechnic Institute (I think about 2002, or so... ASK). It is descended from scheme, with the idea that all objects should be -first class values. In particular, Kernel replaces macros with +first class values. In particular, Kernel replaces macros with operatives (kinda like statically scoped fexprs and fsubrs) and has -first class environments. Kernel also has the notion of encapsulated +first class environments. Kernel also has the notion of encapsulated objects which limits the ammount of information an implementation can share with a Kernel program (e.g. There is no way in Kernel to get the parents or a complete list of bindings of an environment object). @c this is repeated above, in caveats The main reference on Kernel is the preliminary report: -@cite{Revised(-1) Report on the Kernel Programming Language}. Some +@cite{Revised(-1) Report on the Kernel Programming Language}. Some sections of the report are still incomplete, so both klisp and this manual will use specifications from other languages in these sections, -trying to follow the Kernel spirit. These instances will be documented +trying to follow the Kernel spirit. These instances will be documented throughout the manual. You can read all about Kernel at John's homepage at WPI @url{http://www.cs.wpi.edu/~jshutt/}, including the preliminary report on the language and his doctoral dissertation which gives a -theorethical frame for fexprs. You can contact him at +theorethical frame for fexprs. You can contact him at @email{jshutt@@cs.wpi.edu}. @node Conventions, Acknowledgements, Kernel History, Introduction @section Conventions This section explains the notational conventions that are used in this -manual. You may want to skip this section and refer back to it later. +manual. You may want to skip this section and refer back to it later. @menu * Some Terms:: Explanation of terms we use in this manual. @@ -176,13 +176,13 @@ manual. You may want to skip this section and refer back to it later. printer'' are used to refer to those routines in Lisp that convert textual representations of Kernel objects into actual objects, and @c TODO xref to printed representations -vice versa. XXX Printed Representation XXX, for more details. You, the +vice versa. XXX Printed Representation XXX, for more details. You, the person reading this manual, are assumed to be ``the programmer'' or ``the user''. @cindex fonts Examples of Kernel code appear in this font or form: @code{(list 1 2 -3)}. Names that represent arguments or metasyntactic variables appear +3)}. Names that represent arguments or metasyntactic variables appear in this font or form: @var{first-number}. @node Evaluation Notation, Printing Notation, Some Terms, Conventions @@ -190,7 +190,7 @@ in this font or form: @var{first-number}. @cindex evaluation notation @cindex documentation notation - When you evaluate a piece of Kernel code, it produces a result. In the + When you evaluate a piece of Kernel code, it produces a result. In the examples in this manual, this is indicated with @samp{@result{}}: @example @@ -203,7 +203,7 @@ You can read this as ``@code{(car (cons 1 2))} evaluates to 1''. The semantics of a language feature are sometimes clarified, or even defined, in its entry by specifying that two expressions are -equivalent. This is notated with @samp{@equiv{}}. For example, the +equivalent. This is notated with @samp{@equiv{}}. For example, the semantics of applicative list* can be defined by following equivalences: @example @@ -216,8 +216,8 @@ equivalences: @cindex printing notation Many of the examples in this manual print text when they are -evaluated. In examples that print text, the printed text is indicated with -@samp{@print{}}. The value returned by evaluating the form (here +evaluated. In examples that print text, the printed text is indicated with +@samp{@print{}}. The value returned by evaluating the form (here @code{#t}) follows on a separate line. @group @@ -233,11 +233,11 @@ evaluated. In examples that print text, the printed text is indicated with @subsection Error Messages @cindex error message notation - Some examples cause errors to be signaled. The report doesn't + Some examples cause errors to be signaled. The report doesn't specify what objects are passed to the error continuation, but in klisp, objects passed to the error continuation are encapsulated error objects that have at least a message and possibly some additional -objects and context informations (such as source code location). In +objects and context informations (such as source code location). In the examples, the error message is shown on a line starting with @samp{@error{}}. @@ -251,7 +251,7 @@ the examples, the error message is shown on a line starting with @cindex description format Applicatives, operatives, and other objects are described in this manual -in a uniform format. The first line of a description contains the +in a uniform format. The first line of a description contains the name of the item followed by its operands or arguments, if any. @ifinfo The category---operative, applicative, or whatever---appears at the @@ -275,9 +275,9 @@ The description follows on succeeding lines, sometimes with examples. @cindex object descriptions In an applicative description, the name of the applicative being -described appears first. It is followed on the same line by an +described appears first. It is followed on the same line by an applicative combination that includes the name of the applicative and -the arguments, as would appear in a program. The names used for the +the arguments, as would appear in a program. The names used for the arguments are also used in the body of the description. Here is a description of an imaginary applicative @code{foo}: @@ -302,13 +302,13 @@ More generally, Any parameter whose name contains the name of a type (e.g., @var{integer}, @var{integer1} or @var{continuation}) is expected to be of that -type. A plural of a type (such as @var{numbers}) often means a list of -objects of that type. Parameters named @var{object} may be of any +type. A plural of a type (such as @var{numbers}) often means a list of +objects of that type. Parameters named @var{object} may be of any type. @c TODO add xref types of objects (XXX Types of Lisp Object XXX, for a list of Kernel object types.) Parameters with other sorts of names are -discussed specifically in the description of the combiner. In some +discussed specifically in the description of the combiner. In some sections, features common to parameters of several combiners are described at the beginning. @@ -316,7 +316,7 @@ described at the beginning. @c TODO clean this up a little Operative descriptions have the same format, but the word `Applicative' is replaced by `Operative', and `Argument' is replaced -by `Operand'. Also Operatives always have an environment parameter +by `Operand'. Also Operatives always have an environment parameter (that can be #ignore or a symbol). @node Acknowledgements,, Conventions, Introduction @@ -325,6 +325,6 @@ by `Operand'. Also Operatives always have an environment parameter This manual was written by Andres Navarro. The structure and some text for this introductory section were -borrowed from the Elisp Manual by the Free Sofware Foundation. This +borrowed from the Elisp Manual by the Free Sofware Foundation. This manual also borrows freely from both the Kernel Report and the Scheme Reports. diff --git a/manual/src/klisp.texi b/manual/src/klisp.texi @@ -75,6 +75,7 @@ in part. * Booleans:: Boolean module features. * Equivalence:: Equivalence under mutation & Equivalence up to mutation module features. +* Symbols:: Symbol module features. @c TODO complete * Index:: Index including concepts, functions, variables, and other terms. @@ -88,6 +89,7 @@ mutation module features. @include intro.texi @include booleans.texi @include equivalence.texi +@include symbols.texi @c appendices @c TODO diff --git a/manual/src/symbols.texi b/manual/src/symbols.texi @@ -0,0 +1,41 @@ +@c -*-texinfo-*- +@setfilename ../src/symbols + +@node Symbols, Index, Equivalence, Top +@comment node-name, next, previous, up + +@chapter Symbols +@cindex symbols +@c TODO add xref to eq?, identifiers, etc + Two symbols are eq? iff they have the same external +representation. Symbols are immutable, and the symbol type is +encapsulated. The external representations of symbols are usually +identifiers. However, symbols with other external representations may +@c TODO add xref to string->symbol +be created. + +@deffn Applicative symbol? (symbol? . objects) + The primitive type predicate for type symbol. @code{symbol?} +returns true iff all the objects in @code{objects} are of type symbol. +@end deffn + +@deffn Applicative symbol->string (symbol->string symbol) + Applicative @code{symbol->string} returns the name of @code{symbol} +as a string. The string returned is immutable. +@end deffn + +@deffn Applicative string->symbol (string->symbol string) + Applicative @code{string->symbol} returns the symbol with name +@code{string}. The symbol is always interned, which means, that it is +always the case that: +@example +(eq? <symbol> (string->symbol (symbol->string <symbol>))) + @result{} #t +@end example +@c TODO add xrefs for external representation + @code{string->symbol} can create symbols whose external +representation aren't identifiers. Right now klisp uses an output-only +representation, but in the near future it will probably include some +kind of escaping mechanism to allow arbitrary symbols to have readable +external representations as in R7RS Scheme. +@end deffn