Core API

(% & xs)

Returns the remainder of dividing the first value of xs by each remaining value.

(%= x & ns)

Shorthand for (set x (% x n)).

(* & xs)

Returns the product of all elements in xs. If xs is empty, returns 1.

(*= x & ns)

Shorthand for (set x (* x n)).

Dynamic bindings that will contain command line arguments at program start.

Bound to the name of the currently compiling file.

Enables a built in debugger on errors and other useful features for debugging in a repl.

Optional namespace prefix to add to keywords declared with defdyn. Use this to prevent keyword collisions between dynamic bindings.

Whether or not to colorize documentation printed with doc-format.

Width in columns to print documentation printed with doc-format.

Where error printing prints output to.

Whether or not to turn on error coloring in stacktraces and other error messages.

Name of the interpreter executable used to execute this program. Corresponds to argv[0] in the call to int main(int argc, char **argv);.

When set, will cause the current context to complete. Can be set to exit from repl (or file), for example.

Set the return value from run-context upon an exit.

Current native library for ffi/bind and other settings

The current lint error level. The error level is the lint level at which compilation will exit with an error and not continue.

A table of keyword alias to numbers denoting a lint level. Can be used to provided custom aliases for numeric lint levels.

The current lint warning level. The warning level is the lint level at which and error will be printed but compilation will continue as normal.

Inside a macro, is bound to the source form that invoked the macro

Bound to an array of lint messages that will be reported by the compiler inside a macro. To indicate an error or warning, a macro author should use maclintf.

Dynamic binding for overriding module/cache

Dynamic binding for overriding module/loaders

Dynamic binding for overriding module/loading

Dynamic binding for creating new environments for import, require, and dofile. Overrides make-env.

Dynamic binding for overriding module/paths

Where normal print functions print output to.

The implicit base grammar used when compiling PEGs. Any undefined keywords found when compiling a peg will use lookup in this table (if defined).

Format specifier for the pp function

Path to profile file loaded when starting up the repl.

When set, allow dynamically rebinding top level defs. Will slow generated code and is intended to be used for development.

Allow setting a custom prompt at the default REPL. Not all REPLs will respect this binding.

Path of directory to load system modules from.

When spawning a thread or fiber, the task-id can be assigned for concurrency control.

(+ & xs)

Returns the sum of all xs. xs must be integers or real numbers only. If xs is empty, return 0.

(++ x)

Increments the var x by 1.

(+= x & ns)

Increments the var x by n.

(- & xs)

Returns the difference of xs. If xs is empty, returns 0. If xs has one element, returns the negative value of that element. Otherwise, returns the first element in xs minus the sum of the rest of the elements.

(-- x)

Decrements the var x by 1.

(-= x & ns)

Decrements the var x by n.

(-> x & forms)

Threading macro. Inserts x as the second value in the first form in forms, and inserts the modified first form into the second form in the same manner, and so on. Useful for expressing pipelines of data.

(->> x & forms)

Threading macro. Inserts x as the last value in the first form in forms, and inserts the modified first form into the second form in the same manner, and so on. Useful for expressing pipelines of data.

(-?> x & forms)

Short circuit threading macro. Inserts x as the second value in the first form in forms, and inserts the modified first form into the second form in the same manner, and so on. The pipeline will return nil if an intermediate value is nil. Useful for expressing pipelines of data.

(-?>> x & forms)

Short circuit threading macro. Inserts x as the last value in the first form in forms, and inserts the modified first form into the second form in the same manner, and so on. The pipeline will return nil if an intermediate value is nil. Useful for expressing pipelines of data.

(/ & xs)

Returns the quotient of xs. If xs is empty, returns 1. If xs has one value x, returns the reciprocal of x. Otherwise return the first value of xs repeatedly divided by the remaining values.

(/= x & ns)

Shorthand for (set x (/ x n)).

(< & xs)

Check if xs is in ascending order. Returns a boolean.

(<= & xs)

Check if xs is in non-descending order. Returns a boolean.

(= & xs)

Check if all values in xs are equal. Returns a boolean.

(> & xs)

Check if xs is in descending order. Returns a boolean.

(>= & xs)

Check if xs is in non-ascending order. Returns a boolean.

(abstract? x)

Check if x is an abstract type.

(accumulate f init ind)

Similar to reduce, but accumulates intermediate values into an array. The last element in the array is what would be the return value from reduce. The init value is not added to the array (the return value will have the same number of elements as ind). Returns a new array.

(accumulate2 f ind)

The 2-argument version of accumulate that does not take an initialization value. The first value in ind will be added to the array as is, so the length of the return value will be (length ind).

(all pred ind & inds)

Returns true if (pred item) is truthy for every item in ind. Otherwise, returns the first falsey result encountered. Returns true if ind is empty.

(all-bindings &opt env local)

Get all symbols available in an environment. Defaults to the current fiber's environment. If local is truthy, will not show inherited bindings (from prototype tables).

(all-dynamics &opt env local)

Get all dynamic bindings in an environment. Defaults to the current fiber's environment. If local is truthy, will not show inherited bindings (from prototype tables).

(and & forms)

Evaluates to the last argument if all preceding elements are truthy, otherwise evaluates to the first falsey argument.

(any? ind)

Evaluates to the last element of ind if all preceding elements are falsey, otherwise evaluates to the first truthy element.

(apply f & args)

Applies a function f to a variable number of arguments. Each element in args is used as an argument to f, except the last element in args, which is expected to be an array or a tuple. Each element in this last argument is then also pushed as an argument to f.

(array & items)

Create a new array that contains items. Returns the new array.

(array/clear arr)

Empties an array, setting it's count to 0 but does not free the backing capacity. Returns the modified array.

(array/concat arr & parts)

Concatenates a variable number of arrays (and tuples) into the first argument, which must be an array. If any of the parts are arrays or tuples, their elements will be inserted into the array. Otherwise, each part in parts will be appended to arr in order. Return the modified array arr.

(array/ensure arr capacity growth)

Ensures that the memory backing the array is large enough for capacity items at the given rate of growth. capacity and growth must be integers. If the backing capacity is already enough, then this function does nothing. Otherwise, the backing memory will be reallocated so that there is enough space.

(array/fill arr &opt value)

Replace all elements of an array with value (defaulting to nil) without changing the length of the array. Returns the modified array.

(array/insert arr at & xs)

Insert all xs into array arr at index at. at should be an integer between 0 and the length of the array. A negative value for at will index backwards from the end of the array, inserting after the index such that inserting at -1 appends to the array. Returns the array.

(array/join arr & parts)

Join a variable number of arrays and tuples into the first argument, which must be an array. Return the modified array arr.

(array/new capacity)

Creates a new empty array with a pre-allocated capacity. The same as (array) but can be more efficient if the maximum size of an array is known.

(array/new-filled count &opt value)

Creates a new array of count elements, all set to value, which defaults to nil. Returns the new array.

(array/peek arr)

Returns the last element of the array. Does not modify the array.

(array/pop arr)

Remove the last element of the array and return it. If the array is empty, will return nil. Modifies the input array.

(array/push arr & xs)

Push all the elements of xs to the end of an array. Modifies the input array and returns it.

(array/remove arr at &opt n)

Remove up to n elements starting at index at in array arr. at can index from the end of the array with a negative index, and n must be a non-negative integer. By default, n is 1. Returns the array.

(array/slice arrtup &opt start end)

Takes a slice of array or tuple from start to end. The range is half open, [start, end). Indexes can also be negative, indicating indexing from the end of the array. By default, start is 0 and end is the length of the array. Note that if the range is negative, it is taken as (start, end] to allow a full negative slice range. Returns a new array.

(array/trim arr)

Set the backing capacity of an array to its current length. Returns the modified array.

(array/weak capacity)

Creates a new empty array with a pre-allocated capacity and support for weak references. Similar to array/new.

(array? x)

Check if x is an array.

(as-> x as & forms)

Thread forms together, replacing as in forms with the value of the previous form. The first form is the value x. Returns the last value.

(as-macro f & args)

Use a function or macro literal f as a macro. This lets any function be used as a macro. Inside a quasiquote, the idiom (as-macro ,my-custom-macro arg1 arg2...) can be used to avoid unwanted variable capture of my-custom-macro.

(as?-> x as & forms)

Thread forms together, replacing as in forms with the value of the previous form. The first form is the value x. If any intermediate values are falsey, return nil; otherwise, returns the last value.

(asm assembly)

