(c) Software Lab. Alexander Burger
This document demonstrates some aspects of the PicoLisp system in detail and example. For a general description of the PicoLisp kernel please look at the PicoLisp Reference.
This is not a Lisp tutorial, as it assumes some basic knowledge of programming, Lisp, and even PicoLisp. Please read these sections before coming back here: Introduction and The PicoLisp Machine. This tutorial concentrates on the specificities of PicoLisp, and its differences with other Lisp dialects.
If not stated otherwise, all examples assume that PicoLisp was started from a global installation (see Installation) from the shell prompt as
$ pil +
:
It loads the PicoLisp base system and the debugging environment, and waits
for you to enter input lines at the interpreter prompt (:). You can
terminate the interpreter and return to the shell at any time, by either hitting
the Ctrl-D key, or by executing the function (bye).
Please note that special handling is done during character input. This one
is incompatible with rlwrap for example but is more powerful.
vi-like command-line editing (typos fixes and history with ESC,
h, j, k and l but not
arrows)," appear).If you prefer to use Emacs, please use the picolisp-mode bundled in the "el/" directory (that is "@lib/el" for a local installation, or some system dependent directory for a global installation).
If you feel that you absolutely have to use an IDE, rlwrap or
another input front-end, please create an empty "~/.pil/editor" file. This
effectively disables the command line editor. Note that in this case, however,
you will not have the TAB symbol completion feature available during command
line editing.
If you are new to PicoLisp, you might want to read the following sections in the given order, as some of them assume knowledge about previous ones. Otherwise just jump anywhere you are interested in.
PicoLisp permanently reads input from the current input channel (i.e. the console in interactive mode), evaluates it, and prints the result to the current output channel. This is called a "read-eval-print-loop" (REPL).
This is the default line editor, as it needs less system resources and works also on dumb terminals. It is similar to - though simpler than - the 'vi' edit modes of the 'korn' and 'bash' shells. For an analog 'emacs' style editor, please see below.
It is very helpful - though not absolutely necessary - when you know how to
use the vi text editor.
To alleviate the task of manual line input, a command line editor is provided
which is similar to (though much simpler than) the readline feature
of the bash shell. Only a subset of the vi mode is
supported, which is restricted to single-key commands (the "real"
vi supports multi-key commands and the modification of most
commands with count prefixes). It is loaded at startup in debug mode, you find
its source in "lib/led.l".
You can enter lines in the normal way, correcting mistypes with the BACKSPACE key, and terminating them with the ENTER key. This is the Insert Mode.
If you hit ESC, you get into Command Mode. Now you can navigate
horizontally in the current input line, or vertically in the history of
previously entered lines, with key commands borrowed from the vi
editor (only h, j, k and l
and not arrows). Note, however, that there is always only a single line visible.
Let's say you did some calculation
: (* (+ 2 3) (- 7 2))
-> 25
:
If you want to repeat a modified version of this command, using
8 instead of 7, you don't have to re-type the
whole command, but type
k to get one line "up"
f and 7 to "find" the character 7
r and 8 to "replace" with 8
Then you hit ENTER to execute the modified line. Instead of jumping to the
7 with the "find" command, you may also type l (move
"right") repeatedly till you reach the correct position.
The key commands in the Command Mode are listed below. Some commands change the mode back to Insert Mode as indicated in parentheses. Deleting or changing a "word" take either the current atom (number or symbol), or a whole expression when the cursor is at a left parenthesis.
k - Go up one line
j - Go down one line
l - Go right one character
h - Go left one character
w - Go right one word
b - Go back (left) one word
0 - Go to the beginning of the line
$ - Go to the end of the line
i - Enter Insert Mode at the cursor position
a - Append (Insert Mode) after the cursor position
A - Append (Insert Mode) at the end of the line
I - Insert (Insert Mode) at the beginning of the line
x - Delete the character at the cursor position
X - Delete the character left of the cursor position
r - Replace the character at the cursor position with the next key
s - Substitute the character at the cursor position (Insert Mode)
S - Substitute the whole line (Insert Mode)
d - Delete the word at the cursor position (Insert Mode)
D - Delete the rest of the line
c - Change the word at the cursor position (Insert Mode)
C - Change the rest of the line (Insert Mode)
f - Find next key in the rest of the current line
p - Paste data deleted with x, X, d or D after the cursor position
P - Paste data deleted with x, X, d or D before the cursor position
/ - Accept an input pattern and search the history for it
n - Search for next occurrence of pattern (as entered with /)
N - Search for previous occurrence of pattern
% - Go to matching parenthesis
~ - Convert character to opposite (lower or upper) case and move right
u - Undo the last change (one level only)
U - Undo all changes of the current line
g - Display current contents of cut buffer (not in vi)
Notes:
d command corresponds to the dw command of the
vi editor, and c corresponds to cw.
@" characters as wildcards.
The following two key-combinations work both in Insert and Command Mode:
Ctrl-D will immediately terminate the current process.
Ctrl-X discards all input, abandons further processing, and
returns to the interpreter's top level (equivalent to invoking quit). This is also useful when the program
stopped at a breakpoint (see single-stepping Debugging), or
after program execution was interrupted with Ctrl-C.
Besides these two keys, in Insert Mode only the following keys have a special meaning:
Ctrl-H) and DEL erase the character to the left
Ctrl-V inserts the next key literally
Ctrl-E lets you edit
the history
You can switch the command line editor to an 'emacs' style, if you call the
function (em) (i.e. without arguments). A single call is enough.
Alternatively, you could invoke PicoLisp at least once with the -em
command line option
$ pil -em +
:
The style will be remembered in a file "~/.pil/editor", and used in all subsequent PicoLisp sessions.
To switch back to 'vi' style, call (vi), use the
-vi command line option, or simply remove "~/.pil/editor".
Please take some time to experiment and to get used to command line editing. It will make life much easier in the future :-)
PicoLisp provides some functionality for inspecting pieces of data and code within the running system.
print,
size
...
But you will appreciate some more powerful tools like:
match, a predicate which
compares S-expressions with bindable wildcards when matching,The most commonly used tool is probably the show function. It takes a symbolic argument,
and shows the symbol's name (if any), followed by its value, and then the
contents of the property list on the following lines (assignment of such things
to a symbol can be done with set,
setq, and put).
: (setq A '(This is the value)) # Set the value of 'A'
-> (This is the value)
: (put 'A 'key1 'val1) # Store property 'key1'
-> val1
: (put 'A 'key2 'val2) # and 'key2'
-> val2
: (show 'A) # Now 'show' the symbol 'A'
A (This is the value)
key2 val2
key1 val1
-> A
show accepts an arbitrary number of arguments which are
processed according to the rules of get, resulting in a symbol which is showed then.
: (put 'B 'a 'A) # Put 'A' under the 'a'-property of 'B'
-> A
: (setq Lst '(A B C)) # Create a list with 'B' as second argument
-> (A B C)
: (show Lst 2 'a) # Show the property 'a of the 2nd element of 'Lst'
A (This is the value) # (which is 'A' again)
key2 val2
key1 val1
-> A
Similar to show is edit. It takes an arbitrary number of symbolic
arguments, writes them to a temporary file in a format similar to
show, and starts the vim editor with that file.
: (edit 'A 'B)
The vim window will look like
A (This is the value)
key1 val1
key2 val2
(=======)
B NIL
a A # (This is the value)
(=======)
Now you can modify values or properties. You should not touch the
parenthesized asterisks, as they serve as delimiters. If you position the cursor
on the first character of a symbol name and type 'K' ("Keyword
lookup"), the editor will be restarted with that symbol added to the editor
window. 'Q' (for "Quit") will bring you back to the previous view.
edit is also very useful to browse in a database. You can follow
the links between objects with 'K', and even - e.g. for low-level
repairs - modify the data (but only if you are really sure about what you are
doing, and don't forget to commit
when you are done).
The pretty-print function pp
takes a symbol that has a function defined (or two symbols that specify message
and class for a method definition), and displays that definition in a formatted
and indented way.
: (pp 'pretty)
(de pretty (X N)
(setq N (abs (space (or N 0))))
(while (and (pair X) (== 'quote (car X)))
(prin "'")
(pop 'X) )
(cond
...
(T (prtty0 X N)) ) )
-> pretty
The style is the same as we use in source files:
size is greater than 12), pretty-print the CAR
on the current line, and each element of the CDR recursively on its own line.
more is a simple tool that displays
the elements of a list one by one. It stops after each element and waits for
input. If you just hit ENTER, more continues with the next element,
otherwise (usually I type a dot (.) followed by ENTER) it
terminates.
: (more (1 2 3 4 5 6))
1 # Hit ENTER
2. # Hit '.' and ENTER
-> T # stopped
Optionally more takes a function as a second argument and
applies that function to each element (instead of the default print). Here, often show or
pp (see below) is used.
: (more '(A B)) # Step through 'A' and 'B'
A
B
-> NIL
: (more '(A B) show) # Step through 'A' and 'B' with 'show'
A (This is the value) # showing 'A'
key2 val2
key1 val1
# Hit ENTER
B NIL # showing 'B'
a A
-> NIL
The what function returns a list of
all internal symbols in the system which match a given pattern (with
'@' wildcard characters).
: (what "prin@")
-> (prin print prinl print> printsp println)
The function who returns "who
contains that", i.e. a list of symbols that contain a given argument
somewhere in their value or property list.
: (who 'print)
-> (query pretty pp msg more "edit" view show (print> . +Date) rules select
(print> . +relation))A dotted pair indicates either a method definition or a property entry. So
(print> . +relation) denotes the print> method of
the +relation class.
who can be conveniently combined with more and
pp:
: (more (who 'print) pp)
(de query ("Q" "Dbg") # Pretty-print these functions one by one
(use "R"
(loop
(NIL (prove "Q" "Dbg"))
(T (=T (setq "R" @)) T)
(for X "R"
(space)
(print (car X))
(print '=)
(print (cdr X))
(flush) )
(T (line)) ) ) )
(de pretty (X N)
...
The argument to who may also be a pattern list (see match):
: (who '(print @ (val @)))
-> (show)
: (more (who '(% @ 7)) pp)
(de day (Dat Lst)
(get
(or Lst *DayFmt)
(inc (% (inc Dat) 7)) ) )
(de _week (Dat)
(/ (- Dat (% (inc Dat) 7)) 7) )
The function can returns a list
which indicates which classes can accept a given message. Again, this
list is suitable for iteration with pp:
: (can 'del>) # Which classes accept 'del>' ?
-> ((del> . +List) (del> . +Entity) (del> . +relation))
: (more (can 'del>) pp) # Inspect the methods with 'pp'
(dm (del> . +List) (Obj Old Val)
(and ((<> Old Val) (delete Val Old)) )
(dm (del> . +Entity) (Var Val)
(when
(and
Val
(has> (meta This Var) Val (get This Var)) )
(let Old (get This Var)
(rel>
(meta This Var)
This
Old
(put This Var (del> (meta This Var) This Old @)) )
(when (asoq Var (meta This 'Aux))
(relAux This Var Old (cdr @)) )
(upd> This Var Old) ) ) )
(dm (del> . +relation) (Obj Old Val)
(and ((<> Old Val) Val) )
dep shows the dependencies in a
class hierarchy. That is, for a given class it displays the tree of its
(super)class(es) above it, and the tree of its subclasses below it.
To view the complete hierarchy of input fields, we start with the root class
+relation:
: (dep '+relation)
+relation
+Bag
+Any
+Blob
+Link
+Joint
+Bool
+Symbol
+String
+Number
+Time
+Date
-> +relation
If we are interested in +Link:
: (dep '+Link)
+relation
+Link
+Joint
-> +Link
This says that +Link is a subclass of +relation, and has a single subclass
(+Joint).
Most of the time during programming is spent defining functions (or methods).
In the following we will concentrate on functions, but most will be true for
methods as well except for using dm
instead of de.
The notorious "Hello world" function must be defined:
: (de hello ()
(prinl "Hello world") )
-> hello
The () in the first line indicates a function without arguments.
The body of the function is in the second line, consisting of a single
statement. The last line is the return value of de, which here is
the defined symbol. From now on we will omit the return values of examples when
they are unimportant.
Now you can call this function this way:
: (hello)
Hello world
A function with an argument might be defined this way:
: (de hello (X)
(prinl "Hello " X) )
# hello redefined
-> hello
PicoLisp informs you that you have just redefined the function. This might be a useful warning in case you forgot that a bound symbol with that name already existed.
: (hello "world")
Hello world
: (hello "Alex")
Hello Alex
Normally, PicoLisp evaluates the arguments before it passes them to a function:
: (hello (+ 1 2 3))
Hello 6
: (setq A 1 B 2) # Set 'A' to 1 and 'B' to 2
-> 2
: (de foo (X Y) # 'foo' returns the list of its arguments
(list X Y) )
-> foo
: (foo A B) # Now call 'foo' with 'A' and 'B'
-> (1 2) # -> We get a list of 1 and 2, the values of 'A' and 'B'
In some cases you don't want that. For some functions (setq for example) it is better if the function
gets all arguments unevaluated, and can decide for itself what to do with them.
For such cases you do not define the function with a list of parameters, but give it a single atomic parameter instead. PicoLisp will then bind all (unevaluated) arguments as a list to that parameter.
: (de foo X
(list (car X) (cadr X)) ) # 'foo' lists the first two arguments
: (foo A B) # Now call it again
-> (A B) # -> We don't get '(1 2)', but '(A B)'
: (de foo X
(list (car X) (eval (cadr X))) ) # Now evaluate only the second argument
: (foo A B)
-> (A 2) # -> We get '(A 2)'
As a logical consequence, you can combine these principles. To define a function with 2 evaluated and an arbitrary number of unevaluated arguments:
: (de foo (X Y . Z) # Evaluate only the first two args
(list X Y Z) )
: (foo A B C D E)
-> (1 2 (C D E)) # -> Get the value of 'A' and 'B' and the remaining list
More common, in fact, is the case where you want to pass an arbitrary number
of evaluated arguments to a function. For that, PicoLisp recognizes the
symbol @ as a single atomic parameter and remembers all evaluated
arguments in an internal frame. This frame can then be accessed sequentially
with the args, next, arg and rest functions.
: (de foo @
(list (next) (next)) ) # Get the first two arguments
: (foo A B)
-> (1 2)
Again, this can be combined:
: (de foo (X Y . @)
(list X Y (next) (next)) ) # 'X' and 'Y' are fixed arguments
: (foo A B (+ 3 4) (* 3 4))
-> (1 2 7 12) # All arguments are evaluated
These examples are not very useful, because the advantage of a variable number of arguments is not used. A function that prints all its evaluated numeric arguments, each on a line followed by its squared value:
: (de foo @
(while (args) # Check if there are some args left
(println (next) (* (arg) (arg))) ) ) # Call the last arg (next) returned
: (foo (+ 2 3) (- 7 1) 1234 (* 9 9))
5 25
6 36
1234 1522756
81 6561
-> 6561
This next example shows the behaviour of args and
rest:
: (de foo @
(while (args)
(next)
(println (arg) (args) (rest)) ) )
: (foo 1 2 3)
1 T (2 3)
2 T (3)
3 NIL NIL
Finally, it is possible to pass all these evaluated arguments to another
function, using pass:
: (de foo @
(pass println 9 8 7) # First print all arguments preceded by 9, 8, 7
(pass + 9 8 7) ) # Then add all these values
: (foo (+ 2 3) (- 7 1) 1234 (* 9 9))
9 8 7 5 6 1234 81 # Printing ...
-> 1350 # Return the result
quote will do what you want (see
also this FAQ entry).
: ((quote (X) (* X X)) 9)
-> 81
: (setq f '((X) (* X X))) # This is equivalent to (de f (X) (* X X))
-> ((X) (* X X))
: f
-> ((X) (* X X))
: (f 3)
-> 9
There are two major ways to debug functions (and methods) at runtime: Tracing and single-stepping.
In this section we will use the REPL to explore the debugging facilities, but in the Scripting section, you will learn how to launch PicoLisp scripts with some selected functions debugged:
$ pil app/file1.l -"trace 'foo" -main -"debug 'bar" app/file2.l +
Tracing means letting functions of interest print their name and arguments when they are entered, and their name again and the return value when they are exited.
For demonstration, let's define the unavoidable factorial function (or just
load the file "@doc/fun.l"):
(de fact (N)
(if (=0 N)
1
(* N (fact (dec N))) ) )
With trace we can put it in trace
mode:
: (trace 'fact)
-> fact
Calling fact now will display its execution trace.
: (fact 3)
fact : 3
fact : 2
fact : 1
fact : 0
fact = 1
fact = 1
fact = 2
fact = 6
-> 6
As can be seen here, each level of function call will indent by an additional
space. Upon function entry, the name is separated from the arguments with a
colon (:), and upon function exit with an equals sign
(=) from the return value.
trace works by modifying the function body, so generally it
works only for functions defined as lists (lambda expressions, see Evaluation). Tracing a C-function is possible, however,
when it is a function that evaluates all its arguments.
So let's trace the functions =0 and
*:
: (trace '=0)
-> =0
: (trace '*)
-> *
If we call fact again, we see the additional output:
: (fact 3)
fact : 3
=0 : 3
=0 = NIL
fact : 2
=0 : 2
=0 = NIL
fact : 1
=0 : 1
=0 = NIL
fact : 0
=0 : 0
=0 = 0
fact = 1
* : 1 1
* = 1
fact = 1
* : 2 1
* = 2
fact = 2
* : 3 2
* = 6
fact = 6
-> 6
To reset a function to its untraced state, call untrace:
: (untrace 'fact)
-> fact
: (untrace '=0)
-> =0
: (untrace '*)
-> *
or simply use mapc:
: (mapc untrace '(fact =0 *))
-> *
Single-stepping means to execute a function step by step, giving the
programmer an opportunity to look more closely at what is happening. The
function debug inserts a breakpoint
into each top-level expression of a function. When the function is called, it
stops at each breakpoint, displays the expression it is about to execute next
(this expression is also stored into the global variable ^) and enters a read-eval-loop. The programmer can
then