# The prelude

The prelude is written in the language itself and evaluated before every
file. Its names need no `require`. A module may define its own binding with
a prelude name without changing anyone else's; an unbound symbol falls
back to the prelude by name. Special forms are not part of it; see
[special forms](https://sexpgpu.041.io/docs/special-forms.md).

## Control macros

| form | expands to |
|---|---|
| `(when test body...)` | `(if test (progn body...) nil)` |
| `(unless test body...)` | `(if test nil (progn body...))` |
| `(cond (test body...)... (true body...))` | nested `if`s; a clause with no body returns its test's value |
| `(and x...)` | the last value when every one is true, else the first false one; `(and)` is `true` |
| `(or x...)` | the first true value, else the last one; `(or)` is `nil` |

`and`, `or` and `cond` bind their tests to gensyms, so each is evaluated
once.

## Threading

| form | meaning |
|---|---|
| `(-> x (f a) g)` | `(g (f x a))`: the value goes into the first position |
| `(->> x (f a) g)` | `(g (f a x))`: the value goes into the last position |

```lisp
(-> x norm1 attn (+ x))         ; (+ (attn (norm1 x)) x)
(->> (range 4) (map inc) (reduce + 0)) ; 10
```

## Functions

| function | result |
|---|---|
| `(inc x)` `(dec x)` | `x` plus or minus one |
| `(second xs)` | `(first (rest xs))` |
| `(last xs)` | the last element |
| `(zip xs ys)` | a list of two-element lists, up to the shorter length |

## Macro helpers

| form | meaning |
|---|---|
| `(with-gensyms (name...) body...)` | binds each name to a fresh symbol |
| `(once-only (arg...) body...)` | in a macro, evaluate each argument once, in order |
| `(defmacro/g! name ll body...)` | every `g!name` in the body is a fresh symbol per expansion (the Let Over Lambda convention) |

See [macros and symbols](https://sexpgpu.041.io/docs/macros.md).

## Place macros

| form | expands to |
|---|---|
| `(incf name [amount])` | `(setq name (+ name amount))`, amount 1 by default |
| `(decf name [amount])` | `(setq name (- name amount))` |
| `(push value name)` | `(setq name (cons value name))` |

They take variable names, not generalized places.

## Not in the prelude

`truthy` is a builtin; `dotimes` and `dolist` are special forms. The
neural network and optimizer definitions are in the standard modules
[sexpgpu/nn](https://sexpgpu.041.io/docs/nn.md) and [sexpgpu/optim](https://sexpgpu.041.io/docs/optim.md), which need a
[`require`](https://sexpgpu.041.io/docs/require.md).

Related: [builtins](https://sexpgpu.041.io/docs/builtins.md), [It is Common Lisp](https://sexpgpu.041.io/docs/lisp.md).

---

SexpGPU documentation. Every page: https://sexpgpu.041.io/llms.txt