Core API

(% dividend divisor)

Returns the remainder of dividend / divisor.

(% 10 3) # -> 1
(% -10 3) # -> -1
(% 10 -3) # -> 1
(% -10 -3) # -> -1
(% 1.4 1) # -> 0.4
(% -1.4 1) # -> -0.4
(% 1.4 1) # -> 0.4
(% -1.4 1) # -> -0.4
(% -1.4 0) # -> -nan
(% -1.4 0) # -> -nan

(%= x n)

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

(var x 10) # -> 10
(%= x 3) # -> 1
x # -> 1

(* & xs)

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

(*) # -> 1
(* 10) # -> 10
(* 10 20) # -> 200
(* 1 2 3 4 5 6 7) #-> 5040

# Can take product of array with splice, but 'product' is better
(* ;(range 1 20)) #-> 1.21645e+17
(product (range 1 20)) #-> 1.21645e+17

(*= x n)

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

(var x 100) # -> 100
x # -> 100
(*= x 10) # -> 1000
x # -> 1000

(+ & xs)

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

(+) # -> 0
(+ 10) # -> 10
(+ 1 2) # -> 3
(+ 1.4 -4.5) # -> -3.1
(+ 1 2 3 4 5 6 7 8 9 10) # -> 55

# Splice can be used to sum arrays, but 'sum' is better
(+ ;(range 101)) # -> 5050
(sum (range 101)) # -> 5050

# Janet can add types that support the :+ or :r+ method
(+ (int/s64 "10") 10) # -> <core/s64 20>

# Bad types give errors
(+ nil 10) # -> error: could not find method :+ for nil, or :r+ for 10

(++ x)

Increments the var x by 1.

(+= x n)

Increments the var x by n.

(var x 100) # -> 100
x # -> 100
(+= x 10) # -> 110
x # -> 110

