abu@software-lab.de

A Pico Lisp Tutorial

(c) Software Lab. Alexander Burger

This document demonstrates some aspects of the Pico Lisp system in detail and example. For a general description of the Pico kernel please look at the Pico Lisp Reference.

This is not a Lisp tutorial, as it assumes some working knowledge of Lisp (and programming in general). It concentrates on the specialities of Pico Lisp, and its differences to other Lisp dialects.

If not stated otherwise, all examples assume that Pico was started from the shell prompt as 


$ ./p dbg.l
:

This loads the Pico 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 RETURN key (i.e. by entering an empty line), or by executing the function (bye).

It is very helpful - though not absolutely necessary - when you know how to use the vi editor.

We recommend that you have a terminal window open, and try the examples by yourself. You may either type them in directly to the Pico interpreter, or edit a separate source file (e.g. "test.l") in a second terminal window and load it into Pico with 


: (load "test.l")

each time you have modified and saved it.

If you are new to Pico, 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.

The Command Line Editor

Pico 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.

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. 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).

You can enter lines in the normal way, correcting mistypes with the BACKSPACE key, and terminating them with the RETURN 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. 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

Then you hit RETURN 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. Commands which operate on a "word" take either the current atom (number or symbol), or a whole expression when the cursor is at a left parenthesis.

Notes:

In Input Mode, only the following keys have a special meaning:

Please take some time to experiment and to get used to command line editing. It will make life much easier in the future :-)

Browsing

Pico provides some functionality for inspecting pieces of data and code within the running system.

Most commonly used is probably the show function. It takes a symbolic argument, and shows the symbol's name (if any), followed by its value cell, and then the contents of the property list on the following lines. 


