ref.html

A very small LISP implementation with several packages and demo programs.

<p><hr>
<h5><a name="transient">Transient Symbols</a></h5>

<p>Transient symbols are only interned into a hashed list structure for a
certain time (e.g. while reading the current source file), and are released
after that. That means, a transient symbol cannot be accessed then by its name,
and there may be several transient symbols in the system having the same name.

<p>Transient symbols are used

<p><ul>
<li>as text strings

<li>as identifiers with a limited access scope (like, for example,
<code>static</code> identifiers in the C language family)

<li>as anonymous, dynamically created objects (without a name)

</ul>

<p>Initially, a new transient symbol's VAL is that symbol itself.

<p>A transient symbol without a name can be created with the <code><a
href="refB.html#box">box</a></code> or <code><a
href="refN.html#new">new</a></code> functions.


<p><hr>
<h5><a name="external">External Symbols</a></h5>

<p>External symbols reside in a database file, and are loaded into memory - and
written back to the file - dynamically as needed, and transparent to the
programmer.

<p>The interpreter recognizes external symbols, because in addition to the
symbol bit(2), also bit(1) is set:

<p><pre><code>
      xxxxxxxxxxxxxxxxxxxxxxxxxxxxx110
</code></pre>

<p>There cannot be two different external symbols with the same name. External
symbols are maintained in hash structures while they are loaded into memory, and
have their external location (disk block, network URL, etc.) directly coded into
their names.

<p>Initially, a new external symbol's VAL is <code>NIL</code>, unless otherwise
specified at creation time.


<p><hr>
<h4><a name="lst">Lists</a></h4>

<p>A list is a sequence of one or more cells, holding numbers, symbols, or
lists. Lists are used in Pico Lisp to emulate composite data structures like
arrays, trees, stacks or queues.

<p>In contrast to lists, numbers and symbols are collectively called "Atoms".

<p>Typically, the CDR of each cell in a list points to the following cell,
except for the last cell which points <code>NIL</code>. If, however, the CDR of
the last cell points to an atom, that cell is called a "dotted pair" (because of
its I/O syntax with a dot '.' between the two values).


<p><hr>
<h3><a name="mem">Memory Management</a></h3>

<p>The Pico Lisp interpreter has complete knowledge of all data in the system,
due to the type information associated with every pointer. Therefore, an
efficient garbage collector mechanism can easily be implemented. Pico Lisp
employs a simple but fast mark-and-sweep garbage collector.

<p>As the collection process is very fast (in the order of milliseconds per
megabyte), it was not necessary to develop more complicated, time-consuming and
error-prone garbage collection algorithms (e.g. incremental collection). A
compacting garbage collector is also not necessary, because the single cell data
type cannot cause heap fragmentation.


<p><hr>
<h2><a name="penv">Programming Environment</a></h2>

<p>Lisp was chosen as the programming language, because of its clear and simple
structure.

<p>In some previous versions, a Forth-like syntax was also implemented on top of
a similar virtual machine (Lifo). Though that language was more flexible and
expressive, the traditional Lisp syntax proved easier to handle, and the virtual
machine can be kept considerably simpler.

Pico Lisp inherits the major advantages of classical Lisp systems like

<p><ul>
<li>Dynamic data types and structures
<li>Formal equivalence of code and data
<li>Functional programming style
<li>An interactive environment
</ul>

<p>In the following, some concepts and peculiarities of the Pico Lisp language
and environment are described.


<p><hr>
<h3><a name="invoc">Invocation</a></h3>

<p>When Pico Lisp is invoked from the command line, an arbitrary number of
arguments may follow the command name.

<p>By default, each argument is the name of a file to be executed by the
interpreter. If, however, the argument's first character is a hyphen '-', then
the rest of that argument is taken as a Lisp function call (without the
surrounding parentheses). A hyphen by itself as an argument stops evaluation of
the rest of the command line (it may be processed later using the <code><a
href="refA.html#argv">argv</a></code> and <code><a
href="refO.html#opt">opt</a></code> functions). This mechanism corresponds to
calling <code>(<a href="refL.html#load">load</a> T)</code>.

