add more documentation for stdlib functions

includes a cheap workaround for the stdlib TOC 😁

README.md

@@ -79,6 +79,20 @@ Make yourself familiar with Rudi using the documentation:
 
 ### Command Line
 
+Rudi comes with a standalone CLI tool called `rudi`.
+
+```
+Usage of rudi:
+      --coalesce string   Type conversion handling, choose one of strict, pedantic or humane. (default "strict")
+      --debug-ast         Output syntax tree of the parsed script in non-interactive mode.
+  -h, --help              Show help and documentation.
+  -i, --interactive       Start an interactive REPL to run expressions.
+  -p, --pretty            Output pretty-printed JSON.
+  -s, --script string     Load Rudi script from file instead of first argument (only in non-interactive mode).
+  -V, --version           Show version and exit.
+  -y, --yaml              Output pretty-printed YAML instead of JSON.
+```
+
 `rudi` can run in one of two modes:
 
 * **Interactive Mode** is enabled by passing `--interactive` (or `-i`). This will start a REPL

docs/README.md

@@ -19,6 +19,48 @@ Welcome to the Rudi documentation :smile:
 * [`set`](functions/core-set.md) – set a value in a variable/document, only really useful with ! modifier (set!)
 * [`try`](functions/core-try.md) – returns the fallback if the first expression errors out
 
+## Comparisons Functions
+
+* [`eq?`](functions/comparisons-eq.md) – equality check: return true if both arguments are the same
+* [`gt?`](functions/comparisons-gt.md) – returns a > b
+* [`gte?`](functions/comparisons-gte.md) – returns a >= b
+* [`identical?`](functions/comparisons-identical.md) – like `eq?`, but always uses strict coalecsing
+* [`like?`](functions/comparisons-like.md) – like `eq?`, but always uses humane coalecsing
+* [`lt?`](functions/comparisons-lt.md) – returns a < b
+* [`lte?`](functions/comparisons-lte.md) – return a <= b
+
+## Dates Functions
+
+* [`now`](functions/dates-now.md) – returns the current date & time (UTC), formatted like a Go date
+
+## Encoding Functions
+
+* [`from-base64`](functions/encoding-from-base64.md) – decode a base64 encoded string
+* [`to-base64`](functions/encoding-to-base64.md) – apply base64 encoding to the given string
+
+## Hashes Functions
+
+* [`sha1`](functions/hashes-sha1.md) – return the lowercase hex representation of the SHA-1 hash
+* [`sha256`](functions/hashes-sha256.md) – return the lowercase hex representation of the SHA-256 hash
+* [`sha512`](functions/hashes-sha512.md) – return the lowercase hex representation of the SHA-512 hash
+
+## Lists Functions
+
+* [`append`](functions/lists-append.md) – appends more strings to a string or arbitrary items into a vector
+* [`contains?`](functions/lists-contains.md) – returns true if a string contains a substring or a vector contains the given element
+* [`filter`](functions/lists-filter.md) – returns a copy of a given vector/object with only those elements remaining that satisfy a condition
+* [`len`](functions/lists-len.md) – returns the length of a string, vector or object
+* [`map`](functions/lists-map.md) – applies an expression to every element in a vector or object
+* [`prepend`](functions/lists-prepend.md) – prepends more strings to a string or arbitrary items into a vector
+* [`range`](functions/lists-range.md) – allows to iterate (loop) over a vector or object
+* [`reverse`](functions/lists-reverse.md) – reverses a string or the elements of a vector
+
+## Logic Functions
+
+* [`and`](functions/logic-and.md) – returns true if all arguments are true
+* [`not`](functions/logic-not.md) – negates the given argument
+* [`or`](functions/logic-or.md) – returns true if any of the arguments is true
+
 ## Math Functions
 
 * [`*`](functions/math-mult.md) – returns the product of all of its arguments
@@ -29,5 +71,20 @@ Welcome to the Rudi documentation :smile:
 ## Strings Functions
 
 * [`concat`](functions/strings-concat.md) – concatenate items in a vector using a common glue string
+* [`has-prefix?`](functions/strings-has-prefix.md) – returns true if the given string has the prefix
+* [`has-suffix?`](functions/strings-has-suffix.md) – returns true if the given string has the suffix
 * [`split`](functions/strings-split.md) – split a string into a vector
