ludus/prelude.md

# Ludus prelude documentation
These functions are available in every Ludus script.
The documentation for any function can be found within Ludus by passing the function to `doc!`, 
e.g., running `doc! (add)` will send the documentation for `add` to the console.

## A few notes
**Naming conventions.** Functions whose name ends with a question mark, e.g., `eq?`, return booleans.
Functions whose name ends with an exclamation point, e.g., `make!`, change state in some way.
In other words, they _do things_ rather than _calculating values_. 
Functions whose name includes a slash either convert from one value to another, e.g. `deg/rad`,
or they are variations on a function, e.g. `div/0` as a variation on `div`.

**How entries are formatted.** Each entry has a brief (sometimes too brief!) description of what it does.
It is followed by the patterns for each of its function clauses.

•[abs](#abs)    •[add](#add)    •[and](#and)    •[angle](#angle)    •[append](#append)    •[assert!](#assert)    •[assoc](#assoc)    •[assoc?](#assoc)    •[at](#at)    •[atan/2](#atan/2)    •[back!](#back)    •[background!](#background)    •[bg!](#bg)    •[bgcolor](#bgcolor)    •[bk!](#bk)    •[bool](#bool)    •[bool?](#bool)    •[butlast](#butlast)    •[ceil](#ceil)    •[clear!](#clear)    •[coll?](#coll)    •[colors](#colors)    •[concat](#concat)    •[console](#console)    •[cos](#cos)    •[count](#count)    •[dec](#dec)    •[deg/rad](#deg/rad)    •[deg/turn](#deg/turn)    •[deref](#deref)    •[dict](#dict)    •[diff](#diff)    •[dissoc](#dissoc)    •[dist](#dist)    •[div](#div)    •[div/0](#div/0)    •[div/safe](#div/safe)    •[doc!](#doc)    •[each!](#each)    •[eq?](#eq)    •[err](#err)    •[err?](#err)    •[even?](#even)    •[false?](#false)    •[fd!](#fd)    •[first](#first)    •[floor](#floor)    •[flush!](#flush)    •[fn?](#fn)    •[fold](#fold)    •[forward!](#forward)    •[get](#get)    •[goto!](#goto)    •[gt?](#gt)    •[gte?](#gte)    •[heading](#heading)    •[heading/vector](#heading/vector)    •[home!](#home)    •[inc](#inc)    •[join](#join)    •[keys](#keys)    •[keyword?](#keyword)    •[last](#last)    •[left!](#left)    •[list](#list)    •[lt!](#lt)    •[lt?](#lt)    •[lte?](#lte)    •[make!](#make)    •[map](#map)    •[mod](#mod)    •[mult](#mult)    •[neg](#neg)    •[neg?](#neg)    •[nil?](#nil)    •[not](#not)    •[odd?](#odd)    •[ok](#ok)    •[ok?](#ok)    •[or](#or)    •[ordered?](#ordered)    •[p5_calls](#p5_calls)    •[panic!](#panic)    •[pc!](#pc)    •[pd!](#pd)    •[pencolor](#pencolor)    •[pencolor!](#pencolor)    •[pendown!](#pendown)    •[pendown?](#pendown)    •[penup!](#penup)    •[penwidth](#penwidth)    •[penwidth!](#penwidth)    •[pi](#pi)    •[pos?](#pos)    •[position](#position)    •[print!](#print)    •[prn!](#prn)    •[pu!](#pu)    •[pw!](#pw)    •[rad/deg](#rad/deg)    •[rad/turn](#rad/turn)    •[random](#random)    •[range](#range)    •[render_turtle!](#render_turtle)    •[report!](#report)    •[reset_turtle!](#reset_turtle)    •[rest](#rest)    •[right!](#right)    •[round](#round)    •[rt!](#rt)    •[second](#second)    •[set](#set)    •[show](#show)    •[sin](#sin)    •[slice](#slice)    •[some](#some)    •[some?](#some)    •[square](#square)    •[string](#string)    •[string?](#string)    •[sub](#sub)    •[sum_of_squares](#sum_of_squares)    •[tan](#tan)    •[tau](#tau)    •[turn/deg](#turn/deg)    •[turn/rad](#turn/rad)    •[turtle_commands](#turtle_commands)    •[turtle_state](#turtle_state)    •[turtle_states](#turtle_states)    •[type](#type)    •[unwrap!](#unwrap)    •[unwrap_or](#unwrap_or)    •[update](#update)    •[update!](#update)    •[values](#values)    •[zero?](#zero)
## Function documentation
### abs

Returns the absolute value of a number.```
(0)
(n)
```

### add

Adds numbers or vectors.```
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
((x1, y1), (x2, y2))
```

### and

Returns true if all values passed in are truthy.```
()
(x)
(x, y)
(x, y, ...zs)
```

### angle

Calculates the angle between two vectors.```
(v1, v2)
```

### append

Adds an element to a list or set.```
()
(xs as :list)
(xs as :list, x)
(xs as :set)
(xs as :set, x)
```

### assert!

Asserts a condition: returns the value if the value is truthy, panics if the value is falsy. Takes an optional message.```
(value)
(value, message)
```

### assoc

Takes a dict, key, and value, and returns a new dict with the key set to value.```
()
(dict as :dict)
(dict as :dict, key as :keyword, value)
(dict as :dict, (key as :keyword, value))
```

### assoc?

Returns true if a value is an associative collection: a dict, struct, or namespace.```
(assoc as :dict)
(assoc as :struct)
(assoc as :ns)
(_)
```

### at

Returns the element at index n of a list or tuple. Zero-indexed: the first element is at index 0.```
(xs as :list, n as :number)
(xs as :tuple, n as :number)
```

### atan/2

Returns an angle from a slope. Takes an optional keyword argument to specify units. Takes either two numbers or a vector tuple.```
(x as :number, y as :number)
(x, y, :turns)
(x, y, :radians)
(x, y, :degrees)
((x, y))
((x, y), units as :keyword)
```

### back!

Moves the turtle backward by a number of steps. Alias: bk!```
(steps as :number)
```

### background!

Sets the background color behind the turtle and path. Alias: bg!```
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
```

### bg!

Sets the background color behind the turtle and path. Alias: bg!```
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
```

### bgcolor
No documentation available.


### bk!

Moves the turtle backward by a number of steps. Alias: bk!```
(steps as :number)
```

### bool

Returns false if a value is nil or false, otherwise returns true.```
(nil)
(false)
(_)
```

### bool?

Returns true if a value is of type :boolean.```
(false)
(true)
(_)
```

### butlast

Returns a list, omitting the last element.```
(xs as :list)
```

### ceil

Truncates a number towards positive infinity. With negative numbers, it returns the integer part. With positive numbers, returns the next more-positive integer.```
(n as :number)
```

### clear!

Clears the canvas and sends the turtle home.```
()
```

### coll?

Returns true if a value is a collection: dict, struct, list, tuple, or set.```
(coll as :dict)
(coll as :struct)
(coll as :list)
(coll as :tuple)
(coll as :set)
(coll as :ns)
(_)
```

### colors
No documentation available.


### concat

Combines two lists, strings, or sets.```
(x as :string, y as :string)
(xs as :list, ys as :list)
(xs as :set, ys as :set)
(xs, ys, ...zs)
```

### console
No documentation available.


### cos

Returns the cosine of an angle. Default angle measure is turns. An optional keyword argument specifies the units of the angle passed in.```
(a as :number)
(a as :number, :turns)
(a as :number, :degrees)
(a as :number, :radians)
```

### count

Returns the number of elements in a collection (including string).```
(xs as :list)
(xs as :tuple)
(xs as :dict)
(xs as :string)
(xs as :set)
(xs as :struct)
```

### dec

Decrements a number.```
(x as :number)
```

### deg/rad

Converts an angle in degrees to an angle in radians.```
(a as :number)
```

### deg/turn

Converts an angle in degrees to an angle in turns.```
(a as :number)
```

### deref

Resolves a ref into a value.```
(r as :ref)
```

### dict

Takes a struct or ns, and returns it as a dict. Or, takes a list or tuple of (key, value) tuples and returns it as a dict. Returns dicts unharmed.```
(struct as :struct)
(ns_ as :ns)
(dict as :dict)
(list as :list)
(tup as :tuple)
```

### diff

Takes two associate data structures and returns a dict describing their differences. Does this shallowly, offering diffs only for keys in the original dict.```
(d1 as :dict, d2 as :dict)
```

### dissoc

Takes a dict and a key, and returns a new dict with the key and associated value omitted.```
(dict as :dict)
(dict as :dict, key as :keyword)
```

### dist

Returns the distance from the origin to a point described by (x, y).```
(x as :number, y as :number)
((x, y))
```

### div

Divides numbers. Panics on division by zero.```
(x as :number)
(_, 0)
(x as :number, y as :number)
(x, y, ...zs)
```

### div/0

Divides numbers. Returns 0 on division by zero.```
(x as :number)
(_, 0)
(x as :number, y as :number)
(x, y, ...zs)
```

### div/safe

Divides a number. Returns a result tuple.```
(x as :number)
(_, 0)
(x, y)
(x, y, ...zs)
```

### doc!

Prints the documentation of a function to the console.```
(f as :fn)
(_)
```

### each!

Takes a list and applies a function, presumably with side effects, to each element in the list. Returns nil.```
(f! as :fn, [])
(f! as :fn, [x])
(f! as :fn, [...xs])
```

### eq?

Returns true if all arguments have the same value.```
(x)
(x, y)
(x, y, ...zs)
```

### err

Takes a value and wraps it in an :err result tuple, presumably as an error message.```
(msg)
```

### err?

Takes a value and returns true if it is an :err result tuple.```
((:err, _))
(_)
```

### even?

Returns true if a value is an even number, otherwise returns false.```
(x as :number)
(_)
```

### false?

Returns true if a value is false, otherwise returns false. Useful to distinguish between false and nil.```
(false)
(_)
```

### fd!

Moves the turtle forward by a number of steps. Alias: fd!```
(steps as :number)
```

### first

Returns the first element of a list or tuple.```
(xs)
```

### floor

Truncates a number towards negative infinity. With positive numbers, it returns the integer part. With negative numbers, returns the next more-negative integer.```
(n as :number)
```

### flush!

Clears the console, and returns the messages.```
()
```

### fn?

Returns true if an argument is a function.```
(f as :fn)
(_)
```

### fold

Folds a list.```
(f as :fn, xs as :list)
(f as :fn, xs as :list, root)
```

### forward!

Moves the turtle forward by a number of steps. Alias: fd!```
(steps as :number)
```

### get

Takes a dict or struct, key, and optional default value; returns the value at key. If the value is not found, returns nil or the default value. Returns nil or default if the first argument is not a dict or struct.```
(key as :keyword)
(key as :keyword, coll)
(key as :keyword, coll, default)
```

### goto!

Sends the turtle to (x, y) coordinates. If the pen is down, the turtle will draw a path to its new location.```
(x as :number, y as :number)
((x, y))
```

### gt?

Returns true if numbers are in decreasing order.```
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
```

### gte?

Returns true if numbers are in decreasing or flat order.```
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
```

### heading

Returns the turtle's current heading.```
()
```

### heading/vector

Takes a turtle heading, and returns a unit vector of that heading.```
(heading)
```

### home!

Sends the turtle home: to the centre of the screen, pointing up. If the pen is down, the turtle will draw a path to home.```
()
```

### inc

Increments a number.```
(x as :number)
```

### join

Takes a list of strings, and joins them into a single string, interposing an optional separator.```
([])
([str as :string])
(strs as :list)
([str, ...strs], separator as :string)
```

### keys

Takes an associative collection and returns a list of keys in that collection. Returns an empty list on anything other than a collection.```
(coll)
```

### keyword?

Returns true if a value is a keyword, otherwise returns false.```
(kw as :keyword)
(_)
```

### last

Returns the last element of a list or tuple.```
(xs)
```

### left!

Rotates the turtle left, measured in turns. Alias: lt!```
(turns as :number)
```

### list

Takes a value and returns it as a list. For values, it simply wraps them in a list. For collections, conversions are as follows. A tuple->list conversion preservers order and length. Unordered collections do not preserve order. Associative collections return lists of (key, value) tuples.```
(x)
```

### lt!

Rotates the turtle left, measured in turns. Alias: lt!```
(turns as :number)
```

### lt?

Returns true if numbers are in increasing order.```
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
```

### lte?

Returns true if numbers are in increasing or flat order.```
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
```

### make!

Sets the value of a ref.```
(r as :ref, value)
```

### map

Maps over a list.```
(f as :fn, xs)
(kw as :keyword, xs)
```

### mod

Returns the modulus of num and div. Truncates towards negative infinity.```
(num as :number, y as :number)
```

### mult

Multiplies numbers or vectors.```
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
(scalar as :number, (x, y))
((x, y), scalar as :number)
```

### neg

Multiplies a number by -1, negating it.```
(n as :number)
```

### neg?

Returns true if a value is a negative number, otherwise returns false.```
(x as :number)
(_)
```

### nil?

Returns true if a value is nil.```
(nil)
(_)
```

### not

Returns false if a value is truthy, true if a value is falsy.```
(nil)
(false)
(_)
```

### odd?

Returns true if a value is an odd number, otherwise returns false.```
(x as :number)
(_)
```

### ok

Takes a value and wraps it in an :ok result tuple.```
(value)
```

### ok?

Takes a value and returns true if it is an :ok result tuple.```
((:ok, _))
(_)
```

### or

Returns true if any value passed in is truthy.```
()
(x)
(x, y)
(x, y, ...zs)
```

### ordered?

Returns true if a value is an indexed collection: list or tuple.```
(coll as :list)
(coll as :tuple)
(_)
```

### p5_calls
No documentation available.


### panic!

Causes Ludus to panic, outputting any arguments as messages.```
()
(...args)
```

### pc!

Changes the turtle's pen color. Takes a single grayscale value, an rgb tuple, or an rgba tuple. Alias: pc!```
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
```

### pd!

Lowers the turtle's pen, causing it to draw. Alias: pd!```
()
```

### pencolor

Returns the turtle's pen color as an (r, g, b, a) tuple.```
()
```

### pencolor!

Changes the turtle's pen color. Takes a single grayscale value, an rgb tuple, or an rgba tuple. Alias: pc!```
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
```

### pendown!

Lowers the turtle's pen, causing it to draw. Alias: pd!```
()
```

### pendown?

Returns the turtle's pen state: true if the pen is down.```
()
```

### penup!

Lifts the turtle's pen, stopping it from drawing. Alias: pu!```
()
```

### penwidth

Returns the turtle's pen width in pixels.```
()
```

### penwidth!

Sets the width of the turtle's pen, measured in pixels. Alias: pw!```
(width as :number)
```

### pi
No documentation available.


### pos?

Returns true if a value is a positive number, otherwise returns false.```
(x as :number)
(_)
```

### position

Returns the turtle's current position.```
()
```

### print!

Sends a text representation of Ludus values to the console.```
(...args)
```

### prn!

Prints the underlying Clojure data structure of a Ludus value.```
(x)
```

### pu!

Lifts the turtle's pen, stopping it from drawing. Alias: pu!```
()
```

### pw!

Sets the width of the turtle's pen, measured in pixels. Alias: pw!```
(width as :number)
```

### rad/deg

Converts an angle in radians to an angle in degrees.```
(a as :number)
```

### rad/turn

Converts an angle in radians to an angle in turns.```
(a as :number)
```

### random

Returns a random number. With zero arguments, returns a random number between 0 (inclusive) and 1 (exclusive). With one argument, returns a random number between 0 and n. With two arguments, returns a random number between m and n.```
()
(n as :number)
(m as :number, n as :number)
```

### range

Returns the set of integers between start (inclusive) and end (exclusive) as a list. With one argument, starts at 0. If end is less than start, returns an empty list.```
(end as :number)
(start as :number, end as :number)
```

### render_turtle!

```
()
```

### report!

Prints a value, then returns it.```
(x)
(msg as :string, x)
```

### reset_turtle!

Resets the turtle to its original state.```
()
```

### rest

Returns all but the first element of a list or tuple, as a list.```
(xs as :list)
(xs as :tuple)
```

### right!

Rotates the turtle right, measured in turns. Alias: rt!```
(turns as :number)
```

### round

Rounds a number to the nearest integer.```
(n as :number)
```

### rt!

Rotates the turtle right, measured in turns. Alias: rt!```
(turns as :number)
```

### second

Returns the second element of a list or tuple.```
(xs)
```

### set

Takes an ordered collection--list or tuple--and turns it into a set.```
(xs as :list)
(xs as :tuple)
```

### show

Returns a text representation of a Ludus value as a string.```
(x)
```

### sin

Returns the sine of an angle. Default angle measure is turns. An optional keyword argument specifies the units of the angle passed in.```
(a as :number)
(a as :number, :turns)
(a as :number, :degrees)
(a as :number, :radians)
```

### slice

Returns a slice of a list, representing a sub-list.```
(xs as :list, end as :number)
(xs as :list, start as :number, end as :number)
```

### some

Takes a possibly nil value and a default value. Returns the value if it's not nil, returns the default if it's nil.```
(nil, default)
(value, _)
```

### some?

Returns true if a value is not nil.```
(nil)
(_)
```

### square

Squares a number.```
(x as :number)
```

### string

Converts a value to a string by using `show`. If it is a string, returns it unharmed. Use this to build up strings of differen kinds of values.```
(x as :string)
(x)
(x, ...xs)
```

### string?

Returns true if a value is a string.```
(x as :string)
(_)
```

### sub

Subtracts numbers or vectors.```
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
((x1, y1), (x2, y2))
```

### sum_of_squares

Returns the sum of squares of numbers.```
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
```

### tan

Returns the sine of an angle. Default angle measure is turns. An optional keyword argument specifies the units of the angle passed in.```
(a as :number)
(a as :number, :turns)
(a as :number, :degrees)
(a as :number, :radians)
```

### tau
No documentation available.


### turn/deg

Converts an angle in turns to an angle in degrees.```
(a as :number)
```

### turn/rad

Converts an angle in turns to an angle in radians.```
(a as :number)
```

### turtle_commands
No documentation available.


### turtle_state

Returns the turtle's current state.```
()
```

### turtle_states
No documentation available.


### type

Returns a keyword representing the type of the value passed in.```
(x)
```

### unwrap!

Takes a result tuple. If it's :ok, then returns the value. If it's not :ok, then it panics. If it's not a result tuple, it also panics.```
((:ok, value))
((:err, msg))
(_)
```

### unwrap_or

Takes a value that is a result tuple and a default value. If it's :ok, then it returns the value. If it's :err, returns the default value.```
((:ok, value), _)
((:err, _), default)
```

### update

Takes a dict, key, and function, and returns a new dict with the key set to the result of applying the function to original value held at the key.```
(dict as :dict)
(dict as :dict, key as :keyword, updater as :fn)
```

### update!

Updates a ref by applying a function to its value. Returns the new value.```
(r as :ref, f as :fn)
```

### values

Takes an associative collection and returns a list of values in that collection. Returns an empty list on anything other than a collection.```
(coll)
```

### zero?

Returns true if a number is 0.```
(0)
(_)
```