Returns a new function that is the compiled result of the assembly. The syntax for the assembly can be found on the Janet website, and should correspond to the return value of disasm. Will throw an error on invalid assembly.

(assert x &opt err)

Throw an error if x is not truthy. Will not evaluate err if x is truthy.

(assertf x fmt & args)

Convenience macro that combines assert and string/format.

(bad-compile msg macrof where &opt line col)

Default handler for a compile error.

(bad-parse p where)

Default handler for a parse error.

(band & xs)

Returns the bit-wise and of all values in xs. Each x in xs must be an integer.

(blshift x & shifts)

Returns the value of x bit shifted left by the sum of all values in shifts. x and each element in shift must be an integer.

(bnot x)

Returns the bit-wise inverse of integer x.

(boolean? x)

Check if x is a boolean.

(bor & xs)

Returns the bit-wise or of all values in xs. Each x in xs must be an integer.

(brshift x & shifts)

Returns the value of x bit shifted right by the sum of all values in shifts. x and each element in shift must be an integer.

(brushift x & shifts)

Returns the value of x bit shifted right by the sum of all values in shifts. x and each element in shift must be an integer. The sign of x is not preserved, so for positive shifts the return value will always be positive.

(buffer & xs)

Creates a buffer by concatenating the elements of xs together. If an element is not a byte sequence, it is converted to bytes via describe. Returns the new buffer.

(buffer/bit buffer index)

Gets the bit at the given bit-index. Returns true if the bit is set, false if not.

(buffer/bit-clear buffer index)

Clears the bit at the given bit-index. Returns the buffer.

(buffer/bit-set buffer index)

Sets the bit at the given bit-index. Returns the buffer.

(buffer/bit-toggle buffer index)

Toggles the bit at the given bit index in buffer. Returns the buffer.

(buffer/blit dest src &opt dest-start src-start src-end)

Insert the contents of src into dest. Can optionally take indices that indicate which part of src to copy into which part of dest. Indices can be negative in order to index from the end of src or dest. Returns dest.

(buffer/clear buffer)

Sets the size of a buffer to 0 and empties it. The buffer retains its memory so it can be efficiently refilled. Returns the modified buffer.

(buffer/fill buffer &opt byte)

Fill up a buffer with bytes, defaulting to 0s. Does not change the buffer's length. Returns the modified buffer.

(buffer/format buffer format & args)

Snprintf like functionality for printing values into a buffer. Returns the modified buffer.

(buffer/format-at buffer at format & args)

Snprintf like functionality for printing values into a buffer. Returns the modified buffer.

(buffer/from-bytes & byte-vals)

Creates a buffer from integer parameters with byte values. All integers will be coerced to the range of 1 byte 0-255.

(buffer/new capacity)

Creates a new, empty buffer with enough backing memory for capacity bytes. Returns a new buffer of length 0.

(buffer/new-filled count &opt byte)

Creates a new buffer of length count filled with byte. By default, byte is 0. Returns the new buffer.

(buffer/popn buffer n)

Removes the last n bytes from the buffer. Returns the modified buffer.

(buffer/push buffer & xs)

Push both individual bytes and byte sequences to a buffer. For each x in xs, push the byte if x is an integer, otherwise push the bytesequence to the buffer. Thus, this function behaves like both buffer/push-string and buffer/push-byte. Returns the modified buffer. Will throw an error if the buffer overflows.

(buffer/push-at buffer index & xs)

Same as buffer/push, but copies the new data into the buffer at index index.

(buffer/push-byte buffer & xs)

Append bytes to a buffer. Will expand the buffer as necessary. Returns the modified buffer. Will throw an error if the buffer overflows.

(buffer/push-float32 buffer order data)

Push the underlying bytes of a 32 bit float data onto the end of the buffer. Returns the modified buffer.

(buffer/push-float64 buffer order data)

Push the underlying bytes of a 64 bit float data onto the end of the buffer. Returns the modified buffer.

(buffer/push-string buffer & xs)

Push byte sequences onto the end of a buffer. Will accept any of strings, keywords, symbols, and buffers. Returns the modified buffer. Will throw an error if the buffer overflows.

(buffer/push-uint16 buffer order data)

Push a 16 bit unsigned integer data onto the end of the buffer. Returns the modified buffer.

(buffer/push-uint32 buffer order data)

Push a 32 bit unsigned integer data onto the end of the buffer. Returns the modified buffer.

(buffer/push-uint64 buffer order data)

Push a 64 bit unsigned integer data onto the end of the buffer. Returns the modified buffer.

(buffer/push-word buffer & xs)

Append machine words to a buffer. The 4 bytes of the integer are appended in twos complement, little endian order, unsigned for all x. Returns the modified buffer. Will throw an error if the buffer overflows.

(buffer/slice bytes &opt start end)

Takes a slice of a byte sequence from start to end. The range is half open, [start, end). Indexes can also be negative, indicating indexing from the end of the end of the array. By default, start is 0 and end is the length of the buffer. Returns a new buffer.

(buffer/trim buffer)

Set the backing capacity of the buffer to the current length of the buffer. Returns the modified buffer.

(buffer? x)

Check if x is a buffer.

(bundle/add manifest src &opt dest chmod-mode)

Add files and directories during a bundle install relative to (dyn *syspath*). Added paths will be recorded in the bundle manifest such that they are properly tracked and removed during an upgrade or uninstall.

(bundle/add-bin manifest src &opt dest chmod-mode)

Shorthand for adding scripts during an install. Scripts will be installed to (string (dyn *syspath*) "/bin") by default and will be set to be executable.

(bundle/add-directory manifest dest &opt chmod-mode)

Add a directory during the install process relative to (dyn *syspath*)

(bundle/add-file manifest src &opt dest chmod-mode)

Add files during an install relative to (dyn *syspath*)

(bundle/install path &keys config)

Install a bundle from the local filesystem. The name of the bundle will be inferred from the bundle, or passed as a parameter :name in config.

(bundle/installed? bundle-name)

Check if a bundle is installed.

(bundle/list)

Get a list of all installed bundles in lexical order.

(bundle/manifest bundle-name)

Get the manifest for a give installed bundle

(bundle/prune)

Remove all orphaned bundles from the syspath. An orphaned bundle is a bundle that is marked for :auto-remove and is not depended on by any other bundle.

(bundle/reinstall bundle-name &keys new-config)

Reinstall an existing bundle from the local source code.

(bundle/replace bundle-name path &keys new-config)

Reinstall an existing bundle from a new directory. Similar to bundle/reinstall, but installs the replacement bundle from any directory. This is necesarry to replace a package without breaking any dependencies.

(bundle/topolist)

Get topological order of all bundles, such that each bundle is listed after its dependencies.

(bundle/uninstall bundle-name)

Remove a bundle from the current syspath

(bundle/update-all &keys configs)

Reinstall all bundles

(bundle/whois path)

Given a file path, figure out which bundle installed it.

(bxor & xs)

Returns the bit-wise xor of all values in xs. Each in xs must be an integer.

(bytes? x)

Check if x is a string, symbol, keyword, or buffer.

(cancel fiber err)

Resume a fiber but have it immediately raise an error. This lets a programmer unwind a pending fiber. Returns the same result as resume.

(case dispatch & pairs)

Select the body that equals the dispatch value. When pairs has an odd number of elements, the last is the default expression. If no match is found, returns nil.

(catseq head & body)

Similar to loop, but concatenates each element from the loop body into an array and returns that. See loop for details.

(cfunction? x)

Check if x a cfunction.

(chr c)

Convert a string of length 1 to its byte (ascii) value at compile time.

(cli-main args)

Entrance for the Janet CLI tool. Call this function with the command line arguments as an array or tuple of strings to invoke the CLI interface.

(cmp x y)

Returns -1 if x is strictly less than y, 1 if y is strictly greater than x, and 0 otherwise. To return 0, x and y must be the exact same type.

(comment &)

Ignores the body of the comment.

(comp & functions)

Takes multiple functions and returns a function that is the composition of those functions.

(compare x y)

Polymorphic compare. Returns -1, 0, 1 for x < y, x = y, x > y respectively. Differs from the primitive comparators in that it first checks to see whether either x or y implement a compare method which can compare x and y. If so, it uses that method. If not, it delegates to the primitive comparators.

(compare< & xs)

Equivalent of < but using polymorphic compare instead of primitive comparator.

(compare<= & xs)

Equivalent of <= but using polymorphic compare instead of primitive comparator.

(compare= & xs)

Equivalent of = but using polymorphic compare instead of primitive comparator.

