ludus/prelude.md
2023-12-13 20:42:50 -05:00

27 KiB

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.

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. 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! and 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    bool    bool?    false?    not    or

Dicts

assoc    assoc?    dict    diff    dissoc    get    keys    update    values

Environment and i/o

doc!    flush!    print!    prn!    report!

Errors

assert!    panic!

Lists

append    at    butlast    concat    count    each!    first    fold    last    list    list?    map    ordered?    range    rest    second    slice

Math

abs    add    angle    atan/2    ceil    cos    dec    deg/rad    deg/turn    dist    div    div/0    div/safe    even?    floor    gt?    gte?    heading/vector    inc    lt?    lte?    mod    mult    neg    neg?    odd?    pi    pos?    rad/deg    rad/turn    random    range    round    sin    square    sub    sum_of_squares    tan    tau    turn/deg    turn/rad    zero?

References and state

deref    make!    update!

Results

err    err?    ok    ok?    unwrap!    unwrap_or

Sets

set    set?

Strings

count    join    show    string    string?

Turtle graphics

back!    background!    bk!    clear!    fd!    forward!    goto!    heading    heading/vector    home!    left!    lt!    pc!    pd!    pencolor    pencolor!    pendown!    pendown?    penup!    penwidth    penwidth!    position    pu!    pw!    render_turtle!    reset_turtle!    right!    rt!    turtle_state

Types and values

bool?    coll?    dict?    eq?    fn?    keyword?    list?    neq?    nil?    number?    ordered?    show    some    some?    type

All functions, alphabetically

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