Top Level Bindings

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

(/= x n)

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

(any? ind)

Returns the first truthy value in ind, otherwise nil.
falsey value.

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

(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? 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, 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 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 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, return nil.

(coro & body)

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

(count pred ind)

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.

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-tags 1 2) # raises arity error
(with-tags 1 2 3) # -> (1 2 3 ())
(with-tags 1 2 3 4) # -> (1 2 3 (4))
(with-tags 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 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.
* :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.

(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 &keys {:read read :parser parser :source src :evaluator evaluator :expander expander :env env :exit exit})

Evaluate a file, file path, or stream and return the resulting environment. :env, :expander,
: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.

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

# 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-fn flags & body)

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

(fiber? x)

Check if x is a fiber.

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

(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 a indexed structure.

(from-pairs ps)

Takes a sequence of pairs and creates a table from each pair. The inverse of
`pairs` on a 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.

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

(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 table. The keys of
the table are the distinct return values of `f`, and the values are arrays of all elements of `ind`
that are equal to that value.

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

(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? 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 where the keys of an associative data structure
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.

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

(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? 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 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 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 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.
  lets try putting a loop item on multiple lines.
* `: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 :in 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.

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

Map a function over every value in a 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 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 -- an array will match only if all of its elements match the
 corresponding elements in `x`.

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

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

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

(merge-module target source &opt prefix export)

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.

(min & args)

Returns the numeric minimum of the arguments.

(min-of args)

Returns the numeric minimum of the argument sequence.

(mod dividend divisor)

Returns the modulo of dividend / divisor.

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

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

(pairs x)

Get the key-value pairs 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.

(partial f & more)

Partial function application.

(partition n ind)

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

(partition-by f ind)

Partition elements of a sequential data structure by a representative function `f`. Partitions
split when `(f x)` changes values when iterating to the next element `x` of `ind`. Returns a new array
of arrays.

(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 by applying f to
each element in order. f is a function of 2 arguments, (f accum el), where
accum is the initial value and el is the next value in the indexed type ind.
f returns a value that will be used as accum in the next call to f. reduce
returns the value of the final call to f.

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

(repeat n & body)

Evaluate body n times. If n is negative, body will be evaluated 0 times. Evaluates to nil.

(repl &opt chunks onsignal env parser read)

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, as well as an optional parser or read function to pass
to `run-context.`

(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. If string or buffer is provided function returns array of chars reversed.

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

(reverse! t)

Reverses the order of the elements in a given array or buffer and returns it
mutated.

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

(run-context opts)

Run a context. This evaluates expressions in an environment,
and 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
 * `:on-compile-warning` - callback for any linting error - default is warn-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.
  * `:parser` - provide a custom parser that implements the same interface as Janet's built-in parser.
  * `:read` - optional function to get the next form, called like `(read env source)`.
    Overrides all parsing.

(scan-number str &opt base)

Parse a number from a byte sequence and return that number, either an 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. Optionally provide a base - if a base is provided, no radix specifier is expected at the beginning of the 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)

Shorthand for fn. Arguments are given as $n, where n is the 0-indexed
argument of the function. $ is also an alias for the first (index 0) argument.
The $& symbol will make the anonymous function variadic if it appears in the
body of the function - it can be combined with positional arguments.

Example usage:

 * (short-fn (+ $ $)) - A function that doubles 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 ind &opt before?)

Sort `ind` in-place, and return it. Uses quick-sort and is not a stable sort.
If a `before?` comparator function is provided, sorts elements using that,
otherwise uses `<`.

(sort-by f ind)

Returns `ind` sorted by calling
a function `f` on each element and comparing the result with `<`.

(sorted ind &opt before?)

Returns a new sorted array without modifying the old one.
If a `before?` comparator function is provided, sorts elements using that,
otherwise uses `<`.

(sorted-by f ind)

Returns a new sorted array that compares elements by invoking
a function `f` 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 & xs)

Creates a string 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 string.

(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 the elements of `xs` together. If an element is not a byte sequence, it is converted to bytes via `describe`. 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? x)

Check if x a table.

(take n ind)

Take the first n elements of a fiber, indexed or bytes type. Returns a new array, tuple or string, respectively.

(take-until pred ind)

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

(take-while pred ind)

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

(trace func)

Enable tracing on a function. Returns the function.

(tracev x)

Print a value and a description of the form that produced that value to
stderr. Evaluates to x.

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

* :fiber

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 then 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 module
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.

(warn-compile msg level where &opt line col)

Default handler for a compile warning

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

(xprin to & xs)

Print to a file or other value explicitly (no dynamic bindings). The value to print to is the first argument, and is otherwise the same as prin. Returns nil.

(xprinf to fmt & xs)

Like prinf but prints to an explicit file or value to. Returns nil.

(xprint to & xs)

Print to a file or other value explicitly (no dynamic bindings) with a trailing newline character. The value to print to is the first argument, and is otherwise the same as print. Returns nil.

(xprintf to fmt & xs)

Like printf but prints to an explicit file or value to. Returns nil.

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