blob: 9df5ac898945ae9e1d618fcd4fbbf0988beb78f5 [file] [log] [blame]
swissChilie9fec8b2021-06-22 13:59:33 -07001Lisp Standard Library
2=====================
3
4This provides documentation for every built-in function in the Lisp standard
5library. It is not auto-generated, please update this documentation if you
6change the API in any way.
7
8In general every user-facing API in the standard library should be documented
9here.
10
swissChili61ced3b2021-07-02 14:52:05 -070011- ``(x ...)`` represents a list ``x``.
12- ``& body`` means that the rest of the list is represented by ``body``.
13- ``[something]`` means that ``something`` is optional.
14
15Top-level primitives
swissChilie9fec8b2021-06-22 13:59:33 -070016--------------------
17
swissChili61ced3b2021-07-02 14:52:05 -070018These are "functions" that can only appear at the top-level of the program. This
19means they can't be nested in any other expressions.
swissChilic3b56c12021-07-02 20:52:09 -070020
swissChili61ced3b2021-07-02 14:52:05 -070021.. function:: (defun function-name (args ...) & body)
22
23 Defines a function ``function-name`` that takes ``args`` and evaluates
24 ``body``. ``function-name`` is quoted, not evaluated.
swissChilic3b56c12021-07-02 20:52:09 -070025
26 .. code-block:: lisp
swissChili61ced3b2021-07-02 14:52:05 -070027
28 (defun say-hi (name)
29 (print "Hi, ")
30 (print name))
31
32 (say-hi "Joe")
33 ; "Hi,"
34 ; "Joe"
35
36.. function:: (defmacro macro-name (args ...) & body)
37
38 ``defmacro`` is to macros as ``defun`` is to functions. When ``macro-name``
39 is called, whatever it evaluates to will be compiled.
40
41 Note that internally this compiles a function the same way all other
42 functions are compiled, meaning you can call **any** lisp function from a
43 macro definition and it will work as expected.
44
45 .. code-block:: Lisp
46
47 (defun double (n)
48 (+ n n))
swissChilic3b56c12021-07-02 20:52:09 -070049
swissChili61ced3b2021-07-02 14:52:05 -070050 (defmacro call-with-4 (whatever)
51 (print "this was run at **compile time**")
52 (print whatever)
53 ;; ``whatever`` expands to the form passed to this macro, in this case
54 ;; ``double``.
55 (list whatever 4))
56
57 (print (call-with-4 double))
58 ; "this was run at **compile time**"
59 ; 'double
60 ; 8
61
swissChili5500f702021-06-30 22:11:17 -070062Functions
63---------
swissChilic3b56c12021-07-02 20:52:09 -070064
swissChilie9fec8b2021-06-22 13:59:33 -070065.. function:: (if condition true-condition [false-condition])
66
swissChilic3b56c12021-07-02 20:52:09 -070067 Evaluates ``condition``, if it is truthy (non-``nil``) ``true-condition`` is
68 evaluated. Otherwise ``false-condition`` is evaluated. If
69 ``false-condition`` is not provided and ``condition`` is ``nil``, ``if``
70 will evaluate to ``nil``.
71
72 .. code-block:: lisp
73
74 (print (if (= 2 3)
75 "2 = 3"
76 "2 /= 3"))
77 ; 2 /= 3
swissChilie9fec8b2021-06-22 13:59:33 -070078
79.. function:: (let1 (variable binding) & body)
80
swissChilic3b56c12021-07-02 20:52:09 -070081 Evaluates ``binding`` and binds it to ``variable``, then evaluates ``body``.
82 After ``body`` is evaluated ``variable`` is unbound.
swissChilie9fec8b2021-06-22 13:59:33 -070083
swissChilic3b56c12021-07-02 20:52:09 -070084 .. code-block:: lisp
swissChilie9fec8b2021-06-22 13:59:33 -070085
swissChilic3b56c12021-07-02 20:52:09 -070086 (let1 (greeting (greet "John"))
87 (do-something greeting)
88 (print greeting))
89 ; greeting is no longer bound
swissChilie9fec8b2021-06-22 13:59:33 -070090
91.. function:: (gc)
92
swissChilic3b56c12021-07-02 20:52:09 -070093 Force the garbage collector (GC) to run.
swissChilie9fec8b2021-06-22 13:59:33 -070094
swissChilie9fec8b2021-06-22 13:59:33 -070095.. function:: (car pair)
96
swissChilic3b56c12021-07-02 20:52:09 -070097 Return the first item in ``pair``.
swissChilie9fec8b2021-06-22 13:59:33 -070098
swissChili61ced3b2021-07-02 14:52:05 -070099 .. code-block:: lisp
100
101 (car (cons 'a 'b)) ;=> 'a
102
swissChilie9fec8b2021-06-22 13:59:33 -0700103.. function:: (cdr pair)
104
swissChilic3b56c12021-07-02 20:52:09 -0700105 Return the second (last) item in ``pair``.
swissChilie9fec8b2021-06-22 13:59:33 -0700106
swissChili61ced3b2021-07-02 14:52:05 -0700107 .. code-block:: lisp
108
109 (cdr (cons 'a 'b)) ;=> 'b
110
swissChilie9fec8b2021-06-22 13:59:33 -0700111.. function:: (cons a b)
112
swissChilic3b56c12021-07-02 20:52:09 -0700113 Return a cons-pair containing ``a`` and ``b``.
swissChilie9fec8b2021-06-22 13:59:33 -0700114
115.. function:: (print val)
116
swissChilic3b56c12021-07-02 20:52:09 -0700117 Print out ``val`` to standard output. This will not be formatted as an
118 s-expression, but in a manner more similar to the internal representation.
119
swissChili5500f702021-06-30 22:11:17 -0700120.. function:: (list & items)
121
122 Returns a cons-list of items.
123
swissChili61ced3b2021-07-02 14:52:05 -0700124 .. code-block:: lisp
125
126 (list 1 2 3)
127 ; is the same as
128 (cons 1 (cons 2 (cons 3 nil)))
129
swissChili5500f702021-06-30 22:11:17 -0700130.. function:: (quote form)
131
132 Returns form without evaluating it.
133
134 .. code-block:: lisp
swissChili5500f702021-06-30 22:11:17 -0700135
136 '(cons a b)
137 ; or
138 (quote cons a b)
139 ; is the same as
140 (list 'cons 'a 'b)
swissChili74348422021-07-04 13:23:24 -0700141
142.. function:: (lambda (args ...) & body)
143
144 Creates an anonymous function (closure). This function uses **lexical
145 scope** meaning that any free variables (variables bound outside this lambda
146 definition) are "captured" by the closure. You can call this function with
147 ``funcall`` (to be implemented) or ``apply``.
148
149 .. code-block:: lisp
150
151 (let1 (number 3)
152 (let1 (adds-number-to (lambda (n)
153 (+ n number)))
154 (print (apply adds-number-to '(5)))))
155 ; 8
156
157.. function:: (apply function (args ...))
158
159 Call ``function`` with ``args`` and return the result. Note that since this
160 is a Lisp-2 (i.e. functions and variables do not share the same namespace)
161 you need to pass a **function object** (i.e. a lambda or quoted function).