blob: 0f204b9d753690d878ca99257d1e35e95f9c2178 [file] [log] [blame]
swissChili8a4b4ed2021-08-03 19:27:32 -07001\documentclass[letterpaper,11pt,twocolumn]{article}
2\usepackage[top=2cm, bottom=2cm, left=2cm, right=2cm]{geometry}\usepackage[T1]{fontenc}
3\usepackage[utf8]{inputenc}
4\usepackage{lmodern}
5\usepackage{amsmath}
6\usepackage{amsfonts}
7\usepackage{amssymb}
8\usepackage{amsthm}
9\usepackage{graphicx}
10\usepackage{color}
11\usepackage{xcolor}
12\usepackage{url}
13\usepackage{textcomp}
14\usepackage{listings}
15\usepackage{glossaries}
16\usepackage{parskip}
17\usepackage{imakeidx}
18\usepackage[normalem]{ulem}
19
20\title{Bluejay Lisp Reference}
21\author{swissChili}
22\date{Development Version: \today}
23
24\newcommand{\startexplanation}{$\triangleright$\hskip1.4ex}
25\newcommand{\definition}[2]{#1
swissChili36f2c692021-08-08 14:31:44 -070026 \begin{quote}%
swissChili8a4b4ed2021-08-03 19:27:32 -070027 \startexplanation#2%
swissChili36f2c692021-08-08 14:31:44 -070028 \end{quote}}
swissChili8a4b4ed2021-08-03 19:27:32 -070029\newcommand{\plus}{\texttt{+}}
30\newcommand{\pluses}[1]{\plus{}#1\plus{}}
31\newcommand{\earmuff}{\texttt{*}}
32\newcommand{\earmuffs}[1]{\earmuff{}#1\earmuff{}}
33\newcommand{\func}[1]{\text{$_f$\textbf{#1}}}
34\newcommand{\mac}[1]{\text{$_m$\textbf{#1}}}
35\newcommand{\reader}[1]{\text{$_r$\textbf{#1}}}
36\newcommand{\const}[1]{\text{$_c$\textbf{#1}}}
37\newcommand{\var}[1]{\text{$_v$\textbf{#1}}}
38\newcommand{\param}[1]{\textit{#1}}
39\newcommand{\ret}[1]{\uline{#1}}
40\newcommand{\type}[1]{\text{$_t$\textbf{#1}}}
41\newcommand{\more}{ \ldots}
42\newcommand{\T}{\texttt{t}}
43\newcommand{\nil}{\texttt{nil}}
44\newcommand{\default}[1]{\text{\textsubscript{
swissChili36f2c692021-08-08 14:31:44 -070045 \setlength{\fboxsep}{1pt}\setlength{\fboxrule}{0.2bp}%
46 \fbox{#1}}}}
swissChili8a4b4ed2021-08-03 19:27:32 -070047\newcommand{\opt}[2]{\text{$[$}\param{#1}\default{#2}\text{$]$}}
48\newcommand{\mut}[1]{\text{$\widetilde{#1}$}}
swissChilia89ee442021-08-04 20:54:51 -070049\newcommand{\mighteval}[1]{\text{$\widehat{#1}$}}
swissChili8a4b4ed2021-08-03 19:27:32 -070050\newcommand{\super}[1]{\text{$ ^{#1} $}}
51
52\newcommand{\optlist}[1]{\text{\(
53 \left\{
swissChili36f2c692021-08-08 14:31:44 -070054 \begin{array}{l}
swissChili8a4b4ed2021-08-03 19:27:32 -070055 #1
swissChili36f2c692021-08-08 14:31:44 -070056 \end{array}
swissChili8a4b4ed2021-08-03 19:27:32 -070057 \right\}
swissChili36f2c692021-08-08 14:31:44 -070058 \)}}
swissChili8a4b4ed2021-08-03 19:27:32 -070059
60\makeindex
61\makeglossaries
62
swissChili36f2c692021-08-08 14:31:44 -070063\newglossaryentry{closure}{name={closure},description={A
64 \type{function-object} that captures certain variables from its
65 defining context}}
swissChili8a4b4ed2021-08-03 19:27:32 -070066
swissChili36f2c692021-08-08 14:31:44 -070067\newglossaryentry{lexical-scope}{name={lexical scope},description={A
68 method of scoping where the values in scope at a given time are
69 determined by the static content of the source program, not by the
70 state of the callstack or other execution details. This allows for
71 example closures to \gls{closure}s to capture some of the state of
72 their defining context}}
swissChili8a4b4ed2021-08-03 19:27:32 -070073
swissChili36f2c692021-08-08 14:31:44 -070074\newglossaryentry{truthy}{name={truthy},description={A value that is
75 not \nil}}
swissChili8a4b4ed2021-08-03 19:27:32 -070076
77\begin{document}
78
79\maketitle
80\tableofcontents
81
82\section{Introduction}
83
swissChili36f2c692021-08-08 14:31:44 -070084This document provides a brief reference to the Bluejay Lisp language
85and standard library. It documents every currently valid function,
86macro, reader macro, and special form supported by the compiler.
swissChili8a4b4ed2021-08-03 19:27:32 -070087
88\subsection{Typography}
89
swissChili36f2c692021-08-08 14:31:44 -070090The following text styles and symbols are used within this document to
91indicate particular values or meanings:
swissChili8a4b4ed2021-08-03 19:27:32 -070092
swissChilia89ee442021-08-04 20:54:51 -070093\begin{tabular}[t]{p{0.2\linewidth} p{0.64\linewidth}}
swissChili36f2c692021-08-08 14:31:44 -070094 \func{cons} & A function ``cons.'' \\
95 \const{\plus{}foo\plus} & A constant ``\plus{}foo\plus.'' \\
96 \var{\earmuff{}bar\earmuff} & A global variable ``\earmuff{}bar\earmuff''. \\
97 \reader{baz} & A reader macro ``baz.'' \\
98 \mac{quux} & A macro ``quux.'' \\
99 \param{parameter} & A function argument ``parameter'' \\
100 \opt{var}{123} & An optional function argument ``var'' with the default value ``123.'' \\
101 \param{args}\more & ``args'' represents the rest of the items in the list. \\
102 \mut{\param{mut}} & A function argument ``mut'' that might be mutated. \\
103 \mighteval{\param{maybe}} & ``maybe'' may or may not be evaluated. \\
104 \ret{value} & Indicates that a form will evaluate to ``value''. \\
105 \type{integer} & The type ``integer''. \\
106 \optlist{\text{a}\\\text{b}} & One of ``a'' or ``b.''
swissChili8a4b4ed2021-08-03 19:27:32 -0700107\end{tabular}
108
109\section{Primitives}
110
111\subsection{Type Predicates}
112
113\definition{
swissChili36f2c692021-08-08 14:31:44 -0700114 (\optlist{
115 \func{nilp} \text{ or } \func{not} \\
swissChilifc5c9412021-08-08 19:08:26 -0700116 \func{closurep} \text{ or } \func{functionp} \\
117 \func{integerp} \\
118 \func{consp} \\
119 \func{symbolp}
swissChili36f2c692021-08-08 14:31:44 -0700120 } \param{value})\index{nilp}\index{not}
swissChili8a4b4ed2021-08-03 19:27:32 -0700121}{
swissChili36f2c692021-08-08 14:31:44 -0700122 \ret{\T} if \param{value} is of the specified type, \ret{\nil}
123 otherwise.
swissChili8a4b4ed2021-08-03 19:27:32 -0700124}
125
126\subsection{Definitions and Variables}
127
128\definition{
swissChili36f2c692021-08-08 14:31:44 -0700129 (\mac{defun} \param{name} (\param{args}\more) \param{body}\more)\index{defun} \\
130 (\mac{defmacro} \param{name} (\param{args}\more) \param{body}\more)\index{defmacro}
swissChili8a4b4ed2021-08-03 19:27:32 -0700131}{
swissChili36f2c692021-08-08 14:31:44 -0700132 Define a function or macro respectively, taking \param{args}
133 arguments and evaluating \param{body} in turn, finally evaluating to
134 \ret{the final entry in \param{body}} or \ret{\nil} if \param{body}
135 is empty.
swissChili8a4b4ed2021-08-03 19:27:32 -0700136}
137
138\definition{
swissChilifc5c9412021-08-08 19:08:26 -0700139 (\mac{let1} (\param{variable} \param{form}) \param{body}\more)\index{let1} \\
140 (\mac{let} ((\param{variable} \param{form})\more) \param{body}\more)\index{let}
swissChili8a4b4ed2021-08-03 19:27:32 -0700141}{
swissChili36f2c692021-08-08 14:31:44 -0700142 First evaluate \param{form}, binding it to \param{variable}. Then
143 evaluate \param{body}, finally evaluating to \ret{the final entry in
144 \param{body}} or \ret{\nil} if \param{body} is
145 empty. \param{variable} is no longer in scope after this form ends.
swissChilifc5c9412021-08-08 19:08:26 -0700146 \mac{let} is similar to \mac{let*} in other lisps, later variables
147 can reference previous ones.
148}
149
150\definition{
151 (\mac{flet1} (\param{name} (\param{args}\more) \param{body}\more)) \\
152 (\mac{flet} ((\param{name} (\param{args}\more)\more) \param{body}\more))
153 \index{flet}\index{flet1}
154}{
155 Like \mac{let} and \mac{let1} but creates a lambda. Unlike other
156 lisps the defined function remains in the variable namespace as a
157 \type{function-object}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700158}
159
160\definition{
swissChili36f2c692021-08-08 14:31:44 -0700161 \reader{\textquotesingle}\param{value} \\
162 (\mac{quote} \param{value})\index{quote}
swissChili8a4b4ed2021-08-03 19:27:32 -0700163}{
swissChili36f2c692021-08-08 14:31:44 -0700164 \ret{Return \param{value}} as-is, without evaluating it.
165}
166
167\definition{
168 \reader{\`}\param{value} \\
169 (\mac{backquote} \param{value})\index{backquote}\index{\`}
170}{
171 Return \ret{\param{value}} as-is, except for any \mac{unquote}
172 and \mac{unquote-splice} forms (and their reader-macro equivalents).
swissChili8a4b4ed2021-08-03 19:27:32 -0700173}
174
swissChili3f7f5842021-08-08 17:13:45 -0700175\definition{
176 \reader{,}\param{value} \\
177 (\mac{unquote} \param{value}) \\
178 \reader{,\texttt{@}}\param{value} \\
179 (\mac{unquote-splice} \param{value})
180 \index{unquote}\index{unquote-splice}
181 \index{,}\index{,@}
182}{
183 In the context of a \mac{backquote}, evaluate \param{value} instead of
184 using it as-is. \mac{unquote-splice} and \reader{,\texttt{@}} take a
185 list as their argument, and ``splice'' each element in to
186 the \mac{backquote} list so that each element of that argument corresponds
187 to an element of the \mac{backquote} list.
188 The other two macros insert their argument as a single element in the list.
189}
190
swissChili8a4b4ed2021-08-03 19:27:32 -0700191\subsection{Control Flow}
192
193\definition{
swissChili36f2c692021-08-08 14:31:44 -0700194 (\mac{if} \param{predicate} \param{then} \opt{otherwise}{nil})\index{if} \\
195 (\mac{when} \param{predicate} \param{then\more})\index{when} \\
196 (\mac{unless} \param{predicate} \param{otherwise\more})\index{unless}
swissChili8a4b4ed2021-08-03 19:27:32 -0700197}{
swissChili36f2c692021-08-08 14:31:44 -0700198 First evaluate \param{predicate}. If it is \gls{truthy} evaluate and
199 return \ret{\param{then}}, otherwise \ret{\param{otherwise}}. If
200 either is not provided return \ret{\nil}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700201}
202
203\definition{
swissChili36f2c692021-08-08 14:31:44 -0700204 (\mac{progn} \opt{forms\more}{nil})\index{progn}
swissChili8a4b4ed2021-08-03 19:27:32 -0700205}{
swissChili36f2c692021-08-08 14:31:44 -0700206 Evaluate \param{forms} from first to last, finally returning
207 \ret{the last form}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700208}
209
swissChilia89ee442021-08-04 20:54:51 -0700210\definition{
swissChili36f2c692021-08-08 14:31:44 -0700211 (\mac{and} \param{first} \param{\mighteval{rest}}\more)\index{and} \\
212 (\mac{or} \param{first} \param{\mighteval{rest}}\more)\index{or}
swissChilia89ee442021-08-04 20:54:51 -0700213}{
swissChili36f2c692021-08-08 14:31:44 -0700214 Short circuiting $\land$ and $\lor$, respectively. Return the first
215 value that is \nil{} or truthy, respectively, or the last value if
216 all are truthy/\nil{}.
swissChilia89ee442021-08-04 20:54:51 -0700217}
218
swissChili8a4b4ed2021-08-03 19:27:32 -0700219\section{Numbers}
220
221\subsection{Integers}
222
223\definition{
swissChili36f2c692021-08-08 14:31:44 -0700224 (\func{$+$} \param{a b})\index{+} \\
225 (\func{$-$} \param{a b})\index{-} \\
226 (\func{$*$} \param{a b})\index{*} \\
227 (\func{$/$} \param{a b})\index{/}
swissChili8a4b4ed2021-08-03 19:27:32 -0700228}{
swissChili36f2c692021-08-08 14:31:44 -0700229 The \ret{sum, difference, product, or quotient} of \param{a} and
230 \param{b} as an \type{integer}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700231}
232
233\definition{
swissChili36f2c692021-08-08 14:31:44 -0700234 (\func{=} \param{a b})
swissChili8a4b4ed2021-08-03 19:27:32 -0700235}{
swissChili36f2c692021-08-08 14:31:44 -0700236 \ret{\T} if \param{a} and \param{b} hold the same \type{integer}
237 value, \ret{\nil} otherwise.
swissChili8a4b4ed2021-08-03 19:27:32 -0700238}
239
240\section{Function Manipulation}
241
242\definition{
swissChili36f2c692021-08-08 14:31:44 -0700243 (\func{funcall} \param{args}\more)\index{funcall} \\
244 (\func{apply} \param{function} \param{args})\index{apply}
swissChili8a4b4ed2021-08-03 19:27:32 -0700245}{
swissChili36f2c692021-08-08 14:31:44 -0700246 Call the \type{closure} or \type{function-object} \param{function}
247 with \param{args} and evaluate to \ret{its result}. An error occurs
248 if \param{args} are not acceptable.
swissChili8a4b4ed2021-08-03 19:27:32 -0700249}
250
251\definition{
swissChili36f2c692021-08-08 14:31:44 -0700252 (\func{recurse} \param{args}\more)\index{recurse}
swissChili8a4b4ed2021-08-03 19:27:32 -0700253}{
swissChili36f2c692021-08-08 14:31:44 -0700254 In a lambda definition, call the current lambda with \param{args}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700255}
256
257\definition{
swissChili36f2c692021-08-08 14:31:44 -0700258 (\mac{function} \param{function-name})\index{function} \\
259 \reader{\#\textquotesingle}\param{function-name}\index{\#\textquotesingle}
swissChili8a4b4ed2021-08-03 19:27:32 -0700260}{
swissChili36f2c692021-08-08 14:31:44 -0700261 Create a \ret{\type{function-object} from an existing function or
262 macro}. \param{function} must be a symbol literal at compile time.
swissChili8a4b4ed2021-08-03 19:27:32 -0700263}
264
265\definition{
swissChili36f2c692021-08-08 14:31:44 -0700266 (\func{lambda} (\param{args}\more) \param{body}\more)\index{lambda}
swissChili8a4b4ed2021-08-03 19:27:32 -0700267}{
swissChili36f2c692021-08-08 14:31:44 -0700268 Create a \ret{lexically-scoped \type{\gls{closure}}} taking
269 \param{args} and evaluating to \param{body}.
270}
271
272\definition{
273 (\func{eval} \param{form})\index{eval}
274}{
275 Evaluate and return \ret{\param{form}} in the current global
276 environment. The evaluated form does not use \gls{lexical-scope}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700277}
278
279\section{Lists}
280
281\subsection{Creating Lists}
282
283\definition{
swissChili36f2c692021-08-08 14:31:44 -0700284 (\func{cons} \param{a} \param{b})\index{cons}
swissChili8a4b4ed2021-08-03 19:27:32 -0700285}{
swissChili36f2c692021-08-08 14:31:44 -0700286 Join \param{a} and \param{b} into a \ret{\type{cons} pair}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700287}
288
289\definition{
swissChili36f2c692021-08-08 14:31:44 -0700290 (\func{list} \param{values}\more)\index{list}
swissChili8a4b4ed2021-08-03 19:27:32 -0700291}{
swissChili36f2c692021-08-08 14:31:44 -0700292 Construct a \ret{\type{cons}-list of \param{values}}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700293}
294
295\subsection{Deconstructing Lists}
296
297\definition{
swissChili36f2c692021-08-08 14:31:44 -0700298 (\func{length} \param{list})\index{list}
swissChili8a4b4ed2021-08-03 19:27:32 -0700299}{
swissChili36f2c692021-08-08 14:31:44 -0700300 Return the \ret{length of \param{list}} if it is a \type{cons}-list,
301 \nil{} otherwise.
swissChili8a4b4ed2021-08-03 19:27:32 -0700302}
303
304\definition{
swissChili36f2c692021-08-08 14:31:44 -0700305 (\func{car} \param{pair})\index{car} \\
306 (\func{cdr} \param{pair})\index{cdr}
swissChili8a4b4ed2021-08-03 19:27:32 -0700307}{
swissChili36f2c692021-08-08 14:31:44 -0700308 Return the \ret{first or second item} of \type{cons} \param{pair},
309 respectively.
swissChili8a4b4ed2021-08-03 19:27:32 -0700310}
311
312\definition{
swissChili36f2c692021-08-08 14:31:44 -0700313 (\optlist{
314 \func{caar}\\
315 \func{cadr}\\
316 \func{caddr}\\
317 \func{cadar}\\
318 \func{caddar}
319 } \param{val})
swissChili8a4b4ed2021-08-03 19:27:32 -0700320}{
swissChili36f2c692021-08-08 14:31:44 -0700321 Behave like a combination of \func{car} and \func{cdr} would.
swissChili8a4b4ed2021-08-03 19:27:32 -0700322}
323
324\definition{
swissChili36f2c692021-08-08 14:31:44 -0700325 (\func{elt} \param{list} \param{n})\index{elt}
swissChili8a4b4ed2021-08-03 19:27:32 -0700326}{
swissChili36f2c692021-08-08 14:31:44 -0700327 Return the \ret{\param{n}\super{th} element of \param{list}},
328 starting from 0, or \ret{\nil} if \param{n} $ \ge $ (\func{length}
329 \param{list}) or \param{list} is not a \type{cons}-list or \param{n}
330 is not an \type{integer}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700331}
332
333\subsection{Operating on Lists}
334
335\definition{
swissChili36f2c692021-08-08 14:31:44 -0700336 (\func{mapcar} \param{fun} \param{list})\index{mapcar}
swissChili8a4b4ed2021-08-03 19:27:32 -0700337}{
swissChili36f2c692021-08-08 14:31:44 -0700338 Apply \param{fun} to each element of \param{list}, returning a
339 \ret{new \type{cons}-list} containing the results of the respective
340 applications of \param{fun}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700341}
342
343\definition{
swissChili36f2c692021-08-08 14:31:44 -0700344 (\optlist{\func{remove-if}\\\func{remove-if-not}}
345 \param{predicate} \param{list})\index{remove-if}\index{remove-if-not}
swissChili8a4b4ed2021-08-03 19:27:32 -0700346}{
swissChili36f2c692021-08-08 14:31:44 -0700347 Return a \ret{new \type{cons}-list} of all the items of \param{list}
348 that either do not or do satisfy \param{predicate}, respectively.
swissChili8a4b4ed2021-08-03 19:27:32 -0700349}
350
351\definition{
swissChili36f2c692021-08-08 14:31:44 -0700352 (\func{reduce} \param{fun} \param{list} \opt{initial-value}{\nil})
swissChili8a4b4ed2021-08-03 19:27:32 -0700353}{
swissChili36f2c692021-08-08 14:31:44 -0700354 Apply \param{fun} to two arguments at a time, starting with
355 \param{initial-value} and (\func{car} \param{list}) and continuing
356 with the result of the previous invocation and the successive
357 element of \param{list}. Return \ret{the result of the final
358 invocation}, or \ret{\param{initial-value}} if \param{list} is
359 empty.
swissChili8a4b4ed2021-08-03 19:27:32 -0700360}
361
362\section{Input \& Output}
363
364\definition{
swissChili36f2c692021-08-08 14:31:44 -0700365 (\func{print} \param{value})\index{print}
swissChili8a4b4ed2021-08-03 19:27:32 -0700366}{
swissChili36f2c692021-08-08 14:31:44 -0700367 Print \param{value} to standard output. Return \ret{\nil}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700368}
369
370\definition{
swissChili36f2c692021-08-08 14:31:44 -0700371 (\func{read})\index{read}
swissChili8a4b4ed2021-08-03 19:27:32 -0700372}{
swissChili36f2c692021-08-08 14:31:44 -0700373 Read and return an \ret{S-expression} from standard input
swissChili8a4b4ed2021-08-03 19:27:32 -0700374}
375
376\subsection{Loading Programs}
377
378\definition{
swissChili36f2c692021-08-08 14:31:44 -0700379 \const{\pluses{current-file}}\index{\pluses{current-file}}
swissChili8a4b4ed2021-08-03 19:27:32 -0700380}{
swissChili36f2c692021-08-08 14:31:44 -0700381 The current file being compiled, or \nil{} if not compiling a file.
swissChili8a4b4ed2021-08-03 19:27:32 -0700382}
383
384\definition{
swissChili36f2c692021-08-08 14:31:44 -0700385 (\func{load} \param{lisp-file})\index{load}
swissChili8a4b4ed2021-08-03 19:27:32 -0700386}{
swissChili36f2c692021-08-08 14:31:44 -0700387 Load and evaluate \type{string} \param{lisp-file} as a local path
388 relative to the current file, or the current working directory if
389 not compiling a file. Return \ret{\nil}.
swissChili8a4b4ed2021-08-03 19:27:32 -0700390}
391
swissChili04d94162022-07-30 21:46:49 -0700392\section{Inspecting \& Modifying the Environment}
393
394\subsection{Managing Memory}
395
396\definition{
397 (\func{gc})\index{gc}
398}{
399 Run the garbage collector.
400}
401
402\definition{
403 (\func{gc-stats})\index{gc-stats}
404}{
405 Return some
406 statistics about the garbage collector, in the form of a list:
407 \ret{(\param{total-allocs} \param{gc-runs})}, where
408 \param{total-allocs} is the current number of active allocations,
409 and \param{gc-runs} is the total number of times the garbage
410 collector has been run.
411}
412
413\subsection{Introspection}
414
415\definition{ \const{\pluses{current-env}} }{ An opaque object
416 representing the current environment. }
417
418\definition{
419 (\func{env-functions} \param{current-env})
420}{
421 Returns a
422 list of symbols, each of which is the name of a function defined in
423 the environment specified by \param{current-env}.
424}
425
swissChili8a4b4ed2021-08-03 19:27:32 -0700426\printindex
427
428\printglossaries
429
430\end{document}