<p>As a convention, Pico Lisp source files have the extension "<code>.l</code>".

<p>Note that the Pico Lisp executable itself does not expect or accept any
command line flags or options. They are reserved for application programs.

<p>The simplest and shortest invocation of Pico Lisp does nothing, and exits
immediately by calling <code><a href="refB.html#bye">bye</a></code>:

<p><pre><code>
$ bin/picolisp -bye
$
</code></pre>

<p>In interactive mode, the Pico Lisp interpreter (see <code><a
href="refL.html#load">load</a></code>) will also exit when an empty line is
entered:

<p><pre><code>
$ bin/picolisp
:                       # Typed ENTER
$
</code></pre>

<p>To start up the standard Pico Lisp environment, several files should be
loaded. The most commonly used things are in "lib.l" and in a bunch of other
files, which are in turn loaded by "ext.l". Thus, a typical call would be:

<p><pre><code>
$ bin/picolisp lib.l ext.l
</code></pre>

<p>The recommended way, however, is to call the "p" shell script, which includes
"lib.l" and "ext.l". Given that your current project is loaded by some file
"myProject.l" and your startup function is <code>main</code>, your invocation
would look like:

<p><pre><code>
$ ./p myProject.l -main
</code></pre>

<p>For interactive development and debugging it is recommended also to load
"dbg.l", to get the vi-style command line editor, single-stepping, tracing and
other debugging utilities.

<p><pre><code>
$ ./p dbg.l myProject.l -main
</code></pre>

<p>In any case, the directory part of the first file name supplied on the
command line (normally, the path to "lib.l") is remembered internally as the
<u>Pico Lisp Home Directory</u>. This path is later automatically substituted
for any leading "<code>@</code>" character in file name arguments to I/O
functions (see <code><a href="refP.html#path">path</a></code>).


<p><hr>
<h3><a name="io">Input/Output</a></h3>

<p>In Lisp, each internal data structure has a well-defined external
representation in human-readable format. All kinds of data can be written to a
file, and restored later to their original form by reading that file.

<p>In normal operation, the Pico Lisp interpreter continuously executes an
infinite "read-eval-print loop". It reads one expression at a time, evaluates
it, and prints the result to the console. Any input into the system, like data
structures and function definitions, is done in a consistent way no matter
whether it is entered at the console or read from a file.

<p>Comments can be embedded in the input stream with the hash <code>#</code>
character. Everything up to the end of that line will be ignored by the reader.

<p><pre><code>
: (* 1 2 3)  # This is a comment
-> 6
</code></pre>

<p>Here is the I/O syntax for the individual Pico Lisp data types:


<p><hr>
<h4><a name="num-io">Numbers</a></h4>

<p>A number consists of an arbitrary number of digits (<code>'0'</code> through
<code>'9'</code>), optionally preceded by a sign character (<code>'+'</code> or
<code>'-'</code>). Legal number input is:

<p><pre><code>
: 7
-> 7
: -12345678901245678901234567890
-> -12345678901245678901234567890
</code></pre>

<p>Fixed-point numbers can be input by embedding a decimal point
<code>'.'</code>, and setting the global variable <code><a
href="refS.html#*Scl">*Scl</a></code> appropriately:

<p><pre><code>
: *Scl
-> 0

: 123.45
-> 123
: 456.78
-> 457

: (setq *Scl 3)
-> 3
: 123.45
-> 123450
: 456.78
-> 456780
</code></pre>

<p>Thus, fixed-point input simply scales the number to an integer value
corresponding to the number of digits in <code><a
href="refS.html#*Scl">*Scl</a></code>.

<p>Formatted output of scaled fixed-point values can be done with the <code><a
href="refF.html#format">format</a></code> function:

<p><pre><code>
: (format 1234567890 2)
-> "12345678.90"
: (format 1234567890 2 "." ",")
-> "12,345,678.90"
</code></pre>


<p><hr>
<h4><a name="sym-io">Symbols</a></h4>