(compare> & xs)

Equivalent of > but using polymorphic compare instead of primitive comparator.

(compare>= & xs)

Equivalent of >= but using polymorphic compare instead of primitive comparator.

(compif cnd tru &opt fals)

Check the condition cnd at compile time -- if truthy, compile tru, else compile fals.

(compile ast &opt env source lints)

Compiles an Abstract Syntax Tree (ast) into a function. Pair the compile function with parsing functionality to implement eval. Returns a new function and does not modify ast. Returns an error struct with keys :line, :column, and :error if compilation fails. If a lints array is given, linting messages will be appended to the array. Each message will be a tuple of the form (level line col message).

(complement f)

Returns a function that is the complement to the argument.

(comptime x)

Evals x at compile time and returns the result. Similar to a top level unquote.

(compwhen cnd & body)

Check the condition cnd at compile time -- if truthy, compile (upscope ;body), else compile nil.

(cond & pairs)

Evaluates conditions sequentially until the first true condition is found, and then executes the corresponding body. If there are an odd number of forms, and no forms are matched, the last expression is executed. If there are no matches, returns nil.

(coro & body)

A wrapper for making fibers that may yield multiple values (coroutine). Same as (fiber/new (fn [] ;body) :yi).

(count pred ind & inds)

Count the number of items in ind for which (pred item) is true.

(curenv &opt n)

Get the current environment table. Same as (fiber/getenv (fiber/current)). If n is provided, gets the nth prototype of the environment table.

(debug &opt x)

Throws a debug signal that can be caught by a parent fiber and used to inspect the running state of the current fiber. Returns the value passed in by resume.

(debug/arg-stack fiber)

Gets all values currently on the fiber's argument stack. Normally, this should be empty unless the fiber signals while pushing arguments to make a function call. Returns a new array.

(debug/break source line col)

Sets a breakpoint in source at a given line and column. Will throw an error if the breakpoint location cannot be found. For example

(debug/break "core.janet" 10 4)

will set a breakpoint at line 10, 4th column of the file core.janet.

(debug/fbreak fun &opt pc)

Set a breakpoint in a given function. pc is an optional offset, which is in bytecode instructions. fun is a function value. Will throw an error if the offset is too large or negative.

(debug/lineage fib)

Returns an array of all child fibers from a root fiber. This function is useful when a fiber signals or errors to an ancestor fiber. Using this function, the fiber handling the error can see which fiber raised the signal. This function should be used mostly for debugging purposes.

(debug/stack fib)

Gets information about the stack as an array of tables. Each table in the array contains information about a stack frame. The top-most, current stack frame is the first table in the array, and the bottom-most stack frame is the last value. Each stack frame contains some of the following attributes:

• :c - true if the stack frame is a c function invocation

• :source-column - the current source column of the stack frame

• :function - the function that the stack frame represents

• :source-line - the current source line of the stack frame

• :name - the human-friendly name of the function

• :pc - integer indicating the location of the program counter

• :source - string with the file path or other identifier for the source code

• :slots - array of all values in each slot

• :tail - boolean indicating a tail call

(debug/stacktrace fiber &opt err prefix)

Prints a nice looking stacktrace for a fiber. Can optionally provide an error value to print the stack trace with. If prefix is nil or not provided, will skip the error line. Returns the fiber.

(debug/step fiber &opt x)

Run a fiber for one virtual instruction of the Janet machine. Can optionally pass in a value that will be passed as the resuming value. Returns the signal value, which will usually be nil, as breakpoints raise nil signals.

(debug/unbreak source line column)

Remove a breakpoint with a source key at a given line and column. Will throw an error if the breakpoint cannot be found.

(debug/unfbreak fun &opt pc)

Unset a breakpoint set with debug/fbreak.

(debugger fiber &opt level)

Run a repl-based debugger on a fiber. Optionally pass in a level to differentiate nested debuggers.

An environment that contains dot prefixed functions for debugging.

(debugger-on-status env &opt level is-repl)

Create a function that can be passed to run-context's :on-status argument that will drop into a debugger on errors. The debugger will only start on abnormal signals if the env table has the :debug dyn set to a truthy value.

(dec x)

Returns x - 1.

(deep-not= x y)

Like not=, but mutable types (arrays, tables, buffers) are considered equal if they have identical structure. Much slower than not=.

(deep= x y)

Like =, but mutable types (arrays, tables, buffers) are considered equal if they have identical structure. Much slower than =.

(def- name & more)

Define a private value that will not be exported.

(default sym val)

Define a default value for an optional argument. Expands to (def sym (if (= nil sym) val sym)).

The default grammar used for pegs. This grammar defines several common patterns that should make it easier to write more complex patterns.

(defdyn alias & more)

Define an alias for a keyword that is used as a dynamic binding. The alias is a normal, lexically scoped binding that can be used instead of a keyword to prevent typos. defdyn does not set dynamic bindings or otherwise replace dyn and setdyn. The alias _must_ start and end with the * character, usually called "earmuffs".

(defer form & body)

Run form unconditionally after body, even if the body throws an error. Will also run form if a user signal 0-4 is received.

(defglobal name value)

Dynamically create a global def.

(defmacro name & more)

Define a macro.

(defmacro- name & more)

Define a private macro that will not be exported.

(defn name & more)

Define a function. Equivalent to (def name (fn name [args] ...)).

(defn- name & more)

Define a private function that will not be exported.

(delay & forms)

Lazily evaluate a series of expressions. Returns a function that returns the result of the last expression. Will only evaluate the body once, and then memoizes the result.

(describe x)

Returns a string that is a human-readable description of x. For recursive data structures, the string returned contains a pointer value from which the identity of x can be determined.

(dictionary? x)

Check if x is a table or struct.

(disasm func &opt field)

Returns assembly that could be used to compile the given function. func must be a function, not a c function. Will throw on error on a badly typed argument. If given a field name, will only return that part of the function assembly. Possible fields are:

• :arity - number of required and optional arguments.
• :min-arity - minimum number of arguments function can be called with.
• :max-arity - maximum number of arguments function can be called with.
• :vararg - true if function can take a variable number of arguments.
• :bytecode - array of parsed bytecode instructions. Each instruction is a tuple.
• :source - name of source file that this function was compiled from.
• :name - name of function.
• :slotcount - how many virtual registers, or slots, this function uses. Corresponds to stack space used by function.
• :symbolmap - all symbols and their slots.
• :constants - an array of constants referenced by this function.
• :sourcemap - a mapping of each bytecode instruction to a line and column in the source file.
• :environments - an internal mapping of which enclosing functions are referenced for bindings.
• :defs - other function definitions that this function may instantiate.

(distinct xs)

Returns an array of the deduplicated values in xs.

(div & xs)

Returns the floored division of xs. If xs is empty, returns 1. If xs has one value x, returns the reciprocal of x. Otherwise return the first value of xs repeatedly divided by the remaining values.

(doc &opt sym)

Shows documentation for the given symbol, or can show a list of available bindings. If sym is a symbol, will look for documentation for that symbol. If sym is a string or is not provided, will show all lexical and dynamic bindings in the current environment containing that string (all bindings will be shown if no string is given).

(doc* &opt sym)

Get the documentation for a symbol in a given environment. Function form of doc.

(doc-format str &opt width indent colorize)

Reformat a docstring to wrap a certain width. Docstrings can either be plaintext or a subset of markdown. This allows a long single line of prose or formatted text to be a well-formed docstring. Returns a buffer containing the formatted text.

(doc-of x)

Searches all loaded modules in module/cache for a given binding and prints out its documentation. This does a search by value instead of by name. Returns nil.

(dofile path &named exit env source expander evaluator read parser)

Evaluate a file, file path, or stream and return the resulting environment. :env, :expander, :source, :evaluator, :read, and :parser are passed through to the underlying run-context call. If exit is true, any top level errors will trigger a call to (os/exit 1) after printing the error.

(drop n ind)

Drop the first n elements in an indexed or bytes type. Returns a new tuple or string instance, respectively. If n is negative, drops the last n elements instead.

(drop-until pred ind)

Same as (drop-while (complement pred) ind).

(drop-while pred ind)

Given a predicate, remove elements from an indexed or bytes type that satisfy the predicate, and abort on first failure. Returns a new tuple or string, respectively.

(dyn key &opt default)

Get a dynamic binding. Returns the default value (or nil) if no binding found.

(each x ds & body)

Loop over each value in ds. Returns nil.

(eachk x ds & body)

