diff --git a/prelude.md b/prelude.md index a59603f..bf1426d 100644 --- a/prelude.md +++ b/prelude.md @@ -36,79 +36,58 @@ 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) - ## All functions, alphabetically -[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) +[abs](#abs)    [add](#add)    [and](#and)    [angle](#angle)    [any?](#any)    [append](#append)    [assert!](#assert)    [assoc](#assoc)    [assoc?](#assoc)    [at](#at)    [atan/2](#atan/2)    [back!](#back)    [background!](#background)    [between?](#between)    [bg!](#bg)    [bgcolor](#bgcolor)    [bk!](#bk)    [bool](#bool)    [bool?](#bool)    [box?](#box)    [butlast](#butlast)    [ceil](#ceil)    [clear!](#clear)    [coll?](#coll)    [colors](#colors)    [concat](#concat)    [cos](#cos)    [count](#count)    [dec](#dec)    [deg/rad](#deg/rad)    [deg/turn](#deg/turn)    [dict](#dict)    [dict?](#dict)    [diff](#diff)    [dissoc](#dissoc)    [dist](#dist)    [div](#div)    [div/0](#div/0)    [div/safe](#div/safe)    [doc!](#doc)    [downcase](#downcase)    [each!](#each)    [empty?](#empty)    [eq?](#eq)    [err](#err)    [err?](#err)    [even?](#even)    [false?](#false)    [fd!](#fd)    [filter](#filter)    [first](#first)    [floor](#floor)    [fn?](#fn)    [fold](#fold)    [forward!](#forward)    [get](#get)    [goto!](#goto)    [gt?](#gt)    [gte?](#gte)    [heading](#heading)    [heading/vector](#heading/vector)    [home!](#home)    [inc](#inc)    [inv](#inv)    [inv/0](#inv/0)    [inv/safe](#inv/safe)    [join](#join)    [keep](#keep)    [keys](#keys)    [keyword?](#keyword)    [last](#last)    [left!](#left)    [list](#list)    [list?](#list)    [load\_turtle_state!](#load\_turtle_state)    [lt!](#lt)    [lt?](#lt)    [lte?](#lte)    [map](#map)    [max](#max)    [min](#min)    [mod](#mod)    [mult](#mult)    [neg](#neg)    [neg?](#neg)    [neq?](#neq)    [nil?](#nil)    [not](#not)    [odd?](#odd)    [ok](#ok)    [ok?](#ok)    [or](#or)    [ordered?](#ordered)    [p5\_calls](#p5\_calls)    [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)    [pu!](#pu)    [pw!](#pw)    [rad/deg](#rad/deg)    [rad/turn](#rad/turn)    [random](#random)    [random\_int](#random\_int)    [range](#range)    [render\_turtle!](#render\_turtle)    [report!](#report)    [reset\_turtle!](#reset\_turtle)    [rest](#rest)    [right!](#right)    [round](#round)    [rt!](#rt)    [second](#second)    [sentence](#sentence)    [set](#set)    [set?](#set)    [show](#show)    [sin](#sin)    [slice](#slice)    [some](#some)    [some?](#some)    [split](#split)    [square](#square)    [state](#state)    [store!](#store)    [string](#string)    [string?](#string)    [strip](#strip)    [sub](#sub)    [sum\_of_squares](#sum\_of_squares)    [tan](#tan)    [tau](#tau)    [trim](#trim)    [tuple?](#tuple)    [turn/deg](#turn/deg)    [turn/rad](#turn/rad)    [turtle\_commands](#turtle\_commands)    [turtle\_state](#turtle\_state)    [turtle\_states](#turtle\_states)    [type](#type)    [unbox](#unbox)    [unwrap!](#unwrap)    [unwrap\_or](#unwrap\_or)    [upcase](#upcase)    [update](#update)    [update!](#update)    [values](#values)    [words](#words)    [ws?](#ws)    [zero?](#zero) ## Function documentation ### abs Returns the absolute value of a number. ``` (0) -(n) +(n as :number) ``` + ### add Adds numbers or vectors. ``` () (x as :number) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) ((x1, y1), (x2, y2)) ``` + ### and -Returns true if all values passed in are truthy. +Returns true if all values passed in are truthy. Note that this does not short-circuit: all arguments are evaulated before they are passed in. ``` () (x) (x, y) -(x, y, ...zs) +(x, y, ...) ``` + ### angle Calculates the angle between two vectors. ``` (v1, v2) ``` + +### any? +Returns true if something is not empty, otherwise returns false (including for things that can't be logically full, like numbers). +``` +([...]) +(#{...}) +(s as :set) +((...)) +(s as :string) +(_) +``` + + ### append Adds an element to a list or set. ``` @@ -119,13 +98,15 @@ Adds an element to a list or 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) +(msg, value) ``` + ### assoc Takes a dict, key, and value, and returns a new dict with the key set to value. ``` @@ -135,22 +116,26 @@ Takes a dict, key, and value, and returns a new dict with the key set to value. (dict as :dict, (key as :keyword, value)) ``` + ### assoc? -Returns true if a value is an associative collection: a dict, struct, or namespace. +Returns true if a value is an associative collection: a dict or a pkg. ``` (assoc as :dict) -(assoc as :struct) -(assoc as :ns) +(assoc as :pkg) (_) ``` + ### at -Returns the element at index n of a list or tuple. Zero-indexed: the first element is at index 0. +Returns the element at index n of a list or tuple, or the byte at index n of a string. Zero-indexed: the first element is at index 0. Returns nil if nothing is found in a list or tuple; returns an empty string if nothing is found in a string. ``` (xs as :list, n as :number) (xs as :tuple, n as :number) +(str as :string, 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. ``` @@ -162,12 +147,14 @@ Returns an angle from a slope. Takes an optional keyword argument to specify uni ((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! ``` @@ -176,6 +163,14 @@ Sets the background color behind the turtle and path. Alias: bg! ((r as :number, g as :number, b as :number, a as :number)) ``` + +### between? +Returns true if a number is in the range [lower, higher): greater than or equal to the lower number, less than the higher. +``` +(lower as :number, higher as :number, x as :number) +``` + + ### bg! Sets the background color behind the turtle and path. Alias: bg! ``` @@ -184,6 +179,7 @@ Sets the background color behind the turtle and path. Alias: bg! ((r as :number, g as :number, b as :number, a as :number)) ``` + ### bgcolor No documentation available. @@ -194,6 +190,7 @@ 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. ``` @@ -202,6 +199,7 @@ Returns false if a value is nil or false, otherwise returns true. (_) ``` + ### bool? Returns true if a value is of type :boolean. ``` @@ -210,36 +208,48 @@ Returns true if a value is of type :boolean. (_) ``` + +### box? +Returns true if a value is a box. +``` +(b as :box) +(_) +``` + + ### 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. +Returns true if a value is a collection: dict, list, pkg, tuple, or set. ``` (coll as :dict) -(coll as :struct) (coll as :list) (coll as :tuple) (coll as :set) -(coll as :ns) +(coll as :pkg) (_) ``` + ### colors No documentation available. @@ -250,12 +260,9 @@ 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) +(xs, ys, ...) ``` -### 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. @@ -266,6 +273,7 @@ Returns the cosine of an angle. Default angle measure is turns. An optional keyw (a as :number, :radians) ``` + ### count Returns the number of elements in a collection (including string). ``` @@ -274,49 +282,54 @@ Returns the number of elements in a collection (including string). (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. +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) ``` + +### dict? +Returns true if a value is a dict. +``` +(dict as :dict) +(_) +``` + + ### 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. +Takes two dicts 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. ``` @@ -324,6 +337,7 @@ Takes a dict and a key, and returns a new dict with the key and associated value (dict as :dict, key as :keyword) ``` + ### dist Returns the distance from the origin to a point described by (x, y). ``` @@ -331,33 +345,37 @@ Returns the distance from the origin to a point described by (x, y). ((x, y)) ``` + ### div Divides numbers. Panics on division by zero. ``` (x as :number) (_, 0) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) ``` + ### div/0 Divides numbers. Returns 0 on division by zero. ``` (x as :number) (_, 0) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) ``` + ### div/safe Divides a number. Returns a result tuple. ``` (x as :number) (_, 0) (x, y) -(x, y, ...zs) +(x, y, ...) ``` + ### doc! Prints the documentation of a function to the console. ``` @@ -365,28 +383,51 @@ Prints the documentation of a function to the console. (_) ``` + +### downcase +Takes a string and returns it in all lowercase. Works only for ascii characters. +``` +(str as :string) +``` + + ### 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]) +(f! as :fn, [...]) ``` + +### empty? +Returns true if something is empty. Otherwise returns false (including for things that can't logically be empty, like numbers). +``` +([]) +(#{}) +(s as :set) +(()) +("") +(_) +``` + + ### eq? Returns true if all arguments have the same value. ``` (x) (x, y) -(x, y, ...zs) +(x, y, ...) ``` + ### 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. ``` @@ -394,6 +435,7 @@ Takes a value and returns true if it is an :err result tuple. (_) ``` + ### even? Returns true if a value is an even number, otherwise returns false. ``` @@ -401,36 +443,42 @@ Returns true if a value is an even number, otherwise returns false. (_) ``` + ### false? -Returns true if a value is false, otherwise returns false. Useful to distinguish between false and nil. +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) ``` + +### filter +Takes a list and a predicate function, and returns a new list with only the items that produce truthy values when the function is called on them. E.g., `filter ([1, 2, 3, 4], odd?) &=> [1, 3]`. +``` +(p? as :fn, xs) +``` + + ### 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. @@ -439,6 +487,7 @@ Returns true if an argument is a function. (_) ``` + ### fold Folds a list. ``` @@ -446,20 +495,23 @@ Folds a 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. +Takes a key, dict, and optional default value; returns the value at key. If the value is not found, returns nil or the default value. ``` (key as :keyword) -(key as :keyword, coll) -(key as :keyword, coll, default) +(key as :keyword, dict as :dict) +(key as :keyword, dict as :dict, default) ``` + ### goto! Sends the turtle to (x, y) coordinates. If the pen is down, the turtle will draw a path to its new location. ``` @@ -467,61 +519,99 @@ Sends the turtle to (x, y) coordinates. If the pen is down, the turtle will draw ((x, y)) ``` + ### gt? Returns true if numbers are in decreasing order. ``` (x as :number) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) ``` + ### gte? Returns true if numbers are in decreasing or flat order. ``` (x as :number) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) ``` + ### 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) ``` + +### inv +Returns the inverse of a number: 1/n or `div (1, n)`. Panics on division by zero. +``` +(x as :number) +``` + + +### inv/0 +Returns the inverse of a number: 1/n or `div/0 (1, n)`. Returns 0 on division by zero. +``` +(x as :number) +``` + + +### inv/safe +Returns the inverse of a number: 1/n or `div/safe (1, n)`. Returns a result tuple. +``` +(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) +([str], separator as :string) +([str, ...], separator as :string) ``` + +### keep +Takes a list and returns a new list with any `nil` values omitted. +``` +(xs) +``` + + ### keys -Takes an associative collection and returns a list of keys in that collection. Returns an empty list on anything other than a collection. +Takes a dict and returns a list of keys in that dict. ``` -(coll) +(dict as :dict) ``` + ### keyword? Returns true if a value is a keyword, otherwise returns false. ``` @@ -529,82 +619,120 @@ Returns true if a value is a keyword, otherwise returns false. (_) ``` + ### 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) ``` + +### list? +Returns true if the value is a list. +``` +(l as :list) +(_) +``` + + +### load_turtle_state! +Sets the turtle state to a previously saved state. Returns the state. +``` +(state) +``` + + ### 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) +(x, y, ...) ``` + ### lte? Returns true if numbers are in increasing or flat order. ``` (x as :number) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) ``` -### make! -Sets the value of a ref. -``` -(r as :ref, value) -``` ### map -Maps over a list. +Maps a function over a list: returns a new list with elements that are the result of applying the function to each element in the original list. E.g., `map ([1, 2, 3], inc) &=> [2, 3, 4]`. ``` (f as :fn, xs) (kw as :keyword, xs) ``` + +### max +Returns the number in its arguments that is closest to positive infinity. +``` +(x as :number) +(x as :number, y as :number) +(x, y, ...) +``` + + +### min +Returns the number in its arguments that is closest to negative infinity. +``` +(x as :number) +(x as :number, y as :number) +(x, y, ...) +``` + + ### mod Returns the modulus of num and div. Truncates towards negative infinity. ``` -(num as :number, y as :number) +(num as :number, div as :number) ``` + ### mult Multiplies numbers or vectors. ``` () (x as :number) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) (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. ``` @@ -612,6 +740,16 @@ Returns true if a value is a negative number, otherwise returns false. (_) ``` + +### neq? +Returns true if none of the arguments have the same value. +``` +(x) +(x, y) +(x, y, ...) +``` + + ### nil? Returns true if a value is nil. ``` @@ -619,6 +757,7 @@ Returns true if a value is nil. (_) ``` + ### not Returns false if a value is truthy, true if a value is falsy. ``` @@ -627,6 +766,7 @@ Returns false if a value is truthy, true if a value is falsy. (_) ``` + ### odd? Returns true if a value is an odd number, otherwise returns false. ``` @@ -634,12 +774,14 @@ Returns true if a value is an odd number, otherwise returns false. (_) ``` + ### 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. ``` @@ -647,15 +789,17 @@ Takes a value and returns true if it is an :ok result tuple. (_) ``` + ### or -Returns true if any value passed in is truthy. +Returns true if any value passed in is truthy. Note that this does not short-circuit: all arguments are evaluated before they are passed in. ``` () (x) (x, y) -(x, y, ...zs) +(x, y, ...) ``` + ### ordered? Returns true if a value is an indexed collection: list or tuple. ``` @@ -664,17 +808,11 @@ Returns true if a value is an indexed collection: list or 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! ``` @@ -683,18 +821,21 @@ Changes the turtle's pen color. Takes a single grayscale value, an rgb tuple, or ((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! ``` @@ -703,36 +844,42 @@ Changes the turtle's pen color. Takes a single grayscale value, an rgb tuple, or ((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. @@ -744,23 +891,20 @@ Returns true if a value is a positive number, otherwise returns false. (_) ``` + ### 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! @@ -768,45 +912,62 @@ 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. +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. Alternately, given a list, it returns a random member of that list. ``` () (n as :number) (m as :number, n as :number) +(l as :list) +(d as :dict) ``` + +### random_int +Returns a random integer. With one argument, returns a random integer between 0 and that number. With two arguments, returns a random integer between them. +``` +(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. +Returns the set of integers between start (inclusive) and end (exclusive) as a list: [start, end). 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! +### render_turtle! +No docstring available. ``` () ``` + ### report! Prints a value, then returns it. ``` @@ -814,12 +975,14 @@ Prints a value, then returns it. (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. ``` @@ -827,30 +990,42 @@ Returns all but the first element of a list or tuple, as a 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) ``` + +### sentence +Takes a list of words and turns it into a sentence. +``` +(strs as :list) +``` + + ### set Takes an ordered collection--list or tuple--and turns it into a set. ``` @@ -858,12 +1033,22 @@ Takes an ordered collection--list or tuple--and turns it into a set. (xs as :tuple) ``` + +### set? +Returns true if a value is a set. +``` +(xs as :set) +(_) +``` + + ### 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. ``` @@ -873,13 +1058,17 @@ Returns the sine of an angle. Default angle measure is turns. An optional keywor (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) +(str as :string, end as :number) +(str as :string, 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. ``` @@ -887,6 +1076,7 @@ Takes a possibly nil value and a default value. Returns the value if it's not ni (value, _) ``` + ### some? Returns true if a value is not nil. ``` @@ -894,20 +1084,41 @@ Returns true if a value is not nil. (_) ``` + +### split +Takes a string, and turns it into a list of strings, breaking on the separator. +``` +(str as :string, break as :string) +``` + + ### square Squares a number. ``` (x as :number) ``` + +### state +No documentation available. + + +### store! +Stores a value in a box, replacing the value that was previously there. Returns the value. +``` +(b as :box, value) +``` + + ### 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. +Converts a value to a string by using `show`. If it is a string, returns it unharmed. Use this to build up strings of different kinds of values. ``` (x as :string) (x) -(x, ...xs) +(x, ...) ``` + ### string? Returns true if a value is a string. ``` @@ -915,25 +1126,41 @@ Returns true if a value is a string. (_) ``` + +### strip +Removes punctuation from a string, removing all instances of ,.;:?! +``` +("{x},{y}") +("{x}.{y}") +("{x};{y}") +("{x}:{y}") +("{x}?{y}") +("{x}!{y}") +(x) +``` + + ### sub Subtracts numbers or vectors. ``` () (x as :number) (x as :number, y as :number) -(x, y, ...zs) +(x, y, ...) ((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) +(x, y, ...) ``` + ### tan Returns the sine of an angle. Default angle measure is turns. An optional keyword argument specifies the units of the angle passed in. ``` @@ -943,22 +1170,42 @@ Returns the sine of an angle. Default angle measure is turns. An optional keywor (a as :number, :radians) ``` + ### tau No documentation available. +### trim +Trims whitespace from a string. Takes an optional argument, `:left` or `:right`, to trim only on the left or right. +``` +(str as :string) +(str as :string, :left) +(str as :string, :right) +``` + + +### tuple? +Returns true if a value is a tuple. +``` +(tuple as :tuple) +(_) +``` + + ### 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. @@ -969,6 +1216,7 @@ Returns the turtle's current state. () ``` + ### turtle_states No documentation available. @@ -979,6 +1227,14 @@ Returns a keyword representing the type of the value passed in. (x) ``` + +### unbox +Returns the value that is stored in a box. +``` +(b as :box) +``` + + ### 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. ``` @@ -987,6 +1243,7 @@ Takes a result tuple. If it's :ok, then returns the value. If it's not :ok, then (_) ``` + ### 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. ``` @@ -994,6 +1251,14 @@ Takes a value that is a result tuple and a default value. If it's :ok, then it r ((:err, _), default) ``` + +### upcase +Takes a string and returns it in all uppercase. Works only for ascii characters. +``` +(str as :string) +``` + + ### 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. ``` @@ -1001,21 +1266,41 @@ Takes a dict, key, and function, and returns a new dict with the key set to the (dict as :dict, key as :keyword, updater as :fn) ``` + ### update! -Updates a ref by applying a function to its value. Returns the new value. +Updates a box by applying a function to its value. Returns the new value. ``` -(r as :ref, f as :fn) +(b as :box, 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. +Takes a dict and returns a list of values in that dict. ``` -(coll) +(dict) ``` + +### words +Takes a string and returns a list of the words in the string. Strips all whitespace. +``` +(str as :string) +``` + + +### ws? +Tells if a string is a whitespace character. +``` +(" ") +("\n") +("\t") +(_) +``` + + ### zero? Returns true if a number is 0. ``` (0) (_) -``` \ No newline at end of file +``` diff --git a/src/doc.janet b/src/doc.janet new file mode 100644 index 0000000..7eb4501 --- /dev/null +++ b/src/doc.janet @@ -0,0 +1,127 @@ +(import /src/base :as base) +(import /src/prelude :as prelude) + +(defn map-values [f dict] + (from-pairs (map (fn [[k v]] [k (f v)]) (pairs dict)))) + +(def with-docs (map-values base/doc prelude/ctx)) + +(def sorted-names (-> with-docs keys sort)) + +(defn escape-underscores [str] (string/replace "_" "\\_" str)) + +(defn escape-punctuation [str] (->> str + (string/replace "?" "") + (string/replace "!" ""))) + +(defn toc-entry [name] + (def escaped (escape-underscores name)) + (string "[" escaped "](#" (escape-punctuation escaped) ")")) + +(def alphabetical-list + (string/join (map toc-entry sorted-names) "    ")) + +(def topics { + "math" ["abs" "add" "angle" "atan/2" "between?" "ceil" "cos" "dec" "deg/rad" "deg/turn" "dist" "div" "div/0" "div/safe" "even?" "floor" "gt?" "gte?" "heading/vector" "inc" "inv" "inv/0" "inv/safe" "lt?" "lte?" "max" "min" "mod" "mult" "neg" "neg?" "odd?" "pi" "pos?" "rad/deg" "rad/turn" "random" "random_int" "range" "round" "sin" "square" "sub" "sum_of_squares" "tan" "tau" "turn/deg" "turn/rad" "zero?"] + "boolean" ["and" "bool" "bool?" "false?" "not" "or"] + "dicts" ["any?" "assoc" "assoc?" "coll?" "count" "dict" "dict?" "diff" "dissoc" "empty?" "get" "keys" "random" "update" "values"] + "lists" ["any?" "append" "at" "butlast" "coll?" "concat" "count" "each!" "empty?" "filter" "first" "fold" "join" "keep" "last" "list" "list?" "map" "ordered?""random" "range" "rest" "second" "sentence" "slice"] + "sets" ["any?" "append" "coll?" "concat" "count" "empty?" "random" "set" "set?"] + "strings" ["any?" "concat" "count" "downcase" "empty?" "join" "sentence" "show" "slice" "split" "string" "string?" "strip" "trim" "upcase" "words"] + "types and values" ["assoc?" "bool?" "coll?" "dict?" "eq?" "fn?" "keyword?" "list?" "neq?" "nil?" "number?" "ordered?" "show" "some" "some?" "string?" "type"] + "boxes and state" ["unbox" "store!" "update!"] + "results" ["err" "err?" "ok" "ok?" "unwrap!" "unwrap_or"] + "errors" ["assert!"] + "turtle graphics" ["back!" "background!" "bk!" "clear!" "colors" "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"] + "environment and i/o" ["doc!" "print!" "report!" "state"] + }) + +(defn capitalize [str] + (def fst (slice str 0 1)) + (def rest (slice str 1)) + (def init_cap (string/ascii-upper fst)) + (def lower_rest (string/ascii-lower rest)) + (string init_cap lower_rest)) + +(defn topic-entry [topic] + (string "### " (capitalize topic) "\n" + (as-> topic _ (topics _) (slice _) (sort _) (map toc-entry _) + (string/join _ "    ")) + "\n")) + +(def by-topic (let [the-topics (-> topics keys sort) + topics-entries (map topic-entry the-topics)] + (string/join topics-entries "\n"))) + +(defn compose-entry [name] + (def header (string "### " name "\n")) + (def the-doc (get with-docs name)) + (when (= "No documentation available." the-doc) + (break (string header the-doc "\n"))) + (def lines (string/split "\n" the-doc)) + (def description (last lines)) + (def patterns (string/join (slice lines 1 (-> lines length dec)) "\n")) + (string header description "\n```\n" patterns "\n```\n")) + +(compose-entry "update") + +(def entries (string/join (map compose-entry sorted-names) "\n\n")) + +(def doc-file (string +``` +# 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). + +## 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!`](#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 + +``` +by-topic +``` + +## All functions, alphabetically + +``` +alphabetical-list +``` + +## Function documentation + +``` +entries +)) + +(spit "prelude.md" doc-file)