<p>The reader is able to recognize the individual symbol types from their
syntactic form. A symbol name should - of course - not look like a legal number
(see above).

<p>In general, symbol names are case-sensitive. <code>car</code> is not the same
as CAR.


<p><hr>
<h5><a name="nilSym-io">NIL</a></h5>

<p>Besides for standard normal form, <code>NIL</code> is also recognized as
<code>()</code>, <code>[]</code> or <code>""</code>.

<p><pre><code>
: NIL
-> NIL
: ()
-> NIL
: ""
-> NIL
</code></pre>

<p>Output will always appear as <code>NIL</code>.


<p><hr>
<h5><a name="internal-io">Internal Symbols</a></h5>

<p>Internal symbol names can consist of any printable (non-whitespace)
character, except for the following meta characters:

<p><pre><code>
   "  '  (  )  [  ]  `  ~
</code></pre>

<p>It is possible, though, to include these special characters into symbol names
by escaping them with a backslash '<code>\</code>'.

<p>As a rule, anything not recognized by the reader as another data type will be
returned as an internal symbol.


<p><hr>
<h5><a name="transient-io">Transient Symbols</a></h5>

<p>A transient symbol is anything surrounded by double quotes '<code>"</code>'.
With that, it looks - and can be used - like a string constant in other
languages. However, it is a real symbol, and may be assigned a value or a
function definition, and properties.

<p>Initially, a transient symbol's value is that symbol itself, so that it does
not need to be quoted for evaluation:

<p><pre><code>
: "This is a string"
-> "This is a string"
</code></pre>

<p>However, care must be taken when assigning a value to a transient symbol.
This may cause unexpected behavior:

<p><pre><code>
: (setq "This is a string" 12345)
-> 12345
: "This is a string"
-> 12345
</code></pre>

<p>The name of a transient symbol can contain any character except zero. A
double quote character can be escaped with a backslash '<code>\</code>', and a
backslash itself has to be escaped with another backslash. Control characters
can be written with a preceding hat '<code>^</code>' character.

<p><pre><code>
: "We^Ird\\Str\"ing"
-> "We^Ird\\Str\"ing"
: (chop @)
-> ("W" "e" "^I" "r" "d" "\\" "S" "t" "r" "\"" "i" "n" "g")
</code></pre>

<p>The hash table for transient symbols is cleared automatically before and
after <code><a href="refL.html#load">load</a></code>ing a source file, or it can
be reset explicitly with the <code><a href="ref_.html#====">====</a></code>
function. With that mechanism, it is possible to create symbols with a local
access scope, not accessible from other parts of the program.

<p>A special case of transient symbols are <i>anonymous symbols</i>. These are
symbols without name (see <code><a href="refB.html#box">box</a></code>, <code><a
href="refB.html#box?">box?</a></code> or <code><a
href="refN.html#new">new</a></code>). They print as a dollar sign
(<code>$</code>) followed by a decimal digit string (actually their machine
address).


<p><hr>
<h5><a name="external-io">External Symbols</a></h5>

<p>External symbol names are surrounded by braces (<code>'{'</code> and
<code>'}'</code>). The characters of the symbol's name itself identify the
physical location of the external object. This is currently the number of the
starting block in the database file, encoded in base-64 notation (characters
'<code>0</code>' through '<code>9</code>', '<code>:</code>' through
'<code>;</code>', '<code>A</code>' through '<code>Z</code>' and '<code>a</code>'
through '<code>z</code>'). Later versions might include other formats like
Internet URL's.


<p><hr>
<h4><a name="lst-io">Lists</a></h4>

<p>Lists are surrounded by parentheses (<code>'('</code> and <code>')'</code>).

<p><code>(A)</code> is a list consisting of a single cell, with the symbol
<code>A</code> in its CAR, and <code>NIL</code> in its CDR.

<p><code>(A B C)</code> is a list consisting of three cells, with the symbols
<code>A</code>, <code>B</code> and <code>C</code> respectively in their CAR, and
<code>NIL</code> in the last cell's CDR.

<p><code>(A . B)</code> is a "dotted pair", a list consisting of a single cell,