# API Index
135 forms available:
[`*`](#-STAR)
[`**`](#-STAR-STAR)
[`+`](#+)
[`-`](#-)
[`/`](#/)
[`<`](#<)
[`<=`](#<=)
[`=`](#=)
[`>`](#>)
[`>=`](#>=)
[`abs`](#abs)
[**`and`**](#and)
[`apply`](#apply)
[`atom?`](#atom-QMARK)
[`bang`](#bang)
[`body`](#body)
[`butlast`](#butlast)
[`capitalize`](#capitalize)
[`car`](#car)
[`cdr`](#cdr)
[`colon`](#colon)
[`comma`](#comma)
[*`comment`*](#comment)
[`comp`](#comp)
[`complement`](#complement)
[`concat`](#concat)
[`concat2`](#concat2)
[**`cond`**](#cond)
[`cons`](#cons)
[`constantly`](#constantly)
[`dec`](#dec)
[**`def`**](#def)
[**`defmacro`**](#defmacro)
[**`defn`**](#defn)
[`doc`](#doc)
[*`dotimes`*](#dotimes)
[`downcase`](#downcase)
[`drop`](#drop)
[`enumerate`](#enumerate)
[**`error`**](#error)
[**`errors`**](#errors)
[`eval`](#eval)
[`even?`](#even-QMARK)
[`every`](#every)
[`exclaim`](#exclaim)
[`exit`](#exit)
[`filter`](#filter)
[`flatten`](#flatten)
[*`foreach`*](#foreach)
[`forms`](#forms)
[`fuse`](#fuse)
[`gensym`](#gensym)
[`help`](#help)
[`identity`](#identity)
[*`if`*](#if)
[*`if-not`*](#if-not)
[`inc`](#inc)
[`interpose`](#interpose)
[*`is`*](#is)
[`isqrt`](#isqrt)
[`juxt`](#juxt)
[**`lambda`**](#lambda)
[`last`](#last)
[`len`](#len)
[**`let`**](#let)
[*`let*`*](#let-STAR)
[`list`](#list)
[`list*`](#list-STAR)
[`list?`](#list-QMARK)
[`load`](#load)
[**`loop`**](#loop)
[`macroexpand-1`](#macroexpand-1)
[`map`](#map)
[`mapcat`](#mapcat)
[`max`](#max)
[`min`](#min)
[`neg?`](#neg-QMARK)
[`not`](#not)
[`not=`](#not=)
[`nth`](#nth)
[`number?`](#number-QMARK)
[`odd?`](#odd-QMARK)
[**`or`**](#or)
[`partial`](#partial)
[`period`](#period)
[`pos?`](#pos-QMARK)
[`print`](#print)
[`printl`](#printl)
[`println`](#println)
[*`progn`*](#progn)
[`punctuate`](#punctuate)
[`punctuate-atom`](#punctuate-atom)
[**`quote`**](#quote)
[`randalpha`](#randalpha)
[`randchoice`](#randchoice)
[`randigits`](#randigits)
[`randint`](#randint)
[`range`](#range)
[`readlist`](#readlist)
[`reduce`](#reduce)
[`rem`](#rem)
[`remove`](#remove)
[`repeat`](#repeat)
[`repeatedly`](#repeatedly)
[`reverse`](#reverse)
[`screen-clear`](#screen-clear)
[`screen-end`](#screen-end)
[`screen-get-key`](#screen-get-key)
[`screen-size`](#screen-size)
[`screen-start`](#screen-start)
[`screen-write`](#screen-write)
[`second`](#second)
[**`set!`**](#set-BANG)
[`shell`](#shell)
[`shuffle`](#shuffle)
[`sleep`](#sleep)
[`some`](#some)
[`sort`](#sort)
[`sort-by`](#sort-by)
[`source`](#source)
[`split`](#split)
[**`swallow`**](#swallow)
[**`syntax-quote`**](#syntax-quote)
[`take`](#take)
[**`test`**](#test)
[`tosentence`](#tosentence)
[`true?`](#true-QMARK)
[**`try`**](#try)
[`upcase`](#upcase)
[`version`](#version)
[*`when`*](#when)
[*`when-not`*](#when-not)
[*`while`*](#while)
[*`with-screen`*](#with-screen)
[`zero?`](#zero-QMARK)
# Operators
## `*`
Multiply 0 or more numbers
Type: native function
Arity: 0+
Args: `(() . xs)`
### Examples
```
> (* 1 2 3)
;;=>
6
> (*)
;;=>
1
```
[Back to index](#api-index)
-----------------------------------------------------
## `**`
Exponentiation operator
Type: function
Arity: 2
Args: `(n m)`
### Examples
```
> (** 1 0)
;;=>
1
> (** 2 4)
;;=>
16
> (** 10 10)
;;=>
10000000000
```
[Back to index](#api-index)
-----------------------------------------------------
## `+`
Add 0 or more numbers
Type: native function
Arity: 0+
Args: `(() . xs)`
### Examples
```
> (+ 1 2 3)
;;=>
6
> (+)
;;=>
0
```
[Back to index](#api-index)
-----------------------------------------------------
## `-`
Subtract 0 or more numbers from the first argument
Type: native function
Arity: 1+
Args: `(x . xs)`
### Examples
```
> (- 1 1)
;;=>
0
> (- 5 2 1)
;;=>
2
> (- 99)
;;=>
-99
```
[Back to index](#api-index)
-----------------------------------------------------
## `/`
Divide the first argument by the rest
Type: native function
Arity: 2+
Args: `(numerator denominator1 . more)`
### Examples
```
> (/ 1 2)
;;=>
0
> (/ 12 2 3)
;;=>
2
> (/ 1 0)
;;=>
ERROR: ((builtin function /) (division by zero))
```
[Back to index](#api-index)
-----------------------------------------------------
## `<`
Return t if the arguments are in strictly increasing order, () otherwise
Type: native function
Arity: 1+
Args: `(x . xs)`
### Examples
```
> (< 1 2)
;;=>
t
> (< 1 1)
;;=>
()
> (< 1)
;;=>
t
> (apply < (range 100))
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `<=`
Return t if the arguments are in increasing or equal order, () otherwise
Type: native function
Arity: 1+
Args: `(x . xs)`
### Examples
```
> (<= 1 2)
;;=>
t
> (<= 1 1)
;;=>
t
> (<= 1)
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `=`
Return t if the arguments are equal, () otherwise
Type: native function
Arity: 1+
Args: `(x . xs)`
### Examples
```
> (= 1 1)
;;=>
t
> (= 1 2)
;;=>
()
> (apply = (repeat 10 t))
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `>`
Return t if the arguments are in strictly decreasing order, () otherwise
Type: native function
Arity: 1+
Args: `(x . xs)`
### Examples
```
> (> 1 2)
;;=>
()
> (> 1 1)
;;=>
()
> (> 1)
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `>=`
Return t if the arguments are in decreasing or equal order, () otherwise
Type: native function
Arity: 1+
Args: `(x . xs)`
### Examples
```
> (>= 1 2)
;;=>
()
> (>= 1 1)
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `abs`
Return absolute value of x
Type: function
Arity: 1
Args: `(x)`
### Examples
```
> (abs 1)
;;=>
1
> (abs -100)
;;=>
100
```
[Back to index](#api-index)
-----------------------------------------------------
## `and`
Boolean and
Type: special form
Arity: 0+
Args: `(() . xs)`
### Examples
```
(and)
;;=>
true
> (and t t)
;;=>
true
> (and t t ())
;;=>
()
> (and () (/ 1 0))
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `apply`
Apply a function to a list of arguments
Type: native function
Arity: 2
Args: `(f args)`
### Examples
```
> (apply + (repeat 10 1))
;;=>
10
> (apply * (cdr (range 10)))
;;=>
362880
```
[Back to index](#api-index)
-----------------------------------------------------
## `atom?`
Return t if the argument is an atom, () otherwise
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (atom? 1)
;;=>
()
> (atom? (quote one))
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `bang`
Add an exclamation point at end of atom
Type: function
Arity: 1
Args: `(a)`
### Examples
```
> (bang (quote Bang))
;;=>
Bang!
```
[Back to index](#api-index)
-----------------------------------------------------
## `body`
Return the body of a lambda function
Type: native function
Arity: 1
Args: `(f)`
### Examples
```
> (body (lambda (x) (+ x 1)))
;;=>
((+ x 1))
```
[Back to index](#api-index)
-----------------------------------------------------
## `butlast`
Return everything but the last element
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (butlast ())
;;=>
()
> (butlast (range 3))
;;=>
(0 1)
```
[Back to index](#api-index)
-----------------------------------------------------
## `capitalize`
Return the atom argument, capitalized
Type: function
Arity: 1
Args: `(a)`
### Examples
```
> (capitalize (quote hello))
;;=>
Hello
```
[Back to index](#api-index)
-----------------------------------------------------
## `car`
Return the first element of a list
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (car (quote (one two)))
;;=>
one
> (car ())
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `cdr`
Return a list with the first element removed
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (cdr (quote (one two)))
;;=>
(two)
> (cdr ())
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `colon`
Add a colon at end of atom
Type: function
Arity: 1
Args: `(a)`
### Examples
```
> (colon (quote remember-this))
;;=>
remember-this:
```
[Back to index](#api-index)
-----------------------------------------------------
## `comma`
Add a comma at end of atom
Type: function
Arity: 1
Args: `(a)`
### Examples
```
> (comma (quote hello))
;;=>
hello,
```
[Back to index](#api-index)
-----------------------------------------------------
## `comment`
Ignore the expressions in the block
Type: macro
Arity: 0+
Args: `(() . body)`
### Examples
```
> (comment twas brillig, and the slithy toves did gyre and gimble in the wabe)
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `comp`
Function composition -- return a function which applies a series of functions in reverse order
Type: function
Arity: 0+
Args: `(() . fs)`
### Examples
```
> ((comp) (quote hello))
;;=>
hello
> ((comp split) (quote hello))
;;=>
(h e l l o)
> ((comp len split) (quote hello))
;;=>
5
> ((comp (partial apply +) (partial map len) (partial map split)) (quote (hello world)))
;;=>
10
```
[Back to index](#api-index)
-----------------------------------------------------
## `complement`
Return the logical complement of the supplied function
Type: function
Arity: 1
Args: `(f)`
### Examples
```
> ((complement even?) 1)
;;=>
t
> (map (complement odd?) (range 5))
;;=>
(t () t () t)
```
[Back to index](#api-index)
-----------------------------------------------------
## `concat`
Concatenenate any number of lists
Type: function
Arity: 0+
Args: `(() . lists)`
### Examples
```
> (concat (range 3) (quote (wow)) (reverse (range 3)))
;;=>
(0 1 2 wow 2 1 0)
```
[Back to index](#api-index)
-----------------------------------------------------
## `concat2`
Concatenate two lists
Type: function
Arity: 2
Args: `(a b)`
### Examples
```
> (concat2 () ())
;;=>
()
> (concat2 (quote (1 2)) (quote (3 4)))
;;=>
(1 2 3 4)
```
[Back to index](#api-index)
-----------------------------------------------------
## `cond`
Fundamental branching construct
Type: special form
Arity: 0+
Args: `(() . pairs)`
### Examples
```
> (cond)
;;=> ()
> (cond (t 1) (t 2) (t 3))
;;=> 1
> (cond (() 1) (t 2))
;;=> 2
```
[Back to index](#api-index)
-----------------------------------------------------
## `cons`
Add an element to the front of a (possibly empty) list
Type: native function
Arity: 2
Args: `(x xs)`
### Examples
```
> (cons 1 (quote (one two)))
;;=>
(1 one two)
> (cons 1 ())
;;=>
(1)
> (cons 1 2)
;;=>
(1 . 2)
```
[Back to index](#api-index)
-----------------------------------------------------
## `constantly`
Given a value, return a function which always returns that value
Type: function
Arity: 1
Args: `(x)`
### Examples
```
> (map (constantly t) (range 10))
;;=>
(t t t t t t t t t t)
```
[Back to index](#api-index)
-----------------------------------------------------
## `dec`
Return the supplied integer argument, minus one
Type: function
Arity: 1
Args: `(n)`
### Examples
```
> (dec 2)
;;=>
1
> (dec -1)
;;=>
-2
```
[Back to index](#api-index)
-----------------------------------------------------
## `def`
Set a value
Type: special form
Arity: 2
Args: `(name value)`
### Examples
```
> (def a 1)
;;=>
1
> a
;;=>
1
```
[Back to index](#api-index)
-----------------------------------------------------
## `defmacro`
Create and name a macro
Type: special form
Arity: 2+
Args: `(name args . body)`
### Examples
```
> (defmacro ignore-car (l)
(doc (ignore first element of list,
treat rest as normal expression)
(examples
(ignore-car (adorable + 1 2 3))
(ignore-car (deplorable - 4 4))))
(cdr l))
;;=>
()
> (ignore-car (hilarious * 2 3 4))
;;=>
24
```
[Back to index](#api-index)
-----------------------------------------------------
## `defn`
Create and name a function
Type: special form
Arity: 2+
Args: `(name args . body)`
### Examples
```
> (defn add (x y) (+ x y))
;;=>
()
> (add 1 2)
;;=>
3
> (defn add (x y)
(doc (add two numbers)
(examples
(add 1 2)))
(+ x y))
;;=>
()
> (doc add)
;;=>
((add two numbers) (examples (add 1 2)))
```
[Back to index](#api-index)
-----------------------------------------------------
## `doc`
Return the doclist for a function
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (doc (lambda (x) (doc (does stuff) (and other stuff)) (+ x 1)))
;;=>
((does stuff) (and other stuff))
```
[Back to index](#api-index)
-----------------------------------------------------
## `dotimes`
Execute body for each value in a list
Type: macro
Arity: 1+
Args: `(n . body)`
[Back to index](#api-index)
-----------------------------------------------------
## `downcase`
Return a new atom with all characters in lower case
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (downcase (quote Hello))
;;=>
hello
> (downcase (quote HELLO))
;;=>
hello
```
[Back to index](#api-index)
-----------------------------------------------------
## `drop`
Drop n items from a list, then return the rest
Type: function
Arity: 2
Args: `(n l)`
### Examples
```
> (drop 3 (range 10))
;;=>
(3 4 5 6 7 8 9)
```
[Back to index](#api-index)
-----------------------------------------------------
## `enumerate`
Returning list of (i, x) pairs where i is the index (from zero) and x is the original element from l
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (enumerate (quote (a b c)))
;;=>
((0 a) (1 b) (2 c))
```
[Back to index](#api-index)
-----------------------------------------------------
## `error`
Raise an error
Type: special form
Arity: 1
Args: `(l)`
### Examples
```
> (defn ensure-list (x)
(when-not (list? x)
(error '(ensure-list argument not a list!))))
;;=>
()
> (ensure-list 3)
;;=>
ERROR in '(ensure-list 3)':
(ensure-list argument not a list!)
```
[Back to index](#api-index)
-----------------------------------------------------
## `errors`
Error checking, for tests
Type: special form
Arity: 1+
Args: `(expected . body)`
### Examples
```
> (errors '(is not a function)
(1))
;;=>
()
> (errors '(is not a function)
(+))
;;=>
ERROR in '(errors (quote (is not a function)) (+))':
error not found in ((quote (is not a function)) (+))
```
[Back to index](#api-index)
-----------------------------------------------------
## `eval`
Evaluate an expression
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (eval (quote (one two)))
;;=>
ERROR: ((builtin function eval) (evaluating function object) (unknown symbol: one))
> (eval (quote (+ 1 2)))
;;=>
3
```
[Back to index](#api-index)
-----------------------------------------------------
## `even?`
Return true if the supplied integer argument is even
Type: function
Arity: 1
Args: `(n)`
### Examples
```
> (map even? (range 5))
;;=>
(t () t () t)
```
[Back to index](#api-index)
-----------------------------------------------------
## `every`
Return t if f applied to every element in l is truthy, else ()
Type: function
Arity: 2
Args: `(f l)`
### Examples
```
> (every odd? (quote (1 3 5)))
;;=>
t
> (every odd? (quote (1 2 3 5)))
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `exclaim`
Return l as a sentence... emphasized!
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (exclaim (quote (well, hello)))
;;=>
(Well, hello!)
> (exclaim (quote (help)))
;;=>
(Help!)
> (exclaim (quote (begone, fiend)))
;;=>
(Begone, fiend!)
```
[Back to index](#api-index)
-----------------------------------------------------
## `exit`
Exit the program
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `filter`
Keep only values for which function f is true
Type: function
Arity: 2
Args: `(f l)`
### Examples
```
> (filter odd? (range 5))
;;=>
(1 3)
```
[Back to index](#api-index)
-----------------------------------------------------
## `flatten`
Return a (possibly nested) list, flattened
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (flatten (quote (this is a (really (nested) list))))
;;=>
(this is a really nested list)
```
[Back to index](#api-index)
-----------------------------------------------------
## `foreach`
Execute body for each value in a list
Type: macro
Arity: 2+
Args: `(x xs . body)`
[Back to index](#api-index)
-----------------------------------------------------
## `forms`
Return available operators, as a list
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `fuse`
Fuse a list of numbers or atoms into a single atom
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (fuse (quote (A B C)))
;;=>
ABC
> (fuse (reverse (range 10)))
;;=>
9876543210
```
[Back to index](#api-index)
-----------------------------------------------------
## `gensym`
Return a new symbol
Type: native function
Arity: 0+
Args: `(() . more)`
[Back to index](#api-index)
-----------------------------------------------------
## `help`
Print a help message
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `identity`
Return the argument
Type: function
Arity: 1
Args: `(x)`
[Back to index](#api-index)
-----------------------------------------------------
## `if`
Simple conditional with two branches
Type: macro
Arity: 3
Args: `(condition then else)`
### Examples
```
> (if t 111 333)
;;=>
111
> (if () (quote abc) (quote def))
;;=>
def
```
[Back to index](#api-index)
-----------------------------------------------------
## `if-not`
Simple (inverted) conditional with two branches
Type: macro
Arity: 3
Args: `(condition then else)`
### Examples
```
> (if-not (odd? 3) (quote (help, they broke three)) (quote (three is odd)))
;;=>
(three is odd)
```
[Back to index](#api-index)
-----------------------------------------------------
## `inc`
Return the supplied integer argument, plus one
Type: function
Arity: 1
Args: `(n)`
[Back to index](#api-index)
-----------------------------------------------------
## `interpose`
Interpose x between all elements of l
Type: function
Arity: 2
Args: `(x l)`
### Examples
```
> (interpose BANG (range 5))
;;=>
(0 ! 1 ! 2 ! 3 ! 4)
```
[Back to index](#api-index)
-----------------------------------------------------
## `is`
Assert a condition is truthy, or show failing code
Type: macro
Arity: 1
Args: `(condition)`
### Examples
```
> (is t)
;;=>
()
> (is (car (cons () (quote (this one should fail)))))
;;=>
ERROR: ((assertion failed: (car (cons () (quote (this one should fail))))))
```
[Back to index](#api-index)
-----------------------------------------------------
## `isqrt`
Integer square root
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (isqrt 4)
;;=>
2
> (isqrt 5)
;;=>
2
```
[Back to index](#api-index)
-----------------------------------------------------
## `juxt`
Create a function which combines multiple operations into a single list of results
Type: function
Arity: 0+
Args: `(() . fs)`
### Examples
```
> ((juxt inc dec) 0)
;;=>
(1 -1)
> (map (juxt inc dec) (range 3))
;;=>
((1 -1) (2 0) (3 1))
> (map (juxt even? odd? zero?) (quote (-2 -1 0 1 2)))
;;=>
((t () ()) (() t ()) (t () t) (() t ()) (t () ()))
> (map (juxt) (range 3))
;;=>
(() () ())
```
[Back to index](#api-index)
-----------------------------------------------------
## `lambda`
Create a function
Type: special form
Arity: 1+
Args: `(args . more)`
### Examples
```
> ((lambda () t))
;;=>
t
> ((lambda (x) (+ 5 x)) 5)
;;=>
10
> ((lambda my-length (x)
(if-not x
0
(+ 1 (my-length (cdr x)))))
(range 20))
;;=>
20
```
[Back to index](#api-index)
-----------------------------------------------------
## `last`
Return the last item in a list
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (last (range 10))
;;=>
9
> (last (split (quote ATOM!)))
;;=>
!
```
[Back to index](#api-index)
-----------------------------------------------------
## `len`
Return the length of a list
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (len (range 10))
;;=>
10
```
[Back to index](#api-index)
-----------------------------------------------------
## `let`
Create a local scope with bindings
Type: special form
Arity: 1+
Args: `(binding-pairs . body)`
### Examples
```
> (let ((a 1)
(b 2))
(+ a b))
;;=>
3
```
[Back to index](#api-index)
-----------------------------------------------------
## `let*`
Let form with ability to refer to previously-bound pairs in the binding list
Type: macro
Arity: 1+
Args: `(pairs . body)`
### Examples
```
> (let* ((a 1) (b (inc a))) (+ a b))
;;=>
3
```
[Back to index](#api-index)
-----------------------------------------------------
## `list`
Return a list of the given arguments
Type: native function
Arity: 0+
Args: `(() . xs)`
### Examples
```
> (list 1 2 3)
;;=>
(1 2 3)
> (list)
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `list*`
Create a list by consing everything but the last arg onto the last
Type: function
Arity: 0+
Args: `(() . args)`
### Examples
```
> (list* 1 2 (quote (3)))
;;=>
(1 2 3)
> (list* 1 2 (quote (3 4)))
;;=>
(1 2 3 4)
> (list*)
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `list?`
Return t if the argument is a list, () otherwise
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (list? (range 10))
;;=>
t
> (list? 1)
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `load`
Load and execute a file
Type: native function
Arity: 1
Args: `(filename)`
[Back to index](#api-index)
-----------------------------------------------------
## `loop`
Loop forever
Type: special form
Arity: 1+
Args: `()`
### Examples
```
> (loop
(printl '(Help me, I am looping forever!))
(sleep 1000))
;; Prints =>
Help me, I am looping forever!
Help me, I am looping forever!
Help me, I am looping forever!
...
```
[Back to index](#api-index)
-----------------------------------------------------
## `macroexpand-1`
Expand a macro
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (macroexpand-1 (quote (+ x 1)))
;;=>
(+ x 1)
> (macroexpand-1 (quote (if () 1 2)))
;;=>
(cond (() 1) (t 2))
```
[Back to index](#api-index)
-----------------------------------------------------
## `map`
Apply the supplied function to every element in the supplied list
Type: function
Arity: 2
Args: `(f l)`
### Examples
```
> (map odd? (range 5))
;;=>
(() t () t ())
> (map true? (quote (foo t () t 3)))
;;=>
(() t () t ())
```
[Back to index](#api-index)
-----------------------------------------------------
## `mapcat`
Map a function onto a list and concatenate results
Type: function
Arity: 2
Args: `(f l)`
### Examples
```
> (map list (range 5))
;;=>
((0) (1) (2) (3) (4))
> (mapcat list (range 5))
;;=>
(0 1 2 3 4)
> (map range (range 5))
;;=>
(() (0) (0 1) (0 1 2) (0 1 2 3))
> (mapcat range (range 5))
;;=>
(0 0 1 0 1 2 0 1 2 3)
```
[Back to index](#api-index)
-----------------------------------------------------
## `max`
Find maximum of one or more numbers
Type: function
Arity: 0+
Args: `(() . args)`
### Examples
```
> (max -5)
;;=>
-5
> (max 2 3)
;;=>
3
> (apply max (range 10))
;;=>
9
```
[Back to index](#api-index)
-----------------------------------------------------
## `min`
Find minimum of one or more numbers
Type: function
Arity: 0+
Args: `(() . args)`
### Examples
```
> (min -5)
;;=>
-5
> (min 2 3)
;;=>
2
> (apply min (range 10))
;;=>
0
```
[Back to index](#api-index)
-----------------------------------------------------
## `neg?`
Return true iff the supplied integer argument is less than zero
Type: function
Arity: 1
Args: `(n)`
### Examples
```
> (map neg? (map (lambda (x) (- x 5)) (range 10)))
;;=>
(t t t t t () () () () ())
```
[Back to index](#api-index)
-----------------------------------------------------
## `not`
Return t if the argument is nil, () otherwise
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (not ())
;;=>
t
> (not t)
;;=>
()
> (not (range 10))
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `not=`
Complement of = function
Type: function
Arity: 0+
Args: `(() . terms)`
### Examples
```
> (not= 1 2)
;;=>
t
> (not= (quote a) (quote a))
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `nth`
Find the nth value of a list, starting from zero
Type: function
Arity: 2
Args: `(n l)`
### Examples
```
> (nth 3 (quote (one two three four five)))
;;=>
four
> (nth 1000 (range 2))
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `number?`
Return true if the argument is a number, else ()
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (number? 1)
;;=>
t
> (number? t)
;;=>
()
> (number? +)
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `odd?`
Return true if the supplied integer argument is odd
Type: function
Arity: 1
Args: `(n)`
### Examples
```
> (map even? (range 5))
;;=>
(t () t () t)
```
[Back to index](#api-index)
-----------------------------------------------------
## `or`
Boolean or
Type: special form
Arity: 0+
Args: `(() . xs)`
### Examples
```
> (or)
;; => false
> (or t t)
;; => true
> (or t t ())
;; => t
```
[Back to index](#api-index)
-----------------------------------------------------
## `partial`
Partial function application
Type: function
Arity: 1+
Args: `(f . args)`
### Examples
```
> ((partial + 1) 1)
;;=>
2
> ((partial + 2 3) 4 5)
;;=>
14
```
[Back to index](#api-index)
-----------------------------------------------------
## `period`
Add a period at end of atom
Type: function
Arity: 1
Args: `(a)`
### Examples
```
> (period (quote Woot))
;;=>
Woot.
```
[Back to index](#api-index)
-----------------------------------------------------
## `pos?`
Return true iff the supplied integer argument is greater than zero
Type: function
Arity: 1
Args: `(n)`
### Examples
```
> (map pos? (map (lambda (x) (- x 5)) (range 10)))
;;=>
(() () () () () () t t t t)
```
[Back to index](#api-index)
-----------------------------------------------------
## `print`
Print the arguments
Type: native function
Arity: 0+
Args: `(() . xs)`
[Back to index](#api-index)
-----------------------------------------------------
## `printl`
Print a list argument, without parentheses
Type: native function
Arity: 1
Args: `(x)`
[Back to index](#api-index)
-----------------------------------------------------
## `println`
Print the arguments and a newline
Type: native function
Arity: 0+
Args: `(() . xs)`
[Back to index](#api-index)
-----------------------------------------------------
## `progn`
Execute multiple statements, returning the last
Type: macro
Arity: 0+
Args: `(() . body)`
### Examples
```
> (progn)
;;=>
()
> (progn 1 2 3)
;;=>
3
```
[Back to index](#api-index)
-----------------------------------------------------
## `punctuate`
Return x capitalized, with punctuation determined by the supplied function
Type: function
Arity: 2
Args: `(f x)`
[Back to index](#api-index)
-----------------------------------------------------
## `punctuate-atom`
Add a punctuation mark at end of atom
Type: function
Arity: 2
Args: `(a mark)`
### Examples
```
> (punctuate-atom (quote list) (quote *))
;;=>
list*
> (punctuate-atom (quote list) COLON)
;;=>
list:
```
[Back to index](#api-index)
-----------------------------------------------------
## `quote`
Quote an expression
Type: special form
Arity: 1
Args: `(x)`
### Examples
```
> (quote foo)
foo
> (quote (1 2 3))
(1 2 3)
> '(1 2 3)
(1 2 3)
```
[Back to index](#api-index)
-----------------------------------------------------
## `randalpha`
Return a list of random (English/Latin/unaccented) lower-case alphabetic characters
Type: function
Arity: 1
Args: `(n)`
[Back to index](#api-index)
-----------------------------------------------------
## `randchoice`
Return an element at random from the supplied list
Type: function
Arity: 1
Args: `(l)`
[Back to index](#api-index)
-----------------------------------------------------
## `randigits`
Return a random integer between 0 and the argument minus 1
Type: function
Arity: 1
Args: `(n)`
[Back to index](#api-index)
-----------------------------------------------------
## `randint`
Return a random integer between 0 and the argument minus 1
Type: native function
Arity: 1
Args: `(x)`
[Back to index](#api-index)
-----------------------------------------------------
## `range`
List of integers from 0 to n
Type: function
Arity: 1
Args: `(n)`
### Examples
```
> (range 10)
;;=>
(0 1 2 3 4 5 6 7 8 9)
> (len (range 100))
;;=>
100
```
[Back to index](#api-index)
-----------------------------------------------------
## `readlist`
Read a list from stdin
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `reduce`
Successively apply a function against a list of arguments
Type: function
Arity: 2+
Args: `(f x . args)`
### Examples
```
> (reduce * (cdr (range 10)))
;;=>
362880
> (reduce (lambda (acc x) (cons x acc)) () (range 10))
;;=>
(9 8 7 6 5 4 3 2 1 0)
```
[Back to index](#api-index)
-----------------------------------------------------
## `rem`
Return remainder when second arg divides first
Type: native function
Arity: 2
Args: `(x y)`
### Examples
```
> (rem 5 2)
;;=>
1
> (rem 4 2)
;;=>
0
> (rem 1 0)
;;=>
ERROR: ((builtin function rem) (division by zero))
```
[Back to index](#api-index)
-----------------------------------------------------
## `remove`
Keep only values for which function f is false / the empty list
Type: function
Arity: 2
Args: `(f l)`
### Examples
```
> (remove odd? (range 5))
;;=>
(0 2 4)
```
[Back to index](#api-index)
-----------------------------------------------------
## `repeat`
Return a list of length n whose elements are all x
Type: function
Arity: 2
Args: `(n x)`
### Examples
```
> (repeat 5 (quote repetitive))
;;=>
(repetitive repetitive repetitive repetitive repetitive)
```
[Back to index](#api-index)
-----------------------------------------------------
## `repeatedly`
Return a list of length n whose elements are made from calling f repeatedly
Type: function
Arity: 2
Args: `(n f)`
### Examples
```
> (repeatedly 3 (lambda () (range 5)))
;;=>
((0 1 2 3 4) (0 1 2 3 4) (0 1 2 3 4))
```
[Back to index](#api-index)
-----------------------------------------------------
## `reverse`
Reverse a list
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (= (quote (c b a)) (reverse (quote (a b c))))
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `screen-clear`
Clear the screen
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `screen-end`
Stop screen for text UIs, return to console mode
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `screen-get-key`
Return a keystroke as an atom
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `screen-size`
Return the screen size: width, height
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `screen-start`
Start screen for text UIs
Type: native function
Arity: 0
Args: `()`
[Back to index](#api-index)
-----------------------------------------------------
## `screen-write`
Write a string to the screen
Type: native function
Arity: 3
Args: `(x y list)`
[Back to index](#api-index)
-----------------------------------------------------
## `second`
Return the second element of a list, or () if not enough elements
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (second ())
;;=>
()
> (second (quote (a)))
;;=>
()
> (second (quote (a b)))
;;=>
b
> (second (quote (1 2 3)))
;;=>
2
```
[Back to index](#api-index)
-----------------------------------------------------
## `set!`
Update a value in an existing binding
Type: special form
Arity: 2
Args: `(name value)`
### Examples
```
> (def a 1)
;;=>
1
> a
;;=>
1
> (set! a 2)
;;=>
2
> a
;;=>
2
```
[Back to index](#api-index)
-----------------------------------------------------
## `shell`
Run a shell subprocess, and return stdout, stderr, and exit code
Type: native function
Arity: 1
Args: `(cmd)`
[Back to index](#api-index)
-----------------------------------------------------
## `shuffle`
Return a (quickly!) shuffled list
Type: native function
Arity: 1
Args: `(xs)`
[Back to index](#api-index)
-----------------------------------------------------
## `sleep`
Sleep for the given number of milliseconds
Type: native function
Arity: 1
Args: `(ms)`
[Back to index](#api-index)
-----------------------------------------------------
## `some`
Return f applied to first element for which that result is truthy, else ()
Type: function
Arity: 2
Args: `(f l)`
### Examples
```
> (some even? (quote (1 3 5 7 9 11 13)))
;;=>
()
> (some even? (quote (1 3 5 7 9 1000 11 13)))
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `sort`
Sort a list
Type: native function
Arity: 1
Args: `(xs)`
### Examples
```
> (sort (quote (3 2 1)))
;;=>
(1 2 3)
> (sort (quote ()))
;;=>
()
> (sort (quote (c b a)))
;;=>
(a b c)
```
[Back to index](#api-index)
-----------------------------------------------------
## `sort-by`
Sort a list by a function
Type: native function
Arity: 2
Args: `(f xs)`
### Examples
```
> (sort-by first (quote ((3) (2) (1))))
;;=>
((1) (2) (3))
> (sort-by first (quote ()))
;;=>
()
> (sort-by second (quote ((quux 333) (zip 222) (afar 111))))
;;=>
((afar 111) (zip 222) (quux 333))
```
[Back to index](#api-index)
-----------------------------------------------------
## `source`
Show source for a function
Type: native function
Arity: 1
Args: `(form)`
### Examples
```
> (source map)
;;=>
(lambda (f l) (when l (cons (f (car l)) (map f (cdr l)))))
> (source +)
;;=>
ERROR: ((builtin function source) (cannot get source of builtin function ))
```
[Back to index](#api-index)
-----------------------------------------------------
## `split`
Split an atom or number into a list of single-digit numbers or single-character atoms
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (split 123)
;;=>
(1 2 3)
> (split (quote abc))
;;=>
(a b c)
```
[Back to index](#api-index)
-----------------------------------------------------
## `swallow`
Swallow errors thrown in body, return t if any occur
Type: special form
Arity: 0+
Args: `(() . body)`
### Examples
```
> (swallow
(error '(boom)))
;;=>
t
> (swallow 1 2 3)
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `syntax-quote`
Syntax-quote an expression
Type: special form
Arity: 1
Args: `(x)`
### Examples
```
> (syntax-quote foo)
foo
> (syntax-quote (1 2 3 4))
(1 2 3 4)
> (syntax-quote (1 (unquote (+ 1 1)) (splicing-unquote (list 3 4))))
(1 2 3 4)
> `(1 ~(+ 1 1) ~@(list 3 4))
(1 2 3 4)
```
[Back to index](#api-index)
-----------------------------------------------------
## `take`
Take up to n items from the supplied list
Type: function
Arity: 2
Args: `(n l)`
### Examples
```
> (take 3 (range 10))
;;=>
(0 1 2)
```
[Back to index](#api-index)
-----------------------------------------------------
## `test`
Run tests
Type: special form
Arity: 0+
Args: `(() . body)`
[Back to index](#api-index)
-----------------------------------------------------
## `tosentence`
Return l as a sentence... capitalized, with a period at the end
Type: function
Arity: 1
Args: `(l)`
### Examples
```
> (tosentence (quote (to be, or not to be, that is the question)))
;;=>
(To be, or not to be, that is the question.)
```
[Back to index](#api-index)
-----------------------------------------------------
## `true?`
Return t if the argument is t
Type: function
Arity: 1
Args: `(x)`
### Examples
```
> (true? 3)
;;=>
()
> (true? t)
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------
## `try`
Try to evaluate body, catch errors and handle them
Type: special form
Arity: 0+
Args: `(() . body)`
### Examples
```
> (try (error '(boom)))
;;=>
ERROR:
((boom))
> (try
(error '(boom))
(catch e
(printl e)))
;;=>
(boom)
> (try (/ 1 0) (catch e (len e)))
2
>
```
[Back to index](#api-index)
-----------------------------------------------------
## `upcase`
Return the uppercase version of the given atom
Type: native function
Arity: 1
Args: `(x)`
### Examples
```
> (upcase (quote abc))
;;=>
ABC
```
[Back to index](#api-index)
-----------------------------------------------------
## `version`
Return the version of the interpreter
Type: native function
Arity: 0
Args: `()`
### Examples
```
> (version)
;;=>
(0 0 56 dirty)
```
[Back to index](#api-index)
-----------------------------------------------------
## `when`
Simple conditional with single branch
Type: macro
Arity: 1+
Args: `(condition . body)`
### Examples
```
> (when () (/ 1 0))
;;=>
()
> (when t (quote (the sun rises in the east)))
;;=>
(the sun rises in the east)
```
[Back to index](#api-index)
-----------------------------------------------------
## `when-not`
Complement of the when macro
Type: macro
Arity: 1+
Args: `(condition . body)`
### Examples
```
> (when-not () (quote (do all the things)))
;;=>
(do all the things)
> (when-not t (error (quote (oh no mister bill))))
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `while`
Loop for as long as condition is true
Type: macro
Arity: 1+
Args: `(condition . body)`
### Examples
```
> (while () (launch-missiles))
;;=>
()
```
[Back to index](#api-index)
-----------------------------------------------------
## `with-screen`
Prepare for and clean up after screen operations
Type: macro
Arity: 0+
Args: `(() . body)`
[Back to index](#api-index)
-----------------------------------------------------
## `zero?`
Return true iff the supplied argument is zero
Type: function
Arity: 1
Args: `(n)`
### Examples
```
> (zero? (quote zero))
;;=>
()
> (zero? (- 1 1))
;;=>
t
```
[Back to index](#api-index)
-----------------------------------------------------