+* [`to-lower`](functions/strings-to-lower.md) – returns the lowercased version of the given string
+* [`to-upper`](functions/strings-to-upper.md) – returns the uppercased version of the given string
+* [`trim`](functions/strings-trim.md) – returns the given whitespace with leading/trailing whitespace removed
+* [`trim-prefix`](functions/strings-trim-prefix.md) – removes the prefix from the string, if it exists
+* [`trim-suffix`](functions/strings-trim-suffix.md) – removes the suffix from the string, if it exists
+
+## Types Functions
+
+* [`to-bool`](functions/types-to-bool.md) – try to convert the given argument losslessly to a bool
+* [`to-float`](functions/types-to-float.md) – try to convert the given argument losslessly to a float64
+* [`to-int`](functions/types-to-int.md) – try to convert the given argument losslessly to an int64
+* [`to-string`](functions/types-to-string.md) – try to convert the given argument losslessly to a string
+* [`type-of`](functions/types-type-of.md) – returns the type of a given value (e.g. "string" or "number")
 <!-- END_TOC -->

docs/functions/README.md

@@ -14,24 +14,81 @@ applied to all functions (so technically `eq?!` is valid, though weird looking).
 <!-- BEGIN_TOC -->
 ## Core Functions
 
-* [`default`](functions/core-default.md) – returns the default value if the first argument is empty
-* [`delete`](functions/core-delete.md) – removes a key from an object or an item from a vector
-* [`do`](functions/core-do.md) – eval a sequence of statements where only one expression is valid
-* [`empty?`](functions/core-empty.md) – returns true when the given value is empty-ish (0, false, null, "", ...)
-* [`has?`](functions/core-has.md) – returns true if the given symbol's path expression points to an existing value
-* [`if`](functions/core-if.md) – evaluate one of two expressions based on a condition
-* [`set`](functions/core-set.md) – set a value in a variable/document, only really useful with ! modifier (set!)
-* [`try`](functions/core-try.md) – returns the fallback if the first expression errors out
+* [`default`](../functions/core-default.md) – returns the default value if the first argument is empty
+* [`delete`](../functions/core-delete.md) – removes a key from an object or an item from a vector
+* [`do`](../functions/core-do.md) – eval a sequence of statements where only one expression is valid
+* [`empty?`](../functions/core-empty.md) – returns true when the given value is empty-ish (0, false, null, "", ...)
+* [`has?`](../functions/core-has.md) – returns true if the given symbol's path expression points to an existing value
+* [`if`](../functions/core-if.md) – evaluate one of two expressions based on a condition
+* [`set`](../functions/core-set.md) – set a value in a variable/document, only really useful with ! modifier (set!)
+* [`try`](../functions/core-try.md) – returns the fallback if the first expression errors out
+
+## Comparisons Functions
+
+* [`eq?`](../functions/comparisons-eq.md) – equality check: return true if both arguments are the same
+* [`gt?`](../functions/comparisons-gt.md) – returns a > b
+* [`gte?`](../functions/comparisons-gte.md) – returns a >= b
+* [`identical?`](../functions/comparisons-identical.md) – like `eq?`, but always uses strict coalecsing
+* [`like?`](../functions/comparisons-like.md) – like `eq?`, but always uses humane coalecsing
+* [`lt?`](../functions/comparisons-lt.md) – returns a < b
+* [`lte?`](../functions/comparisons-lte.md) – return a <= b
+
+## Dates Functions
+
+* [`now`](../functions/dates-now.md) – returns the current date & time (UTC), formatted like a Go date
+
+## Encoding Functions
+
+* [`from-base64`](../functions/encoding-from-base64.md) – decode a base64 encoded string
+* [`to-base64`](../functions/encoding-to-base64.md) – apply base64 encoding to the given string
+
+## Hashes Functions
+
+* [`sha1`](../functions/hashes-sha1.md) – return the lowercase hex representation of the SHA-1 hash
+* [`sha256`](../functions/hashes-sha256.md) – return the lowercase hex representation of the SHA-256 hash
+* [`sha512`](../functions/hashes-sha512.md) – return the lowercase hex representation of the SHA-512 hash
+
+## Lists Functions
+
+* [`append`](../functions/lists-append.md) – appends more strings to a string or arbitrary items into a vector
+* [`contains?`](../functions/lists-contains.md) – returns true if a string contains a substring or a vector contains the given element
+* [`filter`](../functions/lists-filter.md) – returns a copy of a given vector/object with only those elements remaining that satisfy a condition
+* [`len`](../functions/lists-len.md) – returns the length of a string, vector or object
+* [`map`](../functions/lists-map.md) – applies an expression to every element in a vector or object
+* [`prepend`](../functions/lists-prepend.md) – prepends more strings to a string or arbitrary items into a vector
+* [`range`](../functions/lists-range.md) – allows to iterate (loop) over a vector or object
+* [`reverse`](../functions/lists-reverse.md) – reverses a string or the elements of a vector
+
+## Logic Functions
+
+* [`and`](../functions/logic-and.md) – returns true if all arguments are true
+* [`not`](../functions/logic-not.md) – negates the given argument
+* [`or`](../functions/logic-or.md) – returns true if any of the arguments is true
 
 ## Math Functions
 