: (setq A '(This is the value))  # Set the value cell 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 aguments 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 vi editor with that file. 


: (edit 'A 'B)

The vi window will look like 


A (This is the value)
key1 val111
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 char of a symbol name and hit Ctrl-] the editor will be restarted with that symbol added to the editor window (this is similar to the "tags"-feature of vi). Ctrl-T 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 Ctrl-], and even modify the data if you are sure about what you are doing (and don't forget to commit when you are done).

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 RETURN, more continues with the next element, otherwise (usually I type a dot (.) followed by RETURN) it terminates. 


: (more (1 2 3 4 5 6))
1                          # Hit RETURN
2.                         # Hit '.' and RETURN
-> 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-> T
: (more '(A B) show)       # Step through 'A' and 'B' with 'show'
A (This is the value)      # showing 'A'
   key2 val2
   key1 val111
                           # Hit RETURN
B NIL                      # showing 'B'
   a A
-> T

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)
   (space (default N 0))
   (if (or (atom X) (<= (size X) 12))
      (print X)
      (while (== 'quote (car X))
         (prin "'")
         (pop 'X) )
      (let Z
         X
         (prin "(")
         (when
            (and
               (memq (print (pop 'X)) *PP)
               (or
                  (atom (car X))
                  (<= (size (car X)) 12) ) )
            (space)
            (print (pop 'X)) )
         (do NIL
            (NIL X)
            (T (== Z X) (prin " ."))
            (T (atom X) (prin " . ") (print X))
            (prinl)
            (pretty (pop 'X) (+ 3 N)) )
         (space)
         (prin ")") ) ) )
-> pretty

The style is the same as we use in all our source files:

The what function returns a list of all internal symbols in the system. If an optional pattern argument (with '@' wildcard characters ) is given, only symbols matching that pattern are returned. 


: (what "@Field")
-> (+HttpField hotField +TimeField +PwField +DigField +FixField +IntField
+MailField +SymField +DateField +McField +TextField +DrawField +ClsField
+PictField +NumField +FileField)

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 'cdar)
-> (step dbg ubg _scan (T . _sel) _gen _iter _reti (set> . +Map) _nacs)

A dotted pair indicates either a method definition or a property entry.

who can be conveniently combined with more and pp: 


: (more (who 'cdar) pp)
(de step (Q F)          # Pretty-print these functions one by one
   ...

The argument to who may also be a pattern list (see match): 


: (more (who '(+ @ 1)) pp)
(de _week (Dat)
   (/ (- Dat (% (+ Dat 1) 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> . +Relation) (del> . +Entity) (del> . +List))
: (more (can 'del>) pp)                         # Inspect the methods with 'pp'
(dm (del> . +Relation) (Obj Old Val)
   (and (<> Old Val) Val) )

(dm (del> . +Entity) (Var Val)
   (when
      (and
         Val
         (has> (meta This Var) Val (get This Var)) )
      (rel>
         (meta This Var)
         This
         (get This Var)
         (put
            This
            Var
            (del> (meta This Var) This (get This Var) @) ) )
      (upd> This Var) ) )

(dm (del> . +List) (Obj Old Val)
   (delete Val Old) )

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 +field: 


: (dep '+field)
+field
   +Button
      +ChgButton
      +ClrButton
      +SetButton
   +Label
   +TextField
      +HttpField
      +TimeField
      +PwField
      +DigField
         +NumField
            +IntField
      +FixField
      +MailField
      +SymField
      +DateField
      +McField
      +ClsField
      +FileField
   +DrawField
   +PictField
   +Checkbox
-> +field

If we are interested in +DigField: 


: (dep '+DigField)
         +Font
      +Mono
   +Align
      +field
   +TextField
+DigField
   +NumField
      +IntField
-> +DigField

This says for example that +DigField has two direct superclasses (+Align and +TextField) and one direct subclass (+NumField).

Defining Functions

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. From now on we will omit the return values of examples when they are unimportant.

You'll know that you can call this function as 


: (hello)
Hello world

A function with an argument might look this way: 


: (de hello (X)
   (prinl "Hello " X) )
hello redefined

Pico 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 Pico 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. Pico will then bind all (unevaluated) arguments to that list. 


: (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, Pico recognizes the symbol @ as a single atomic parameter and remembers all evaluated arguments in an internal list. This list can then be access sequentially with the args, 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 incremented value: 


: (de foo @
   (while (args)
      (println (next) (+ 1 (arg))) ) )

: (foo (+ 2 3) (- 7 1) 1234 (* 9 9))
5 6
6 7
1234 1235
81 82
-> 82

Finally, it is possible to pass all these evaluated argument to another function, using args: 


: (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

Debugging

There are two major ways to debug functions (and methods) at runtime: Tracing and single-stepping.

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 (- N 1))) ) )

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 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, and when the number of arguments is known in advance. Then this number must be passed to trace.

The function =0 is a single-argument predicate. We'll trace it too (with '1' for one parameter): 


: (trace '=0 1)
-> =0

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 = T
    fact = 1
   fact = 1
  fact = 2
 fact = 6
-> 6

To reset a function to its untraced state, call 


: (untrace 'fact)
-> fact
: (untrace '=0)
-> =0

or simply 


: (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

Thus, in the simplest case, single-stepping consists of just hitting RETURN repeatedly to step through the function.

To try it out, let's look at the stamp system function. 


(de stamp (Dat Tim)
   (default
      Dat (date)
      Tim (time) )
   (setq Tim (time Tim))
   (pack
      (dat$ Dat "-")
      " "
      (pack
         (pad 2 (car Tim)) ":"
         (pad 2 (cadr Tim)) ":"
         (pad 2 (caddr Tim)) ) ) )



: (debug 'stamp)                       # Debug it
-> T
: (stamp)                              # Call it again
(default Dat (date) Tim (time))        # stopped at first expression
!                                      # RETURN
(setq Tim (time Tim))                  # stopped at second expression
!                                      # RETURN
(pack (dat$ Dat "-") " " (pack ...     # third expression
! Tim                                  # inspect 'Tim' variable
-> (11 22 35)
!                                      # RETURN
-> "2002-12-15 11:22:35"               # done, as there are only 3 expressions

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


: (stamp)                              # Call it again
(default Dat (date) Tim (time))
!                                      # RETURN
(setq Tim (time Tim))
!                                      # RETURN
(pack (dat$ Dat "-") " " (pack ...     # here we want to look closer
! (d)                                  # debug this expression
-> T
!                                      # RETURN
(dat$ Dat "-")                         # stopped at first subexpression
! (e)                                  # evaluate it
-> "2002-12-15"
!                                      # RETURN
(pack (pad 2 (car Tim)) ":" (pad ...   # stopped at second subexpression
! (e)                                  # evaluate it
-> "11:27:17"
!                                      # RETURN
-> "2002-12-15 11:27:17"               # done

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


: (pp 'stamp)
(de stamp (Dat Tim)
   (! default Dat (date) Tim (time))
   (! setq Tim (time Tim))
   (! pack
      (! dat$ Dat "-")
      " "
      (! pack
         (pad 2 (car Tim))
         ":"
         (pad 2 (cadr Tim))
         ":"
         (pad 2 (caddr Tim)) ) ) )
-> stamp

To reset the function to its normal state, call 


: (unbug 'stamp)

Often, you will not want to single-step a whole function. Just juse edit (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 RETURN when you are done.

Objects and Classes

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 in Pico; classes are more a conceptual design consideration in the head of the programmer than a physical reality.

Having said this, we declare:

  1. A Class
  2. An Object

So the main difference between classes and objects is that the former ones usually have names. By convention, these names start with a '+'. Sometimes it makes sense, however, to create named objects (as global singletons, for example), or even anonymous classes.

Both classes and objects have a list in their value cell, consisting of method definitions (often empty for objects) and (super)class(es). And both classes and objects have local data in their property lists (often empty for classes). This implies, that any given object (as an instace of a class) may have private (object-local) methods defined.

It is rather difficult to contrive a simple OOP example. We constructed a hierarchy of geometric shapes, with a base class +Shape and two subclasses +Rectangle and +Circle.

The source code is included as "doc/shape.l" in the Pico Lisp distribution, so you don't have to type it in. Just load the file, or start it from the shell as: 


$ ./p dbg.l doc/shape.l

Let's look at it piece by piece. Here's the base class: 


(class +Shape)
# x y

(dm T (X Y)
   (=: x X)
   (=: y Y) )

(dm move> (DX DY)
   (inc (:: x) DX)
   (inc (:: y) DY) )

The first line '(class +Shape)' defines the symbol +Shape as a class without superclasses. The following method definitions will go to that class.

The comment '# x y' in the second line is just a convention, to indicate what instance variables (properties) that class uses. As Pico is a dynamic language, a class can be extended at runtime with any number of properties, and there is nothing like a fixed object size or structure. This comment is a hint of what the programmer thinks to be essential and typical for that class. In the case of +Shape, x and y are the coordinates of the shape's origin.

Then we have two method definitions, using the keyword dm for "define method". The first method is special, in that its name is T. Each time a new object is created, and a method with that name is found in its class hierarchy, that method will be executed. Though this looks like a "constructor" in other programming languages, it should probably better be called "initializer". The T method of +Shape takes two arguments X and Y, and stores them in the object's property list.

The second method move> changes the object's origin by adding the offset values DX and DY to the object's origin.

Now to the first derived class: 


(class +Rectangle +Shape)
# dx dy

(dm T (X Y DX DY)
   (super X Y)
   (=: dx DX)
   (=: dy DY) )

(dm area> ()
   (* (: dx) (: dy)) )

(dm perimeter> ()
   (+ (* 2 (: dx)) (* 2 (: dy))) )

(dm draw> ()
   (drawRect (: x) (: y) (: dx) (: dy)) )

+Rectangle is defined as a subclass of +Shape. The comment '# dx dy' indicates that +Rectangle has a width and a height in addition to the origin coordinates inherited from +Shape.

The T method passes the origin coordinates X and Y to the T method of the superclass (+Shape), then stores the width and height parameters into dx and dy.

Next we define the methods area> and perimeter> which do some obvious calculations, and a method draw> which is supposed to draw the shape on the screen by calling some hypothetical function drawRect.

Finally, we define a +Circle class in an analog way, postulating the hypothetical function drawCircle: 


(class +Circle +Shape)
# r

(dm T (X Y R)
   (super X Y)
   (=: r R) )

(dm area> ()
   (*/ (* (: r) (: r)) 31415627 10000000 T) )

(dm perimeter> ()
   (*/ (* 2 (: r)) 31415627 10000000 T) )

(dm draw> ()
   (drawCircle (: x) (: y) (: r)) )

Now we can experiment with geometrical shapes. We create a rectangle at point (0,0) with a width of 30 and a height of 20, and keep it in the variable R: 


: (setq R (new '(+Rectangle) 0 0 30 20))  # New rectangle
-> $134432824                             # returned anonymous symbol
: (show R)
$134432824 (+Rectangle)                   # Show the rectangle
   dy 20
   dx 30
   y 0
   x 0

We see that the symbol $134432824 has a list of classes '(+Rectangle)' in its value cell, and the coordinates, width and height in is property list.

Sending messages to that object 


: (area> R)                               # Calculate area
-> 600
: (perimeter> R)                          # and perimeter
-> 100

will return the values for area and perimeter, respectively.

Then we move the object's origin: 


: (move> R 10 5)                          # Move 10 right and 5 down
-> 5
: (show R)
$134432824 (+Rectangle)
   y 5                                    # Origin changed (0,0) -> (10,5)
   x 10
   dy 20
   dx 30

Though a method move> wasn't defined for the +Rectangle class, it is inherited from the +Shape superclass.

Similarly, we create and use a circle object: 


: (setq C (new '(+Circle) 10 10 30))      # New circle
-> $134432607                             # returned anonymous symbol
: (show C)
$134432607 (+Circle)                      # Show the circle
   r 30
   y 10
   x 10
-> $134432607
: (area> C)                               # Calculate area
-> 2827
: (perimeter> C)                          # and perimeter
-> 188
: (move> C 10 5)                          # Move 10 right and 5 down
-> 15
: (show C)
$134432607 (+Circle)                      # Origin changed (10,10) -> (20,15)
   y 15
   x 20
   r 30

It is also easy to send messages to objects in a list: 


: (mapcar 'area> (list R C))              # Get list of areas
-> (600 2827)
: (mapc
   '((Shape) (move> Shape 10 10))         # Move all 10 right and down
   (list R C) )
-> 20
: (show R)
$134431493 (+Rectangle)
   y 15
   x 20
   dy 20
   dx 30
-> $134431493
: (show C)
$134431523 (+Circle)
   y 25
   x 30
   r 30

Assume that we want to extend our shape system. From time to time, we need shapes that behave exactly like the ones above, but are tied to a fixed position. That is, they do not change their position even if they receive a move> message.

One solution would be to modify the move> method in the +Shape class to a no-operation. But this would require to duplicate the whole shape hierarchy (e.g. by defining +FixedShape, +FixedRectangle and +FixedCircle classes).

The Pico Way is the use of Prefix Classes through multiple inheritance. It uses the fact that searching for method definitions is a depth-first, left-to-right search of the class tree. We define a prefix class: 


: (class +Fixed)

(dm move> (DX DY))      # Do-nothing method

We can now create a fixed rectangle, and try to move it: 


: (setq R (new '(+Fixed +Rectangle) 0 0 30 20))    # '+Fixed' prefix class
-> $134432881
: (move> R 10 5)                                   # Send 'move>' message
-> NIL
: (show R)
$134432881 (+Fixed +Rectangle)
   dy 20
   dx 30
   y 0                                             # Did not move!
   x 0

We see, prefix classes can surgically change the inheritance tree for selected objects or classes.

Persistence (External Symbols)

Pico Lisp has persistent objects built-in as a first class data type. They are, in fact, simply a special type of symbolic atoms (called "External Symbols"), that happen to be read from a pool file when accessed, and written back automatically when modified.

In all other aspects they are normal symbols. They have a value cell, a property list and a name.

The name cannot be directly controlled by the programmer, as it is assigned when the symbol is created. It is an encoded index of the symbol's location in the pool file ("database"). In its visual representation (output by the print functions and input by the read functions) it is surrounded by braces.

To make use of external symbols, you need to open a database file first: 


: (pool "test.db")

If a file with that name did not exist, it got created now. Also created at the same moment was {1}, the very first symbol in the file. This symbol is of great importance, and is handled especially by Pico. Therefore a global constant *DB exists, which points to that symbol {1}, which should be used exclusively to access the symbol {1}, and which should never be modified by the programmer. 


: *DB                   # The value of '*DB'
-> {1}                  # is '{1}'
: (show *DB)
{1} NIL                 # Value of '{1}' is NIL, property list empty

Now let's put something into the value cell and property list of {1}. 


: (set *DB "Hello world")  # Set value of '{1}' to a transient symbol (string)
-> "Hello world"
: (put *DB 'a 1)           # Property 'a' to 1
-> 1
: (put *DB 'b 2)           # Property 'b' to 2
-> 2
: (show *DB)               # Now show the symbol '{1}'
{1} "Hello world"
   b 2
   a 1

Note that instead of '(set *DB "Hello world")', we might also have written '(setq {1} "Hello world")', and instead of '(put *DB 'a 1)' we might have written '(put '{1} 'a 1)'. This would have the same effect, but as a rule external symbols should never be be accessed literally in application programs, because the garbage collector might not be able to free these symbols and all symbols connected to them (and that might well be the whole database). It is perfectly all right, however, to access external symbols literally during interactive debugging.

Now we can create own first own external symbol. This can be done with new when a T argument is supplied: 


: (new T)
-> {2}               # Got a new symbol

We store it in the database root {1}: 


: (put *DB 'newSym '{2})   # Literal '{2}' (ok during debugging)
-> {2}
: (show *DB)
{1} "Hello world"
   newSym {2}              # '{2}' is now stored in '{1}'
   b 2
   a 1

Put some property value into '{2}' 


: (put *DB 'newSym 'x 777) # Put 777 as 'x'-property of '{2}'
-> 777
: (show *DB 'newSym)       # Show '{2}' (indirectly)
{2} NIL
   x 777
-> {2}
: (show '{2})              # Show '{2}' (directly)
{2} NIL
   x 777

All modifications to - and creations of - external symbols done so far are not written to the database yet. We could call rollback (or simply exit Pico) to undo all the changes. But as we want to keep them: 


: (commit)           # Commit all changes
-> T
: (bye)              # Exit pico
$                    # back to the shell

So, the next time when .. 


$ ./p dbg.l             # .. we start Pico
: (pool "test.db")      # and open the database file,
-> T
: (show *DB)            # our two symbols are there again
{1} "Hello world"
   newSym {2}
   b 2
   a 1
-> {1}
: (show *DB 'newSym)
{2} NIL
   x 777
-> {2}

Database Progamming

To a database, there is more than just persistence. Pico Lisp includes an entity/relation class framework (see also Database) which allows a close mapping of the application data structure to the database.

We provided a simple yet complete database and GUI demo application in doc/famDb.l. We recommend to start it up for testing purposes in the following way: 


$ ./p dbg.l doc/famDb.l -main
:

This loads the source file, initializes the database by calling the main function, and prompts for user input.

The data model is small and simple. We define a class +Person and two subclasses +Man and +Woman. 


(class +Person +Entity)

+Person is a subclass of the +Entity system class. Usually all data in a database are a direct or indirect subclasses of +Entity. We can then define the relations to other data with the rel function. 


(rel nm     (+Key +String))                     # Name

This defines the name property (nm) of a person. The first argument to rel is always a list of relation classes (subclasses of +Relation), optionally followed by further arguments, causing relation daemon objects be created and stored in the class definition. These daemon objects control the entity's behavior later at runtime.

Relation daemons are a kind of metadata, controlling the interactions between entities, and maintaining database integrity. Like other classes, relation classes can be extended and refined, and in combination with proper prefix classes a fine-grained description of the application's structure can be produced.

Besides primitive relation classes, like +Number, +String or +Date, there are

In the case of the person's name (nm) above, the relation object is of type (+Key +String). Thus, the name of each person in this demo database must be unique, and the person object can be located with a single index lookup. 


(rel pa     (+Joint) kids (+Man))               # Father
(rel ma     (+Joint) kids (+Woman))             # Mother
(rel mate   (+Joint) mate (+Person))            # Partner

The attributes for father (pa), Mother (ma) and partner (mate) are all defined as +Joints. A +Joint is probably the most powerful relation mechanism in Pico; it establishes a bi-directional link between two objects.

The above declarations say that the father (pa) attribute points to an object of type +Man, and is joined with that object's kids attribute (which is a list of joints back to all his children).

The consistency of +Joints is maintained automatically by the relation daemons. These become active whenever a value is stored to a person's pa, ma, mate or kids property.

For example, interesting things happen when a person's mate is changed to a new value. Then the mate property of the old mate's object is cleared (she has no mate after that). Now when the person pointed to by the new value already has a mate, then that mate's mate property gets cleared, and the happy new two mates now get their joints both set correctly.

The programmer doesn't have to care about all that. He just declares these relations as +Joints.

The last four attributes of person objects are just static data: 


(rel job    (+String))                          # Occupation
(rel dat    (+Date))                            # Date of birth
(rel fin    (+Date))                            # Date of death
(rel txt    (+String))                          # Info

Notes:

  1. Date values in Pico are just numbers, representing the numbers of days since first of March in the year zero.
  2. If want to search your database later for persons given their occupation or date of birth, you might also write: 

    
(rel job    (+Ref +String))                     # Occupation
(rel dat    (+Ref +Date))                       # Date of birth

    to create non-unique indices for these values.

A method url> is defined: 


(dm url> ()
   (pack "@person?" This) )

It is needed later in the GUI, to cause a double-click to switch to that object.

The classes +Man and +Woman are subclasses of +Person: 


(class +Man +Person)
(rel kids   (+List +Joint) pa (+Person))        # Children

(class +Woman +Person)
(rel kids   (+List +Joint) ma (+Person))        # Children

They inherit everything from +Person, except for the kids attribute. This attribute joins with the pa or ma attribute of the child, depending on the parent's gender.

That's the whole data model for our demo database application.

User Interface Programming

The only type of GUI supported by the Pico application server framework is either dynamically generated (but static by nature) HTML, or an interactive applet frontend.

Before we explain the GUI of our demo database application, we present a minimal example for a plain HTML GUI in doc/hello.l. Start the application server as: 


$ ./p -'server 8080 "doc/hello.l"' -wait

Now point your browser to the address 'http://localhost:8080'. You should see a very simple HTML page. You can come back here with normal browser navigation, or with the '<<<' link in the upper right corner.

You can call the page repeatedly, or concurrently with many clients if you like. To terminate the server, you have to send it a TERM signal (e.g. 'killall pico'), or type the Quit key (typically Ctrl-\) in the console window.

In our demo database application, a single function person is responsible for the whole GUI. Again, please look at doc/famDb.l.

To start the database and the application server, call: 


$ ./p dbg.l doc/famDb.l -main -go

As before, the database is opened with main. The function go is also defined in doc/famDb.l: 


(de go ()
   (server 8080 "@person") )

It starts the HTTP server listening on TCP port 8080 (we did a similar thing in our minimal GUI example above directly on the command line). Each connect to that port will cause the function person to be invoked.

Again, point your browser to the address 'http://localhost:8080' (please make sure that Java is enabled).

You should see a new browser window with the input form created by the function person. If you started the application for the first time, it should be empty (in fact, it displays the empty +Man object created by main). Please type a name into the first field, and perhaps also an occupation and birth date.

To assign a father attribute, you must first create a new person: Click on the "Man" button at the bottom of the page. A search dialog pops up, so click on "create" to get a new person. Again, enter a name and perhaps occupation and birth date. Then click on the first field in the "Children" chart. You can select the child by either typing the first char(s) of the name and/or by hitting F2 for a selection list.

If you go back now to the first object (with browser navigation or with the '<<<' link in the upper right corner), the "Father" field of that object should be filled now (thanks to the +Joint relation).

On the console where you started Pico Lisp, there should a prompt have appeared just when the browser connected. You can debug the application interactively while it is running. For example, the global variable *Top always contains the top level GUI object: 


: (show *Top)

To take a look at the field with the current input current focus: 


: (show *Top 'focus)

A production application would be started in a slightly different way: 


$ ./p doc/famDb.l -main -go -wait

In that case, no debug prompt will appear. In both cases, however, two pico processes will be running now. One is the initial server process which will continue to run until it is killed. The other is a child process which is connected to the applet in the browser, it will terminate when the browser is closed, or when (bye) or a plain RETURN is entered at the Pico prompt.

Now back to the explanation of the GUI function person: 


(de person (*ID)
   (app)
   (html (get (default *ID (seq *DB)) 'nm)
      (<head> "Family")
      (new '(+ObjForm) '(+Person) *ID 800 500
         (quote

It gets passed the object ID as a single argument. The function (app) must be called at least once when the GUI is initialized (it doesn't harm, though, if it is called each time as in this case).

The principal function to generate a HTML page is the function html (see also the previous minimal doc/hello.l example). html takes a page title as the first argument, and interprets all following arguments as a body description. Each item may be an atom (in that case it will be simply printed as "This is Pico" in doc/hello.l), or a list which is executed.

In this case the body consists only of three statements:

All components like fields and buttons are passed to (new '(+ObjForm) ..) as a quoted list. The function gui creates a single GUI component and takes the type (a list of classes) and a variable number of arguments depending on the needs of these classes. 


   (row
      (gui '(+E/R +TextField) '(nm : home obj) "Name" 30)

This creates a +TextField with the label "Name" and a length of 30 characters. The +E/R (: Entity/Relation) prefix class connects that field to a database object, the nm attribute of a person in this case, so that the person's name is displayed in that text field, and any changes entered into that field are propagated to the database automatically.

The call to row causes all argument fields to be arranged horizontally (normally, all components produced by gui are arranged vertically below each other). 


   (gui '(+Set +ClassField)
      '((V)
         (unless (= V (val (: home obj)))
            (extra V)
            (upd> (: home)) ) )
      '(: home obj) "Sex"
      '(("Male" +Man) ("Female" +Woman)) ) )
   ...

A +ClassField displays and changes the class of an object, in this case the person's sex from +Man to +Woman and vice versa. The +Set prefix class is needed to call upd> on the whole form, because setting the sex of a person may change the kids <-> pa/ma relations as a side effect, and thus require a refresh of the display. 


   ...
   (----)
   ...

This is a function that opens a new panel in the GUI layout. Pico applets use the AWT GridBagLayout to arrange components in panels, so calling (----) allows a certain degree of control. 


   ...
   (---- T)
   (gui '(+E/R +Chart)
      '(kids : home obj)
      5 '("Children" "born" "Father" "Mother")
      (quote
   ...

When (---- T) is called, the panel is equipped with a vertical scroll bar. A +Chart creates a two-dimensional array of fields, here it is to hold the list of children showing name, date of birth, and the names of the parents. Typing the name of a (previously created) child here can also be used to establish the +Joint (as opposed to set the pa or ma attribute in the child).

As you see, there is no place where explicit accesses to the database have to be programmed, no select or update. This is all encapsulated in the GUI components, mainly in the +E/R prefix class. The above function person is fully functional as we present it and allows creation, modification and deletion of person objects in the database.

Pilog -- Pico Prolog

Work in progress ..

Pitfalls

Work in progress ..

References

[knuth73] Donald E. Knuth: ``The Art of Computer Programming'', Vol.3, Addison-Vesley, 1973, p. 392