Loop over each key in ds. Returns nil.

(eachp x ds & body)

Loop over each (key, value) pair in ds. Returns nil.

(edefer form & body)

Run form after body in the case that body terminates abnormally (an error or user signal 0-4). Otherwise, return last form in body.

(eflush)

Flush (dyn :err stderr) if it is a file, otherwise do nothing.

(empty? xs)

Check if xs is empty.

(env-lookup env)

Creates a forward lookup table for unmarshalling from an environment. To create a reverse lookup table, use the invert function to swap keys and values in the returned table.

(eprin & xs)

Same as prin, but uses (dyn :err stderr) instead of (dyn :out stdout).

(eprinf fmt & xs)

Like eprintf but with no trailing newline.

(eprint & xs)

Same as print, but uses (dyn :err stderr) instead of (dyn :out stdout).

(eprintf fmt & xs)

Prints output formatted as if with (string/format fmt ;xs) to (dyn :err stderr) with a trailing newline.

(error e)

Throws an error e that can be caught and handled by a parent fiber.

(errorf fmt & args)

A combination of error and string/format. Equivalent to (error (string/format fmt ;args)).

(ev/acquire-lock lock)

Acquire a lock such that this operating system thread is the only thread with access to this resource. This will block this entire thread until the lock becomes available, and will not yield to other fibers on this system thread.

(ev/acquire-rlock rwlock)

Acquire a read lock an a read-write lock.

(ev/acquire-wlock rwlock)

Acquire a write lock on a read-write lock.

(ev/all-tasks)

Get an array of all active fibers that are being used by the scheduler.

(ev/call f & args)

Call a function asynchronously. Returns a fiber that is scheduled to run the function.

(ev/cancel fiber err)

Cancel a suspended fiber in the event loop. Differs from cancel in that it returns the canceled fiber immediately.

(ev/capacity channel)

Get the number of items a channel will store before blocking writers.

(ev/chan &opt capacity)

Create a new channel. capacity is the number of values to queue before blocking writers, defaults to 0 if not provided. Returns a new channel.

(ev/chan-close chan)

Close a channel. A closed channel will cause all pending reads and writes to return nil. Returns the channel.

(ev/chunk stream n &opt buffer timeout)

Same as ev/read, but will not return early if less than n bytes are available. If an end of stream is reached, will also return early with the collected bytes.

(ev/close stream)

Close a stream. This should be the same as calling (:close stream) for all streams.

(ev/count channel)

Get the number of items currently waiting in a channel.

(ev/deadline sec &opt tocancel tocheck)

Schedules the event loop to try to cancel the tocancel task as with ev/cancel. After sec seconds, the event loop will attempt cancellation of tocancel if the tocheck fiber is resumable. sec is a number that can have a fractional part. tocancel defaults to (fiber/root), but if specified, must be a task (root fiber). tocheck defaults to (fiber/current), but if specified, should be a fiber. Returns tocancel immediately.

(ev/do-thread & body)

Run some code in a new thread. Suspends the current fiber until the thread is complete, and evaluates to nil.

(ev/full channel)

Check if a channel is full or not.

(ev/gather & bodies)

Run a number of fibers in parallel on the event loop, and join when they complete. Returns the gathered results in an array.

(ev/give channel value)

Write a value to a channel, suspending the current fiber if the channel is full. Returns the channel if the write succeeded, nil otherwise.

(ev/give-supervisor tag & payload)

Send a message to the current supervisor channel if there is one. The message will be a tuple of all of the arguments combined into a single message, where the first element is tag. By convention, tag should be a keyword indicating the type of message. Returns nil.

(ev/go fiber-or-fun &opt value supervisor)

Put a fiber on the event loop to be resumed later. If a function is used, it is wrapped with fiber/new first. Optionally pass a value to resume with, otherwise resumes with nil. Returns the fiber. An optional core/channel can be provided as a supervisor. When various events occur in the newly scheduled fiber, an event will be pushed to the supervisor. If not provided, the new fiber will inherit the current supervisor.

(ev/lock)

Create a new lock to coordinate threads.

(ev/read stream n &opt buffer timeout)

Read up to n bytes into a buffer asynchronously from a stream. n can also be the keyword :all to read into the buffer until end of stream. Optionally provide a buffer to write into as well as a timeout in seconds after which to cancel the operation and raise an error. Returns the buffer if the read was successful or nil if end-of-stream reached. Will raise an error if there are problems with the IO operation.

(ev/release-lock lock)

Release a lock such that other threads may acquire it.

(ev/release-rlock rwlock)

Release a read lock on a read-write lock

(ev/release-wlock rwlock)

Release a write lock on a read-write lock

(ev/rselect & clauses)

Similar to ev/select, but will try clauses in a random order for fairness.

(ev/rwlock)

Create a new read-write lock to coordinate threads.

(ev/select & clauses)

Block until the first of several channel operations occur. Returns a tuple of the form [:give chan], [:take chan x], or [:close chan], where a :give tuple is the result of a write and a :take tuple is the result of a read. Each clause must be either a channel (for a channel take operation) or a tuple [channel x] (for a channel give operation). Operations are tried in order such that earlier clauses take precedence over later clauses. Both give and take operations can return a [:close chan] tuple, which indicates that the specified channel was closed while waiting, or that the channel was already closed.

(ev/sleep sec)

Suspend the current fiber for sec seconds without blocking the event loop.

(ev/spawn & body)

Run some code in a new fiber. This is shorthand for (ev/go (fn [] ;body)).

(ev/spawn-thread & body)

Run some code in a new thread. Like ev/do-thread, but returns nil immediately.

(ev/take channel)

Read from a channel, suspending the current fiber if no value is available.

(ev/thread main &opt value flags supervisor)

Run main in a new operating system thread, optionally passing value to resume with. The parameter main can either be a fiber, or a function that accepts 0 or 1 arguments. Unlike ev/go, this function will suspend the current fiber until the thread is complete. If you want to run the thread without waiting for a result, pass the :n flag to return nil immediately. Otherwise, returns nil. Available flags:

• :n - return immediately
• :t - set the task-id of the new thread to value. The task-id is passed in messages to the supervisor channel.
• :a - don't copy abstract registry to new thread (performance optimization)
• :c - don't copy cfunction registry to new thread (performance optimization)

(ev/thread-chan &opt limit)

Create a threaded channel. A threaded channel is a channel that can be shared between threads and used to communicate between any number of operating system threads.

(ev/to-file)

Create core/file copy of the stream. This value can be used when blocking IO behavior is needed.

(ev/with-deadline sec & body)

Create a fiber to execute body, schedule the event loop to cancel the task (root fiber) associated with body's fiber, and start body's fiber by resuming it.

The event loop will try to cancel the root fiber if body's fiber has not completed after at least sec seconds.

sec is a number that can have a fractional part.

(ev/with-lock lock & body)

Run a body of code after acquiring a lock. Will automatically release the lock when done.

(ev/with-rlock lock & body)

Run a body of code after acquiring read access to an rwlock. Will automatically release the lock when done.

(ev/with-wlock lock & body)

Run a body of code after acquiring write access to an rwlock. Will automatically release the lock when done.

(ev/write stream data &opt timeout)

Write data to a stream, suspending the current fiber until the write completes. Takes an optional timeout in seconds, after which will return nil. Returns nil, or raises an error if the write failed.

(eval form &opt env)

Evaluates a form in the current environment. If more control over the environment is needed, use run-context. Optionally pass in an env table with available bindings.

(eval-string str &opt env)

Evaluates a string in the current environment. If more control over the environment is needed, use run-context. Optionally pass in an env table with available bindings.

(even? x)

Check if x is even.

(every? ind)

Evaluates to the last element of ind if all preceding elements are truthy, otherwise evaluates to the first falsey element.

(extreme order args)

Returns the most extreme value in args based on the function order. order should take two values and return true or false (a comparison). Returns nil if args is empty.

(false? x)

Check if x is false.

(ffi/align type)

Get the align of an ffi type in bytes.

(ffi/call pointer signature & args)

Call a raw pointer as a function pointer. The function signature specifies how Janet values in args are converted to native machine types.

(ffi/calling-conventions)

Get an array of all supported calling conventions on the current architecture. Some architectures may have some FFI functionality (ffi/malloc, ffi/free, ffi/read, ffi/write, etc.) but not support any calling conventions. This function can be used to get all supported calling conventions that can be used on this architecture. All architectures support the :none calling convention which is a placeholder that cannot be used at runtime.

(ffi/close native)

