blob: 52e9e4b1ca7898fe2fa54fb1be228f34bda2a724 [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
26\begin{quote}%
27 \startexplanation#2%
28\end{quote}}
29\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{
45 \setlength{\fboxsep}{1pt}\setlength{\fboxrule}{0.2bp}%
46 \fbox{#1}}}}
47\newcommand{\opt}[2]{\text{$[$}\param{#1}\default{#2}\text{$]$}}
48\newcommand{\mut}[1]{\text{$\widetilde{#1}$}}
49\newcommand{\super}[1]{\text{$ ^{#1} $}}
50
51\newcommand{\optlist}[1]{\text{\(
52 \left\{
53 \begin{array}{l}
54 #1
55 \end{array}
56 \right\}
57\)}}
58
59\makeindex
60\makeglossaries
61
62\newglossaryentry{closure}{name={closure},description={A \type{function-object} that captures certain variables from its defining context}}
63
64\newglossaryentry{lexical-scope}{name={lexical scope},description={A method of scoping where the values in scope at a given time are determined by the static content of the source program, not by the state of the callstack or other execution details. This allows for example closures to \gls{closure}s to capture some of the state of their defining context}}
65
66\newglossaryentry{truthy}{name={truthy},description={A value that is not \nil}}
67
68\begin{document}
69
70\maketitle
71\tableofcontents
72
73\section{Introduction}
74
75This document provides a brief reference to the Bluejay Lisp language and standard library. It documents every currently valid function, macro, reader macro, and special form supported by the compiler.
76
77\subsection{Typography}
78
79The following text styles and symbols are used within this document to indicate particular values or meanings:
80
81\begin{tabular}[t]{p{0.2\linewidth} p{0.7\linewidth}}
82 \func{cons} & A function ``cons.'' \\
83 \const{\plus{}foo\plus} & A constant ``\plus{}foo\plus.'' \\
84 \var{\earmuff{}bar\earmuff} & A global variable ``\earmuff{}bar\earmuff''. \\
85 \reader{baz} & A reader macro ``baz.'' \\
86 \mac{quux} & A macro ``quux.'' \\
87 \param{parameter} & A function argument ``parameter`` \\
88 \opt{var}{123} & An optional function argument ``var'' with the default value ``123.'' \\
89 \param{args}\more & ``args'' represents the rest of the items in the list. \\
90 \mut{\param{mut}} & A function argument ``mut'' that might be mutated. \\
91 \ret{value} & Indicates that a form will evaluate to ``value''. \\
92 \type{integer} & The type ``integer''. \\
93 \optlist{\text{a}\\\text{b}} & One of ``a'' or ``b.''
94\end{tabular}
95
96\section{Primitives}
97
98\subsection{Type Predicates}
99
100\definition{
101 (\optlist{
102 \func{nilp} \text{ or } \func{not} \\
103 \func{integerp}
104 } \param{value})\index{nilp}\index{not}
105}{
106 \ret{\T} if \param{value} is of the specified type, \ret{\nil} otherwise.
107}
108
109\subsection{Definitions and Variables}
110
111\definition{
112 (\mac{defun} \param{name} (\param{args}\more) \param{body}\more)\index{defun} \\
113 (\mac{defmacro} \param{name} (\param{args}\more) \param{body}\more)\index{defmacro}
114}{
115 Define a function or macro respectively, taking \param{args} arguments and evaluating \param{body} in turn, finally evaluating to \ret{the final entry in \param{body}} or \ret{\nil} if \param{body} is empty.
116}
117
118\definition{
119 (\mac{let1} (\param{variable} \param{form}) \param{body}\more)\index{let1}
120}{
121 First evaluate \param{form}, binding it to \param{variable}. Then evaluate \param{body}, finally evaluating to \ret{the final entry in \param{body}} or \ret{\nil} if \param{body} is empty. \param{variable} is no longer in scope after this form ends.
122}
123
124\definition{
125 \reader{\textquotesingle}\param{value} \\
126 (\mac{quote} \param{value})\index{quote}
127}{
128 \ret{Return \param{value}} as-is, without evaluating it.
129}
130
131\subsection{Control Flow}
132
133\definition{
134 (\mac{if} \param{predicate} \param{then} \opt{otherwise}{nil})\index{if} \\
135 (\mac{when} \param{predicate} \param{then\more})\index{when} \\
136 (\mac{unless} \param{predicate} \param{otherwise\more})\index{unless}
137}{
138 First evaluate \param{predicate}. If it is \gls{truthy} evaluate and return \ret{\param{then}}, otherwise \ret{\param{otherwise}}. If either is not provided return \ret{\nil}.
139}
140
141\definition{
142 (\mac{progn} \opt{forms\more}{nil})\index{progn}
143}{
144 Evaluate \param{forms} from first to last, finally returning \ret{the last form}.
145}
146
147\section{Numbers}
148
149\subsection{Integers}
150
151\definition{
152 (\func{$+$} \param{a b})\index{+} \\
153 (\func{$-$} \param{a b})\index{-} \\
154 (\func{$*$} \param{a b})\index{*} \\
155 (\func{$/$} \param{a b})\index{/}
156}{
157 The \ret{sum, difference, product, or quotient} of \param{a} and \param{b} as an \type{integer}.
158}
159
160\definition{
161 (\func{=} \param{a b})
162}{
163 \ret{\T} if \param{a} and \param{b} hold the same \type{integer} value, \ret{\nil} otherwise.
164}
165
166\section{Function Manipulation}
167
168\definition{
169 (\mac{funcall} \param{function} \param{args}\more)\index{funcall} \\
170 (\func{apply} \param{function} \param{args})\index{apply}
171}{
172 Call the \type{closure} or \type{function-object} \param{function} with \param{args} and evaluate to \ret{its result}. An error occurs if \param{args} are not acceptable.
173}
174
175\definition{
176 (\mac{function} \param{function-name})\index{function} \\
177 \reader{\#\textquotesingle}\param{function-name}\index{\#\textquotesingle}
178}{
179 Create a \ret{\type{function-object} from an existing function}. \param{function} must be a symbol literal at compile time.
180}
181
182\definition{
183 (\func{lambda} (\param{args}\more) \param{body}\more)\index{lambda}
184}{
185 Create a \ret{lexically-scoped \type{\gls{closure}}} taking \param{args} and evaluating to \param{body}.
186}
187
188\definition{
189 (\func{eval} \param{form})\index{eval}
190}{
191 Evaluate and return \ret{\param{form}} in the current global environment. The evaluated form does not use \gls{lexical-scope}.
192}
193
194\section{Lists}
195
196\subsection{Creating Lists}
197
198\definition{
199 (\func{cons} \param{a} \param{b})\index{cons}
200}{
201 Join \param{a} and \param{b} into a \ret{\type{cons} pair}.
202}
203
204\definition{
205 (\func{list} \param{values}\more)\index{list}
206}{
207 Construct a \ret{\type{cons}-list of \param{values}}.
208}
209
210\subsection{Deconstructing Lists}
211
212\definition{
213 (\func{length} \param{list})\index{list}
214}{
215 Return the \ret{length of \param{list}} if it is a \type{cons}-list, \nil{} otherwise.
216}
217
218\definition{
219 (\func{car} \param{pair})\index{car} \\
220 (\func{cdr} \param{pair})\index{cdr}
221}{
222 Return the \ret{first or second item} of \type{cons} \param{pair}, respectively.
223}
224
225\definition{
226 (\optlist{
227 \func{caar}\\
228 \func{cadr}\\
229 \func{caddr}\\
230 \func{cadar}\\
231 \func{caddar}
232 } \param{val})
233}{
234 Behave like a combination of \func{car} and \func{cdr} would.
235}
236
237\definition{
238 (\func{elt} \param{list} \param{n})\index{elt}
239}{
240 Return the \ret{\param{n}\super{th} element of \param{list}}, starting from 0, or \ret{\nil} if \param{n} $ \ge $ (\func{length} \param{list}) or \param{list} is not a \type{cons}-list or \param{n} is not an \type{integer}.
241}
242
243\subsection{Operating on Lists}
244
245\definition{
246 (\func{mapcar} \param{fun} \param{list})\index{mapcar}
247}{
248 Apply \param{fun} to each element of \param{list}, returning a \ret{new \type{cons}-list} containing the results of the respective applications of \param{fun}.
249}
250
251\definition{
252 (\optlist{\func{remove-if}\\\func{remove-if-not}} \param{predicate} \param{list})\index{remove-if}\index{remove-if-not}
253}{
254 Return a \ret{new \type{cons}-list} of all the items of \param{list} that either do not or do satisfy \param{predicate}, respectively.
255}
256
257\definition{
258 (\func{reduce} \param{fun} \param{list} \opt{initial-value}{\nil})
259}{
260 Apply \param{fun} to two arguments at a time, starting with \param{initial-value} and (\func{car} \param{list}) and continuing with the result of the previous invocation and the successive element of \param{list}. Return \ret{the result of the final invocation}, or \ret{\param{initial-value}} if \param{list} is empty.
261}
262
263\section{Input \& Output}
264
265\definition{
266 (\func{print} \param{value})\index{print}
267}{
268 Print \param{value} to standard output. Return \ret{\nil}.
269}
270
271\definition{
272 (\func{read})\index{read}
273}{
274 Read and return an \ret{S-expression} from standard input
275}
276
277\subsection{Loading Programs}
278
279\definition{
280 \const{\pluses{current-file}}\index{\pluses{current-file}}
281}{
282 The current file being compiled, or \nil{} if not compiling a file.
283}
284
285\definition{
286 (\func{load} \param{lisp-file})\index{load}
287}{
288 Load and evaluate \type{string} \param{lisp-file} as a local path relative to the current file, or the current working directory if not compiling a file. Return \ret{\nil}.
289}
290
291\printindex
292
293\printglossaries
294
295\end{document}