Miscellaneous Functions

(always x)

Return a function that discards any arguments and always returns `x`.

(antepenultimate xs)

Get the third-to-last element from an indexed data structure.

(binary-search x arr &opt <?)

Returns the index of `x` in a sorted array or tuple or the index of
the next item if `x` is not present. This is the correct insert index
for `x` within `arr`. If a `<?` comparator is given, the search uses
that to compare elements, otherwise uses `<`.

(binary-search-by x arr f)

Returns the index of `x` in an array or tuple which has been sorted
by a mapping function `f`, or the index of the next item if `x` is not
present. This is the correct insert index for `x` within `arr`.

(caperr & body)

Captures the standard error output of the variadic `body` and returns it
as a buffer.

(capout & body)

Captures the standard output of the variadic `body` and returns it as
a buffer.

(cond-> val & clauses)

Threading conditional macro. It takes `val` to mutate,
and `clauses` pairs with condition and operation to which `val`,
is passed as first argument. All conditions are tried and
for truthy conditions the operation is executed.
Returns the value mutated if any condition is truthy.

(cond->> val & clauses)

Threading conditional macro. It takes `val` to mutate,
and `clauses` pairs of condition and operation to which `val`,
is passed as last argument. All conditions are tried and
for truthy conditions the operation is executed.
Returns mutated value if any condition is truthy.

(dedent & xs)

Remove indentation after concatenating the arguments. Works by removing
leading whitespace, and then removing that same pattern of whitespace after
new lines.

(defs & bindings)

Defines many constants as in let `bindings`, but without creating a new scope.

(dfs data visit-leaf &opt node-before node-after get-children seen)

Do a depth first, pre-order traversal over a data structure.
Also allow for callbacks before and after visiting the children
of a node. Also allow for a custom `get-children` function to
change traversal as needed. Will detect cycles if an empty table
is passed as the `seen` parameter, which is used to cache values
that have been visited.

(do-def c d & body)

Convenience macro for defining constant named `c` with value `d` before `body`
and returning it after evaluating `body`, that presumably modifies
the content referred to by `c`. For example, a buffer, table or array.

(do-var v d & body)

Convenience macro for defining variable named `v` with value `d` before `body`
and returning it after evaluating `body`, that presumably modifies `v`.

(format-table buf-into data &opt columns header-mapping column-mapping)

Same as print-table but pushes table into a buffer.

(gett ds & keyz)

Recursive macro (get). Similar to get-in, but `keyz` is variadic.

(insert-sorted arr <? & xs)

Insert elements in `arr` such that it remains sorted by the comparator. If
`arr` is not sorted beforehand, the results are undefined. Returns `arr`.

(insert-sorted-by arr f & xs)

Insert elements in `arr` such that it remains sorted by the value returned
when `f` is called with the element, comparing the values with `<`. If `arr` is
not sorted beforehand, the results are undefined. Returns `arr`.

(int->string int &opt base)

Stringify an integer in a particular base. Defaults to decimal (base 10).

(int/ & xs)

Perform integer division.

(log level & args)

Print to a dynamic binding stream if that stream is set, otherwise do
nothing. Evaluate to nil.
For example, `(log :err "value error: %V" my-value)` will print
to `(dyn :err)` only if `(dyn :err)` has been set.

(make prototype & pairs)

Convenience macro for creating new table from even number of kvs pairs in variadic `pairs`
arguments and setting its prototype to `prototype`.
Factory function for creating new objects from prototypes.

(make-id &opt prefix)

Create a random, printable keyword id with 10 bytes of entropy
with an optional prefix.

(map-keys f data)

Returns new table with function `f` applied to `data`'s
keys recursively.

(map-keys-flat f data)

Returns new table with function `f` applied to `data`'s
keys without recursing.

(map-vals f data)

Returns new table with function `f` applied to `data`'s values.

(merge-sorted a b &opt <?)

Merges two sorted arrays so that the result remains sorted, using an optional comparator.
If no comparator is given, `<` is used.

(merge-sorted-by a b f)

Merges two sorted arrays so that result remains sorted when `f` is called on each element,
comparing the values with `<`.

(penultimate xs)

Get the second-to-last element from an indexed data structure.

(print-table data &opt columns header-mapping column-mapping)

Iterate through the rows of a data structure and print a table in a human
readable way, with padding and heading information. Can optionally provide
a function used to print a row, as well as optionally select column keys
for each row. Lastly, a `header-mapping` dictionary can be provided that
changes the printed header names by mapping column keys to the desired
header name. If no mapping is found, then the column key will be used as
the header name. Returns nil.

(randomize-array arr &opt rng)

Randomizes array using the fisher-yates shuffle, takes an optional random
number generator.

(second xs)

Get the second element from an indexed data structure.

(select-keys data keyz)

Returns new table with selected `keyz` from dictionary `data`.

(set* tgts exprs)

Parallel `set` function. Takes a list of targets and
expressions, evaluates all the expressions, and then
assigns them to the targets. Each target can be a variable
or a 2-tuple, just like in the normal `set` special form.

(string->int str &opt base)

Parse an integer in the given base. Defaults to decimal (base 10). Differs
from scan-number in that this does not recognize floating point notation.

(table-filter pred dict)

Filter a key-value structure into a table. Semantics are the same as for
built-in `filter`, except that `pred` takes two arguments (key and value).
Does not consider prototypes.

(third xs)

Get the third element from an indexed data structure.

(trim-prefix prefix str)

Trim the specified prefix of a string if it has one

(trim-suffix suffix str)

Trim the specified suffix of a string if it has one

(until cnd & body)

Repeat `body` while the `cnd` is false.
Equivalent to (while (not cnd) ;body).

(vars & bindings)

Defines many variables as in let `bindings`, but without creating a new scope.