Support via Liberapay

PicoLisp Source Code Blocks in Org Mode

Org Mode support for PicoLisp


Brief description of PicoLisp

PicoLisp is a minimal and pure Lisp dialect created by Alexander Burger. First of all, PicoLisp is a virtual machine architecture, and then a programming language. It is the result of a language design study, trying to answer the question "What is a minimal but useful architecture for a virtual machine?"

However, PicoLisp is no academic exercise in language design. It has been used in several commercial and research programming projects since 1988. Its internal structures are simple enough, allowing an experienced programmer always to fully understand what's going on under the hood, and its language features, efficiency and extensibility make it suitable for almost any practical programming task. Some of the outstanding features of PicoLisp are:

Integrated Database

Database functionality is built into the core of the language. PicoLisp is a database query and manipulation language.

Database entities are first class objects. They are called "external symbols", because they are automatically fetched from database files when accessed, but otherwise behave like normal symbols.

This fetching from external files is completely transparent, the symbols "are just there", and there is no need (or even a function) to read or write them explicitly. Pilog (a built-in Prolog engine) is used as a query language.

It is possible with PicoLisp to build large multi-user databases, distributed across many machines or in a cloud. Such a database system can be optimally fine-tuned, because all its levels are under the developer's control.

Equivalence of Code and Data

This is actually a feature of Lisp in general. However, PicoLisp really lives it. It makes it easy to write things like the HTML, PostScript or TeX libraries, exploring a syntax of nested function calls. This results in very succinct and precisely expressed programs.

For a closer explanation, see the article The Equivalence of Code and Data.


PicoLisp is a very expressive language. Programs are often much shorter and concise than equivalent programs written in other languages.

Examples of various programming tasks and their solutions can be found at Rosettacode.


PicoLisp uses (at least when compared to other Lisps) very little memory, on disk as well as in memory (heap space).

For example, the installation size in the OpenWRT distribution is only 575 kB (uncompressed), where the statically linked interpreter with 296 kB takes the largest part. Yet, it includes the full runtime system with interpreter, database, HTTP server, XHTML and JavaScript application framework, watchdog, and the debugger, PostScript and XML libraries.

PicoLisp has no compiler, everything starts up very quickly, and code dynamically loaded at runtime (e.g. GUI pages) is immediately ready. Yet, the interpreter is quite fast, usually three times a fast as Python, for example.

Range of typical uses within Org Mode

At first sight, it might not be obvious why Org Mode users should use anything else but Emacs Lisp when writing lisp code blocks. But Picolisp offers at least two features that make it a valuable Org Babel language: its object-oriented database, and its highly efficient framework for interactive web-applications.

Requirements and Setup

Installation and configuration of PicoLisp software

PicoLisp can be downloaded from this download page. There is a 32-bit version written in C, and a 64-bit version written in assembler. Some GNU/Linux distributions ship with PicoLisp packages, so you might be able to use your package manager for installation. A pure Java version (Ersatz PicoLisp) and a minimal version (Mini PicoLisp) are available too.

Detailed and comprehensive installation instructions can be found in the INSTALL file.

Emacs configuration

The original author of PicoLisp, Alexander Burger, does all his programming work using xterm and vi. PicoLisp is really living the old Unix tradition of simplicity and minimalism.

However, there are no editor-wars going on in the PicoLisp community. Several PicoLisp programmers are Emacs users and contributed to Emacs to enable it as PicoLisp editor.

After installing PicoLisp, you find the elisp files that constitute the Emacs picolisp-mode in the directory picolisp/lib/el. There is a picolisp.el and an inferior-picolisp.el as well as a paredit patch.

There is another file called tsm.el. It makes PicoLisp's transient symbols appear in a special way in the source code, reminding the programmer that they look like Strings and are used as Strings, but are not really Strings but just (transient) Symbols.

The README file in the same directory gives the necesary instructions for configuring the PicoLisp mode for Emacs. Since it is not very long, I cite it here:

;; In order to get the picolisp-mode working correctly you have to
;; add the following expressions to your .emacs and adapt them 
;; according to your set-up: 