Free a native object. Dereferencing pointers to symbols in the object will have undefined behavior after freeing.

(ffi/context &opt native-path &named map-symbols lazy)

Set the path of the dynamic library to implicitly bind, as well as other global state for ease of creating native bindings.

(ffi/defbind name ret-type & body)

Generate bindings for native functions in a convenient manner.

(ffi/defbind-alias name alias ret-type & body)

Generate bindings for native functions in a convenient manner. Similar to defbind but allows for the janet function name to be different than the FFI function.

(ffi/free pointer)

Free memory allocated with ffi/malloc. Returns nil.

(ffi/jitfn bytes)

Create an abstract type that can be used as the pointer argument to ffi/call. The content of bytes is architecture specific machine code that will be copied into executable memory.

(ffi/lookup native symbol-name)

Lookup a symbol from a native object. All symbol lookups will return a raw pointer if the symbol is found, else nil.

(ffi/malloc size)

Allocates memory directly using the janet memory allocator. Memory allocated in this way must be freed manually! Returns a raw pointer, or nil if size = 0.

(ffi/native &opt path)

Load a shared object or dll from the given path, and do not extract or run any code from it. This is different than native, which will run initialization code to get a module table. If path is nil, opens the current running binary. Returns a core/native.

(ffi/pointer-buffer pointer capacity &opt count offset)

Create a buffer from a pointer. The underlying memory of the buffer will not be reallocated or freed by the garbage collector, allowing unmanaged, mutable memory to be manipulated with buffer functions. Attempts to resize or extend the buffer beyond its initial capacity will raise an error. As with many FFI functions, this is memory unsafe and can potentially allow out of bounds memory access. Returns a new buffer.

(ffi/pointer-cfunction pointer &opt name source-file source-line)

Create a C Function from a raw pointer. Optionally give the cfunction a name and source location for stack traces and debugging.

(ffi/read ffi-type bytes &opt offset)

Parse a native struct out of a buffer and convert it to normal Janet data structures. This function is the inverse of ffi/write. bytes can also be a raw pointer, although this is unsafe.

(ffi/signature calling-convention ret-type & arg-types)

Create a function signature object that can be used to make calls with raw function pointers.

(ffi/size type)

Get the size of an ffi type in bytes.

(ffi/struct & types)

Create a struct type definition that can be used to pass structs into native functions.

(ffi/trampoline cc)

Get a native function pointer that can be used as a callback and passed to C libraries. This callback trampoline has the signature void trampoline(void \*ctx, void \*userdata) in the given calling convention. This is the only function signature supported. It is up to the programmer to ensure that the userdata argument contains a janet function the will be called with one argument, ctx which is an opaque pointer. This pointer can be further inspected with ffi/read.

(ffi/write ffi-type data &opt buffer index)

Append a native type to a buffer such as it would appear in memory. This can be used to pass pointers to structs in the ffi, or send C/C++/native structs over the network or to files. Returns a modified buffer or a new buffer if one is not supplied.

(fiber-fn flags & body)

A wrapper for making fibers. Same as (fiber/new (fn [] ;body) flags).

(fiber/can-resume? fiber)

Check if a fiber is finished and cannot be resumed.

(fiber/current)

Returns the currently running fiber.

(fiber/getenv fiber)

Gets the environment for a fiber. Returns nil if no such table is set yet.

(fiber/last-value fiber)

Get the last value returned or signaled from the fiber.

(fiber/maxstack fib)

Gets the maximum stack size in janet values allowed for a fiber. While memory for the fiber's stack is not allocated up front, the fiber will not allocated more than this amount and will throw a stack-overflow error if more memory is needed.

(fiber/new func &opt sigmask env)

Create a new fiber with function body func. Can optionally take a set of signals sigmask to capture from child fibers, and an environment table env. The mask is specified as a keyword where each character is used to indicate a signal to block. If the ev module is enabled, and this fiber is used as an argument to ev/go, these "blocked" signals will result in messages being sent to the supervisor channel. The default sigmask is :y. For example,

        (fiber/new myfun :e123)

blocks error signals and user signals 1, 2 and 3. The signals are as follows:

• :a - block all signals
• :d - block debug signals
• :e - block error signals
• :t - block termination signals: error + user[0-4]
• :u - block user signals
• :y - block yield signals
• :w - block await signals (user9)
• :r - block interrupt signals (user8)
• :0-9 - block a specific user signal

The sigmask argument also can take environment flags. If any mutually exclusive flags are present, the last flag takes precedence.

• :i - inherit the environment from the current fiber
• :p - the environment table's prototype is the current environment table

(fiber/root)

Returns the current root fiber. The root fiber is the oldest ancestor that does not have a parent.

(fiber/setenv fiber table)

Sets the environment table for a fiber. Set to nil to remove the current environment.

(fiber/setmaxstack fib maxstack)

Sets the maximum stack size in janet values for a fiber. By default, the maximum stack size is usually 8192.

(fiber/status fib)

Get the status of a fiber. The status will be one of:

• :dead - the fiber has finished
• :error - the fiber has errored out
• :debug - the fiber is suspended in debug mode
• :pending - the fiber has been yielded
• :user(0-7) - the fiber is suspended by a user signal
• :interrupted - the fiber was interrupted
• :suspended - the fiber is waiting to be resumed by the scheduler
• :alive - the fiber is currently running and cannot be resumed
• :new - the fiber has just been created and not yet run

(fiber? x)

Check if x is a fiber.

(file/close f)

Close a file and release all related resources. When you are done reading a file, close it to prevent a resource leak and let other processes read the file.

(file/flush f)

Flush any buffered bytes to the file system. In most files, writes are buffered for efficiency reasons. Returns the file handle.

(file/lines file)

Return an iterator over the lines of a file.

(file/open path &opt mode buffer-size)

Open a file. path is an absolute or relative path, and mode is a set of flags indicating the mode to open the file in. mode is a keyword where each character represents a flag. If the file cannot be opened, returns nil, otherwise returns the new file handle. Mode flags:

• r - allow reading from the file

• w - allow writing to the file

• a - append to the file

Following one of the initial flags, 0 or more of the following flags can be appended:

• b - open the file in binary mode (rather than text mode)

• + - append to the file instead of overwriting it

• n - error if the file cannot be opened instead of returning nil

See fopen (<stdio.h>, C99) for further details.

(file/read f what &opt buf)

Read a number of bytes from a file f into a buffer. A buffer buf can be provided as an optional third argument, otherwise a new buffer is created. what can either be an integer or a keyword. Returns the buffer with file contents. Values for what:

• :all - read the whole file

• :line - read up to and including the next newline character

• n (integer) - read up to n bytes from the file

(file/seek f &opt whence n)

Jump to a relative location in the file f. whence must be one of:

• :cur - jump relative to the current file location

• :set - jump relative to the beginning of the file

• :end - jump relative to the end of the file

By default, whence is :cur. Optionally a value n may be passed for the relative number of bytes to seek in the file. n may be a real number to handle large files of more than 4GB. Returns the file handle.

(file/tell f)

Get the current value of the file position for file f.

(file/temp)

Open an anonymous temporary file that is removed on close. Raises an error on failure.

(file/write f bytes)

Writes to a file. 'bytes' must be string, buffer, or symbol. Returns the file.

(filewatch/add watcher path &opt flags)

Add a path to the watcher. Available flags depend on the current OS, and are as follows:

Windows/MINGW (flags correspond to FILE_NOTIFY_CHANGE_* flags in win32 documentation):

• :all - trigger an event for all of the below triggers.

• :attributes - FILE_NOTIFY_CHANGE_ATTRIBUTES

• :creation - FILE_NOTIFY_CHANGE_CREATION

• :dir-name - FILE_NOTIFY_CHANGE_DIR_NAME

• :last-access - FILE_NOTIFY_CHANGE_LAST_ACCESS

• :last-write - FILE_NOTIFY_CHANGE_LAST_WRITE

• :security - FILE_NOTIFY_CHANGE_SECURITY

• :size - FILE_NOTIFY_CHANGE_SIZE

• :recursive - watch subdirectories recursively

Linux (flags correspond to IN_* flags from <sys/inotify.h>):

• :access - IN_ACCESS

• :all - IN_ALL_EVENTS

• :attrib - IN_ATTRIB

• :close-nowrite - IN_CLOSE_NOWRITE

• :close-write - IN_CLOSE_WRITE

• :create - IN_CREATE

• :delete - IN_DELETE

• :delete-self - IN_DELETE_SELF

