Documentation

I'll probably get to this part eventually, if there's sufficient interest. For now you're gonna have to use the source, here's some quick description on where you find what.

Primitive functions

Primitive functions are defined in plain JavaScript, in js/primitives.js. There's a function there called defp — all primitives are defined through it. That function takes two arguments:

• A boolean which specifies whether the primitive does any side-effects. This is used to optimize away calls to primitive functions when no return value is expected and no side-effects are done.

• A JavaScript function of two arguments that handles the primitive operation. The arguments for this one, in turn, are:

  • m — a LispMachine object.
  • nargs — the number of arguments that have been passed to this function.

  Whatever this function returns is passed to the Lisp program via the stack, except if it returns nothing (undefined—in that case no value is pushed to the stack and you are expected to have done this yourself via m.push(...).

  Additionally, if this function returns a Promise (say, if it's marked async) then no value is pushed to the stack, and the associated process will be paused. You'll have to resume the process manually, after pushing a return value, when it becomes available.

The arguments are on the machine's stack and can be fetched in reverse order by calling m.pop().

Currently all primitive functions are defined in the base package (%) and they're all exported, although many of them should be kept private. Those that I wasn't sure I'd like to export as they are have names that start with a funny character like “%”.

Types

In js/types.js we have definitions and supporting functions for various basic types in the system.

List operations

In js/list.js we have defined most operations for linked lists. But from Lisp, of course, you'd access them via primitive functions.

The very basic Lisp system

The first Lisp file that is loaded by the system is lisp/compiler.lisp and it defines a bunch of basic functions and macros that are exported, as well as the reader and the compiler. Stuff defined here is exported in lisp/init.lisp, which also implements additional functionality like macros for the package system, destructuring-bind, etc.

Closette

The object system is implemented in lisp/closette.lisp. Original source: https://github.com/binghe/closette.

FORMAT and printer

There's a pretty comprehensive implementation, though by no means complete, of the format function in lisp/format.lisp. The printer is implemented in lisp/printer.lisp.