-* [`*`](functions/math-mult.md) – returns the product of all of its arguments
-* [`+`](functions/math-sum.md) – returns the sum of all of its arguments
-* [`-`](functions/math-sub.md) – returns arg1 - arg2 - .. - argN
-* [`/`](functions/math-div.md) – returns arg1 / arg2 / .. / argN
+* [`*`](../functions/math-mult.md) – returns the product of all of its arguments
+* [`+`](../functions/math-sum.md) – returns the sum of all of its arguments
+* [`-`](../functions/math-sub.md) – returns arg1 - arg2 - .. - argN
+* [`/`](../functions/math-div.md) – returns arg1 / arg2 / .. / argN
 
 ## Strings Functions
 
-* [`concat`](functions/strings-concat.md) – concatenate items in a vector using a common glue string
-* [`split`](functions/strings-split.md) – split a string into a vector
+* [`concat`](../functions/strings-concat.md) – concatenate items in a vector using a common glue string
+* [`has-prefix?`](../functions/strings-has-prefix.md) – returns true if the given string has the prefix
+* [`has-suffix?`](../functions/strings-has-suffix.md) – returns true if the given string has the suffix
+* [`split`](../functions/strings-split.md) – split a string into a vector
+* [`to-lower`](../functions/strings-to-lower.md) – returns the lowercased version of the given string
+* [`to-upper`](../functions/strings-to-upper.md) – returns the uppercased version of the given string
+* [`trim`](../functions/strings-trim.md) – returns the given whitespace with leading/trailing whitespace removed
+* [`trim-prefix`](../functions/strings-trim-prefix.md) – removes the prefix from the string, if it exists
+* [`trim-suffix`](../functions/strings-trim-suffix.md) – removes the suffix from the string, if it exists
+
+## Types Functions
+
+* [`to-bool`](../functions/types-to-bool.md) – try to convert the given argument losslessly to a bool
+* [`to-float`](../functions/types-to-float.md) – try to convert the given argument losslessly to a float64
+* [`to-int`](../functions/types-to-int.md) – try to convert the given argument losslessly to an int64
+* [`to-string`](../functions/types-to-string.md) – try to convert the given argument losslessly to a string
+* [`type-of`](../functions/types-type-of.md) – returns the type of a given value (e.g. "string" or "number")
 <!-- END_TOC -->

docs/functions/comparisons-eq.md

@@ -0,0 +1,35 @@
+# eq?
+
+`eq?` compares two arguments for equalities. Equality is defined based on the
+currently active [coalescer](../coalescing.md), so for example with strict
+coalescing, `(eq 1 "1")` is false, but with humane coalescing is true.
+
+See also [`like?`](comparisons-like.md), which always uses humane coalescing,
+and [`identical?`](comparisons-identical.md), which always uses strict
+coalescing.
+
+## Examples
+
+* `(eq? "" "")` -> `true`
+* `(eq? 1 2)` -> `false`
+* `(eq? (+ 1 1) 2)` -> `true`
+
+## Forms
+
+### `(eq? left right)`
+
+* `left` is an arbitrary expression, except for identifiers.
+* `right` is likewise an arbitrary expression, except for identifiers.
+
+Both expressions are evaluated and then compared using the current coalescer.
+If evaluation of either of the expressions yields and error, that error is
+returned.
+
+Equality is not defined for all type combinations and so `eq?` can, depending
+on the coalescer, return errors for invalid comparisons. With strict coalescing,
+`(eq? true 2)` returns an error because numbers cannot be converted to booleans.
+With humane coalescing, true would be returned instead and no error is generated.
+
+## Context
+
+`eq?` executes both expressions in their own contexts, so nothing is shared.

docs/functions/comparisons-gt.md

@@ -0,0 +1,23 @@
+# gt?
+
+`gt?` returns whether the first argument is numerically larger than the second.
+
+## Examples
+
+* `(gt? 3 2)` -> `true`
+* `(gt? 2.0 3)` -> `false`
+
+## Forms
+
+### `(gt? left right)`
+
+* `left` is an arbitrary expression, except for identifiers.
+* `right` is likewise an arbitrary expression, except for identifiers.
+
+`gt?` evaluates both expressions and coalesces their results to be numbers. If
+either evaluation or conversion fail, an error is returned. If the two arguments
+are valid numbers, the result of `left > right` is returned.
+
+## Context
+
+`gt?` executes both expressions in their own contexts, so nothing is shared.

