ludus/prelude.md

1021 lines
27 KiB
Markdown
Raw Normal View History

2023-12-11 21:02:17 +00:00
# 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.
For more information on the syntax & semantics of the Ludus language, see [language.md](./language.md).
2023-12-11 21:16:16 +00:00
## 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.
2023-12-13 19:15:32 +00:00
This should be enough to indicate order of arguments, types, and so on.
**Patterns often, but do not always, indicate types.** Typed patterns are written as `foo as :bar`,
where the type is indicated by the keyword.
Possible ludus types are: `:nil`, `:boolean`, `:number`, `:keyword` (atomic values);
`:string` (strings are their own beast); `:tuple` and `:list` (indexed collections); `:set` (sets are specific),
`:dict` and `:ns` (associative collections); and `:ref` (references).
**Conventional types.** Ludus has two types based on conventions.
* _Result tuples._ Results are a way of modeling the result of a calculation that might fail.
The two possible values are `(:ok, value)` and `(:err, msg)`.
`msg` is usually a string describing what went wrong.
To work with result tuples, see [`unwrap!`](#unwrap) and [`unwrap_or`](#unwrap_or).
That said, usually you work with these using pattern matching.
* _Vectors._ Vectors are 2-element tuples of x and y coordinates.
The origin is `(0, 0)`.
Many math functions take vectors as well as numbers, e.g., `add` and `mult`.
You will see vectors indicated in patterns by an `(x, y)` tuple.
You can see what this looks like in the last clause of `add`: `((x1, y1), (x2, y2))`.
## Functions by topic
### Boolean
[and](#and)    [bool](#bool)    [bool?](#bool)    [false?](#false)    [not](#not)    [or](#or)
### Dicts
[assoc](#assoc)    [assoc?](#assoc)    [dict](#dict)    [diff](#diff)    [dissoc](#dissoc)    [get](#get)    [keys](#keys)    [update](#update)    [values](#values)
### Environment and i/o
[doc!](#doc)    [flush!](#flush)    [print!](#print)    [prn!](#prn)    [report!](#report)
### Errors
[assert!](#assert)    [panic!](#panic)
### Lists
[append](#append)    [at](#at)    [butlast](#butlast)    [concat](#concat)    [count](#count)    [each!](#each)    [first](#first)    [fold](#fold)    [last](#last)    [list](#list)    [list?](#list)    [map](#map)    [ordered?](#ordered)    [range](#range)    [rest](#rest)    [second](#second)    [slice](#slice)
### Math
[abs](#abs)    [add](#add)    [angle](#angle)    [atan/2](#atan/2)    [ceil](#ceil)    [cos](#cos)    [dec](#dec)    [deg/rad](#deg/rad)    [deg/turn](#deg/turn)    [dist](#dist)    [div](#div)    [div/0](#div/0)    [div/safe](#div/safe)    [even?](#even)    [floor](#floor)    [gt?](#gt)    [gte?](#gte)    [heading/vector](#heading/vector)    [inc](#inc)    [lt?](#lt)    [lte?](#lte)    [mod](#mod)    [mult](#mult)    [neg](#neg)    [neg?](#neg)    [odd?](#odd)    [pi](#pi)    [pos?](#pos)    [rad/deg](#rad/deg)    [rad/turn](#rad/turn)    [random](#random)    [range](#range)    [round](#round)    [sin](#sin)    [square](#square)    [sub](#sub)    [sum_of_squares](#sum_of_squares)    [tan](#tan)    [tau](#tau)    [turn/deg](#turn/deg)    [turn/rad](#turn/rad)    [zero?](#zero)
### References and state
[deref](#deref)    [make!](#make)    [update!](#update)
### Results
[err](#err)    [err?](#err)    [ok](#ok)    [ok?](#ok)    [unwrap!](#unwrap)    [unwrap_or](#unwrap_or)
### Sets
[set](#set)    [set?](#set)
### Strings
[count](#count)    [join](#join)    [show](#show)    [string](#string)    [string?](#string)
### Turtle graphics
[back!](#back)    [background!](#background)    [bk!](#bk)    [clear!](#clear)    [fd!](#fd)    [forward!](#forward)    [goto!](#goto)    [heading](#heading)    [heading/vector](#heading/vector)    [home!](#home)    [left!](#left)    [lt!](#lt)    [pc!](#pc)    [pd!](#pd)    [pencolor](#pencolor)    [pencolor!](#pencolor)    [pendown!](#pendown)    [pendown?](#pendown)    [penup!](#penup)    [penwidth](#penwidth)    [penwidth!](#penwidth)    [position](#position)    [pu!](#pu)    [pw!](#pw)    [render_turtle!](#render_turtle)    [reset_turtle!](#reset_turtle)    [right!](#right)    [rt!](#rt)    [turtle_state](#turtle_state)
### Types and values
[bool?](#bool)    [coll?](#coll)    [dict?](#dict)    [eq?](#eq)    [fn?](#fn)    [keyword?](#keyword)    [list?](#list)    [neq?](#neq)    [nil?](#nil)    [number?](#number)    [ordered?](#ordered)    [show](#show)    [some](#some)    [some?](#some)    [type](#type)
2023-12-11 21:16:16 +00:00
## All functions, alphabetically
2023-12-12 20:38:16 +00:00
[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)    [su
2023-12-11 21:02:17 +00:00
## Function documentation
### abs
2023-12-12 20:38:16 +00:00
Returns the absolute value of a number.
```
2023-12-11 21:16:16 +00:00
(0)
(n)
2023-12-11 21:02:17 +00:00
```
### add
2023-12-12 20:38:16 +00:00
Adds numbers or vectors.
```
2023-12-11 21:16:16 +00:00
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
((x1, y1), (x2, y2))
2023-12-11 21:02:17 +00:00
```
### and
2023-12-12 20:38:16 +00:00
Returns true if all values passed in are truthy.
```
2023-12-11 21:16:16 +00:00
()
(x)
(x, y)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### angle
2023-12-12 20:38:16 +00:00
Calculates the angle between two vectors.
```
2023-12-11 21:02:17 +00:00
(v1, v2)
```
### append
2023-12-12 20:38:16 +00:00
Adds an element to a list or set.
```
2023-12-11 21:16:16 +00:00
()
(xs as :list)
(xs as :list, x)
(xs as :set)
(xs as :set, x)
2023-12-11 21:02:17 +00:00
```
### assert!
2023-12-12 20:38:16 +00:00
Asserts a condition: returns the value if the value is truthy, panics if the value is falsy. Takes an optional message.
```
2023-12-11 21:16:16 +00:00
(value)
(value, message)
2023-12-11 21:02:17 +00:00
```
### assoc
2023-12-12 20:38:16 +00:00
Takes a dict, key, and value, and returns a new dict with the key set to value.
```
2023-12-11 21:16:16 +00:00
()
(dict as :dict)
(dict as :dict, key as :keyword, value)
(dict as :dict, (key as :keyword, value))
2023-12-11 21:02:17 +00:00
```
### assoc?
2023-12-12 20:38:16 +00:00
Returns true if a value is an associative collection: a dict, struct, or namespace.
```
2023-12-11 21:16:16 +00:00
(assoc as :dict)
(assoc as :struct)
(assoc as :ns)
(_)
2023-12-11 21:02:17 +00:00
```
### at
2023-12-12 20:38:16 +00:00
Returns the element at index n of a list or tuple. Zero-indexed: the first element is at index 0.
```
2023-12-11 21:16:16 +00:00
(xs as :list, n as :number)
(xs as :tuple, n as :number)
2023-12-11 21:02:17 +00:00
```
### atan/2
2023-12-12 20:38:16 +00:00
Returns an angle from a slope. Takes an optional keyword argument to specify units. Takes either two numbers or a vector tuple.
```
2023-12-11 21:16:16 +00:00
(x as :number, y as :number)
(x, y, :turns)
(x, y, :radians)
(x, y, :degrees)
((x, y))
((x, y), units as :keyword)
2023-12-11 21:02:17 +00:00
```
### back!
2023-12-12 20:38:16 +00:00
Moves the turtle backward by a number of steps. Alias: bk!
```
2023-12-11 21:02:17 +00:00
(steps as :number)
```
### background!
2023-12-12 20:38:16 +00:00
Sets the background color behind the turtle and path. Alias: bg!
```
2023-12-11 21:16:16 +00:00
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
2023-12-11 21:02:17 +00:00
```
### bg!
2023-12-12 20:38:16 +00:00
Sets the background color behind the turtle and path. Alias: bg!
```
2023-12-11 21:16:16 +00:00
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
2023-12-11 21:02:17 +00:00
```
### bgcolor
No documentation available.
### bk!
2023-12-12 20:38:16 +00:00
Moves the turtle backward by a number of steps. Alias: bk!
```
2023-12-11 21:02:17 +00:00
(steps as :number)
```
### bool
2023-12-12 20:38:16 +00:00
Returns false if a value is nil or false, otherwise returns true.
```
2023-12-11 21:16:16 +00:00
(nil)
(false)
(_)
2023-12-11 21:02:17 +00:00
```
### bool?
2023-12-12 20:38:16 +00:00
Returns true if a value is of type :boolean.
```
2023-12-11 21:16:16 +00:00
(false)
(true)
(_)
2023-12-11 21:02:17 +00:00
```
### butlast
2023-12-12 20:38:16 +00:00
Returns a list, omitting the last element.
```
2023-12-11 21:02:17 +00:00
(xs as :list)
```
### ceil
2023-12-12 20:38:16 +00:00
Truncates a number towards positive infinity. With negative numbers, it returns the integer part. With positive numbers, returns the next more-positive integer.
```
2023-12-11 21:02:17 +00:00
(n as :number)
```
### clear!
2023-12-12 20:38:16 +00:00
Clears the canvas and sends the turtle home.
```
2023-12-11 21:02:17 +00:00
()
```
### coll?
2023-12-12 20:38:16 +00:00
Returns true if a value is a collection: dict, struct, list, tuple, or set.
```
2023-12-11 21:16:16 +00:00
(coll as :dict)
(coll as :struct)
(coll as :list)
(coll as :tuple)
(coll as :set)
(coll as :ns)
(_)
2023-12-11 21:02:17 +00:00
```
### colors
No documentation available.
### concat
2023-12-12 20:38:16 +00:00
Combines two lists, strings, or sets.
```
2023-12-11 21:16:16 +00:00
(x as :string, y as :string)
(xs as :list, ys as :list)
(xs as :set, ys as :set)
(xs, ys, ...zs)
2023-12-11 21:02:17 +00:00
```
### console
No documentation available.
### cos
2023-12-12 20:38:16 +00:00
Returns the cosine of an angle. Default angle measure is turns. An optional keyword argument specifies the units of the angle passed in.
```
2023-12-11 21:16:16 +00:00
(a as :number)
(a as :number, :turns)
(a as :number, :degrees)
(a as :number, :radians)
2023-12-11 21:02:17 +00:00
```
### count
2023-12-12 20:38:16 +00:00
Returns the number of elements in a collection (including string).
```
2023-12-11 21:16:16 +00:00
(xs as :list)
(xs as :tuple)
(xs as :dict)
(xs as :string)
(xs as :set)
(xs as :struct)
2023-12-11 21:02:17 +00:00
```
### dec
2023-12-12 20:38:16 +00:00
Decrements a number.
```
2023-12-11 21:02:17 +00:00
(x as :number)
```
### deg/rad
2023-12-12 20:38:16 +00:00
Converts an angle in degrees to an angle in radians.
```
2023-12-11 21:02:17 +00:00
(a as :number)
```
### deg/turn
2023-12-12 20:38:16 +00:00
Converts an angle in degrees to an angle in turns.
```
2023-12-11 21:02:17 +00:00
(a as :number)
```
### deref
2023-12-12 20:38:16 +00:00
Resolves a ref into a value.
```
2023-12-11 21:02:17 +00:00
(r as :ref)
```
### dict
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
(struct as :struct)
(ns_ as :ns)
(dict as :dict)
(list as :list)
(tup as :tuple)
2023-12-11 21:02:17 +00:00
```
### diff
2023-12-12 20:38:16 +00:00
Takes two associate data structures and returns a dict describing their differences. Does this shallowly, offering diffs only for keys in the original dict.
```
2023-12-11 21:02:17 +00:00
(d1 as :dict, d2 as :dict)
```
### dissoc
2023-12-12 20:38:16 +00:00
Takes a dict and a key, and returns a new dict with the key and associated value omitted.
```
2023-12-11 21:16:16 +00:00
(dict as :dict)
(dict as :dict, key as :keyword)
2023-12-11 21:02:17 +00:00
```
### dist
2023-12-12 20:38:16 +00:00
Returns the distance from the origin to a point described by (x, y).
```
2023-12-11 21:16:16 +00:00
(x as :number, y as :number)
((x, y))
2023-12-11 21:02:17 +00:00
```
### div
2023-12-12 20:38:16 +00:00
Divides numbers. Panics on division by zero.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(_, 0)
(x as :number, y as :number)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### div/0
2023-12-12 20:38:16 +00:00
Divides numbers. Returns 0 on division by zero.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(_, 0)
(x as :number, y as :number)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### div/safe
2023-12-12 20:38:16 +00:00
Divides a number. Returns a result tuple.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(_, 0)
(x, y)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### doc!
2023-12-12 20:38:16 +00:00
Prints the documentation of a function to the console.
```
2023-12-11 21:16:16 +00:00
(f as :fn)
(_)
2023-12-11 21:02:17 +00:00
```
### each!
2023-12-12 20:38:16 +00:00
Takes a list and applies a function, presumably with side effects, to each element in the list. Returns nil.
```
2023-12-11 21:16:16 +00:00
(f! as :fn, [])
(f! as :fn, [x])
(f! as :fn, [...xs])
2023-12-11 21:02:17 +00:00
```
### eq?
2023-12-12 20:38:16 +00:00
Returns true if all arguments have the same value.
```
2023-12-11 21:16:16 +00:00
(x)
(x, y)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### err
2023-12-12 20:38:16 +00:00
Takes a value and wraps it in an :err result tuple, presumably as an error message.
```
2023-12-11 21:02:17 +00:00
(msg)
```
### err?
2023-12-12 20:38:16 +00:00
Takes a value and returns true if it is an :err result tuple.
```
2023-12-11 21:16:16 +00:00
((:err, _))
(_)
2023-12-11 21:02:17 +00:00
```
### even?
2023-12-12 20:38:16 +00:00
Returns true if a value is an even number, otherwise returns false.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(_)
2023-12-11 21:02:17 +00:00
```
### false?
2023-12-12 20:38:16 +00:00
Returns true if a value is false, otherwise returns false. Useful to distinguish between false and nil.
```
2023-12-11 21:16:16 +00:00
(false)
(_)
2023-12-11 21:02:17 +00:00
```
### fd!
2023-12-12 20:38:16 +00:00
Moves the turtle forward by a number of steps. Alias: fd!
```
2023-12-11 21:02:17 +00:00
(steps as :number)
```
### first
2023-12-12 20:38:16 +00:00
Returns the first element of a list or tuple.
```
2023-12-11 21:02:17 +00:00
(xs)
```
### floor
2023-12-12 20:38:16 +00:00
Truncates a number towards negative infinity. With positive numbers, it returns the integer part. With negative numbers, returns the next more-negative integer.
```
2023-12-11 21:02:17 +00:00
(n as :number)
```
### flush!
2023-12-12 20:38:16 +00:00
Clears the console, and returns the messages.
```
2023-12-11 21:02:17 +00:00
()
```
### fn?
2023-12-12 20:38:16 +00:00
Returns true if an argument is a function.
```
2023-12-11 21:16:16 +00:00
(f as :fn)
(_)
2023-12-11 21:02:17 +00:00
```
### fold
2023-12-12 20:38:16 +00:00
Folds a list.
```
2023-12-11 21:16:16 +00:00
(f as :fn, xs as :list)
(f as :fn, xs as :list, root)
2023-12-11 21:02:17 +00:00
```
### forward!
2023-12-12 20:38:16 +00:00
Moves the turtle forward by a number of steps. Alias: fd!
```
2023-12-11 21:02:17 +00:00
(steps as :number)
```
### get
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
(key as :keyword)
(key as :keyword, coll)
(key as :keyword, coll, default)
2023-12-11 21:02:17 +00:00
```
### goto!
2023-12-12 20:38:16 +00:00
Sends the turtle to (x, y) coordinates. If the pen is down, the turtle will draw a path to its new location.
```
2023-12-11 21:16:16 +00:00
(x as :number, y as :number)
((x, y))
2023-12-11 21:02:17 +00:00
```
### gt?
2023-12-12 20:38:16 +00:00
Returns true if numbers are in decreasing order.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### gte?
2023-12-12 20:38:16 +00:00
Returns true if numbers are in decreasing or flat order.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### heading
2023-12-12 20:38:16 +00:00
Returns the turtle's current heading.
```
2023-12-11 21:02:17 +00:00
()
```
### heading/vector
2023-12-12 20:38:16 +00:00
Takes a turtle heading, and returns a unit vector of that heading.
```
2023-12-11 21:02:17 +00:00
(heading)
```
### home!
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:02:17 +00:00
()
```
### inc
2023-12-12 20:38:16 +00:00
Increments a number.
```
2023-12-11 21:02:17 +00:00
(x as :number)
```
### join
2023-12-12 20:38:16 +00:00
Takes a list of strings, and joins them into a single string, interposing an optional separator.
```
2023-12-11 21:16:16 +00:00
([])
([str as :string])
(strs as :list)
([str, ...strs], separator as :string)
2023-12-11 21:02:17 +00:00
```
### keys
2023-12-12 20:38:16 +00:00
Takes an associative collection and returns a list of keys in that collection. Returns an empty list on anything other than a collection.
```
2023-12-11 21:02:17 +00:00
(coll)
```
### keyword?
2023-12-12 20:38:16 +00:00
Returns true if a value is a keyword, otherwise returns false.
```
2023-12-11 21:16:16 +00:00
(kw as :keyword)
(_)
2023-12-11 21:02:17 +00:00
```
### last
2023-12-12 20:38:16 +00:00
Returns the last element of a list or tuple.
```
2023-12-11 21:02:17 +00:00
(xs)
```
### left!
2023-12-12 20:38:16 +00:00
Rotates the turtle left, measured in turns. Alias: lt!
```
2023-12-11 21:02:17 +00:00
(turns as :number)
```
### list
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:02:17 +00:00
(x)
```
### lt!
2023-12-12 20:38:16 +00:00
Rotates the turtle left, measured in turns. Alias: lt!
```
2023-12-11 21:02:17 +00:00
(turns as :number)
```
### lt?
2023-12-12 20:38:16 +00:00
Returns true if numbers are in increasing order.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### lte?
2023-12-12 20:38:16 +00:00
Returns true if numbers are in increasing or flat order.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### make!
2023-12-12 20:38:16 +00:00
Sets the value of a ref.
```
2023-12-11 21:02:17 +00:00
(r as :ref, value)
```
### map
2023-12-12 20:38:16 +00:00
Maps over a list.
```
2023-12-11 21:16:16 +00:00
(f as :fn, xs)
(kw as :keyword, xs)
2023-12-11 21:02:17 +00:00
```
### mod
2023-12-12 20:38:16 +00:00
Returns the modulus of num and div. Truncates towards negative infinity.
```
2023-12-11 21:02:17 +00:00
(num as :number, y as :number)
```
### mult
2023-12-12 20:38:16 +00:00
Multiplies numbers or vectors.
```
2023-12-11 21:16:16 +00:00
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
(scalar as :number, (x, y))
((x, y), scalar as :number)
2023-12-11 21:02:17 +00:00
```
### neg
2023-12-12 20:38:16 +00:00
Multiplies a number by -1, negating it.
```
2023-12-11 21:02:17 +00:00
(n as :number)
```
### neg?
2023-12-12 20:38:16 +00:00
Returns true if a value is a negative number, otherwise returns false.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(_)
2023-12-11 21:02:17 +00:00
```
### nil?
2023-12-12 20:38:16 +00:00
Returns true if a value is nil.
```
2023-12-11 21:16:16 +00:00
(nil)
(_)
2023-12-11 21:02:17 +00:00
```
### not
2023-12-12 20:38:16 +00:00
Returns false if a value is truthy, true if a value is falsy.
```
2023-12-11 21:16:16 +00:00
(nil)
(false)
(_)
2023-12-11 21:02:17 +00:00
```
### odd?
2023-12-12 20:38:16 +00:00
Returns true if a value is an odd number, otherwise returns false.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(_)
2023-12-11 21:02:17 +00:00
```
### ok
2023-12-12 20:38:16 +00:00
Takes a value and wraps it in an :ok result tuple.
```
2023-12-11 21:02:17 +00:00
(value)
```
### ok?
2023-12-12 20:38:16 +00:00
Takes a value and returns true if it is an :ok result tuple.
```
2023-12-11 21:16:16 +00:00
((:ok, _))
(_)
2023-12-11 21:02:17 +00:00
```
### or
2023-12-12 20:38:16 +00:00
Returns true if any value passed in is truthy.
```
2023-12-11 21:16:16 +00:00
()
(x)
(x, y)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### ordered?
2023-12-12 20:38:16 +00:00
Returns true if a value is an indexed collection: list or tuple.
```
2023-12-11 21:16:16 +00:00
(coll as :list)
(coll as :tuple)
(_)
2023-12-11 21:02:17 +00:00
```
### p5_calls
No documentation available.
### panic!
2023-12-12 20:38:16 +00:00
Causes Ludus to panic, outputting any arguments as messages.
```
2023-12-11 21:16:16 +00:00
()
(...args)
2023-12-11 21:02:17 +00:00
```
### pc!
2023-12-12 20:38:16 +00:00
Changes the turtle's pen color. Takes a single grayscale value, an rgb tuple, or an rgba tuple. Alias: pc!
```
2023-12-11 21:16:16 +00:00
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
2023-12-11 21:02:17 +00:00
```
### pd!
2023-12-12 20:38:16 +00:00
Lowers the turtle's pen, causing it to draw. Alias: pd!
```
2023-12-11 21:02:17 +00:00
()
```
### pencolor
2023-12-12 20:38:16 +00:00
Returns the turtle's pen color as an (r, g, b, a) tuple.
```
2023-12-11 21:02:17 +00:00
()
```
### pencolor!
2023-12-12 20:38:16 +00:00
Changes the turtle's pen color. Takes a single grayscale value, an rgb tuple, or an rgba tuple. Alias: pc!
```
2023-12-11 21:16:16 +00:00
(gray as :number)
((r as :number, g as :number, b as :number))
((r as :number, g as :number, b as :number, a as :number))
2023-12-11 21:02:17 +00:00
```
### pendown!
2023-12-12 20:38:16 +00:00
Lowers the turtle's pen, causing it to draw. Alias: pd!
```
2023-12-11 21:02:17 +00:00
()
```
### pendown?
2023-12-12 20:38:16 +00:00
Returns the turtle's pen state: true if the pen is down.
```
2023-12-11 21:02:17 +00:00
()
```
### penup!
2023-12-12 20:38:16 +00:00
Lifts the turtle's pen, stopping it from drawing. Alias: pu!
```
2023-12-11 21:02:17 +00:00
()
```
### penwidth
2023-12-12 20:38:16 +00:00
Returns the turtle's pen width in pixels.
```
2023-12-11 21:02:17 +00:00
()
```
### penwidth!
2023-12-12 20:38:16 +00:00
Sets the width of the turtle's pen, measured in pixels. Alias: pw!
```
2023-12-11 21:02:17 +00:00
(width as :number)
```
### pi
No documentation available.
### pos?
2023-12-12 20:38:16 +00:00
Returns true if a value is a positive number, otherwise returns false.
```
2023-12-11 21:16:16 +00:00
(x as :number)
(_)
2023-12-11 21:02:17 +00:00
```
### position
2023-12-12 20:38:16 +00:00
Returns the turtle's current position.
```
2023-12-11 21:02:17 +00:00
()
```
### print!
2023-12-12 20:38:16 +00:00
Sends a text representation of Ludus values to the console.
```
2023-12-11 21:02:17 +00:00
(...args)
```
### prn!
2023-12-12 20:38:16 +00:00
Prints the underlying Clojure data structure of a Ludus value.
```
2023-12-11 21:02:17 +00:00
(x)
```
### pu!
2023-12-12 20:38:16 +00:00
Lifts the turtle's pen, stopping it from drawing. Alias: pu!
```
2023-12-11 21:02:17 +00:00
()
```
### pw!
2023-12-12 20:38:16 +00:00
Sets the width of the turtle's pen, measured in pixels. Alias: pw!
```
2023-12-11 21:02:17 +00:00
(width as :number)
```
### rad/deg
2023-12-12 20:38:16 +00:00
Converts an angle in radians to an angle in degrees.
```
2023-12-11 21:02:17 +00:00
(a as :number)
```
### rad/turn
2023-12-12 20:38:16 +00:00
Converts an angle in radians to an angle in turns.
```
2023-12-11 21:02:17 +00:00
(a as :number)
```
### random
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
()
(n as :number)
(m as :number, n as :number)
2023-12-11 21:02:17 +00:00
```
### range
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
(end as :number)
(start as :number, end as :number)
2023-12-11 21:02:17 +00:00
```
### render_turtle!
2023-12-11 21:16:16 +00:00
```
2023-12-11 21:02:17 +00:00
()
```
### report!
2023-12-12 20:38:16 +00:00
Prints a value, then returns it.
```
2023-12-11 21:16:16 +00:00
(x)
(msg as :string, x)
2023-12-11 21:02:17 +00:00
```
### reset_turtle!
2023-12-12 20:38:16 +00:00
Resets the turtle to its original state.
```
2023-12-11 21:02:17 +00:00
()
```
### rest
2023-12-12 20:38:16 +00:00
Returns all but the first element of a list or tuple, as a list.
```
2023-12-11 21:16:16 +00:00
(xs as :list)
(xs as :tuple)
2023-12-11 21:02:17 +00:00
```
### right!
2023-12-12 20:38:16 +00:00
Rotates the turtle right, measured in turns. Alias: rt!
```
2023-12-11 21:02:17 +00:00
(turns as :number)
```
### round
2023-12-12 20:38:16 +00:00
Rounds a number to the nearest integer.
```
2023-12-11 21:02:17 +00:00
(n as :number)
```
### rt!
2023-12-12 20:38:16 +00:00
Rotates the turtle right, measured in turns. Alias: rt!
```
2023-12-11 21:02:17 +00:00
(turns as :number)
```
### second
2023-12-12 20:38:16 +00:00
Returns the second element of a list or tuple.
```
2023-12-11 21:02:17 +00:00
(xs)
```
### set
2023-12-12 20:38:16 +00:00
Takes an ordered collection--list or tuple--and turns it into a set.
```
2023-12-11 21:16:16 +00:00
(xs as :list)
(xs as :tuple)
2023-12-11 21:02:17 +00:00
```
### show
2023-12-12 20:38:16 +00:00
Returns a text representation of a Ludus value as a string.
```
2023-12-11 21:02:17 +00:00
(x)
```
### sin
2023-12-12 20:38:16 +00:00
Returns the sine of an angle. Default angle measure is turns. An optional keyword argument specifies the units of the angle passed in.
```
2023-12-11 21:16:16 +00:00
(a as :number)
(a as :number, :turns)
(a as :number, :degrees)
(a as :number, :radians)
2023-12-11 21:02:17 +00:00
```
### slice
2023-12-12 20:38:16 +00:00
Returns a slice of a list, representing a sub-list.
```
2023-12-11 21:16:16 +00:00
(xs as :list, end as :number)
(xs as :list, start as :number, end as :number)
2023-12-11 21:02:17 +00:00
```
### some
2023-12-12 20:38:16 +00:00
Takes a possibly nil value and a default value. Returns the value if it's not nil, returns the default if it's nil.
```
2023-12-11 21:16:16 +00:00
(nil, default)
(value, _)
2023-12-11 21:02:17 +00:00
```
### some?
2023-12-12 20:38:16 +00:00
Returns true if a value is not nil.
```
2023-12-11 21:16:16 +00:00
(nil)
(_)
2023-12-11 21:02:17 +00:00
```
### square
2023-12-12 20:38:16 +00:00
Squares a number.
```
2023-12-11 21:02:17 +00:00
(x as :number)
```
### string
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
(x as :string)
(x)
(x, ...xs)
2023-12-11 21:02:17 +00:00
```
### string?
2023-12-12 20:38:16 +00:00
Returns true if a value is a string.
```
2023-12-11 21:16:16 +00:00
(x as :string)
(_)
2023-12-11 21:02:17 +00:00
```
### sub
2023-12-12 20:38:16 +00:00
Subtracts numbers or vectors.
```
2023-12-11 21:16:16 +00:00
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
((x1, y1), (x2, y2))
2023-12-11 21:02:17 +00:00
```
### sum_of_squares
2023-12-12 20:38:16 +00:00
Returns the sum of squares of numbers.
```
2023-12-11 21:16:16 +00:00
()
(x as :number)
(x as :number, y as :number)
(x, y, ...zs)
2023-12-11 21:02:17 +00:00
```
### tan
2023-12-12 20:38:16 +00:00
Returns the sine of an angle. Default angle measure is turns. An optional keyword argument specifies the units of the angle passed in.
```
2023-12-11 21:16:16 +00:00
(a as :number)
(a as :number, :turns)
(a as :number, :degrees)
(a as :number, :radians)
2023-12-11 21:02:17 +00:00
```
### tau
No documentation available.
### turn/deg
2023-12-12 20:38:16 +00:00
Converts an angle in turns to an angle in degrees.
```
2023-12-11 21:02:17 +00:00
(a as :number)
```
### turn/rad
2023-12-12 20:38:16 +00:00
Converts an angle in turns to an angle in radians.
```
2023-12-11 21:02:17 +00:00
(a as :number)
```
### turtle_commands
No documentation available.
### turtle_state
2023-12-12 20:38:16 +00:00
Returns the turtle's current state.
```
2023-12-11 21:02:17 +00:00
()
```
### turtle_states
No documentation available.
### type
2023-12-12 20:38:16 +00:00
Returns a keyword representing the type of the value passed in.
```
2023-12-11 21:02:17 +00:00
(x)
```
### unwrap!
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
((:ok, value))
((:err, msg))
(_)
2023-12-11 21:02:17 +00:00
```
### unwrap_or
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
((:ok, value), _)
((:err, _), default)
2023-12-11 21:02:17 +00:00
```
### update
2023-12-12 20:38:16 +00:00
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.
```
2023-12-11 21:16:16 +00:00
(dict as :dict)
(dict as :dict, key as :keyword, updater as :fn)
2023-12-11 21:02:17 +00:00
```
### update!
2023-12-12 20:38:16 +00:00
Updates a ref by applying a function to its value. Returns the new value.
```
2023-12-11 21:02:17 +00:00
(r as :ref, f as :fn)
```
### values
2023-12-12 20:38:16 +00:00
Takes an associative collection and returns a list of values in that collection. Returns an empty list on anything other than a collection.
```
2023-12-11 21:02:17 +00:00
(coll)
```
### zero?
2023-12-12 20:38:16 +00:00
Returns true if a number is 0.
```
2023-12-11 21:16:16 +00:00
(0)
(_)
2023-12-11 21:02:17 +00:00
```