• :ignored - IN_IGNORED

• :modify - IN_MODIFY

• :move-self - IN_MOVE_SELF

• :moved-from - IN_MOVED_FROM

• :moved-to - IN_MOVED_TO

• :open - IN_OPEN

• :q-overflow - IN_Q_OVERFLOW

• :unmount - IN_UNMOUNT

On Windows, events will have the following possible types:

• :unknown

• :added

• :removed

• :modified

• :renamed-old

• :renamed-new

On Linux, events will a :type corresponding to the possible flags, excluding :all.

(filewatch/listen watcher)

Listen for changes in the watcher.

(filewatch/new channel &opt default-flags)

Create a new filewatcher that will give events to a channel channel. See filewatch/add for available flags.

When an event is triggered by the filewatcher, a struct containing information will be given to channel as with ev/give. The contents of the channel depend on the OS, but will contain some common keys:

• :type -- the type of the event that was raised.

• :file-name -- the base file name of the file that triggered the event.

• :dir-name -- the directory name of the file that triggered the event.

Events also will contain keys specific to the host OS.

Windows has no extra properties on events.

Linux has the following extra properties on events:

• :wd -- the integer key returned by filewatch/add for the path that triggered this.

• :wd-path -- the string path for watched directory of file. For files, will be the same as :file-name, and for directories, will be the same as :dir-name.

• :cookie -- a randomized integer used to associate related events, such as :moved-from and :moved-to events.

(filewatch/remove watcher path)

Remove a path from the watcher.

(filewatch/unlisten watcher)

Stop listening for changes on a given watcher.

(filter pred ind)

Given a predicate, take only elements from an array or tuple for which (pred element) is truthy. Returns a new array.

(find pred ind &opt dflt)

Find the first value in an indexed collection that satisfies a predicate. Returns dflt if not found.

(find-index pred ind &opt dflt)

Find the index of indexed type for which pred is true. Returns dflt if not found.

(first xs)

Get the first element from an indexed data structure.

(flatten xs)

Takes a nested array (tree) xs and returns the depth first traversal of it. Returns a new array.

(flatten-into into xs)

Takes a nested array (tree) xs and appends the depth first traversal of xs to array into. Returns into.

(flush)

Flush (dyn :out stdout) if it is a file, otherwise do nothing.

(flycheck path &keys kwargs)

Check a file for errors without running the file. Found errors will be printed to stderr in the usual format. Macros will still be executed, however, so arbitrary execution is possible. Other arguments are the same as dofile. path can also be a file value such as stdin. Returns nil.

(for i start stop & body)

Do a C-style for-loop for side effects. Returns nil.

(forever & body)

Evaluate body forever in a loop, or until a break statement.

(forv i start stop & body)

Do a C-style for-loop for side effects. The iteration variable i can be mutated in the loop, unlike normal for. Returns nil.

(freeze x)

Freeze an object (make it immutable) and do a deep copy, making child values also immutable. Closures, fibers, and abstract types will not be recursively frozen, but all other types will.

(frequencies ind)

Get the number of occurrences of each value in an indexed data structure.

(from-pairs ps)

Takes a sequence of pairs and creates a table from each pair. It is the inverse of pairs on a table. Returns a new table.

(function? x)

Check if x is a function (not a cfunction).

(gccollect)

Run garbage collection. You should probably not call this manually.

(gcinterval)

Returns the integer number of bytes to allocate before running an iteration of garbage collection.

(gcsetinterval interval)

Set an integer number of bytes to allocate before running garbage collection. Low values for interval will be slower but use less memory. High values will be faster but use more memory.

(generate head & body)

Create a generator expression using the loop syntax. Returns a fiber that yields all values inside the loop in order. See loop for details.

(gensym)

Returns a new symbol that is unique across the runtime. This means it will not collide with any already created symbols during compilation, so it can be used in macros to generate automatic bindings.

(geomean xs)

Returns the geometric mean of xs. If empty, returns NaN.

(get ds key &opt dflt)

Get the value mapped to key in data structure ds, and return dflt or nil if not found. Similar to in, but will not throw an error if the key is invalid for the data structure unless the data structure is an abstract type. In that case, the abstract type getter may throw an error.

(get-in ds ks &opt dflt)

Access a value in a nested data structure. Looks into the data structure via a sequence of keys. If value is not found, and dflt is provided, returns dflt.

(getline &opt prompt buf env)

Reads a line of input into a buffer, including the newline character, using a prompt. An optional environment table can be provided for auto-complete. Returns the modified buffer. Use this function to implement a simple interface for a terminal program.

(getproto x)

Get the prototype of a table or struct. Will return nil if x has no prototype.

(group-by f ind)

Group elements of ind by a function f and put the results into a new table. The keys of the table are the distinct return values from calling f on the elements of ind. The values of the table are arrays of all elements of ind for which f called on the element equals that corresponding key.

(has-key? ds key)

Check if a data structure ds contains the key key.

(has-value? ds value)

Check if a data structure ds contains the value value. Will run in time proportional to the size of ds.

(hash value)

Gets a hash for any value. The hash is an integer can be used as a cheap hash function for all values. If two values are strictly equal, then they will have the same hash value.

(idempotent? x)

Check if x is a value that evaluates to itself when compiled.

(identity x)

A function that returns its argument.

(if-let bindings tru &opt fal)

Make multiple bindings, and if all are truthy, evaluate the tru form. If any are false or nil, evaluate the fal form. Bindings have the same syntax as the let macro.

(if-not condition then &opt else)

Shorthand for (if (not condition) else then).

(if-with [binding ctor dtor] truthy &opt falsey)

Similar to with, but if binding is false or nil, evaluates the falsey path. Otherwise, evaluates the truthy path. In both cases, ctor is bound to binding.

(import path & args)

Import a module. First requires the module, and then merges its symbols into the current environment, prepending a given prefix as needed. (use the :as or :prefix option to set a prefix). If no prefix is provided, use the name of the module as a prefix. One can also use ":export true" to re-export the imported symbols. If ":exit true" is given as an argument, any errors encountered at the top level in the module will cause (os/exit 1) to be called. Dynamic bindings will NOT be imported. Use :fresh to bypass the module cache. Use :only [foo bar baz] to only import select bindings into the current environment.

(import* path & args)

Function form of import. Same parameters, but the path and other symbol parameters should be strings instead.

(in ds key &opt dflt)

Get value in ds at key, works on associative data structures. Arrays, tuples, tables, structs, strings, symbols, and buffers are all associative and can be used. Arrays, tuples, strings, buffers, and symbols must use integer keys that are in bounds or an error is raised. Structs and tables can take any value as a key except nil and will return nil or dflt if not found.

(inc x)

Returns x + 1.

(index-of x ind &opt dflt)

Find the first key associated with a value x in a data structure, acting like a reverse lookup. Will not look at table prototypes. Returns dflt if not found.

(indexed? x)

Check if x is an array or tuple.

(int/s64 value)

Create a boxed signed 64 bit integer from a string value or a number.

(int/to-bytes value &opt endianness buffer)

Write the bytes of an int/s64 or int/u64 into a buffer. The buffer parameter specifies an existing buffer to write to, if unset a new buffer will be created. Returns the modified buffer. The endianness parameter indicates the byte order:

• nil (unset): system byte order
• :le: little-endian, least significant byte first
• :be: big-endian, most significant byte first

(int/to-number value)

Convert an int/u64 or int/s64 to a number. Fails if the number is out of range for an int64.

(int/u64 value)

Create a boxed unsigned 64 bit integer from a string value or a number.

(int? x)

Check if x can be exactly represented as a 32 bit signed two's complement integer.

(interleave & cols)

Returns an array of the first elements of each col, then the second elements, etc.

(interpose sep ind)

Returns a sequence of the elements of ind separated by sep. Returns a new array.

(invert ds)

Given an associative data structure ds, returns a new table where the keys of ds are the values, and the values are the keys. If multiple keys in ds are mapped to the same value, only one of those values will become a key in the returned table.

The build identifier of the running janet program.

The flag set of config options from janetconf.h which is used to check if native modules are compatible with the host program.

The version number of the running janet program.

(juxt & funs)

Macro form of juxt*. Same behavior but more efficient.

(juxt* & funs)

Returns the juxtaposition of functions. In other words, ((juxt* a b c) x) evaluates to [(a x) (b x) (c x)].

(keep pred ind & inds)

Given a predicate pred, return a new array containing the truthy results of applying pred to each element in the indexed collection ind. This is different from filter which returns an array of the original elements where the predicate is truthy.