docs/functions/comparisons-gte.md

@@ -0,0 +1,24 @@
+# gte?
+
+`gte?` returns whether the first argument is numerically larger than or equal to
+the second.
+
+## Examples
+
+* `(gte? 3 2)` -> `true`
+* `(gte? 2.0 3)` -> `false`
+
+## Forms
+
+### `(gte? left right)`
+
+* `left` is an arbitrary expression, except for identifiers.
+* `right` is likewise an arbitrary expression, except for identifiers.
+
+`gte?` evaluates both expressions and coalesces their results to be numbers. If
+either evaluation or conversion fail, an error is returned. If the two arguments
+are valid numbers, the result of `left >= right` is returned.
+
+## Context
+
+`gte?` executes both expressions in their own contexts, so nothing is shared.

docs/functions/comparisons-identical.md

@@ -0,0 +1,33 @@
+# identical?
+
+`identical?` compares two arguments for equalities. Equality is defined using the
+[strict coalescer](../coalescing.md#strict-coalescer), so `(identical? 1 "1")`
+yields a type error because strings cannot be converted to numbers.
+
+See also [`eq?`](comparisons-eq.md), which uses the currently selected coalescer,
+and [`like?`](comparisons-like.md), which always uses humane coalescing.
+
+## Examples
+
+* `(identical? 1 "1")` -> `false`
+* `(identical? 1 1.0)` -> `true`
+
+## Forms
+
+### `(identical? left right)`
+
+* `left` is an arbitrary expression, except for identifiers.
+* `right` is likewise an arbitrary expression, except for identifiers.
+
+Both expressions are evaluated and then compared using the current coalescer.
+If evaluation of either of the expressions yields and error, that error is
+returned.
+
+Equality is not defined for all type combinations and so `identical?` can return
+errors for invalid comparisons. See the coalescing documentation for conversion
+rules.
+
+## Context
+
+`identical?` executes both expressions in their own contexts, so nothing is
+shared.

docs/functions/comparisons-like.md

@@ -0,0 +1,33 @@
+# like?
+
+`like?` compares two arguments for equalities. Equality is defined using the
+[humane coalescer](../coalescing.md#humane-coalescer), so `(like? 1 "1")` yields
+no type error, but true.
+
+See also [`eq?`](comparisons-eq.md), which uses the currently selected coalescer,
+and [`identical?`](comparisons-identical.md), which always uses strict
+coalescing.
+
+## Examples
+
+* `(like? 1 "1")` -> `true`
+* `(like? 1 "2")` -> `false`
+
+## Forms
+
+### `(like? left right)`
+
+* `left` is an arbitrary expression, except for identifiers.
+* `right` is likewise an arbitrary expression, except for identifiers.
+
+Both expressions are evaluated and then compared using the current coalescer.
+If evaluation of either of the expressions yields and error, that error is
+returned.
+
+Equality is not defined for all type combinations, even with the humane coalescer,
+and so `like?` can return errors for invalid comparisons. See the coalescing
+documentation for conversion rules.
+
+## Context
+
+`like?` executes both expressions in their own contexts, so nothing is shared.

docs/functions/comparisons-lt.md

@@ -0,0 +1,23 @@
+# lt?
+
+`lt?` returns whether the first argument is numerically smaller than the second.
+
+## Examples
+
+* `(lt? 3 2)` -> `false`
+* `(lt? 2.0 3)` -> `true`
+
+## Forms
+
+### `(lt? left right)`
+
+* `left` is an arbitrary expression, except for identifiers.
+* `right` is likewise an arbitrary expression, except for identifiers.
+
+`lt?` evaluates both expressions and coalesces their results to be numbers. If
+either evaluation or conversion fail, an error is returned. If the two arguments
+are valid numbers, the result of `left < right` is returned.
+
+## Context
+
+`lt?` executes both expressions in their own contexts, so nothing is shared.

docs/functions/comparisons-lte.md

@@ -0,0 +1,24 @@
+# lte?
+
+`lte?` returns whether the first argument is numerically smaller than or equal to
+the second.
+
+## Examples
+
+* `(lte? 3 2)` -> `true`
+* `(lte? 2.0 3)` -> `false`
+
+## Forms
+
+### `(lte? left right)`
+
+* `left` is an arbitrary expression, except for identifiers.
+* `right` is likewise an arbitrary expression, except for identifiers.
+
+`lte?` evaluates both expressions and coalesces their results to be numbers. If
+either evaluation or conversion fail, an error is returned. If the two arguments
+are valid numbers, the result of `left <= right` is returned.
+
+## Context
+
+`lte?` executes both expressions in their own contexts, so nothing is shared.