Lisp Standard Library

This provides documentation for every built-in function in the Lisp standard library. It is not auto-generated, please update this documentation if you change the API in any way.

In general every user-facing API in the standard library should be documented here.

(x ...) represents a list x.
& body means that the rest of the list is represented by body.
[something] means that something is optional.

Top-level primitives

These are “functions” that can only appear at the top-level of the program. This means they can’t be nested in any other expressions.

(defun function-name (args ...) & body)

Defines a function function-name that takes args and evaluates body. function-name is quoted, not evaluated.

(defun say-hi (name)
  (print "Hi, ")
  (print name))

(say-hi "Joe")
; "Hi,"
; "Joe"

(defmacro macro-name (args ...) & body)

defmacro is to macros as defun is to functions. When macro-name is called, whatever it evaluates to will be compiled.

Note that internally this compiles a function the same way all other functions are compiled, meaning you can call any lisp function from a macro definition and it will work as expected.

(defun double (n)
  (+ n n))

(defmacro call-with-4 (whatever)
  (print "this was run at **compile time**")
  (print whatever)
  ;; ``whatever`` expands to the form passed to this macro, in this case
  ;; ``double``.
  (list whatever 4))

(print (call-with-4 double))
; "this was run at **compile time**"
; 'double
; 8

Functions

(if condition true-condition [false-condition])

Evaluates condition, if it is truthy (non-nil) true-condition is evaluated. Otherwise false-condition is evaluated. If false-condition is not provided and condition is nil, if will evaluate to nil.

(print (if (= 2 3)
          "2 = 3"
          "2 /= 3"))
; 2 /= 3

(let1 (variable binding) & body)

Evaluates binding and binds it to variable, then evaluates body. After body is evaluated variable is unbound.

(let1 (greeting (greet "John"))
  (do-something greeting)
  (print greeting))
; greeting is no longer bound

(gc): Force the garbage collector (GC) to run.

(car pair)

Return the first item in pair.

(car (cons 'a 'b)) ;=> 'a

(cdr pair)

Return the second (last) item in pair.

(cdr (cons 'a 'b)) ;=> 'b

(cons a b): Return a cons-pair containing a and b.

(print val): Print out val to standard output. This will not be formatted as an s-expression, but in a manner more similar to the internal representation.

(list & items)

Returns a cons-list of items.

(list 1 2 3)
; is the same as
(cons 1 (cons 2 (cons 3 nil)))

(quote form)

Returns form without evaluating it.

'(cons a b)
; or
(quote cons a b)
; is the same as
(list 'cons 'a 'b)

(lambda (args ...) & body)

Creates an anonymous function (closure). This function uses lexical scope meaning that any free variables (variables bound outside this lambda definition) are “captured” by the closure. You can call this function with funcall (to be implemented) or apply.

(let1 (number 3)
  (let1 (adds-number-to (lambda (n)
                          (+ n number)))
    (print (apply adds-number-to '(5)))))
; 8

(apply function (args ...)): Call function with args and return the result. Note that since this is a Lisp-2 (i.e. functions and variables do not share the same namespace) you need to pass a function object (i.e. a lambda or quoted function).