(keep-syntax before after)

Creates a tuple with the tuple type and sourcemap of before but the elements of after. If either one of its arguments is not a tuple, returns after unmodified. Useful to preserve syntactic information when transforming an ast in macros.

(keep-syntax! before after)

Like keep-syntax, but if after is an array, it is coerced into a tuple. Useful to preserve syntactic information when transforming an ast in macros.

(keys x)

Get the keys of an associative data structure.

(keyword & xs)

Creates a keyword by concatenating the elements of xs together. If an element is not a byte sequence, it is converted to bytes via describe. Returns the new keyword.

(keyword/slice bytes &opt start end)

Same as string/slice, but returns a keyword.

(keyword? x)

Check if x is a keyword.

(kvs dict)

Takes a table or struct and returns and array of key value pairs like @[k v k v ...]. Returns a new array.

(label name & body)

Set a label point that is lexically scoped. name should be a symbol that will be bound to the label.

(last xs)

Get the last element from an indexed data structure.

(length ds)

Returns the length or count of a data structure in constant time as an integer. For structs and tables, returns the number of key-value pairs in the data structure.

(lengthable? x)

Check if x is a bytes, indexed, or dictionary.

(let bindings & body)

Create a scope and bind values to symbols. Each pair in bindings is assigned as if with def, and the body of the let form returns the last value.

(load-image image)

The inverse operation to make-image. Returns an environment.

A table used in combination with unmarshal to unmarshal byte sequences created by make-image, such that (load-image bytes) is the same as (unmarshal bytes load-image-dict).

(loop head & body)

A general purpose loop macro. This macro is similar to the Common Lisp loop macro, although intentionally much smaller in scope. The head of the loop should be a tuple that contains a sequence of either bindings or conditionals. A binding is a sequence of three values that define something to loop over. Bindings are written in the format:

        binding :verb object/expression

where binding is a binding as passed to def, :verb is one of a set of keywords, and object is any expression. Each subsequent binding creates a nested loop within the loop created by the previous binding.

The available verbs are:

• :iterate -- repeatedly evaluate and bind to the expression while it is truthy.

• :range -- loop over a range. The object should be a two-element tuple with a start and end value, and an optional positive step. The range is half open, [start, end).

• :range-to -- same as :range, but the range is inclusive [start, end].

• :down -- loop over a range, stepping downwards. The object should be a two-element tuple with a start and (exclusive) end value, and an optional (positive!) step size.

• :down-to -- same as :down, but the range is inclusive [start, end].

• :keys -- iterate over the keys in a data structure.

• :pairs -- iterate over the key-value pairs as tuples in a data structure.

• :in -- iterate over the values in a data structure or fiber.

loop also accepts conditionals to refine the looping further. Conditionals are of the form:

        :modifier argument

where :modifier is one of a set of keywords, and argument is keyword-dependent. :modifier can be one of:

• :while expression -- breaks from the current loop if expression is falsey.

• :until expression -- breaks from the current loop if expression is truthy.

• :let bindings -- defines bindings inside the current loop as passed to the let macro.

• :before form -- evaluates a form for a side effect before the next inner loop.

• :after form -- same as :before, but the side effect happens after the next inner loop.

• :repeat n -- repeats the next inner loop n times.

• :when condition -- only evaluates the current loop body when condition is truthy.

• :unless condition -- only evaluates the current loop body when condition is falsey.

The loop macro always evaluates to nil.

(macex x &opt on-binding)

Expand macros completely. on-binding is an optional callback for whenever a normal symbolic binding is encountered. This allows macros to easily see all bindings used by their arguments by calling macex on their contents. The binding itself is also replaced by the value returned by on-binding within the expanded macro.

(macex1 x &opt on-binding)

Expand macros in a form, but do not recursively expand macros. See macex docs for info on on-binding.

(maclintf level fmt & args)

When inside a macro, call this function to add a linter warning. Takes a fmt argument like string/format, which is used to format the message.

(make-env &opt parent)

Create a new environment table. The new environment will inherit bindings from the parent environment, but new bindings will not pollute the parent environment.

(make-image env)

Create an image from an environment returned by require. Returns the image source as a string.

A table used in combination with marshal to marshal code (images), such that (make-image x) is the same as (marshal x make-image-dict).

(map f ind & inds)

Map a function over every value in a data structure and return an array of the results.

(mapcat f ind & inds)

Map a function over every element in an array or tuple and use array/concat to concatenate the results.

(marshal x &opt reverse-lookup buffer no-cycles)

Marshal a value into a buffer and return the buffer. The buffer can then later be unmarshalled to reconstruct the initial value. Optionally, one can pass in a reverse lookup table to not marshal aliased values that are found in the table. Then a forward lookup table can be used to recover the original value when unmarshalling.

(match x & cases)

Pattern matching. Match an expression x against any number of cases. Each case is a pattern to match against, followed by an expression to evaluate to if that case is matched. Legal patterns are:

• symbol -- a pattern that is a symbol will match anything, binding x's value to that symbol.

• array or bracket tuple -- an array or bracket tuple will match only if all of its elements match the corresponding elements in x. Use & rest at the end of an array or bracketed tuple to bind all remaining values to rest.

• table or struct -- a table or struct will match if all values match with the corresponding values in x.

• tuple -- a tuple pattern will match if its first element matches, and the following elements are treated as predicates and are true.

• _ symbol -- the last special case is the _ symbol, which is a wildcard that will match any value without creating a binding.

While a symbol pattern will ordinarily match any value, the pattern (@ <sym>), where <sym> is any symbol, will attempt to match x against a value already bound to <sym>, rather than matching and rebinding it.

Any other value pattern will only match if it is equal to x. Quoting a pattern with ' will also treat the value as a literal value to match against.

The number representing negative infinity

(math/abs x)

Return the absolute value of x.

(math/acos x)

Returns the arccosine of x.

(math/acosh x)

Returns the hyperbolic arccosine of x.

(math/asin x)

Returns the arcsin of x.

(math/asinh x)

Returns the hyperbolic arcsine of x.

(math/atan x)

Returns the arctangent of x.

(math/atan2 y x)

Returns the arctangent of y/x. Works even when x is 0.

(math/atanh x)

Returns the hyperbolic arctangent of x.

(math/cbrt x)

Returns the cube root of x.

(math/ceil x)

Returns the smallest integer value number that is not less than x.

(math/cos x)

Returns the cosine of x.

(math/cosh x)

Returns the hyperbolic cosine of x.

The base of the natural log.

(math/erf x)

Returns the error function of x.

(math/erfc x)

Returns the complementary error function of x.

(math/exp x)

Returns e to the power of x.

(math/exp2 x)

Returns 2 to the power of x.

(math/expm1 x)

Returns e to the power of x minus 1.

(math/floor x)

Returns the largest integer value number that is not greater than x.

(math/frexp x)

Returns a tuple of (mantissa, exponent) from number.

(math/gamma x)

Returns gamma(x).

(math/gcd x y)

Returns the greatest common divisor between x and y.

(math/hypot a b)

Returns c from the equation c^2 = a^2 + b^2.

The number representing positive infinity

The maximum contiguous integer representable by a double (-(2^53))

The minimum contiguous integer representable by a double (2^53)

The maximum contiguous integer representable by a 32 bit signed integer

The minimum contiguous integer representable by a 32 bit signed integer

(math/lcm x y)

Returns the least common multiple of x and y.

(math/ldexp m e)

Creates a new number from a mantissa and an exponent.

(math/log x)

Returns the natural logarithm of x.

(math/log-gamma x)

Returns log-gamma(x).

(math/log10 x)

Returns the log base 10 of x.

(math/log1p x)

Returns (log base e of x) + 1 more accurately than (+ (math/log x) 1)

(math/log2 x)

Returns the log base 2 of x.

Not a number (IEEE-754 NaN)

(math/next x y)

Returns the next representable floating point value after x in the direction of y.

The value pi.

(math/pow a x)

Returns a to the power of x.

(math/random)

Returns a uniformly distributed random number between 0 and 1.

(math/rng &opt seed)

Creates a Pseudo-Random number generator, with an optional seed. The seed should be an unsigned 32 bit integer or a buffer. Do not use this for cryptography. Returns a core/rng abstract type.

(math/rng-buffer rng n &opt buf)

Get n random bytes and put them in a buffer. Creates a new buffer if no buffer is provided, otherwise appends to the given buffer. Returns the buffer.

