tut.html

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

<li>inspect the current environment by typing variable names or calling functions

<li>execute <code>(d)</code> to recursively debug the next expression

<li>execute <code>(<a href="refE.html#e">e</a>)</code> to evaluate the next
expression, to see what will happen without actually advancing on

<li>type ENTER (: enter an empty line) to leave the read-eval loop and continue
with the next expression

</ul>

<p>Thus, in the simplest case, single-stepping consists of just hitting ENTER
repeatedly to step through the function.

<p>To try it out, let's look at the <code><a
href="refS.html#stamp">stamp</a></code> system function.

<p><pre><code>
: (pp 'stamp)
(de stamp (Dat Tim)
   (default  Dat (date)  Tim (time))
   (pack (dat$ Dat "-") " " (tim$ Tim T)) )
-> stamp
</code></pre>

<p><pre><code>
: (debug 'stamp)                       # Debug it
-> T
: (stamp)                              # Call it again
(default Dat (date) Tim (time))        # stopped at first expression
!                                      # ENTER
(pack (dat$ Dat "-") " " (tim$ ...     # second expression
! Tim                                  # inspect 'Tim' variable
-> 41908
! (time Tim)                           # convert it
-> (11 38 28)
!                                      # ENTER
-> "2004-10-29 11:38:28"               # done, as there are only 2 expressions
</code></pre>

<p>Now we execute it again, but this time we want to look at what's happening
inside the second expression.

<p><pre><code>
: (stamp)                              # Call it again
(default Dat (date) Tim (time))
!                                      # ENTER
(pack (dat$ Dat "-") " " (tim$ ...     # here we want to look closer
! (d)                                  # debug this expression
-> T
!                                      # ENTER
(dat$ Dat "-")                         # stopped at first subexpression
! (e)                                  # evaluate it
-> "2004-10-29"
!                                      # ENTER
(tim$ Tim T)                           # stopped at second subexpression
! (e)                                  # evaluate it
-> "11:40:44"
!                                      # ENTER
-> "2004-10-29 11:40:44"               # done
</code></pre>

<p>The breakpoints still remain in the function body. We can see them when we
pretty-print it:

<p><pre><code>
: (pp 'stamp)
(de stamp (Dat Tim)
   (! default Dat (date) Tim (time))
   (! pack
      (! dat$ Dat "-")
      " "
      (! tim$ Tim T) ) )
-> stamp
</code></pre>

<p>To reset the function to its normal state, call

<p><pre><code>
: (unbug 'stamp)
</code></pre>

<p>Often, you will not want to single-step a whole function. Just use
<code>edit</code> (see above) to insert a single breakpoint (the exclamation
mark followed by a space) as CAR of an expression, and run your program.
Execution will then stop there as described above; you can inspect the
environment and continue execution with ENTER when you are done.


<p><hr>
<h2><a name="funio">Functional I/O</a></h2>

<p>Input and output in Pico Lisp is functional, in the sense that there are not
variables assigned to file descriptors, which need then to be passed to I/O
functions for reading, writing and closing. Instead, these functions operate on
implicit input and output channels, which are created and maintained as dynamic
environments.

<p>Standard input and standard output are the default channels. Try reading a
single expression:

<p><pre><code>
: (read)
(a b c)        # Console input
-> (a b c)
</code></pre>

<p>To read from a file, we redirect the input with <code><a
href="refI.html#in">in</a></code>. Note that comments and white space are
automatically skipped by <code>read</code>:

<p><pre><code>
: (in "doc/fun.l" (read))
-> (de fact (N) (if (=0 N) 1 (* N (fact (- N 1)))))
</code></pre>

<p>The <code><a href="refS.html#skip">skip</a></code> function can also be used
directly. To get the first non-white character in the file with <code><a
href="refC.html#char">char</a></code>:

<p><pre><code>
: (in "doc/fun.l" (skip "#") (char))
-> "("
</code></pre>

<p><code><a href="refF.html#from">from</a></code> searches through the input
stream for given patterns. Typically, this is not done with Lisp source files
(there are better ways), but for a simple example let's extract all items
immediately following <code>fact</code> in the file,

<p><pre><code>
: (in "doc/fun.l" (make (while (from "fact ") (link (read)))))
-> ((N) (- N 1))
</code></pre>

<p>or the word following "(de " with <code><a
href="refT.html#till">till</a></code>:

<p><pre><code>
: (in "doc/fun.l" (from "(de ") (till " " T)))
-> "fact"
</code></pre>


<p>With <code><a href="refL.html#line">line</a></code>, a line of characters is
read, either into a single transient symbol,

<p><pre><code>
: (in "doc/tut.html" (line T))
-> "&lt;!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" ..."
</code></pre>

<p>or into a list of characters:

<p><pre><code>
: (in "doc/tut.html" (line))
-> ("&lt;" "!" "D" "O" "C" "T" "Y" "P" "E" " " "H" "T" "M" "L" ...
</code></pre>

<p><code>line</code> is typically used to read tabular data from a file.
Additional arguments can split the line into fixed-width fields, as described in
the <code><a href="refL.html#line">reference manual</a></code>. If, however, the
data are of variable width, delimited by some special character, the <code><a
href="refS.html#split">split</a></code> function can be used to extract the
fields. A typical way to import the contents of such a file is:

<p><pre><code>
(load "lib/import.l")

(in '("bin/utf2" "importFile.txt")              # Pipe: Convert to UTF-8
   (until (eof)                                 # Process whole file
      (let L (split (line) "^I")                # TAB-delimited data
         ... use 'getStr', 'getNum' etc ...     # process them
</code></pre>

<p>Some more examples:

<p><pre><code>
(in "a"                                         # Copy the first 40 Bytes
   (out "b"                                     # from file "a" to file "b"
      (echo 40) ) )

(in "doc/tut.html"                              # Show the HTTP-header
   (line)
   (echo "&lt;body>") )

(out "file.mac"                                 # Convert to Macintosh
   (in "file.txt"                               # from Unix or DOS format:
      (while (char)
         (prin
            (case @
               ("^M" NIL)                       # ignore CR
               ("^J" "^M")                      # convert CR to LF
               (T @) ) ) ) ) )                  # otherwise no change

(out "c"                                        # Merge the contents of "a"
   (in "b"                                      # and "b" into "c"
      (in "a"
         (while (read)                          # Read an item from "a",
            (println @ (in -1 (read))) ) ) ) )  # print it with an item from "b"
</code></pre>


<p><hr>
<h2><a name="script">Scripting</a></h2>

<p>There are two possibilities to get the Pico Lisp interpreter into doing
useful work: Via command line arguments, or as a stand-alone script.

<p>The command line can specify either files for execution, or arbitrary Lisp
expressions for direct evaluation (see <code><a
href="ref.html#invoc">Invocation</a></code>): If an argument starts with a
hyphen, it is evaluated, otherwise <code><a
href="refL.html#load">load</a></code>ed as a file. A typical invocation might
look like:

<p><pre><code>
$ ./p dbg.l app/file1.l -main app/file2.l
</code></pre>

<p>It loads the debugging environment, an application source file, calls the
main function, and then loads another application source. In a typical
development and debugging session, this line is often modified using the shell's
history mechanisms, e.g. by inserting debugging statements:

<p><pre><code>
$ ./p dbg.l app/file1.l -"trace 'foo" -main -"debug 'bar" app/file2.l
</code></pre>

<p>Another convenience during debugging and testing is to put things into the
command line (shell history) which would otherwise have to be done each time in
the application's user interface:

<p><pre><code>
$ ./p dbg.l app/file1.l -main app/file2.l -go -'login "name" "password"'
</code></pre>

<p>The final production release of an application usually includes a shell
script, which initializes the environment, does some bookkeeping and cleanup,
and calls the application with a proper command line. It is no problem if the
command line is long and complicated.

<p>For small utility programs, however, this is overkill. It is better to write
a single executable file using the mechanisms of "interpreter files": If the
first two characters in an executable file are "<code>#!</code>", the operating
system kernel will pass this file to an interpreter program whose pathname is
given in the first line (optionally followed by a single argument). This is fast
and efficient, because the overhead of a subshell is avoided.

<p>Let's assume you installed Pico Lisp in the directory "/home/foo/picolisp/",
and put links to the executable and the installation directory as:

<p><pre><code>
$ ln -s /home/foo/picolisp /usr/lib/picolisp
$ ln -s /usr/lib/picolisp/bin/picolisp /usr/bin/picolisp
</code></pre>

Then a simple hello-world script might look like:

<p><pre><code>
#!/usr/bin/picolisp /usr/lib/picolisp/lib.l
(prinl "Hello world!")
(bye)
</code></pre>

<p>If you write this into a text file, and use <code>chmod</code> to set it to
"executable", it can be executed like any other command. Note that - because
<code>#</code> is the comment character in Pico Lisp - the first line will not
be interpreted, and you can still use that file as a normal command line
argument to Pico Lisp (useful during debugging).

<p>The fact that a hyphen causes evaluation of command line arguments can be
used to simulate something like command line options. The following script
defines two functions <code>a</code> and <code>f</code>, and then calls
<code>(<a href="refL.html#load">load</a> T)</code> to process the rest of the
command line (which otherwise would be ignored because of the <code>(<a
href="refB.html#bye">bye</a>)</code> statement):

<p><pre><code>
#!/usr/bin/picolisp /usr/lib/picolisp/lib.l

(de a ()
   (println '-a '-> (opt)) )

(de f ()
   (println '-f '-> (opt)) )

(load T)
(bye)
</code></pre>

(<code><a href="refO.html#opt">opt</a></code> retrieves the next command line
option)

<p>Calling this script (let's say we named it "testOpts") gives:

<p><pre><code>
$ ./testOpts -f abc
-f -> "abc"
$ ./testOpts -a xxx  -f yyy
-a -> "xxx"
-f -> "yyy"
</code></pre>

<p>We have to be aware of the fact, however, that the aggregation of arguments
like

<p><pre><code>
$ ./testOpts -axxx  -fyyy
</code></pre>

<p>or

<p><pre><code>
$ ./testOpts -af yyy
</code></pre>

<p>cannot be achieved with this simple and general mechanism of command line
processing.

<p>Utilities are typically used outside the context of the Pico Lisp
environment. All examples above assumed that the current working directory is
the Pico Lisp installation directory, which is usually all right for
applications developed in that environment. Command line file arguments like
"dbg.l" or "app/file1.l" will be properly found.

<p>To allow utilities to run in arbitrary places on the host file system, the
concept of <i>home directory substitution</i> was introduced. The interpreter
remembers internally at start-up the pathname of its first argument (usually
"lib.l"), and substitutes any leading "<code>@</code>" character in subsequent
file names with that pathname. Thus, to run the above example in some other
place, simply write:

<p><pre><code>
$ /home/foo/picolisp/p @dbg.l @app/file1.l -main @app/file2.l
</code></pre>

<p>that is, supply a full path name to the initial command (here 'p'), or put it
into your <code>PATH</code> variable, and prefix each file which has to be
loaded from the Pico Lisp home directory with a <code>@</code> character.
"Normal" files (not prefixed by <code>@</code>) will be opened or created
relative to the current working directory as usual.

<p>Stand-alone scripts will often want to load additional modules from the Pico
Lisp environment, beyond the "lib.l" we provided in the first line of the
hello-world script. Typically, at least a call to

<p><pre><code>
(load "@lib/misc.l")
</code></pre>

<p>(note the home directory substitution) will be included near the beginning of
the script.

<p>As a more complete example, here is a script which extracts the date, name
and size of the latest official Pico Lisp release version from the download web
site, and prints it to standard output:

<p><pre><code>
#!/usr/bin/picolisp /usr/lib/picolisp/lib.l

(load "@lib/misc.l" "@lib/http.l")

(use (@Date @Name @Size)
   (when
      (match
         '(@Date " " "-" " " @Name " " "(" @Size ")")
         (client "software-lab.de" 80 "down.html"
            (from "Archive")
            (from ".tgz\">")
            (till "<") ) )
      (prinl @Name)
      (prinl @Date " -- " @Size) ) )

(bye)
</code></pre>


<p><hr>
<h2><a name="oop">Objects and Classes</a></h2>

<p>The Pico Lisp object model is very simple, yet flexible and powerful. Objects
as well as classes are both implemented as symbols. In fact, there is no formal
difference between objects and classes; classes are more a conceptual design
consideration in the head of the programmer than a physical reality.

<p>Having said this, we declare that normally: