PIcolisp Cookbook

One thing which picoLisp needs is a Cookbook. A set of recepies on how to use its quite rich set of primitives to solve particular problems. Currently most of this information is somewhat implicit in the Reference docs. And requires making some big inferences after considering which sets of functions have links to each other.

All of the built in functions are documented, what is missing at the moment however is the various idioms for using them in practice. Thankfully you can usually get a prompt answer on the mailing List.

I came acrose one such are the other day. I was trying to break a circular list, built by fifo, into a plain list. In Common Lisp I'd do this with set. so I tried it to no avail. In Pico (set (cdr A) NIL) actually sets the 2nd element of the lsit A to nil.

It turns out that to set the cdr portion of a cell I want a function called con. My first reaction to that was ... well that's annoying. But then I got to thinking that its not actually a bad thing. Essentially we have to setting functions which are subtly different.

set: is used for setting values, and con is used for manipulating structure. Yes things get a little confusing if you use cells to build a tree structure where both the car and cdr contain pointers to other cells. That aside I when reading code I can assume that calls to set will change values but not alter the underlyign datastructures, while calls to con will alter structure.

The more I think about it the more I like this distinction. It adds something usful to the code. In the end the only thing which tripped me up was documentation. The Picolisp docs are good as far as they go, but missing a few bits.

Alex, the maintainer of PicoLisp, seems somewhat reluctant to make the official documentation more verbose. Well we may have to agree to disagree on that one. But there has been talk of building a picoLisp wiki (powered by picoLisp). And this may go some way to adding the Cookbook style reference that appears to be needed.