(- & 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.

(-) # -> 0
(- 10) # -> -10
(- 1 2) # -> -1
(+ 1.4 -4.5) # -> 5.9

# Equivalent to (- first (+ ;rest))
(- 1 2 3 4 5 6 7 8 9 10) # -> -53

# Janet can subtract types that support the :- or :r- method
(- (int/s64 "10") 10) # -> <core/s64 0>

(-- x)

Decrements the var x by 1.

(-= x n)

Decrements the var x by n.

(var x 10) # -> 10
(-= x 20) # -> -10
x # -> -10

(-> 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.

(/) # -> 1
(/ 10) # -> 0.1
(/ 10 5) # -> 2
(/ 10 5 4) # -> 0.5
(/ 10 5 4 5) # -> 0.1

# More arguments is the same as repeated division.
(/ ;(range 1 20)) # -> 8.22064e-18

(/= x n)

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

(var x 10) # -> 10
(/= x 5) # -> 2
x # -> 2
(/= x 0.2) # -> 10
x # -> 10

(< & 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. Returns a new array.

(accumulate2 f ind)

The 2 argument version of accumulate that does not take an initialization value.

(all pred xs)

Returns true if all xs are truthy, otherwise the result of first falsey predicate value, (pred x).

(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.

(apply f & args)

Applies a function 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-like. Each element in this last argument is then also pushed as an argument to f. For example:

	(apply + 1000 (range 10))

sums the first 10 integers and 1000.

(apply + (range 10)) # -> 45
(apply + []) # -> 0
(apply + 1 2 3 4 5 6 7 [8 9 10]) # -> 55
(apply + 1 2 3 4 5 6 7 8 9 10) # -> error: expected array|tuple, got number 

# Can also be used to call macros like functions.
# Will return the macro expanded code of the original macro.
(apply for 'x 0 10 ['(print x)])
# -> (do (var _000000 0) (def _000001 10) (while ...

(array & items)

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

(array/concat arr & parts)

Concatenates a variadic number of arrays (and tuples) into the first argument which must 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 of xs into array arr at index at. at should be an integer 0 and the length of the array. A negative value for at will index from the end of the array, such that inserting at -1 appends to the array. Returns the array.

(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.

(def arr (array/new 100)) # -> @[]

# Now we can fill up the array without triggering a resize
(for i 0 100
  (put arr i i))

(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 x)

Insert an element in 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 end of the array. By default, start is 0 and end is the length of the array. Note that index -1 is synonymous with index (length arrtup) to allow a full negative slice range. Returns a new array.

(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 for is the value x. Returns the last value.

(as?-> x as & forms)

Thread forms together, replacing as in forms with the value of the previous form. The first for 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. Will throw an
error on invalid assembly.

(assert x &opt err)

Throw an error if x is not truthy.

(bad-compile msg macrof where)

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 new buffer by concatenating values together. Values are converted to bytes via describe if they are not byte sequences. 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 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/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-byte buffer x)

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

(buffer/push-string buffer str)

Push a string onto the end of a buffer. Non string values will be converted to strings before being pushed. Returns the modified buffer. Will throw an error if the buffer overflows.

(buffer/push-word buffer x)

Append a machine word to a buffer. The 4 bytes of the integer are appended in twos complement, little endian order, unsigned. 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? x)

Check if x is a buffer.

(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, or buffer.

(case dispatch & pairs)

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

(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 functions with the command line arguments as an array or tuple of strings to invoke the CLI interface.

(comment &)

Ignores the body of the comment.

(comp & functions)

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

(compile ast &opt env source)

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.

(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.

(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, the last expression is executed if no forms are matched. If there are no matches, return nil.

(coro & body)

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

(count pred ind)

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

(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 byte-offset)

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

	(debug/break "core.janet" 1000)

wil set a breakpoint at the 1000th byte 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
	:column - the current source column of the stack frame
	:function - the function that the stack frame represents
	: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 err)

Prints a nice looking stacktrace for a fiber. The error message err must be passed to the function as fiber's do not keep track of the last error they have thrown. 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.

An environment that contains dot prefixed functions for debugging.

(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.

# In a file module.janet
(def- private-thing :encapsulated)
(def public-thing :exposed)

# In a file main.janet
(import module)

module/private-thing # -> Unknown symbol
module/public-thing # -> :exposed

# Same as normal def with :private metadata
(def :private x private-thing :encapsulated)

(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.

(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.

# Evaluates to 6 after printing "scope left!"
(defer (print "scope left!")
  (+ 1 2 3))

# cleanup will always be called, even if there is a failure
(defer (cleanup)
  (step-1)
  (step-2)
  (if (< 0.1 (math/random)) (error "failure"))
  (step-3))

(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 simple
  [x]
  (print (+ x 1)))

(simple 10) # -> 11

(defn long-body
  [y]
  (print y)
  (print (+ y 1))
  (print (+ y 2))
  (+ y 3))

(defn with-docstring
  "This function has a docstring"
  []
  (print "hello!"))

(defn with-tags
  :tag1 :tag2 :private
  "Also has a docstring and a variadic argument 'more'!"
  [x y z & more]
  [x y z more])

(with-metadata 1 2) # raises arity error
(with-metadata 1 2 3) # -> (1 2 3 ())
(with-metadata 1 2 3 4) # -> (1 2 3 (4))
(with-metadata 1 2 3 4 5) # -> (1 2 3 (4 5))

# Tags (and other metadata) are (usually) visible in the environment.
(dyn 'with-tags) # -> @{:tag2 true :value <function with-tags> :doc "(with-tags x y z & more)\n\nAlso has a docstring..." :source-map ("repl" 4 1) :tag1 true :private true}

(defn- name & more)

Define a private function that will not be exported.

# In a file module.janet
(defn- not-exposed-fn
  [x]
  (+ x x))
(not-exposed-fn 10) # -> 20

# In a file main.janet
(import module)

(module/not-exposed-fn 10) # -> Unknown symbol error

# Same as
(defn not-exposed-fn
  :private
  [x]
  (+ x x))

(describe x)

Returns a string that is a human readable description of a value x.

(dictionary? x)

Check if x a table or struct.

(disasm func)

Returns assembly that could be used be compile the given function.
func must be a function, not a c function. Will throw on error on a badly
typed argument.

(distinct xs)

Returns an array of the deduplicated values in xs.

(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 with that prefix (all bindings will be shown if no prefix is given).

(doc* &opt sym)

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

(doc-format text &opt width)

Reformat text to wrap at a given line.

(dofile path &keys {:expander expander :env env :exit exit :source src :evaluator evaluator})

Evaluate a file and return the resulting environment. :env, :expander, and :evaluator 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 first n elements in an indexed type. Returns new indexed instance.

(drop-until pred ind)

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

(drop-while pred ind)

Given a predicate, remove elements from an indexed type that satisfy the predicate, and abort on first failure. Returns a new array.

(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.

# Half of the time, return "ok", the other
# half of the time, print there was an error and throw "oops".
(edefer (print "there was an error")
  (if (< (math/random) 0.5)
    (error "oops")
    "ok"))

(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))

(eval form)

Evaluates a form in the current environment. If more control over the environment is needed, use run-context.

(eval '(+ 1 2 3)) # -> 6
(eval '(error :oops)) # -> raises error :oops
(eval '(+ nil nil)) # -> raises error

(eval-string str)

Evaluates a string in the current environment. If more control over the environment is needed, use run-context.

(eval-string "(+ 1 2 3 4)") # -> 10
(eval-string ")") # -> parse error
(eval-string "(bloop)") # -> compile error
(eval-string "(+ nil nil)") # -> runtime error

(even? x)

Check if x is even.

(every? ind)

Returns true if each value in is truthy, otherwise the first falsey value.

(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.

(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/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)

Create a new fiber with function body func. Can optionally take a set of signals to block from the current parent fiber when called. The mask is specified as a keyword where each character is used to indicate a signal to block. 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
	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-9) - the fiber is suspended by a user signal
	: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. If the file is the result of a file/popen call, close waits for and returns the process exit status.

(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/open path &opt mode)

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
	b - open the file in binary mode (rather than text mode)
	+ - append to the file instead of overwriting it

(file/popen path &opt mode)

Open a file that is backed by a process. The file must be opened in either the :r (read) or the :w (write) mode. In :r mode, the stdout of the process can be read from the file. In :w mode, the stdin of the process can be written to. Returns the new file.

(file/read f what &opt buf)

Read a number of bytes from a file into a buffer. A buffer can be provided as an optional fourth 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. '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 the 4GB. Returns the file handle.

(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.

(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)

Find the first value in an indexed collection that satisfies a predicate. Returns nil if not found. Note there is no way to differentiate a nil from the indexed collection and a not found. Consider find-index if this is an issue.

(find-index pred ind)

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

(first xs)

Get the first element from an indexed data structure.

(flatten xs)

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

(flatten-into into xs)

Takes a nested array (tree), and appends the depth first traversal of that array to an array 'into'. Returns array into.

(flush)

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

(for i start stop & body)

Do a c style for loop for side effects. 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 a indexed structure.

(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.

# An infinite stream of random numbers, but doubled.
(def g (generate [_ :iterate true :repeat 2] (math/random)))
# -> <fiber 0x5562863141E0>

(resume g) # -> 0.487181
(resume g) # -> 0.487181
(resume g) # -> 0.507917
(resume g) # -> 0.507917
# ...

(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.

(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.

(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.

(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 first 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.

(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.

(indexed? x)

Check if x is an array or tuple.

(int/s64 value)

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

(int/u64 value)

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

(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, etc.

(interpose sep ind)

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

(invert ds)

Returns a table of where the keys of an associative data structure are the values, and the values of the keys. If multiple keys have the same value, one key will be ignored.

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)

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

(keys x)

Get the keys of an associative data structure.

(keyword & xs)

Creates a keyword by concatenating values together. Values are converted to bytes via describe if they are not byte sequences. Returns the new 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.

(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. They are formatted like:

 	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. 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 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 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 keys value pairs as tuples in a data structure.
  	:in - iterate over the values in a data structure.
  	:generate - iterate over values yielded from a fiber. Can be paired with the generator  function for the producer/consumer pattern.

  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 loop if expression is falsey.
  	:until expression - breaks from the loop if expression is truthy.
  	:let bindings - defines bindings inside the loop as passed to the let macro.
  	:before form - evaluates a form for a side effect before of 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 loop body when condition is true.

  The loop macro always evaluates to nil.

# -> prints 0123456789 (not followed by newline)
(loop [x :range [0 10]]
  (prin x))

# Cartesian product (nested loops)

# -> prints 00010203101112132021222330313233
# Same as (for x 0 4 (for y 0 4 (prin x y)))
(loop [x :range [0 4]
       y :range [0 4]]
  (prin x y))

# -> prints bytes of "hello, world" as numbers
(loop [character :in "hello, world"]
  (print character))

# -> prints 1, 2, and 3, in an unspecified order
(loop [value :in {:a 1 :b 2 :c 3}]
  (print value))

# -> prints 0 to 99 inclusive
(loop [x :in (range 100)]
  (print x))

# Complex body
(loop [x :in (range 10)]
  (print x)
  (print (inc c))
  (print (+ x 2)))

# Iterate over keys
(loop [k :keys {:a 1 :b 2 :c 3}]
  (print k))
# print a, b, and c in an unspecified order

(loop [index :keys [:a :b :c :d]]
  (print index))
#  print 0, 1, 2, and 3 in order.

(defn print-pairs
  [x]
  (loop [[k v] :pairs x]
    (printf "[%v]=%v" k v)))

(print-pairs [:a :b :c])
# [0]=:a
# [1]=:b
# [2]=:c

(print-pairs {:a 1 :b 2 :c 3})
# [:a]=1
# [:b]=2
# [:c]=3

# Some modifiers - allow early termination and conditional execution
# of the loop

(loop [x :range [0 100] :when (even? x)]
  (print x))
# prints even numbers 0, 2, 4, ..., 98

(loop [x :range [1 100] :while (pos? (% x 7))]
  (print x))
# prints 1, 2, 3, 4, 5, 6

# Consume fibers as generators
(def f
  (fiber/new
    (fn []
      (for i 0 100
        (yield i)))))

(loop [x :generate f]
  (print x))
# print 0, 1, 2, ... 99

# Modifiers in nested loops

(loop [x :range [0 10]
      :after (print)
       y :range [0 x]]
  (prin y " "))
# 0
# 0 1
# 0 1 2
# 0 1 2 3
# 0 1 2 3 4
# 0 1 2 3 4 5
# 0 1 2 3 4 5 6
# 0 1 2 3 4 5 6 7
# 0 1 2 3 4 5 6 7 8

(macex x &opt on-binding)

Expand macros completely. on-binding is an optional callback whenever a normal symbolic binding is encounter. This allows macros to easily see all bindings use by their arguments by calling macex on their contents. The binding itself is also replaced by the value returned by on-binding within the expand 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.

(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 & inds)

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

(mapcat f ind)

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

(marshal x &opt reverse-lookup buffer)

Marshal a value into a buffer and return the buffer. The buffer can the 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 forwardlookup 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. A pattern that is a symbol will match anything, binding x's value to that symbol. An array will match only if all of it's elements match the corresponding elements in x. A table or struct will match if all values match with the corresponding values in x. A tuple pattern will match if it's first element matches, and the following elements are treated as predicates and are true. The last special case is the '_ symbol, which is a wildcard that will match any value without creating a binding. Any other value pattern will only match if it is equal to x.

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)

Return the hyperbolic arccosine of x.

(math/asin x)

Returns the arcsine of x.

(math/asinh x)

Return the hyperbolic arcsine of x.

(math/atan x)

Returns the arctangent of x.

(math/atan2 y x)

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

(math/atanh x)

Return 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)

Return 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/gamma x)

Returns gamma(x).

(math/hypot a b)

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

The number representing positive infinity

(math/log x)

Returns log base natural number of x.

(math/log10 x)

Returns 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 log base 2 of x.

(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)

Return a to the power of x.

(math/random)

Returns a uniformly distributed random number between 0 and 1.

(math/rng &opt seed)

Creates a Psuedo-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 random integer in the range [0, max] from the RNG. If no max is given, the default is 2^31 - 1.

(math/rng-seed rng seed)

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)

Return 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)

Return 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.

(mean xs)

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

(merge & colls)

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

(merge-into tab & colls)

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

(min & args)

Returns the numeric minimum of the arguments.

(mod dividend divisor)

Returns the modulo of dividend / divisor.

(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 that is module/loaders. Returns the modified module/paths.

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, template, 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
	:cur:	the current file, or (dyn :current-file)
	:dir:	the directory containing the current file
	: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 module.

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.

(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/chunk stream nbytes &opt buf)

Same a net/read, but will wait for all n bytes to arrive rather than return early.

(net/close stream)

Close a stream so that no further communication can occur.

(net/connect host port)

Open a connection to communicate with a server. Returns a duplex stream that can be used to communicate with the server.

(net/read stream nbytes &opt buf)

Read up to n bytes from a stream, suspending the current fiber until the bytes are available. If less than n bytes are available (and more than 0), will push those bytes and return early. Returns a buffer with up to n more bytes in it.

(net/server host port handler)

Start a TCP server. handler is a function that will be called with a stream on each connection to the server. Returns a new stream that is neither readable nor writeable.

(net/write stream data)

Write data to a stream, suspending the current fiber until the write completes. Returns stream.

(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 they 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.

(not x)

Returns the boolean inverse of x.

(not= & xs)

Check if any values in xs are not equal. Returns a boolean.

(number? x)

Check if x is a number.

(odd? x)

Check if x is odd.

(one? x)

Check if x is equal to 1.

(or & forms)

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

(os/arch)

Check the ISA that janet was compiled for. Returns one of:

	:x86
	:x86-64
	:arm
	:aarch64
	:sparc
	:wasm
	:unknown

(os/cd path)

Change current directory to path. Returns nil on success, errors on failure.

(os/chmod path mode)

Change file permissions, where mode is a permission string as returned by os/perm-string, or an integer as returned by os/perm-int. When mode is an integer, it is interpreted as a Unix permission value, best specified in octal, like 8r666 or 8r400. Windows will not differentiate between user, group, and other permissions, and thus will combine all of these permissions. Returns nil.

(os/clock)

Return the number of seconds since some fixed point in time. The clock is guaranteed to be non decreasing in real time.

(os/cryptorand n &opt buf)

Get or append n bytes of good quality random data provided by the OS. Returns a new buffer or buf.

(os/cwd)

Returns the current working directory.

(os/date &opt time local)

Returns the given time as a date struct, or the current time if no time is given. Returns a struct with following key values. Note that all numbers are 0-indexed. Date is given in UTC unless local is truthy, in which case the date is formatted for the local timezone.

	:seconds - number of seconds [0-61]
	:minutes - number of minutes [0-59]
	:hours - number of hours [0-23]
	:month-day - day of month [0-30]
	:month - month of year [0, 11]
	:year - years since year 0 (e.g. 2019)
	:week-day - day of the week [0-6]
	:year-day - day of the year [0-365]
	:dst - If Day Light Savings is in effect

(os/dir dir &opt array)

Iterate over files and subdirectories in a directory. Returns an array of paths parts, with only the file name or directory name and no prefix.

(os/environ)

Get a copy of the os environment table.

(os/execute args &opts flags env)

Execute a program on the system and pass it string arguments. Flags is a keyword that modifies how the program will execute.

	:e - enables passing an environment to the program. Without :e, the current environment is inherited.
	:p - allows searching the current PATH for the binary to execute. Without this flag, binaries must use absolute paths.

env is a table or struct mapping environment variables to values. Returns the exit status of the program.

(os/exit &opt x)

Exit from janet with an exit code equal to x. If x is not an integer, the exit with status equal the hash of x.

(os/getenv variable &opt dflt)

Get the string value of an environment variable.

(os/link oldpath newpath &opt symlink)

Create a link at newpath that points to oldpath and returns nil. Iff symlink is truthy, creates a symlink. Iff symlink is falsey or not provided, creates a hard link. Does not work on Windows.

(os/lstat path &opt tab|key)

Like os/stat, but don't follow symlinks.

(os/mkdir path)

Create a new directory. The path will be relative to the current directory if relative, otherwise it will be an absolute path. Returns true if the directory was created, false if the directory already exists, and errors otherwise.

(os/mktime date-struct &opt local)

Get the broken down date-struct time expressed as the number of seconds since January 1, 1970, the Unix epoch. Returns a real number. Date is given in UTC unless local is truthy, in which case the date is computed for the local timezone.

Inverse function to os/date.

(os/perm-int bytes)

Parse a 9 character permission string and return an integer that can be used by chmod.

(os/perm-string int)

Convert a Unix octal permission value from a permission integer as returned by os/stat to a human readable string, that follows the formatting of unix tools like ls. Returns the string as a 9 character string of r, w, x and - characters. Does not include the file/directory/symlink character as rendered by `ls`.

(os/readlink path)

Read the contents of a symbolic link. Does not work on Windows.

(os/realpath path)

Get the absolute path for a given path, following ../, ./, and symlinks. Returns an absolute path as a string. Will raise an error on Windows.

(os/rename oldname newname)

Rename a file on disk to a new path. Returns nil.

(os/rm path)

Delete a file. Returns nil.

(os/rmdir path)

Delete a directory. The directory must be empty to succeed.

(os/setenv variable value)

Set an environment variable.

(os/shell str)

Pass a command string str directly to the system shell.

(os/sleep nsec)

Suspend the program for nsec seconds. 'nsec' can be a real number. Returns nil.

(os/stat path &opt tab|key)

Gets information about a file or directory. Returns a table If the third argument is a keyword, returns only that information from stat. If the file or directory does not exist, returns nil. The keys are

	:dev - the device that the file is on
	:mode - the type of file, one of :file, :directory, :block, :character, :fifo, :socket, :link, or :other
	:int-permissions - A Unix permission integer like 8r744
	:permissions - A Unix permission string like "rwxr--r--"
	:uid - File uid
	:gid - File gid
	:nlink - number of links to file
	:rdev - Real device of file. 0 on windows.
	:size - size of file in bytes
	:blocks - number of blocks in file. 0 on windows
	:blocksize - size of blocks in file. 0 on windows
	:accessed - timestamp when file last accessed
	:changed - timestamp when file last changed (permissions changed)
	:modified - timestamp when file last modified (content changed)

(os/symlink oldpath newpath)

Create a symlink from oldpath to newpath, returning nil. Same as (os/link oldpath newpath true).

(os/time)

Get the current time expressed as the number of seconds since January 1, 1970, the Unix epoch. Returns a real number.

(os/touch path &opt actime modtime)

Update the access time and modification times for a file. By default, sets times to the current time.

(os/umask mask)

Set a new umask, returns the old umask.

(os/which)

Check the current operating system. Returns one of:

	:windows
	:macos
	:web - Web assembly (emscripten)
	:linux
	:freebsd
	:openbsd
	:netbsd
	:posix - A POSIX compatible system (default)

May also return a custom keyword specified at build time.

(pairs x)

Get the values of an associative data structure.

(parse str)

Parse a string and return the first value. For complex parsing, such as for a repl with error handling, use the parser api.

(parser/byte parser b)

Input a single byte into the parser byte stream. Returns the parser.

(parser/clone p)

Creates a deep clone of a parser that is identical to the input parser. This cloned parser can be used to continue parsing from a good checkpoint if parsing later fails. Returns a new parser.

(parser/consume parser bytes &opt index)

Input bytes into the parser and parse them. Will not throw errors if there is a parse error. Starts at the byte index given by index. Returns the number of bytes read.

(parser/eof parser)

Indicate that the end of file was reached to the parser. This puts the parser in the :dead state.

(parser/error parser)

If the parser is in the error state, returns the message associated with that error. Otherwise, returns nil. Also flushes the parser state and parser queue, so be sure to handle everything in the queue before calling parser/error.

(parser/flush parser)

Clears the parser state and parse queue. Can be used to reset the parser if an error was encountered. Does not reset the line and column counter, so to begin parsing in a new context, create a new parser.

(parser/has-more parser)

Check if the parser has more values in the value queue.

(parser/insert parser value)

Insert a value into the parser. This means that the parser state can be manipulated in between chunks of bytes. This would allow a user to add extra elements to arrays and tuples, for example. Returns the parser.

(parser/new)

Creates and returns a new parser object. Parsers are state machines that can receive bytes, and generate a stream of values.

(parser/produce parser)

Dequeue the next value in the parse queue. Will return nil if no parsed values are in the queue, otherwise will dequeue the next value.

(parser/state parser &opt key)

Returns a representation of the internal state of the parser. If a key is passed, only that information about the state is returned. Allowed keys are:

	:delimiters - Each byte in the string represents a nested data structure. For example, if the parser state is '(["', then the parser is in the middle of parsing a string inside of square brackets inside parentheses. Can be used to augment a REPL prompt.	:frames - Each table in the array represents a 'frame' in the parser state. Frames contain information about the start of the expression being parsed as well as the type of that expression and some type-specific information.

(parser/status parser)

Gets the current status of the parser state machine. The status will be one of:

	:pending - a value is being parsed.
	:error - a parsing error was encountered.
	:root - the parser can either read more values or safely terminate.

(parser/where parser)

Returns the current line number and column of the parser's internal state.

(partial f & more)

Partial function application.

(partition n ind)

Partition an indexed data structure into tuples of size n. Returns a new array.

(peg/compile peg)

Compiles a peg source data structure into a <core/peg>. This will speed up matching if the same peg will be used multiple times.

(peg/match peg text &opt start & args)

Match a Parsing Expression Grammar to a byte string and return an array of captured values. Returns nil if text does not match the language defined by peg. The syntax of PEGs is documented on the Janet website.

(pos? x)

Check if x is greater than 0.

(postwalk f form)

Do a post-order traversal of a data structure and call (f x) on every visitation.

(pp x)

Pretty print to stdout or (dyn :out). The format string used is (dyn :pretty-format "%q").

(prewalk f form)

Similar to postwalk, but do pre-order traversal.

(prin & xs)

Same as print, but does not add trailing newline.

(prinf fmt & xs)

Like printf but with no trailing newline.

(print & xs)

Print values to the console (standard out). Value are converted to strings if they are not already. After printing all values, a newline character is printed. Use the value of (dyn :out stdout) to determine what to push characters to. Expects (dyn :out stdout) to be either a core/file or a buffer. Returns nil.

(printf fmt & xs)

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

(product xs)

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

(product []) # -> 1
(product @[1 2 3]) # -> 6
(product [0 1 2 3]) # -> 0
(product (range 1 10)) # -> 362880

# Product over byte values [0-255] in a string
(product "hello") # -> 1.35996e+10

# Product over values in a table or struct
(sum {:a 1 :b 2 :c 4}) # -> 8

(prompt tag & body)

Set up a checkpoint that can be returned to. Tag should be a value that is used in a return statement, like a keyword.

(propagate x fiber)

Propagate a signal from a fiber to the current fiber. The resulting stack trace from the current fiber will include frames from fiber. If fiber is in a state that can be resumed, resuming the current fiber will first resume fiber. This function can be used to re-raise an error without losing the original stack trace.

(protect & body)

Evaluate expressions, while capturing any errors. Evaluates to a tuple of two elements. The first element is true if successful, false if an error, and the second is the return value or error.

(put ds key value)

Associate a key with a value in any mutable associative data structure. Indexed data structures (arrays and buffers) only accept non-negative integer keys, and will expand if an out of bounds value is provided. In an array, extra space will be filled with nils, and in a buffer, extra space will be filled with 0 bytes. In a table, putting a key that is contained in the table prototype will hide the association defined by the prototype, but will not mutate the prototype table. Putting a value nil into a table will remove the key from the table. Returns the data structure ds.

(put-in ds ks v)

Put a value into a nested data structure. Looks into the data structure via a sequence of keys. Missing data structures will be replaced with tables. Returns the modified, original data structure.

(quit &opt value)

Tries to exit from the current repl or context. Does not always exit the application. Works by setting the :exit dynamic binding to true. Passing a non-nil value here will cause the outer run-context to return that value.

(range & args)

Create an array of values [start, end) with a given step. With one argument returns a range [0, end). With two arguments, returns a range [start, end). With three, returns a range with optional step size.

(range 10) # -> @[0 1 2 3 4  6 7 8 9]
(range 5 10) # -> @[5 6 7 8 9]
(range 5 10 2) # -> @[5 7 9]
(range 5 11 2) # -> @[5 7 9]
(range 10 0 -1) # -> @[10 9 8 7 6 5 4 3 2 1]

(reduce f init ind)

Reduce, also know as fold-left in many languages, transforms an indexed type (array, tuple) with a function to produce a value.

(reduce2 f ind)

The 2 argument version of reduce that does not take an initialization value. Instead the first element of the array is used for initialization.

(repl &opt chunks onsignal env)

Run a repl. The first parameter is an optional function to call to get a chunk of source code that should return nil for end of file. The second parameter is a function that is called when a signal is caught. One can provide an optional environment table to run the repl in.

(require path & args)

Require a module with the given name. Will search all of the paths in module/paths. Returns the new environment returned from compiling and running the file.

(resume fiber &opt x)

Resume a new or suspended fiber and optionally pass in a value to the fiber that will be returned to the last yield in the case of a pending fiber, or the argument to the dispatch function in the case of a new fiber. Returns either the return result of the fiber's dispatch function, or the value from the next yield call in fiber.

(return to &opt value)

Return to a prompt point.

(reverse t)

Reverses the order of the elements in a given array or tuple and returns a new array.

(reverse [1 2 3]) # -> @[3 2 1]
(reverse "abcdef") # -> @[102 101 100 99 98 97]
(reverse :abc) # -> @[99 98 97]

The root environment used to create environments with (make-env)

(run-context opts)

Run a context. This evaluates expressions in an environment, and is encapsulates the parsing, compilation, and evaluation. Returns (in environment :exit-value environment) when complete. opts is a table or struct of options. The options are as follows:

	 :chunks - callback to read into a buffer - default is getline
	 :on-parse-error - callback when parsing fails - default is bad-parse
	 :env - the environment to compile against - default is the current env
	 :source - string path of source for better errors - default is "<anonymous>"
	 :on-compile-error - callback when compilation fails - default is bad-compile
	 :evaluator - callback that executes thunks. Signature is (evaluator thunk source env where)
	 :on-status - callback when a value is evaluated - default is debug/stacktrace
	  :fiber-flags - what flags to wrap the compilation fiber with. Default is :ia.
	  :expander - an optional function that is called on each top level form before being compiled.

(scan-number str)

Parse a number from a byte sequence an return that number, either and integer or a real. The number must be in the same format as numbers in janet source code. Will return nil on an invalid number.

(seq head & body)

Similar to loop, but accumulates the loop body into an array and returns that. See loop for details.

(seq [x :range [0 5]] (* 2 x)) # -> @[0 2 4 6 8]

(setdyn key value)

Set a dynamic binding. Returns value.

(short-fn arg)

fn shorthand.

 usage:

 	(short-fn (+ $ $)) - A function that double's its arguments.
 	(short-fn (string $0 $1)) - accepting multiple args
 	|(+ $ $) - use pipe reader macro for terse function literals
 	|(+ $&) - variadic functions

(signal what x)

Raise a signal with payload x. 

(slice x &opt start end)

Extract a sub-range of an indexed data structure or byte sequence.

(slice @[1 2 3]) # -> (1 2 3) (a new array!)
(slice @[:a :b :c] 1) # -> (:b :c)
(slice [:a :b :c :d :e] 2 4) # -> (:c :d)
(slice [:a :b :d :d :e] 2 -1) # -> (:c :d :e)
(slice [:a :b :d :d :e] 2 -2) # -> (:c :d)
(slice [:a :b :d :d :e] 2 -4) # -> ()
(slice [:a :b :d :d :e] 2 -10) # -> error: range error
(slice "abcdefg" 0 2) # -> "ab"
(slice @"abcdefg" 0 2) # -> "ab"

(slurp path)

Read all data from a file with name path and then close the file.

(some pred xs)

Returns nil if all xs are false or nil, otherwise returns the result of the first truthy predicate, (pred x).

(sort a &opt by)

Sort an array in-place. Uses quick-sort and is not a stable sort.

(sort-by f ind)

Returns a new sorted array that compares elements by invoking a function on each element and comparing the result with <.

(sorted ind &opt by)

Returns a new sorted array without modifying the old one.

(sorted-by f ind)

Returns a new sorted array that compares elements by invoking a function on each element and comparing the result with <.

(spit path contents &opt mode)

Write contents to a file at path. Can optionally append to the file.

The standard error file.

The standard input file.

The standard output file.

(string & parts)

Creates a string by concatenating values together. Values are converted to bytes via describe if they are not byte sequences. Returns the new string.

(string/ascii-lower str)

Returns a new string where all bytes are replaced with the lowercase version of themselves in ASCII. Does only a very simple case check, meaning no unicode support.

(string/ascii-upper str)

Returns a new string where all bytes are replaced with the uppercase version of themselves in ASCII. Does only a very simple case check, meaning no unicode support.

(string/bytes str)

Returns an array of integers that are the byte values of the string.

(string/check-set set str)

Checks that the string str only contains bytes that appear in the string set. Returns true if all bytes in str appear in set, false if some bytes in str do not appear in set.

(string/find patt str)

Searches for the first instance of pattern patt in string str. Returns the index of the first character in patt if found, otherwise returns nil.

(string/find-all patt str)

Searches for all instances of pattern patt in string str. Returns an array of all indices of found patterns. Overlapping instances of the pattern are not counted, meaning a byte in string will only contribute to finding at most on occurrence of pattern. If no occurrences are found, will return an empty array.

(string/format format & values)

Similar to snprintf, but specialized for operating with Janet values. Returns a new string.

(string/from-bytes & byte-vals)

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

(string/has-prefix? pfx str)

Tests whether str starts with pfx.

(string/has-suffix? sfx str)

Tests whether str ends with sfx.

(string/join parts &opt sep)

Joins an array of strings into one string, optionally separated by a separator string sep.

(string/repeat bytes n)

Returns a string that is n copies of bytes concatenated.

(string/replace patt subst str)

Replace the first occurrence of patt with subst in the string str. Will return the new string if patt is found, otherwise returns str.

(string/replace-all patt subst str)

Replace all instances of patt with subst in the string str. Will return the new string if patt is found, otherwise returns str.

(string/reverse str)

Returns a string that is the reversed version of str.

(string/slice bytes &opt start end)

Returns a substring from a byte sequence. The substring is from index start inclusive to index end exclusive. All indexing is from 0. 'start' and 'end' can also be negative to indicate indexing from the end of the string. Note that index -1 is synonymous with index (length bytes) to allow a full negative slice range. 

(string/split delim str &opt start limit)

Splits a string str with delimiter delim and returns an array of substrings. The substrings will not contain the delimiter delim. If delim is not found, the returned array will have one element. Will start searching for delim at the index start (if provided), and return up to a maximum of limit results (if provided).

(string/trim str &opt set)

Trim leading and trailing whitespace from a byte sequence. If the argument set is provided, consider only characters in set to be whitespace.

(string/triml str &opt set)

Trim leading whitespace from a byte sequence. If the argument set is provided, consider only characters in set to be whitespace.

(string/trimr str &opt set)

Trim trailing whitespace from a byte sequence. If the argument set is provided, consider only characters in set to be whitespace.

(string? x)

Check if x is a string.

(struct & kvs)

Create a new struct from a sequence of key value pairs. kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has an odd number of elements, an error will be thrown. Returns the new struct.

(struct? x)

Check if x a struct.

(sum xs)

Returns the sum of xs. If xs is empty, returns 0.

(sum []) # -> 0
(sum @[1]) # -> 1
(sum (range 100)) # -> 4950

# Sum over bytes values [0-255] in a string
(sum "hello") # -> 532

# Sum over values in a table or struct
(sum {:a 1 :b 2 :c 4}) # -> 7

(symbol & xs)

Creates a symbol by concatenating values together. Values are converted to bytes via describe if they are not byte sequences. Returns the new symbol.

(symbol? x)

Check if x is a symbol.

(table & kvs)

Creates a new table from a variadic number of keys and values. kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has an odd number of elements, an error will be thrown. Returns the new table.

(table/clone tab)

Create a copy of a table. Updates to the new table will not change the old table, and vice versa.

(table/getproto tab)

Get the prototype table of a table. Returns nil if a table has no prototype, otherwise returns the prototype.

(table/new capacity)

Creates a new empty table with pre-allocated memory for capacity entries. This means that if one knows the number of entries going to go in a table on creation, extra memory allocation can be avoided. Returns the new table.

(table/rawget tab key)

Gets a value from a table without looking at the prototype table. If a table tab does not contain t directly, the function will return nil without checking the prototype. Returns the value in the table.

(table/setproto tab proto)

Set the prototype of a table. Returns the original table tab.

(table/to-struct tab)

Convert a table to a struct. Returns a new struct. This function does not take into account prototype tables.

(table? x)

Check if x a table.

(take n ind)

Take first n elements in an indexed type. Returns new indexed instance.

(take-until pred ind)

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

(take-while pred ind)

Given a predicate, take only elements from an indexed type that satisfy the predicate, and abort on first failure. Returns a new array.

(tarray/buffer array|size)

Return typed array buffer or create a new buffer.

(tarray/copy-bytes src sindex dst dindex &opt count)

Copy count elements (default 1) of src array from index sindex to dst array at position dindex memory can overlap.

(tarray/length array|buffer)

Return typed array or buffer size.

(tarray/new type size &opt stride offset tarray|buffer)

Create new typed array.

(tarray/properties array)

Return typed array properties as a struct.

(tarray/slice tarr &opt start end)

Takes a slice of a typed array 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 typed array. By default, start is 0 and end is the size of the typed array. Returns a new janet array.

(tarray/swap-bytes src sindex dst dindex &opt count)

Swap count elements (default 1) between src array from index sindex and dst array at position dindex memory can overlap.

(thread/close thread)

Close a thread, unblocking it and ending communication with it. Note that closing a thread is idempotent and does not cancel the thread's operation. Returns nil.

(thread/current)

Get the current running thread.

(thread/new func &opt capacity)

Start a new thread that will start immediately. If capacity is provided, that is how many messages can be stored in the thread's mailbox before blocking senders. The capacity must be between 1 and 65535 inclusive, and defaults to 10. Returns a handle to the new thread.

(thread/receive &opt timeout)

Get a message sent to this thread. If timeout is provided, an error will be thrown after the timeout has elapsed but no messages are received.

(thread/send thread msg)

Send a message to the thread. This will never block and returns thread immediately. Will throw an error if there is a problem sending the message.

(trace func)

Enable tracing on a function. Returns the function.

(true? x)

Check if x is true.

(truthy? x)

Check if x is truthy.

(try body catch)

Try something and catch errors. Body is any expression, and catch should be a form with the first element a tuple. This tuple should contain a binding for errors and an optional binding for the fiber wrapping the body. Returns the result of body if no error, or the result of catch if an error.

(tuple & items)

Creates a new tuple that contains items. Returns the new tuple.

(tuple/brackets & xs)

Creates a new bracketed tuple containing the elements xs.

(tuple/setmap tup line column)

Set the sourcemap metadata on a tuple. line and column indicate should be integers.

(tuple/slice arrtup [,start=0 [,end=(length arrtup)]])

Take a sub sequence of an array or tuple from index start inclusive to index end exclusive. If start or end are not provided, they default to 0 and the length of arrtup respectively. 'start' and 'end' can also be negative to indicate indexing from the end of the input. Note that index -1 is synonymous with index '(length arrtup)' to allow a full negative slice range. Returns the new tuple.

(tuple/sourcemap tup)

Returns the sourcemap metadata attached to a tuple, which is another tuple (line, column).

(tuple/type tup)

Checks how the tuple was constructed. Will return the keyword :brackets if the tuple was parsed with brackets, and :parens otherwise. The two types of tuples will behave the same most of the time, but will print differently and be treated differently by the compiler.

(tuple? x)

Check if x is a tuple.

(type x)

Returns the type of x as a keyword. x is one of
	:nil
	:boolean
	:number
	:array
	:tuple
	:table
	:struct
	:string
	:buffer
	:symbol
	:keyword
	:function
	:cfunction

or another keyword for an abstract type.

(type nil) # -> :nil
(type true) # -> :boolean
(type false) # -> :boolean
(type 1) # -> :number
(type :key) # -> :keyword
(type (int/s64 "100")) # -> :core/s64

(unless condition & body)

Shorthand for (when (not condition) ;body). 

(unmarshal buffer &opt lookup)

Unmarshal a value from a buffer. An optional lookup table can be provided to allow for aliases to be resolved. Returns the value unmarshalled from the buffer.

(untrace func)

Disables tracing on a function. Returns the function.

(update ds key func & args)

Accepts a key argument and passes its associated value to a function. The key is the re-associated to the function's return value. Returns the updated data structure ds.

(update-in ds ks f & args)

Update a value in a nested data structure by applying f to the current value. Looks into the data structure via a sequence of keys. Missing data structures will be replaced with tables. Returns the modified, original data structure.

(use & modules)

Similar to import, but imported bindings are not prefixed with a namespace identifier. Can also import multiple modules in one shot.

(values x)

Get the values of an associative data structure.

(var- name & more)

Define a private var that will not be exported.

(varfn name & body)

Create a function that can be rebound. varfn has the same signature as defn, but defines functions in the environment as vars. If a var 'name' already exists in the environment, it is rebound to the new function. Returns a function.

(varglobal name init)

Dynamically create a global var.

(walk f form)

Iterate over the values in ast and apply f to them. Collect the results in a data structure. If ast is not a table, struct, array, or tuple, returns form.

(when condition & body)

Evaluates the body when the condition is true. Otherwise returns nil.

(when-let bindings & body)

Same as (if-let bindings (do ;body)).

(when-with [binding ctor dtor] & body)

Similar to with, but if binding is false or nil, returns nil without evaluating the body. Otherwise, the same as with.

(with [binding ctor dtor] & body)

Evaluate body with some resource, which will be automatically cleaned up if there is an error in body. binding is bound to the expression ctor, and dtor is a function or callable that is passed the binding. If no destructor (dtor) is given, will call :close on the resource.

# Print all of poetry.txt, and close the file when done,
# even when there is an error.
(with [f (file/open "poetry.txt")]
  (print (:read f :all)))

(with-dyns bindings & body)

Run a block of code in a new fiber that has some dynamic bindings set. The fiber will not mask errors or signals, but the dynamic bindings will be properly unset, as dynamic bindings are fiber local.

(with-syms syms & body)

Evaluates body with each symbol in syms bound to a generated, unique symbol.

(with-vars vars & body)

Evaluates body with each var in vars temporarily bound. Similar signature to let, but each binding must be a var.

(yield &opt x)

Yield a value to a parent fiber. When a fiber yields, its execution is paused until another thread resumes it. The fiber will then resume, and the last yield call will return the value that was passed to resume.

(zero? x)

Check if x is zero.

(zipcoll ks vs)

Creates a table from two arrays/tuples. Returns a new table.