diff --git a/prelude.md b/prelude.md new file mode 100644 index 0000000..41d1993 --- /dev/null +++ b/prelude.md @@ -0,0 +1,806 @@ +# 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. + +•[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) (_) +``` \ No newline at end of file