(math/rng-int rng &opt max)

Extract a random integer in the range [0, max) for max > 0 from the RNG. If max is 0, return 0. If no max is given, the default is 2^31 - 1.

(math/rng-uniform rng)

Extract a random number in the range [0, 1) from the RNG.

(math/round x)

Returns the integer nearest to x.

(math/seedrandom seed)

Set the seed for the random number generator. seed should be an integer or a buffer.

(math/sin x)

Returns the sine of x.

(math/sinh x)

Returns the hyperbolic sine of x.

(math/sqrt x)

Returns the square root of x.

(math/tan x)

Returns the tangent of x.

(math/tanh x)

Returns the hyperbolic tangent of x.

(math/trunc x)

Returns the integer between x and 0 nearest to x.

(max & args)

Returns the numeric maximum of the arguments.

(max-of args)

Returns the numeric maximum of the argument sequence.

(mean xs)

Returns the mean of xs. If empty, returns NaN.

(memcmp a b &opt len offset-a offset-b)

Compare memory. Takes two byte sequences a and b, and return 0 if they have identical contents, a negative integer if a is less than b, and a positive integer if a is greater than b. Optionally take a length and offsets to compare slices of the bytes sequences.

(merge & colls)

Merges multiple tables/structs into one new table. If a key appears in more than one collection in colls, then later values replace any previous ones. Returns the new table.

(merge-into tab & colls)

Merges multiple tables/structs into table tab. If a key appears in more than one collection in colls, then later values replace any previous ones. Returns tab.

(merge-module target source &opt prefix export only)

Merge a module source into the target environment with a prefix, as with the import macro. This lets users emulate the behavior of import with a custom module table. If export is truthy, then merged functions are not marked as private. Returns the modified target environment. If a tuple or array only is passed, only merge keys in only.

(min & args)

Returns the numeric minimum of the arguments.

(min-of args)

Returns the numeric minimum of the argument sequence.

(mod & xs)

Returns the result of applying the modulo operator on the first value of xs with each remaining value. (mod x 0) is defined to be x.

(module/add-paths ext loader)

Add paths to module/paths for a given loader such that the generated paths behave like other module types, including relative imports and syspath imports. ext is the file extension to associate with this module type, including the dot. loader is the keyword name of a loader in module/loaders. Returns the modified module/paths.

A table, mapping loaded module identifiers to their environments.

(module/expand-path path template)

Expands a path template as found in module/paths for module/find. This takes in a path (the argument to require) and a template string, to expand the path to a path that can be used for importing files. The replacements are as follows:

• :all: -- the value of path verbatim.

• :@all: -- Same as :all:, but if path starts with the @ character, the first path segment is replaced with a dynamic binding (dyn <first path segment as keyword>).

• :cur: -- the directory portion, if any, of (dyn :current-file)

• :dir: -- the directory portion, if any, of the path argument

• :name: -- the name component of path, with extension if given

• :native: -- the extension used to load natives, .so or .dll

• :sys: -- the system path, or (dyn :syspath)

(module/find path)

Try to match a module or path name from the patterns in module/paths. Returns a tuple (fullpath kind) where the kind is one of :source, :native, or :image if the module is found, otherwise a tuple with nil followed by an error message.

A table of loading method names to loading functions. This table lets require and import load many different kinds of files as modules.

A table, mapping currently loading modules to true. Used to prevent circular dependencies.

The list of paths to look for modules, templated for module/expand-path. Each element is a two-element tuple, containing the path template and a keyword :source, :native, or :image indicating how require should load files found at these paths.

A tuple can also contain a third element, specifying a filter that prevents module/find from searching that path template if the filter doesn't match the input path. The filter can be a string or a predicate function, and is often a file extension, including the period.

(module/value module sym &opt private)

Given a module table, get the value bound to a symbol sym. If private is truthy, will also resolve private module symbols. If no binding is found, will return nil.

(nan? x)

Check if x is NaN.

(nat? x)

Check if x can be exactly represented as a non-negative 32 bit signed two's complement integer.

(native path &opt env)

Load a native module from the given path. The path must be an absolute or relative path on the file system, and is usually a .so file on Unix systems, and a .dll file on Windows. Returns an environment table that contains functions and other values from the native module.

(neg? x)

Check if x is less than 0.

(net/accept stream &opt timeout)

Get the next connection on a server stream. This would usually be called in a loop in a dedicated fiber. Takes an optional timeout in seconds, after which will raise an error. Returns a new duplex stream which represents a connection to the client.

(net/accept-loop stream handler)

Shorthand for running a server stream that will continuously accept new connections. Blocks the current fiber until the stream is closed, and will return the stream.

(net/address host port &opt type multi)

Look up the connection information for a given hostname, port, and connection type. Returns a handle that can be used to send datagrams over network without establishing a connection. On Posix platforms, you can use :unix for host to connect to a unix domain socket, where the name is given in the port argument. On Linux, abstract unix domain sockets are specified with a leading '@' character in port. If multi is truthy, will return all address that match in an array instead of just the first.

(net/address-unpack address)

Given an address returned by net/address, return a host, port pair. Unix domain sockets will have only the path in the returned tuple.

(net/chunk stream nbytes &opt buf timeout)

Same a net/read, but will wait for all n bytes to arrive rather than return early. Takes an optional timeout in seconds, after which will raise an error.

(net/close stream)

Alias for ev/close.

(net/connect host port &opt type bindhost bindport)

Open a connection to communicate with a server. Returns a duplex stream that can be used to communicate with the server. Type is an optional keyword to specify a connection type, either :stream or :datagram. The default is :stream. Bindhost is an optional string to select from what address to make the outgoing connection, with the default being the same as using the OS's preferred address.

(net/flush stream)

Make sure that a stream is not buffering any data. This temporarily disables Nagle's algorithm. Use this to make sure data is sent without delay. Returns stream.

(net/listen host port &opt type no-reuse)

Creates a server. Returns a new stream that is neither readable nor writeable. Use net/accept or net/accept-loop be to handle connections and start the server. The type parameter specifies the type of network connection, either a :stream (usually tcp), or :datagram (usually udp). If not specified, the default is :stream. The host and port arguments are the same as in net/address. The last boolean parameter no-reuse will disable the use of SO_REUSEADDR and SO_REUSEPORT when creating a server on some operating systems.

(net/localname stream)

Gets the local address and port in a tuple in that order.

(net/peername stream)

Gets the remote peer's address and port in a tuple in that order.

(net/read stream nbytes &opt buf timeout)

Read up to n bytes from a stream, suspending the current fiber until the bytes are available. n can also be the keyword :all to read into the buffer until end of stream. If less than n bytes are available (and more than 0), will push those bytes and return early. Takes an optional timeout in seconds, after which will raise an error. Returns a buffer with up to n more bytes in it, or raises an error if the read failed.

(net/recv-from stream nbytes buf &opt timeout)

Receives data from a server stream and puts it into a buffer. Returns the socket-address the packet came from. Takes an optional timeout in seconds, after which will raise an error.

(net/send-to stream dest data &opt timeout)

Writes a datagram to a server stream. dest is a the destination address of the packet. Takes an optional timeout in seconds, after which will raise an error. Returns stream.

(net/server host port &opt handler type no-reuse)

Start a server asynchronously with net/listen and net/accept-loop. Returns the new server stream.

(net/setsockopt stream option value)

set socket options.

supported options and associated value types:

• :so-broadcast boolean
• :so-reuseaddr boolean
• :so-keepalive boolean
• :ip-multicast-ttl number
• :ip-add-membership string
• :ip-drop-membership string
• :ipv6-join-group string
• :ipv6-leave-group string

(net/shutdown stream &opt mode)

Stop communication on this socket in a graceful manner, either in both directions or just reading/writing from the stream. The mode parameter controls which communication to stop on the socket.

• :wr is the default and prevents both reading new data from the socket and writing new data to the socket.
• :r disables reading new data from the socket.
• :w disable writing data to the socket.

Returns the original socket.

(net/write stream data &opt timeout)

Write data to a stream, suspending the current fiber until the write completes. Takes an optional timeout in seconds, after which will raise an error. Returns nil, or raises an error if the write failed.

(next ds &opt key)

Gets the next key in a data structure. Can be used to iterate through the keys of a data structure in an unspecified order. Keys are guaranteed to be seen only once per iteration if the data structure is not mutated during iteration. If key is nil, next returns the first key. If next returns nil, there are no more keys to iterate through.

(nil? x)

Check if x is nil.