Janet 1.32.1-cc5beda Documentation
(Other Versions:
1.31.0
1.29.1
1.28.0
1.27.0
1.26.0
1.25.1
1.24.0
1.23.0
1.22.0
1.21.0
1.20.0
1.19.0
1.18.1
1.17.1
1.16.1
1.15.0
1.13.1
1.12.2
1.11.1
1.10.1
1.9.1
1.8.1
1.7.0
1.6.0
1.5.1
1.5.0
1.4.0
1.3.1
)
Top Level Bindings
All of the core functions, macros, and bindings that are not part of any module.
Index
% %= * *= *args* *current-file* *debug* *defdyn-prefix* *doc-color* *doc-width* *err* *err-color* *executable* *exit* *exit-value* *ffi-context* *lint-error* *lint-levels* *lint-warn* *macro-form* *macro-lints* *out* *peg-grammar* *pretty-format* *profilepath* *redef* *syspath* *task-id* + ++ += - -- -= -> ->> -?> -?>> / /= < <= = > >= abstract? accumulate accumulate2 all all-bindings all-dynamics and any? apply array array? as-> as-macro as?-> asm assert bad-compile bad-parse band blshift bnot boolean? bor brshift brushift buffer buffer? bxor bytes? cancel case catseq cfunction? chr cli-main cmp comment comp compare compare< compare<= compare= compare> compare>= compif compile complement comptime compwhen cond coro count curenv debug debugger debugger-env debugger-on-status dec deep-not= deep= def- default default-peg-grammar defdyn defer defglobal defmacro defmacro- defn defn- delay describe dictionary? disasm distinct div doc doc* doc-format doc-of dofile drop drop-until drop-while dyn each eachk eachp edefer eflush empty? env-lookup eprin eprinf eprint eprintf error errorf eval eval-string even? every? extreme false? fiber-fn fiber? filter find find-index first flatten flatten-into flush flycheck for forever forv freeze frequencies from-pairs function? gccollect gcinterval gcsetinterval generate gensym get get-in getline getproto group-by has-key? has-value? hash idempotent? identity if-let if-not if-with import import* in inc index-of indexed? int? interleave interpose invert juxt juxt* keep keep-syntax keep-syntax! keys keyword keyword? kvs label last length lengthable? let load-image load-image-dict loop macex macex1 maclintf make-env make-image make-image-dict map mapcat marshal match max max-of mean memcmp merge merge-into merge-module min min-of mod nan? nat? native neg? next nil? not not= number? odd? one? or pairs parse parse-all partial partition partition-by pos? postwalk pp prewalk prin prinf print printf product prompt propagate protect put put-in quit range reduce reduce2 repeat repl require resume return reverse reverse! root-env run-context sandbox scan-number seq setdyn short-fn signal slice slurp some sort sort-by sorted sorted-by spit stderr stdin stdout string string? struct struct? sum symbol symbol? table table? tabseq take take-until take-while thaw toggle trace tracev true? truthy? try tuple tuple? type unless unmarshal untrace update update-in use values var- varfn varglobal walk warn-compile when when-let when-with with with-dyns with-syms with-vars xprin xprinf xprint xprintf yield zero? zipcoll
(% & xs) Returns the remainder of dividing the first value of xs by each remaining value.
(% 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
Community Examples(%= x & ns) Shorthand for (set x (% x n)).
(var x 10) # -> 10
(%= x 3) # -> 1
x # -> 1
Community Examples(* & 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
Community Examples(*= x & ns) Shorthand for (set x (\* x n)).
(var x 100) # -> 100
x # -> 100
(*= x 10) # -> 1000
x # -> 1000
Community ExamplesDynamic bindings that will contain command line arguments at program start.Community Examples
Enables a built in debugger on errors and other useful features for debugging in a repl.Community Examples
Optional namespace prefix to add to keywords declared with `defdyn`. Use this to prevent keyword collisions between dynamic bindings.Community Examples
Whether or not to colorize documentation printed with `doc-format`.Community Examples
Width in columns to print documentation printed with `doc-format`.Community Examples
Whether or not to turn on error coloring in stacktraces and other error messages.Community Examples
Name of the interpreter executable used to execute this program. Corresponds to `argv[0]` in the call to `int main(int argc, char **argv);`.Community Examples
When set, will cause the current context to complete. Can be set to exit from repl (or file), for example.Community Examples
Set the return value from `run-context` upon an exit. By default, `run-context` will return nil.Community Examples
Current native library for ffi/bind and other settingsCommunity Examples
The current lint error level. The error level is the lint level at which compilation will exit with an error and not continue.Community Examples
A table of keyword alias to numbers denoting a lint level. Can be used to provided custom aliases for numeric lint levels.Community Examples
The current lint warning level. The warning level is the lint level at which and error will be printed but compilation will continue as normal.Community Examples
Inside a macro, is bound to the source form that invoked the macroCommunity Examples
Bound to an array of lint messages that will be reported by the compiler inside a macro. To indicate an error or warning, a macro author should use `maclintf`.Community Examples
The implicit base grammar used when compiling PEGs. Any undefined keywords found when compiling a peg will use lookup in this table (if defined).Community Examples
Path to profile file loaded when starting up the repl.Community Examples
When set, allow dynamically rebinding top level defs. Will slow generated code and is intended to be used for development.Community Examples
When spawning a thread or fiber, the task-id can be assigned for concurrency control.Community Examples
(+ & 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
Community Examples(+= x & ns) Increments the var x by n.
(var x 100) # -> 100
x # -> 100
(+= x 10) # -> 110
x # -> 110
Community Examples(- & 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>
Community Examples(-= x & ns) Decrements the var x by n.
(var x 10) # -> 10
(-= x 20) # -> -10
x # -> -10
Community Examples(-> 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.Community Examples
(->> 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.Community Examples
(-?> 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.Community Examples
(-?>> 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.Community Examples
(/ & 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.Community Examples
(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.Community Examples
(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)`.Community Examples
(all pred ind & inds) Returns true if `(pred item)` is truthy for every item in `ind`. Otherwise, returns the first falsey result encountered. Returns true if `ind` is empty.Community Examples
(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).Community Examples
(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).Community Examples
(and & forms) Evaluates to the last argument if all preceding elements are truthy, otherwise evaluates to the first falsey argument.Community Examples
(any? ind) Evaluates to the last element of `ind` if all preceding elements are falsey, otherwise evaluates to the first truthy element.Community Examples
(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 ...
Community Examples(array & items) Create a new array that contains items. Returns the new array.Community Examples
(as-> x as & forms) Thread forms together, replacing `as` in `forms` with the value of the previous form. The first form is the value x. Returns the last value.Community Examples
(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`.Community Examples
(as?-> x as & forms) Thread forms together, replacing `as` in `forms` with the value of the previous form. The first form is the value x. If any intermediate values are falsey, return nil; otherwise, returns the last value.Community Examples
(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.Community Examples
(assert x &opt err) Throw an error if x is not truthy. Will not evaluate `err` if x is truthy.Community Examples
(bad-compile msg macrof where &opt line col) Default handler for a compile error.Community Examples
(band & xs) Returns the bit-wise and of all values in xs. Each x in xs must be an integer.Community Examples
(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.Community Examples
(bor & xs) Returns the bit-wise or of all values in xs. Each x in xs must be an integer.Community Examples
(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.Community Examples
(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.Community Examples
(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.Community Examples
(bxor & xs) Returns the bit-wise xor of all values in xs. Each in xs must be an integer.Community Examples
(bytes? x) Check if x is a string, symbol, keyword, or buffer.Community Examples
(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.Community Examples
(case dispatch & pairs) Select the body that equals the dispatch value. When `pairs` has an odd number of elements, the last is the default expression. If no match is found, returns nil.Community Examples
(catseq head & body) Similar to `loop`, but concatenates each element from the loop body into an array and returns that. See `loop` for details.Community Examples
(chr c) Convert a string of length 1 to its byte (ascii) value at compile time.Community Examples
(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.Community Examples
(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.Community Examples
(comp & functions) Takes multiple functions and returns a function that is the composition of those functions.Community Examples
(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.Community Examples
(compare< & xs) Equivalent of `<` but using polymorphic `compare` instead of primitive comparator.Community Examples
(compare<= & xs) Equivalent of `<=` but using polymorphic `compare` instead of primitive comparator.Community Examples
(compare= & xs) Equivalent of `=` but using polymorphic `compare` instead of primitive comparator.Community Examples
(compare> & xs) Equivalent of `>` but using polymorphic `compare` instead of primitive comparator.Community Examples
(compare>= & xs) Equivalent of `>=` but using polymorphic `compare` instead of primitive comparator.Community Examples
(compif cnd tru &opt fals) Check the condition `cnd` at compile time -- if truthy, compile `tru`, else compile `fals`.Community Examples
(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)`.Community Examples
(complement f) Returns a function that is the complement to the argument.Community Examples
(comptime x) Evals x at compile time and returns the result. Similar to a top level unquote.Community Examples
(compwhen cnd & body) Check the condition `cnd` at compile time -- if truthy, compile `(upscope ;body)`, else compile nil.Community Examples
(cond & pairs) Evaluates conditions sequentially until the first true condition is found, and then executes the corresponding body. If there are an odd number of forms, and no forms are matched, the last expression is executed. If there are no matches, returns nil.Community Examples
(coro & body) A wrapper for making fibers that may yield multiple values (coroutine). Same as `(fiber/new (fn [] ;body) :yi)`.Community Examples
(count pred ind & inds) Count the number of items in `ind` for which `(pred item)` is true.Community Examples
(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.Community Examples
(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.Community Examples
(debugger fiber &opt level) Run a repl-based debugger on a fiber. Optionally pass in a level to differentiate nested debuggers.Community Examples
An environment that contains dot prefixed functions for debugging.Community Examples
(debugger-on-status env &opt level is-repl) Create a function that can be passed to `run-context`'s `:on-status` argument that will drop into a debugger on errors. The debugger will only start on abnormal signals if the env table has the `:debug` dyn set to a truthy value.Community Examples
(deep-not= x y) Like `not=`, but mutable types (arrays, tables, buffers) are considered equal if they have identical structure. Much slower than `not=`.Community Examples
(deep= x y) Like `=`, but mutable types (arrays, tables, buffers) are considered equal if they have identical structure. Much slower than `=`.Community Examples
(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)
Community Examples(default sym val) Define a default value for an optional argument. Expands to `(def sym (if (= nil sym) val sym))`.Community Examples
The default grammar used for pegs. This grammar defines several common patterns that should make it easier to write more complex patterns.Community Examples
(defdyn alias & more) Define an alias for a keyword that is used as a dynamic binding. The alias is a normal, lexically scoped binding that can be used instead of a keyword to prevent typos. `defdyn` does not set dynamic bindings or otherwise replace `dyn` and `setdyn`. The alias _must_ start and end with the `*` character, usually called "earmuffs".Community Examples
(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))
Community Examples(defmacro- name & more) Define a private macro that will not be exported.Community Examples
(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}
Community Examples(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))
Community Examples(delay & forms) Lazily evaluate a series of expressions. Returns a function that returns the result of the last expression. Will only evaluate the body once, and then memoizes the result.Community Examples
(describe x) Returns a string that is a human-readable description of `x`. For recursive data structures, the string returned contains a pointer value from which the identity of `x` can be determined.Community Examples
(disasm func &opt field) Returns assembly that could be used to compile the given function. func must be a function, not a c function. Will throw on error on a badly typed argument. If given a field name, will only return that part of the function assembly. Possible fields are: * :arity - number of required and optional arguments. * :min-arity - minimum number of arguments function can be called with. * :max-arity - maximum number of arguments function can be called with. * :vararg - true if function can take a variable number of arguments. * :bytecode - array of parsed bytecode instructions. Each instruction is a tuple. * :source - name of source file that this function was compiled from. * :name - name of function. * :slotcount - how many virtual registers, or slots, this function uses. Corresponds to stack space used by function. * :symbolmap - all symbols and their slots. * :constants - an array of constants referenced by this function. * :sourcemap - a mapping of each bytecode instruction to a line and column in the source file. * :environments - an internal mapping of which enclosing functions are referenced for bindings. * :defs - other function definitions that this function may instantiate.Community Examples
(distinct xs) Returns an array of the deduplicated values in `xs`.Community Examples
(div & xs) Returns the floored division of xs. If xs is empty, returns 1. If xs has one value x, returns the reciprocal of x. Otherwise return the first value of xs repeatedly divided by the remaining values.Community Examples
(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).Community Examples
(doc* &opt sym) Get the documentation for a symbol in a given environment. Function form of `doc`.Community Examples
(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.Community Examples
(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.Community Examples
(dofile path &named exit env source expander evaluator read parser) Evaluate a file, file path, or stream and return the resulting environment. :env, :expander, :source, :evaluator, :read, and :parser are passed through to the underlying `run-context` call. If `exit` is true, any top level errors will trigger a call to `(os/exit 1)` after printing the error.Community Examples
(drop n ind) Drop the first `n` elements in an indexed or bytes type. Returns a new tuple or string instance, respectively. If `n` is negative, drops the last `n` elements instead.Community Examples
(drop-until pred ind) Same as `(drop-while (complement pred) ind)`.Community Examples
(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.Community Examples
(dyn key &opt default) Get a dynamic binding. Returns the default value (or nil) if no binding found.Community Examples
(eachp x ds & body) Loop over each (key, value) pair in `ds`. Returns nil.Community Examples
(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"))
Community Examples(eflush) Flush `(dyn :err stderr)` if it is a file, otherwise do nothing.Community Examples
(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.Community Examples
(eprin & xs) Same as `prin`, but uses `(dyn :err stderr)` instead of `(dyn :out stdout)`.Community Examples
(eprinf fmt & xs) Like `eprintf` but with no trailing newline.Community Examples
(eprint & xs) Same as `print`, but uses `(dyn :err stderr)` instead of `(dyn :out stdout)`.Community Examples
(eprintf fmt & xs) Prints output formatted as if with `(string/format fmt ;xs)` to `(dyn :err stderr)` with a trailing newline.Community Examples
(error e) Throws an error e that can be caught and handled by a parent fiber.Community Examples
(errorf fmt & args) A combination of `error` and `string/format`. Equivalent to `(error (string/format fmt ;args))`.Community Examples
(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
Community Examples(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
Community Examples(every? ind) Evaluates to the last element of `ind` if all preceding elements are truthy, otherwise evaluates to the first falsey element.Community Examples
(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.Community Examples
(fiber-fn flags & body) A wrapper for making fibers. Same as `(fiber/new (fn [] ;body) flags)`.Community Examples
(filter pred ind) Given a predicate, take only elements from an array or tuple for which `(pred element)` is truthy. Returns a new array.Community Examples
(find pred ind &opt dflt) Find the first value in an indexed collection that satisfies a predicate. Returns `dflt` if not found.Community Examples
(find-index pred ind &opt dflt) Find the index of indexed type for which `pred` is true. Returns `dflt` if not found.Community Examples
(first xs) Get the first element from an indexed data structure.Community Examples
(flatten xs) Takes a nested array (tree) `xs` and returns the depth first traversal of it. Returns a new array.Community Examples
(flatten-into into xs) Takes a nested array (tree) `xs` and appends the depth first traversal of `xs` to array `into`. Returns `into`.Community Examples
(flush) Flush `(dyn :out stdout)` if it is a file, otherwise do nothing.Community Examples
(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.Community Examples
(for i start stop & body) Do a C-style for-loop for side effects. Returns nil.Community Examples
(forever & body) Evaluate body forever in a loop, or until a break statement.Community Examples
(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.Community Examples
(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.Community Examples
(frequencies ind) Get the number of occurrences of each value in an indexed data structure.Community Examples
(from-pairs ps) Takes a sequence of pairs and creates a table from each pair. It is the inverse of `pairs` on a table. Returns a new table.Community Examples
(function? x) Check if x is a function (not a cfunction).Community Examples
(gccollect) Run garbage collection. You should probably not call this manually.Community Examples
(gcinterval) Returns the integer number of bytes to allocate before running an iteration of garbage collection.Community Examples
(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.Community Examples
(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
# ...
Community Examples(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.Community Examples
(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.Community Examples
(get-in ds ks &opt dflt) Access a value in a nested data structure. Looks into the data structure via a sequence of keys. If value is not found, and `dflt` is provided, returns `dflt`.Community Examples
(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.Community Examples
(getproto x) Get the prototype of a table or struct. Will return nil if `x` has no prototype.Community Examples
(group-by f ind) Group elements of `ind` by a function `f` and put the results into a new table. The keys of the table are the distinct return values from calling `f` on the elements of `ind`. The values of the table are arrays of all elements of `ind` for which `f` called on the element equals that corresponding key.Community Examples
(has-key? ds key) Check if a data structure `ds` contains the key `key`.Community Examples
(has-value? ds value) Check if a data structure `ds` contains the value `value`. Will run in time proportional to the size of `ds`.Community Examples
(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.Community Examples
(idempotent? x) Check if x is a value that evaluates to itself when compiled.Community Examples
(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.Community Examples
(if-not condition then &opt else) Shorthand for `(if (not condition) else then)`.Community Examples
(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.Community Examples
(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.Community Examples
(import* path & args) Function form of `import`. Same parameters, but the path and other symbol parameters should be strings instead.Community Examples
(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.Community Examples
(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.Community Examples
(int? x) Check if x can be exactly represented as a 32 bit signed two's complement integer.Community Examples
(interleave & cols) Returns an array of the first elements of each col, then the second elements, etc.Community Examples
(interpose sep ind) Returns a sequence of the elements of `ind` separated by `sep`. Returns a new array.Community Examples
(invert ds) Given an associative data structure `ds`, returns a new table where the keys of `ds` are the values, and the values are the keys. If multiple keys in `ds` are mapped to the same value, only one of those values will become a key in the returned table.Community Examples
(juxt & funs) Macro form of `juxt*`. Same behavior but more efficient.Community Examples
(juxt* & funs) Returns the juxtaposition of functions. In other words, `((juxt* a b c) x)` evaluates to `[(a x) (b x) (c x)]`.Community Examples
(keep pred ind & inds) Given a predicate `pred`, return a new array containing the truthy results of applying `pred` to each element in the indexed collection `ind`. This is different from `filter` which returns an array of the original elements where the predicate is truthy.Community Examples
(keep-syntax before after) Creates a tuple with the tuple type and sourcemap of `before` but the elements of `after`. If either one of its arguments is not a tuple, returns `after` unmodified. Useful to preserve syntactic information when transforming an ast in macros.Community Examples
(keep-syntax! before after) Like `keep-syntax`, but if `after` is an array, it is coerced into a tuple. Useful to preserve syntactic information when transforming an ast in macros.Community Examples
(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.Community Examples
(kvs dict) Takes a table or struct and returns and array of key value pairs like `@[k v k v ...]`. Returns a new array.Community Examples
(label name & body) Set a label point that is lexically scoped. `name` should be a symbol that will be bound to the label.Community Examples
(last xs) Get the last element from an indexed data structure.Community Examples
(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.Community Examples
(lengthable? x) Check if x is a bytes, indexed, or dictionary.Community Examples
(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.Community Examples
(load-image image) The inverse operation to `make-image`. Returns an environment.Community Examples
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)`.Community Examples
(loop head & body) A general purpose loop macro. This macro is similar to the Common Lisp loop macro, although intentionally much smaller in scope. The head of the loop should be a tuple that contains a sequence of either bindings or conditionals. A binding is a sequence of three values that define something to loop over. Bindings are written in the format: binding :verb object/expression where `binding` is a binding as passed to def, `:verb` is one of a set of keywords, and `object` is any expression. Each subsequent binding creates a nested loop within the loop created by the previous binding. The available verbs are: * `:iterate` -- repeatedly evaluate and bind to the expression while it is truthy. * `:range` -- loop over a range. The object should be a two-element tuple with a start and end value, and an optional positive step. The range is half open, [start, end). * `:range-to` -- same as :range, but the range is inclusive [start, end]. * `:down` -- loop over a range, stepping downwards. The object should be a two-element tuple with a start and (exclusive) end value, and an optional (positive!) step size. * `:down-to` -- same as :down, but the range is inclusive [start, end]. * `:keys` -- iterate over the keys in a data structure. * `:pairs` -- iterate over the key-value pairs as tuples in a data structure. * `:in` -- iterate over the values in a data structure or fiber. `loop` also accepts conditionals to refine the looping further. Conditionals are of the form: :modifier argument where `:modifier` is one of a set of keywords, and `argument` is keyword-dependent. `:modifier` can be one of: * `:while expression` -- breaks from the current loop if `expression` is falsey. * `:until expression` -- breaks from the current loop if `expression` is truthy. * `:let bindings` -- defines bindings inside the current loop as passed to the `let` macro. * `:before form` -- evaluates a form for a side effect before the next inner loop. * `:after form` -- same as `:before`, but the side effect happens after the next inner loop. * `:repeat n` -- repeats the next inner loop `n` times. * `:when condition` -- only evaluates the current loop body when `condition` is truthy. * `:unless condition` -- only evaluates the current loop body when `condition` is falsey. The `loop` macro always evaluates to nil.
# -> 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
Community Examples(macex x &opt on-binding) Expand macros completely. `on-binding` is an optional callback for whenever a normal symbolic binding is encountered. This allows macros to easily see all bindings used by their arguments by calling `macex` on their contents. The binding itself is also replaced by the value returned by `on-binding` within the expanded macro.Community Examples
(macex1 x &opt on-binding) Expand macros in a form, but do not recursively expand macros. See `macex` docs for info on `on-binding`.Community Examples
(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.Community Examples
(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.Community Examples
(make-image env) Create an image from an environment returned by `require`. Returns the image source as a string.Community Examples
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)`.Community Examples
(map f ind & inds) Map a function over every value in a data structure and return an array of the results.Community Examples
(mapcat f ind & inds) Map a function over every element in an array or tuple and use `array/concat` to concatenate the results.Community Examples
(marshal x &opt reverse-lookup buffer no-cycles) Marshal a value into a buffer and return the buffer. The buffer can then later be unmarshalled to reconstruct the initial value. Optionally, one can pass in a reverse lookup table to not marshal aliased values that are found in the table. Then a forward lookup table can be used to recover the original value when unmarshalling.Community Examples
(match x & cases) Pattern matching. Match an expression `x` against any number of cases. Each case is a pattern to match against, followed by an expression to evaluate to if that case is matched. Legal patterns are: * symbol -- a pattern that is a symbol will match anything, binding `x`'s value to that symbol. * array or bracket tuple -- an array or bracket tuple will match only if all of its elements match the corresponding elements in `x`. Use `& rest` at the end of an array or bracketed tuple to bind all remaining values to `rest`. * table or struct -- a table or struct will match if all values match with the corresponding values in `x`. * tuple -- a tuple pattern will match if its first element matches, and the following elements are treated as predicates and are true. * `_` symbol -- the last special case is the `_` symbol, which is a wildcard that will match any value without creating a binding. While a symbol pattern will ordinarily match any value, the pattern `(@ <sym>)`, where <sym> is any symbol, will attempt to match `x` against a value already bound to `<sym>`, rather than matching and rebinding it. Any other value pattern will only match if it is equal to `x`. Quoting a pattern with `'` will also treat the value as a literal value to match against.Community Examples
(max-of args) Returns the numeric maximum of the argument sequence.Community Examples
(memcmp a b &opt len offset-a offset-b) Compare memory. Takes two byte sequences `a` and `b`, and return 0 if they have identical contents, a negative integer if a is less than b, and a positive integer if a is greater than b. Optionally take a length and offsets to compare slices of the bytes sequences.Community Examples
(merge & colls) Merges multiple tables/structs into one new table. If a key appears in more than one collection in `colls`, then later values replace any previous ones. Returns the new table.Community Examples
(merge-into tab & colls) Merges multiple tables/structs into table `tab`. If a key appears in more than one collection in `colls`, then later values replace any previous ones. Returns `tab`.Community Examples
(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.Community Examples
(min-of args) Returns the numeric minimum of the argument sequence.Community Examples
(mod & xs) Returns the result of applying the modulo operator on the first value of xs with each remaining value. `(mod x 0)` is defined to be `x`.Community Examples
(nat? x) Check if x can be exactly represented as a non-negative 32 bit signed two's complement integer.Community Examples
(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.Community Examples
(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.Community Examples
(not= & xs) Check if any values in xs are not equal. Returns a boolean.Community Examples
(or & forms) Evaluates to the last argument if all preceding elements are falsey, otherwise evaluates to the first truthy element.Community Examples
(pairs x) Get the key-value pairs of an associative data structure.Community Examples
(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.Community Examples
(parse-all str) Parse a string and return all parsed values. For complex parsing, such as for a repl with error handling, use the parser api.Community Examples
(partition n ind) Partition an indexed data structure `ind` into tuples of size `n`. Returns a new array.Community Examples
(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.Community Examples
(postwalk f form) Do a post-order traversal of a data structure and call `(f x)` on every visitation.Community Examples
(pp x) Pretty-print to stdout or `(dyn *out*)`. The format string used is `(dyn *pretty-format* "%q")`.Community Examples
(prewalk f form) Similar to `postwalk`, but do pre-order traversal.Community Examples
(prin & xs) Same as `print`, but does not add trailing newline.Community Examples
(prinf fmt & xs) Like `printf` but with no trailing newline.Community Examples
(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.Community Examples
(printf fmt & xs) Prints output formatted as if with `(string/format fmt ;xs)` to `(dyn :out stdout)` with a trailing newline.Community Examples
(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
(product {:a 1 :b 2 :c 4}) # -> 8
Community Examples(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.Community Examples
(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.Community Examples
(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.Community Examples
(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.Community Examples
(put-in ds ks v) Put a value into a nested data structure `ds`. Looks into `ds` via a sequence of keys. Missing data structures will be replaced with tables. Returns the modified, original data structure.Community Examples
(quit &opt value) Tries to exit from the current repl or run-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.Community Examples
(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]
Community Examples(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`.Community Examples
(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.Community Examples
(repeat n & body) Evaluate body n times. If n is negative, body will be evaluated 0 times. Evaluates to nil.Community Examples
(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`.Community Examples
(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.Community Examples
(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.Community Examples
(reverse t) Reverses the order of the elements in a given array or tuple and returns a new array. If a string or buffer is provided, returns a buffer instead.
(reverse [1 2 3]) # -> @[3 2 1]
(reverse "abcdef") # -> @[102 101 100 99 98 97]
(reverse :abc) # -> @[99 98 97]
Community Examples(reverse! t) Reverses the order of the elements in a given array or buffer and returns it mutated.Community Examples
(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` -- source path for better errors (use keywords for non-paths) - 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.Community Examples
(sandbox & forbidden-capabilities) Disable feature sets to prevent the interpreter from using certain system resources. Once a feature is disabled, there is no way to re-enable it. Capabilities can be: * :all - disallow all (except IO to stdout, stderr, and stdin) * :env - disallow reading and write env variables * :ffi - disallow FFI (recommended if disabling anything else) * :ffi-define - disallow loading new FFI modules and binding new functions * :ffi-jit - disallow calling `ffi/jitfn` * :ffi-use - disallow using any previously bound FFI functions and memory-unsafe functions. * :fs - disallow access to the file system * :fs-read - disallow read access to the file system * :fs-temp - disallow creating temporary files * :fs-write - disallow write access to the file system * :hrtime - disallow high-resolution timers * :modules - disallow load dynamic modules (natives) * :net - disallow network access * :net-connect - disallow making outbound network connections * :net-listen - disallow accepting inbound network connections * :sandbox - disallow calling this function * :signal - disallow adding or removing signal handlers * :subprocess - disallow running subprocessesCommunity Examples
(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.Community Examples
(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]
Community Examples(short-fn arg &opt name) 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, and 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 functionsCommunity Examples
(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"
Community Examples(slurp path) Read all data from a file with name `path` and then close the file.Community Examples
(some pred ind & inds) Returns nil if `(pred item)` is false or nil for every item in `ind`. Otherwise, returns the first truthy result encountered.Community Examples
(sort ind &opt before?) Sorts `ind` in-place, and returns it. Uses quick-sort and is not a stable sort. If a `before?` comparator function is provided, sorts elements using that, otherwise uses `<`.Community Examples
(sort-by f ind) Sorts `ind` in-place by calling a function `f` on each element and comparing the result with `<`.Community Examples
(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 `<`.Community Examples
(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 `<`.Community Examples
(spit path contents &opt mode) Write `contents` to a file at `path`. Can optionally append to the file.Community Examples
(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.Community Examples
(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.Community Examples
(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
Community Examples(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.Community Examples
(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.Community Examples
(tabseq head key-body & value-body) Similar to `loop`, but accumulates key value pairs into a table. See `loop` for details.Community Examples
(take n ind) Take the first n elements of a fiber, indexed or bytes type. Returns a new array, tuple or string, respectively. If `n` is negative, takes the last `n` elements instead.Community Examples
(take-until pred ind) Same as `(take-while (complement pred) ind)`.Community Examples
(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.Community Examples
(thaw ds) Thaw an object (make it mutable) and do a deep copy, making child value also mutable. Closures, fibers, and abstract types will not be recursively thawed, but all other types willCommunity Examples
(toggle value) Set a value to its boolean inverse. Same as `(set value (not value))`.Community Examples
(trace func) Enable tracing on a function. Returns the function.Community Examples
(tracev x) Print to stderr a value and a description of the form that produced that value. Evaluates to x.Community Examples
(try body catch) Try something and catch errors. `body` is any expression, and `catch` should be a form, the first element of which is 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.Community Examples
(tuple & items) Creates a new tuple that contains items. Returns the new tuple.Community Examples
(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
Community Examples(unless condition & body) Shorthand for `(when (not condition) ;body)`.Community Examples
(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.Community Examples
(untrace func) Disables tracing on a function. Returns the function.Community Examples
(update ds key func & args) For a given key in data structure `ds`, replace its corresponding value with the result of calling `func` on that value. If `args` are provided, they will be passed along to `func` as well. Returns `ds`, updated.Community Examples
(update-in ds ks f & args) Update a value in a nested data structure `ds`. Looks into `ds` via a sequence of keys, and replaces the value found there with `f` applied to that value. Missing data structures will be replaced with tables. Returns the modified, original data structure.Community Examples
(use & modules) Similar to `import`, but imported bindings are not prefixed with a module identifier. Can also import multiple modules in one shot.Community Examples
(values x) Get the values of an associative data structure.Community Examples
(var- name & more) Define a private var that will not be exported.Community Examples
(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.Community Examples
(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.Community Examples
(warn-compile msg level where &opt line col) Default handler for a compile warning.Community Examples
(when condition & body) Evaluates the body when the condition is true. Otherwise returns nil.Community Examples
(when-let bindings & body) Same as `(if-let bindings (do ;body))`.Community Examples
(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`.Community Examples
(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)))
Community Examples(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.Community Examples
(with-syms syms & body) Evaluates `body` with each symbol in `syms` bound to a generated, unique symbol.Community Examples
(with-vars vars & body) Evaluates `body` with each var in `vars` temporarily bound. Similar signature to `let`, but each binding must be a var.Community Examples
(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.Community Examples
(xprinf to fmt & xs) Like `prinf` but prints to an explicit file or value `to`. Returns nil.Community Examples
(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.Community Examples
(xprintf to fmt & xs) Like `printf` but prints to an explicit file or value `to`. Returns nil.Community Examples
(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.Community Examples
(zipcoll ks vs) Creates a table from two arrays/tuples. Returns a new table.Community Examples