(add-to-list 'load-path "<path-to>/picoLisp/lib/el")
(load "tsm.el") ;; Picolisp TransientSymbolsMarkup (*Tsm)
(autoload 'run-picolisp "inferior-picolisp")
(autoload 'picolisp-mode "picolisp" "Major mode for editing
 Picolisp." t)
;; pil is more modern than plmod
(setq picolisp-program-name "<path-to>/picoLisp/plmod") 

;; If you have also SLIME installed, it will suck all possible lisp
;; extensions up (greedy bastard). 
;; So in order to get the correct file-association for picolisp 
;; files you'll have to also add this:

(add-to-list 'auto-mode-alist '("\\.l$" . picolisp-mode))

;; If you want, you can add a few hooks for convenience:

(add-hook 'picolisp-mode-hook
   (lambda ()
      (paredit-mode +1) ;; Loads paredit mode automatically
      (tsm-mode) ;; Enables TSM
      (define-key picolisp-mode-map (kbd "RET") 'newline-and-indent)
      (define-key picolisp-mode-map (kbd "C-h") 'paredit-backward-delete) ) )

;; By the way, don't forget to patch your paredit.el (v21) with the
;;  patch provided to get a smoother editing. 

Org-mode configuration (org-babel-do-load-languages)

The ob-picolisp.el file is part of Emacs now. To activate PicoLisp as an org-babel language, simply add (picolisp . t) to the org-babel-do-load-languages function in your Emacs configuration file, like shown below:

;; activating picolisp as org babel language
 'org-babel-load-languages (quote ((emacs-lisp . t)
                                    (picolisp . t)
                                    (R . t)
                                    (python . t))))

Org Mode Features for PicoLisp Source Code Blocks


Support or not

ob-picolisp supports external evaluation as well as session-based evaluation of PicoLisp source blocks.

Typical use for sessions

Sessions preserve state, therefore the use of sessions in PicoLisp just like in Emacs Lisp makes sense whenever the computations rely on changing state.

Header Arguments and Result Types

Language-specific default values

Depending on the kind of table data you work with, it might be convenient to set the following default header argument:

;; optionally declare default header arguments for this language
(defvar org-babel-default-header-args:picolisp
  '((:colnames . "no"))
  "Default arguments for evaluating a picolisp source block.")

Language-specific header arguments

There are no language specific header arguments for PicoLisp.

Combinations of header-args and result types

Many combinations of header arguments and result types are supported by ob-picolisp. Like always in combinatorics, the number of possible combinations increases rapidly when there are several factors with several levels each that can be freely combined.

The following table shows combinations of header arguments and result types that might make sense for a language like PicoLisp. Many (but nor all) of them have been tried successfully with ob-picolisp source blocks.

evaluation collection type
(:session) (:results) (:results)
external value table (vector)
    scalar (verbatim)
    raw (org)
  output table (vector)
    scalar (verbatim)
    raw (org)
session value table (vector)
    scalar (verbatim)
    raw (org)
  output table (vector)
    scalar (verbatim)
    raw (org)

More special header arguments and their possible values are summarized in the next table:

header-arg   values    
:results silent replace append prepend
:exports code results both none
:comments yes (no?)    
:noweb no yes    
:tangle yes no filename  
:cache no yes    
:var x=y      
:hlines no yes    
:colnames nil no yes  
:rownames no yes    
:shebang "string"      
:eval never query    


Differences from other supported languages

PicoLisp as an Org Babel language works quite similar like its close relatives Emacs Lisp and Scheme, for example.

However, there is one characteristic that really sets it aparts from other supported languages: PicoLisp is not only a language, it is a (object-oriented) database and a web-framework. Unlike other languages, that have (external) frameworks and database drivers, these features are deeply integrated inside the PicoLisp application server framework.

As Alexander Burger describes it in A Unifying Language for Database And User Interface Development:

Databases and user interfaces are separate
worlds: Existing class libraries are concerned about
visual effects and event handling, but not about
application logic and database maintenance. It is the
programmer's responsibility to write glue code that
displays data in corresponding GUI fields, detects
modifications by the user, validates them, writes changes
back to the database, and does other housekeeping.
[PicoLisp is] a language and programming
environment that closes [this] semantic gap, by unifying
database and user interface into a single application
server framework.

Examples of Use

Hello World!

The PicoLisp Tutorial has two versions of the notorious "Hello World" function, one without arguments, the other with one argument:

# no arguments
(de hello-no-args ()
   (prinl "Hello World"))

# with one argument
(de hello-one-arg (X)
   (prinl "Hello " X) )

(hello-one-arg "Argument")

Common uses

PicoLisp can be used, just like Emacs Lisp, as an efficient scripting language inside of Org Mode documents. Due to its smart and powerfull abstractions, much can be achieved in a few lines of code.

From a PicoLisp programmer's point of view, the integration of the language into Org Babel might be usefull for literate programming (e.g. writing well documented PicoLisp libraries or PicoLisp related papers) or for convenient database report building (making use of Org Mode's multi-language environment and export facilities).

From an Org Mode user's and/or Emacs Lisp programmer's point of view, two use cases might be of special interest:

  • use PicoLisp as a real (object-oriented) database replacement for things like bbdb and eieio, i.e. as a tool for object-oriented lisp programming that can handle big (even replicated) databases, offers a powerfull prolog-based query language (Pilog) and speed (see The Need for Speed).
  • use the PicoLisp application server framework to enable interactive web-development with Org Mode, i.e. combine the static html-export facilities of Org Mode with PicoLisp's ability to produce html-forms that communicate directly with an underlying PicoLisp database.

These two use cases are still a bit theoretical, some investigation and experimentation has to be done that hopefully lead to the production of related tutorials on Worg in the future.

Links to tutorials and other resources

Although not all aspects of PicoLisp are documented and the (often surprinsingly short) source code must be used as ultimate reference in some cases, there are many interesting and well written documents available.

The one-stop-shop for everything with regards to PicoLisp is the PicoLisp Wiki. There is a PicoLisp Mailing List too, as well as an IRC channel (#picolisp).

For programmers who want to learn more about PicoLisp, I would suggest to first read Paul Graham's essay The Hundred-Year Language, to get the general idea what PicoLisp is all about. Then, a A Radical Approach to Application Development (PDF) and A Unifying Language for Database And User Interface Development are the next logical steps to learn more about the philosophy behind PicoLisp.

The PicoLisp Reference and the PicoLisp Tutorial are the main references when it comes to 'hands on' experience with the language. Henrik Sarvell's introduction "At a First Glance" is a very helpfull beginners guide too.

The PicoLisp Application Development guide explains in great detail, how amazingly easy and efficient web-programming with PicoLisp can be. There is much more information available, just have a look at the PicoLisp wiki yourself.

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.