Spork

(argparse description &keys options)

Parse (dyn :args) according to options. If the arguments are incorrect, will return nil and print usage information.

Each option is a table or struct that specifies a flag or option for the script. The name of the option should be a string, specified via (argparse/argparse "..." op1-name {...} op2-name {...} ...). A help option and usage text is automatically generated for you.

The keys in each option table are as follows:

• :kind - What kind of option is this? One of :flag, :multi, :option, or :accumulate. A flag can either be on or off, a multi is a flag that can be provided multiple times, each time adding 1 to a returned integer, an option is a key that will be set in the returned table, and accumulate means an option can be specified 0 or more times, each time appending a value to an array.
• :short - Single letter for shorthand access.
• :help - Help text for the option, explaining what it is.
• :default - Default value for the option.
• :required - Whether or not an option is required.
• :short-circuit - Whether or not to stop parsing if this option is hit. Result will also contain the rest of the arguments under the :rest key.
• :action - A function that will be invoked when the option is parsed.
• :map - A function that is applied to the value of the option to transform it

There is also a special option name :default that will be invoked on arguments that do not start with a -- or -. Use this option to collect unnamed arguments to your script. This is separate from the :default key in option specifiers.

After "--", every argument is treated as an unnamed argument.

Once parsed, values are accessible in the returned table by the name of the option. For example (result "verbose") will check if the verbose flag is enabled. You may also use a custom args array when specified via the special option :args.

(base64/decode x)

Decodes a string from Base64. Returns decoded string.

(base64/encode x)

Encodes a string in Base64. Returns encoded string.

(build-rule rules target deps & body)

Add a rule to the rule graph. rules should be a table, target a string or tuple of strings, and deps a tuple of strings. body is code that will be executed to create all of the targets by the rules. If target is a keyword, the rule will always be considered out of date.

(build-run rules targets &opt n-workers)

Build a list of targets, as specified by rules. Return an array of all recursively updated targets.

Archiver, defaults to ar.

If generating intermediate files, store them in this directory

Presets for compiler optimizations, can be :release, :develop, and :debug, defaults to :develop.

C++ compiler, defaults to c++.

C++ standard to use as a 2 digit number, defaults to 11 on GCC-like compilers, 14 on msvc.

Extra C++ compiler flags to use during compilation

C standard to use as a 2 digit number, defaults to 99 on GCC-like compilers, 11 on msvc.

C compiler, defaults to cc.

Extra C compiler flags to use during compilation

Map of extra defines to use when compiling

List of dynamic libraries to use when compiling

Extra linker flags

List of libraries to use when compiling - can be static or dynamic depending on system.

List of .lib libraries to use when compiling with msvc

Path to vcvarsall.bat to use initialize MSVC environment. If unset, msvc-find will try to guess using typical install locations.

Extra flags to pass to pkg-config

Rules to use with visit-add-rule

Try to resolve circular or out-of-order dependencies between libraries by using --start-group and --end-group. Some linkers support this by default, but not at all. Defaults to true on linux and macos.

List of static libraries to use when compiling

Operating system to assume is being used for target compiler toolchain

Optional setting to enable using -rdynamic or -Wl,-export_dynamic when linking executables. This is the preferred way on POSIX systems to let an executable load native modules dynamically at runtime. Defaults to true

Optional setting to enable using (dyn *syspath*) as the runtime path to load for Shared Objects. Defaults to true

Optional callback to process each CLI command and its inputs and outputs

(check-library-exists libname &opt binding test-source-code)

Check if a library exists on the current POSIX system. Will run a test compilation and return true if the compilation succeeds. Libname is passed directly to the compiler/linker, such as -lm on GNU/Linux.

(compile-and-link-executable to & sources)

Compile and link an executable C/C++ program. Return an array of commands.

(compile-and-link-shared to & sources)

Compile and link a shared C/C++ library. Return an array of commands.

(compile-and-make-archive to & sources)

Compile and create a static archive. Return an array of commands.

(compile-c from to)

Compile a C program to an object file. Return the command arguments.

(compile-c++ from to)

Compile a C++ program to an object file. Return the command arguments.

(link-executable-c objects to)

Link a C program to make an executable. Return the command arguments.

(link-executable-c++ objects to)

Link a C++ program to make an executable. Return the command arguments.

(link-shared-c objects to)

Link a C program to make a shared library. Return the command arguments.

(link-shared-c++ objects to)

Link a C++ program to make a shared library. Return the command arguments.

(load-settings settings)

Load settings from a snapshot of settings saved with save-settings.

(make-archive objects to)

Make an archive file. Return the command arguments.

(msvc-compile-and-link-executable to & sources)

Compile and link an executable C/C++ program. Return an array of commands.

(msvc-compile-and-link-shared to & sources)

Compile and link a shared C/C++ library. Return an array of commands.

(msvc-compile-and-make-archive to & sources)

Compile and create a static archive. Return an array of commands.

(msvc-compile-c from to)

Compile a C program with MSVC. Return the command arguments.

(msvc-compile-c++ from to)

Compile a C++ program with MSVC. Return the command arguments.

(msvc-find)

Find vcvarsall.bat and run it to setup the current environment for building. Uses (dyn *msvc-vcvars*) to find the location of the setup script, otherwise defaults to checking typical install locations for Visual Studio. Supports VS 2017, 2019, and 2022, any edition. Will set environment variables such that invocations of cl.exe, link.exe, etc. will work as expected.

(msvc-janet-import-lib)

Get path to the installed Janet import lib. This import lib is needed when create dlls for natives.

(msvc-link-executable objects to)

Link a C/C++ program with MSVC to make an executable. Return the command arguments.

(msvc-link-shared objects to)

Link a C/C++ program with MSVC to make a shared library. Return the command arguments.

(msvc-make-archive objects to)

Make an archive file with MSVC. Return the command arguments.

(msvc-setup?)

Check if MSVC environment is already setup.

(pkg-config & pkg-config-libraries)

Setup defines, cflags, and library flags from pkg-config.

(save-settings)

Get a snapshot of the current settings for various compiler flags, libraries, defines, etc. that can be loaded later.

(search-dynamic-libraries & libs)

Search for dynamic libraries on the current POSIX system and configure (dyn *dynamic-libraries*). This is done by checking for the existence of libraries with check-library-exists. Returns an array of libraries that were not found.

(search-libraries & libs)

Search for libraries on the current POSIX system and configure (dyn *libs*). This is done by checking for the existence of libraries with check-library-exists. Returns an array of libraries that were not found.

(search-static-libraries & libs)

Search for static libraries on the current POSIX system and configure (dyn *static-libs*). This is done by checking for the existence of libraries with check-library-exists. Returns an array of libraries that were not found.

(visit-add-rule cmd inputs outputs message)

Used in conjuction with spork/build-rules. Adds rules to the (dyn *rules* (curenv))

(visit-clean cmd inputs outputs message)

A visiting function that will remove all outputs.

(visit-do-nothing &)

A visiting function that has no side effects and therefor does nothing.

(visit-execute cmd inputs outputs message)

A function that can be provided as (dyn *visit*) that will execute commands.

(visit-execute-if-stale cmd inputs outputs message)

A function that can be provided as (dyn *visit*) that will execute a command if inputs are newer than outputs, providing a simple, single-threaded, incremental build tool. This is not optimal for parallel builds, but is simple and works well for small projects.

(visit-execute-quiet cmd inputs outputs message)

A function that can be provided as (dyn *visit*) that will execute commands quietly.

(visit-generate-makefile cmd inputs outputs message)

A function that can be provided as (dyn *visit*) that will generate Makefile targets.

(from-each iterable &named supervisor)

Returns a channel that gives each item from an iterable data type. each macro is used to iterate over all iterable types. supervisor argument is passed to ev/go which launches two tasks that feed items to the channel. To finish the tasks, drain all items from the channel, or close the channel. Otherwise, the tasks remain frozen. When the tasks finish, the channel is closed. An error caused during iteration finishes the tasks with an error. Writing to the channel finishes the tasks with an error or freezes the fiber that tries to write to the channel.

Array of C Constants defined in the current scope

Array of C Functions defined in the current scope

current indent buffer

(@ & args)

(block & args)

(cdef name & more)

Define constant which will be registered in the module. It takes care of the docstring.

(cfunction name & more)

Define a C Function in cjanet. This also takes care of recording docstrings and such. Arity checking will be generated for you (by insertion of a call to janet_arity or janet_fixarity).

(declare & args)

(emit-block-end &opt nl)

(emit-block-start)

(emit-blocks statements)

Emit a number of statements in a bracketed block

(emit-cdef name & more)

Define constant which will be registered in the module. It takes care of the docstring.

(emit-cfunction name & more)

Functional form of cfunction - takes the same arguments, but parameters must be manually quoted.

(emit-comment msg)

Emit a multi-line comment string for C

(emit-declare binding & form)

Emit a declaration of a variable or constant.

(emit-function name & form)

Emit a C function definition.

(emit-include path)

(emit-indent)

(emit-module-entry name)

Call this at the end of a cjanet module to add a module entry function.

(emit-preprocess & args)

Emit a line of source code for the pre-processor. For example (emit-preprocess "include" "<stdio.h>").

(emit-typedef name definition)

Emit a type declaration (C typedef).

(function & args)

(include path)

(mangle token)

Convert any sequence of bytes to a valid C identifier in a way that is unlikely to collide. print-ir will not mangle symbols for you.

(module-entry name)

Call this at the end of a cjanet module to add a module entry function.

(preprocess & args)

(type-split x &opt dflt-type)

Extract name and type from a variable. Allow typing variables as both (name type) or name:type as a shorthand. If no type is found, default to dflt-type. dflt-type itself defaults to 'auto

(typedef & args)

(math/invmod a m)

Modular multiplicative inverse of a mod m. Both arguments must be integer. The return value has the same type as m. If no inverse exists, returns math/nan instead.

(math/jacobi a m)

Computes the Jacobi Symbol (a|m).

(math/mulmod a b m)

Modular multiplication of a and b mod m. All arguments must be integer. The return value has the same type as m.

(math/powmod a b m)

Modular exponentiation of a to the power of b mod m. All arguments must be integer. The return value has the same type as m.

(crc/make-variant size polynomial &opt init byte-flip xorout)

Create a CRC function based on the given polynomial, initial value, xourout, and whether to invert input bytes.

(crc/named-variant name)

Get a named CRC variant.

(check cron &opt time local)

Check if a given time matches a cron specifier.

(next-timestamp cron &opt time local)

Given a cron schedule, get the next instance on the cron tab after time

(parse-cron str)

Parse a cron string into a valid cron schedule object

(diff a b)

Compares a and b recursively. Returns an array of @[things-only-in-a things-only-in-b things-in-both].

(go-nursery nurse f &opt value)

Spawn a fiber into a nursery, similar to ev/go.

(join-nursery nurse)

Suspend the current fiber until the nursery is emptied.

(multithread-service thread-main n-threads)

Run instances of a function over multiple threads. On failures, restart the failed thread. Normal function returns will not trigger a restart.

(nursery)

Group a number of fibers into a single object for structured concurrency

(pcall f n)

Call a function n times (in parallel) for side effects. Each function is called with an integer argument indicating a fiber index. Returns nil.

(pdag f dag &opt n-workers)

Executes a dag by calling f on every node in the graph. Can set the number of workers for parallel execution. The graph is represented as a table mapping nodes to arrays of child nodes. Each node will only be evaluated after all children have been evaluated. Modifying dag inside f will not affect the scheduling of workers. Returns a table mapping each node to the result of (f node).

(pmap f data &opt n-workers)

Map f over data in parallel, optionally limiting parallelism to n workers.

(pmap-full f data)

Function form of ev/gather. If any of the sibling fibers error, all other siblings will be canceled. Returns the gathered results in an array. data can be any indexed data structure.

(pmap-limited f data n-workers)

Similar to pmap-full, but only runs work n-ways parallel.

(spawn-nursery nurse & body)

Similar to ev/spawn but associate spawned fibers with a nursery

(wait-cancel & body)

Wait forever until the current fiber is canceled, and then run some cleanup code.

A user list of forms that are control forms and should be indented two spaces.

(format source)

Format a string of source code to a buffer.

(format-file file)

Format a file

(format-print source)

Format a string of source code and print the result.

(concat & xs)

Concatenate one or more generators or iterables into a single generator.

(cycle ds)

Repeatedly yield the elements of ds, looping back to the beginning when finished.

(drop n ds)

Drop n elements from ds.

(drop-until p ds)

Drop elements from ds until p is true.

(drop-while p ds)

Drop elements from ds while p is true.

(filter p ds)

Create a generator that filters ds with p.

(from-iterable ds)

Create a new generator around any iterable data structure.

(map f ds)

Create a generator that maps f over ds.

(mapcat f ds)

Map f over ds, concatenating the results into a new generator.

(range from to)

Create a lazy range.

(run s)

Evaluate s for side effects.

(take n ds)

Take n elements from iterable ds.

(take-until p ds)

Return elements from ds until p is true.

(take-while p ds)

Return elements from ds while p is true.

(to-array s)

Consume s into a new array.

(default-autocomplete-context buf pos)

Given a buffer and a cursor position, extract a string that will be used as context for autocompletion. Return a position and substring from the buffer to use for autocompletion.

(default-autocomplete-options prefix &)

Default handler to get available autocomplete options for a given substring.

(default-doc-fetch sym w &)

Default handler for Ctrl-G to lookup docstrings in the current environment.

(make-getline &opt autocomplete-context autocomplete-options doc-fetch)

Reads a line of input into a buffer, like getline. However, allow looking up entries with a general lookup function rather than an environment table.

Maximal amount of items in the history

The html5 doctype header

(escape x)

Escape characters in a string for HTML

(html data &opt buf)

Render HTML from standard data structures. Fills the provided optional buffer, or new one if it is not provided, with the html bytes.

(raw text)

Get an object that can be used to splice in HTML literals. text is not escaped in the output string.

Grammar to parse a cookie header to a series of keys and values.

(cookies nextmw)

Parses cookies into the table under :cookies key

(logger nextmw)

Creates a logging middleware. The logger middleware prints URL route, return status, and elapsed request time.

(middleware x)

Coerce any type to http middleware

Grammar that parses a query string (sans url path and ? character) and returns a table.

(read-body req)

Given a request, read the HTTP body from the connection. Returns the body as a buffer. If the request has no body, returns nil.

(read-request conn buf &opt no-query)

Read an HTTP request header from a connection. Returns a table with the following keys:

• :headers - table mapping header names to header values. Header names are lowercase.
• :connection - the connection stream for the header.
• :buffer - the buffer instance that may contain extra bytes.
• :head-size - the number of bytes used by the header.
• :method - the HTTP method used.
• :path - the path of the resource requested.

The following keys are also present, but omitted if the user passes a truthy parameter to no-query.

• :route - path of the resource requested without query string.
• :query-string - segment of HTTP path after first ? character.
• :query - the query string parsed into a table. Supports a single string value for every string key, and any query parameters that aren't given a value are mapped to true.

Note that data is read in chunks and any data after the header terminator is stored in :buffer.

(read-response conn buf)

Read an HTTP response header from a connection. Returns a table with the following keys:

• :headers - table mapping header names to header values. Header names are lowercase.
• :connection - the connection stream for the header.
• :buffer - the buffer instance that may contain extra bytes.
• :head-size - the number of bytes used by the header.
• :status - the HTTP status code.
• :message - the HTTP status message.

Note that data is read in chunks and any data after the header terminator is stored in :buffer.

(request method url &keys {:body body :headers headers})

Make an HTTP request to a server. Returns a table containing response information.

• :head-size - number of bytes in the http header
• :headers - table mapping header names to header values. Header names are lowercase.
• :connection - the connection stream for the header.
• :buffer - the buffer instance that may contain extra bytes.
• :status - HTTP status code as an integer.
• :message - HTTP status message.
• :body - Bytes of the response body.

PEG for parsing HTTP requests

PEG for parsing HTTP responses

(router routes)

Creates a router middleware. A router will dispatch to different routes based on the URL path.

(send-response conn response &opt buf)

Send an HTTP response over a connection. Will automatically use chunked encoding if body is not a byte sequence. response should be a table with the following keys:

• :headers - optional headers to write
• :status - integer status code to write
• :body - optional byte sequence or iterable (for chunked body) for returning contents. The iterable can be lazy, i.e. for streaming data.

(server handler &opt host port)

Makes a simple http server. By default it binds to 0.0.0.0:8000, returns a new server stream. Simply wraps http/server-handler with a net/server.

(server-handler conn handler)

A simple connection handler for an HTTP server. When a connection is accepted. Call this with a handler function to handle the connect. The handler will be called with one argument, the request table, which will contain the following keys:

• :head-size - number of bytes in the http header.
• :headers - table mapping header names to header values.
• :connection - the connection stream for the header.
• :buffer - the buffer instance that may contain extra bytes.
• :path - HTTP path.
• :method - HTTP method, as a string.

Mapping of HTTP status codes to their status message.

Grammar to parse a URL into domain, port, and path triplet. Only supports the http:// protocol.

(add-bindings-as-routes server &opt env)

Add all local functions defined with :path metadata to a server. Will read from the :schema, :doc, :path, and :route-doc metadata to determine how the route behaves.

(add-route server path docstring schema handler &opt read-mime render-mime)

Add a single route manually to a server. Prefer using httpf/add-bindings-as-routes for the usual case.

(default-payload-wrapper payload)

Add some metadata to all responses

(listen server &opt host port n-workers)

Start server

(server &opt parent)

Create a new server.

($$ & body)

Use infix syntax for writing expressions in a more familiar manner. Useful for writing mathematic expressions.

(json/decode json-source &opt keywords nils)

Returns a janet object after parsing JSON. If keywords is truthy, string keys will be converted to keywords. If nils is truthy, null will become nil instead of the keyword :null.

(json/encode x &opt tab newline buf)

Encodes a janet value in JSON (utf-8). tab and newline are optional byte sequence which are used to format the output JSON. if buf is provided, the formated JSON is append to buf instead of a new buffer. Returns the modifed buffer.

(add m a)

Add a to matrix m where it can be matrix or scalar. Matrix m is mutated.

(add-to-mean m n v)

Adds new value v to mean m from n values.

(approx-eq a e &opt t)

Approximate equality between actual number a and expected number e. Default tolerance t is epsilon.

(bernoulli-distribution p)

Creates Bernoulli distribution from probability p in the tuple.

(binominal-coeficient n k)

Computes binominal coefficient from set of size n and sample size k.

(binominal-distribution t p)

Creates binominal distribution from trials t and probability p in the tuple.

(check-probability p)

Asserts that probability is in the [0 1] range.

Chi Squared distribution table.

(cols m)

Returns number of columns of matrix m.

(copy xs)

Deep copy an array or view xs.

(cumulative-std-normal-probability z)

Computes standard normal probability for y.

(det m)

Computes determinant of matrix m.

(dot v1 v2)

Dot product between two row vectors.

(dot-fast v1 v2)

Fast dot product between two row vectors of equal size.

Epsilon constant

(expand-m n m)

Embeds a matrix m inside an identity matrix of size n.

(extent xs)

Returns the minimum & maximum number in an xs as tuple.

(factor n)

Returns an array containing the prime factors of n.

(factorial n)

Returns factorial of n.

(fliplr m)

Flip a matrix leftside-right.

(flipud m)

Flip a matrix upside-down.

(geometric-mean xs)

Gets the geometric mean from xs.

(get-only-el m)

Convenience macro for geting first element from first row of the two dimensional array m.

(harmonic-mean xs)

Gets the harmonic mean from xs.

(ident c)

Creates identity matrix with c x c size.

(interquartile-range xs)

Gets the interquartile range from xs.

(math/invmod a m)

Modular multiplicative inverse of a mod m. Both arguments must be integer. The return value has the same type as m. If no inverse exists, returns math/nan instead.

(math/jacobi a m)

Computes the Jacobi Symbol (a|m).

(join-cols m1 m2)

Stack horizontally columns of two matrices.

(join-rows m1 m2)

Stack vertically rows of two matrices.

(linear-regression coords)

Computes the slope :m and y-intercept :b of the function in the struct from set of coordinates.

(linear-regression-line {:b b :m m})

Constructs function from struct returned by linear regression.

(m-approx= m1 m2 &opt tolerance)

Compares two matrices of equal size for equivalence within epsilon.

(matmul ma mb)

Matrix multiplication between matrices ma and mb. Does not mutate.

(median xs)

Gets the median value from xs

(median-absolute-deviation xs)

Gets median absolute deviation from xs.

(minor m x y)

Computes minor matrix of matrix m and x, y.

(mode xs)

Gets the mode value from xs.

(mop m op a)

Mutates every cell of the matrix m with op and corresponding cell from matrix arg a.

(mul m a)

Multiply matrix m with a which can be matrix or a list. Mutates m. A list a will be converted to column vector then multiplifed from the right as x * a.

(math/mulmod a b m)

Modular multiplication of a and b mod m. All arguments must be integer. The return value has the same type as m.

(next-prime n)

Returns the next prime number strictly larger than n.

(normalize-v xs)

Returns normalized vector of xs by Euclidian (L2) norm.

(outer v1 v2)

Outer product of vectors v1 and v2.

(perm m)

Computes permanent of the matrix m.

(permutation-test xs ys &opt a k)

Conducts a permutation test to determine if two data sets xs and ys are *significantly* different from each other. You can use alternative hypothesis a, which defaults to :two-side, with :greater and :lesser being the other two options. The last optional argument is k number of values in permutation distribution

(permutations s &opt k)

Returns permutations of length k from members of s

(poisson-distribution lambda)

Creates Poisson distribution from lambda in tuple.

(math/powmod a b m)

Modular exponentiation of a to the power of b mod m. All arguments must be integer. The return value has the same type as m.

(prime? n)

A primality test, deterministic for all n less than 2^63.

(primes)

A boundless prime number generator.

(qr m)

Stable and robust QR decomposition of a matrix. Decompose a matrix using Householder transformations. O(n^3).

(qr1 m)

Transform using Householder reflections by one step.

(quantile xs p)

Gets the quantile value from xs at p from unsorted population.

(quantile-rank xs p)

Gets the quantile rank of value v from unsorted xs.

(quantile-rank-sorted xs v)

Gets the quantile rank of value v from sorted xs.

(quantile-sorted xs p)

Gets the quantile value from xs at p from sorted population.

(quickselect arr k &opt left right)

Rearrange items in arr so that all items in [left, k] range are the smallest. The k-th element will have the (k - left + 1)-th smallest value in [left, right]. Mutates arr.

(relative-err a e)

Gets the relative err between actual number a and expected number e.

(root-mean-square xs)

Gets the root mean square from xs.

(row->col xs)

Transposes a row vector xs to col vector. Returns xs if it has higher dimensions.

(rows m)

Returns number of rows of matrix m.

(sample-correlation xs ys)

Gets the sample correlation between xs and ys.

(sample-covariance xs ys)

Gets the sample covariance between xs and ys.

(sample-skewness xs)

Gets the sample skeweness from the xs.

(sample-standard-deviation xs)

Gets sample standard deviation from xs.

(sample-variance xs)

Get the sample variance from xs.

(scalar c s)

Creates scalar s matrix with c x c size.

(scale v k)

Scale a vector v by a number k.

(shuffle-in-place xs)

Generate random permutation of the array xs which is shuffled in place.

(sign x)

Sign function.

(size m)

Returns tuple with the matrix m size [rows cols].

(slice-m m rslice cslice)

Slice a matrix m by rows and columns.

(sop m op & a)

Mutates every cell of the matrix m with op and variadic args a.

(squeeze m)

Concatenate a list of rows into a single row. Does not mutate m.

(standard-deviation xs)

Gets the standard deviation from ds.

Computed standard normal table.

(subtract v1 v2)

Elementwise subtract vector v2 from v1.

(sum-compensated xs)

Returns sum of the members of xs with Kahan-Babushka algorithm.

(sum-nth-power-deviations xs n)

Get the sum of deviations to the n power.

(svd m &opt n-iter)

Simple Singular-Value-Decomposition based on repeated QR decomposition. The algorithm converges at O(n^3).

(swap arr i j)

Swaps members with indices i and j of arr. Noop when i equals j.

(t-test xs expv)

Computes one sample t-test comparing the mean of xs to known value expv.

(t-test-2 xs ys &opt d)

Computes two sample t-test of two samples xs and ys with difference optional d which defaults to 0.

(trans m)

Tansposes a list of row vectors.

(unit-e n k)

Unit vector of n dimensions along dimension k.

(variance xs)

Get the variance from the xs.

(z-score x m d)

Gets the standard score for number x from mean m and standard deviation d.

(zero c &opt r)

Creates vector of length c, or matrix if r is provided, and fills it with zeros.

Dynamic binding to front matter of markup after parsing, compilation, and evaluation completes.

The htmlgen source that can be used to generate a document with htmlgen/html.

(add-loader)

Allow importing and requiring markup as a module

(anchor name & content)

Create an in-page anchor for a local link.

(bigger content)

Make span element with bigger font

(blockquote content)

Make a block quote element

(center content)

Center some content

(code content)

Make code element with class mendoza-code

(codeblock lang &opt source)

Inline code or codeblock

Make a div element

Make a em element

(hr)

Add a horizontal rule

(html source)

Embed some raw html

(image src alt)

Make an image element

Make a li element

(link url &opt content)

Create an anchor link

(markup source &opt env where)

Parse mendoza markup and evaluate it returning an htmlgen document tree.

(mdz-loader path &)

Loader for the mdz format

Make a ol element

Make a p element

Make a pre element

(section name content)

Create a section. Usually used to embed different parts of the content document into different parts of the main page.

(smaller content)

Make span element with smaller font

Make a strong element

Make a sub element

Make a sup element

(tag name content)

Wrap some content in an html tag. If you need attributes or other properties, you may want to use raw HTML via the html function.

Make a td element

Make a th element

Make a tr element

Make a u element

Make a ul element

(always x)

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

(antepenultimate xs)

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

(binary-search x arr &opt <?)

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

(binary-search-by x arr f)

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

(caperr & body)

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

(capout & body)

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

(cond-> val & clauses)

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

(cond->> val & clauses)

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

(dedent & xs)

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

(defs & bindings)

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

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

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

(do-def c d & body)

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

(do-var v d & body)

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

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

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

(gett ds & keyz)

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

(insert-sorted arr <? & xs)

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

(insert-sorted-by arr f & xs)

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

(int->string int &opt base)

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

(int/ & xs)

Perform integer division.

(log level & args)

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

(make prototype & pairs)

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

(make-id &opt prefix)

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

(map-keys f data)

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

(map-keys-flat f data)

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

(map-vals f data)

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

(merge-sorted a b &opt <?)

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

(merge-sorted-by a b f)

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

(penultimate xs)

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

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

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

(randomize-array arr &opt rng)

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

(second xs)

Get the second element from an indexed data structure.

(select-keys data keyz)

Returns new table with selected keyz from dictionary data.

(set* tgts exprs)

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

(string->int str &opt base)

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

(table-filter pred dict)

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

(third xs)

Get the third element from an indexed data structure.

(trim-prefix prefix str)

Trim the specified prefix of a string if it has one

(trim-suffix suffix str)

Trim the specified suffix of a string if it has one

(until cnd & body)

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

(vars & bindings)

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

(make-proto stream &opt pack unpack)

Create both a send an recv function from a stream, as with make-send and make-recv.

(make-recv stream &opt unpack)

Get a function that, when invoked, gets the next message from a readable stream. Provide an optional unpack function that will parse the received buffer.

(make-send stream &opt pack)

Create a function that when called with a msgs sends that msg. Provide an optional pack function that will convert a message to a string.

(client &opt host port name)

Connect to a repl server. The default host is "127.0.0.1" and the default port is "9365".

Default host to run server on and connect to.

Default port to run the net repl.

(server &opt host port env cleanup welcome-msg)

Start a repl server. The default host is "127.0.0.1" and the default port is "9365". Calling this will start a TCP server that exposes a repl into the given env. If no env is provided, a new env will be created per connection. If env is a function, that function will be invoked with the name and stream on each connection to generate an environment. cleanup is an optional function that will be called for each stream after closing if provided. welcome-msg is an optional string or function (welcome-msg client-name) to generate a message to print for the client on connection.

(server-single &opt host port env cleanup welcome-msg)

Short-hand for serving up a a repl that has a single environment table in it. env must be a proper env table, not a function as is possible in netrepl/server.

(posix/abspath path)

Coerce a path to be absolute.

(posix/abspath? path)

Check if a path is absolute.

(posix/basename path)

Gets the base file name of a path.

Platform delimiter

(posix/dirname path)

Gets the directory name of a path.

(ext path)

Get the file extension for a path.

(posix/join & els)

Join path elements together.

(posix/normalize path)

Normalize a path. This removes . and .. in the path, as well as empty path elements.

(posix/parts path)

Split a path into its parts.

(posix/abspath path)

Coerce a path to be absolute.

(posix/abspath? path)

Check if a path is absolute.

(posix/basename path)

Gets the base file name of a path.

Platform delimiter

(posix/dirname path)

Gets the directory name of a path.

(ext path)

Get the file extension for a path.

(posix/join & els)

Join path elements together.

(posix/normalize path)

Normalize a path. This removes . and .. in the path, as well as empty path elements.

(posix/parts path)

Split a path into its parts.

(posix/relpath source target)

Get the relative path between two subpaths.

Platform separator

(posix/relpath source target)

Get the relative path between two subpaths.

Platform separator

(win32/abspath path)

Coerce a path to be absolute.

(win32/abspath? path)

Check if a path is absolute.

(win32/basename path)

Gets the base file name of a path.

Platform delimiter

(win32/dirname path)

Gets the directory name of a path.

(ext path)

Get the file extension for a path.

(win32/join & els)

Join path elements together.

(win32/normalize path)

Normalize a path. This removes . and .. in the path, as well as empty path elements.

(win32/parts path)

Split a path into its parts.

(win32/relpath source target)

Get the relative path between two subpaths.

Platform separator

(hex->word hex position)

Returns pgp word for hex string <100

(hexs->words hex-string)

Returns an array of pgp words for arbitrary long string of hexs. Sanitizes out the whitespace from hex-string.

(word->hex word)

Returns a hex number as string for the pgp word.

Mapping from hex string < 100 to pgp words. One for odd and one for even position.

(words->hexs words-string)

Returns an array of hexs from the string with pgp words.

RNG used to generate random numbers

(rand-cdf cdf)

Pick a random index, weighted by a discrete cumulative distribution function.

(rand-cdf-path cdf & paths)

Execute one of the paths randomly given a discrete distribution as a CDF

(rand-gaussian &opt m sd)

Get a random sample from the standard Gaussian distribution. Optionall specify the mean m and the standard deviation sd.

(rand-index xs)

Get a random numeric index of an indexed data structure

(rand-int start end)

Get a random integer in a range [start, end) that is approximately uniformly distributed

(rand-path & paths)

Execute one of the paths randomly with uniform distribution

(rand-uniform)

Get a random number uniformly between 0 and 1

(rand-value xs)

Get a random value of an indexed data structure

(rand-weights weights)

Pick a random index given a set of weights

(rand-weights-path weights & paths)

Execute one of the paths randomly given a discrete distribution as a set of weights

(sample-n f n)

Generate n samples based on the random sampler f.

(set-seed seed)

Sets the RNG seed for execution

(weights-to-cdf weights)

Convert an array of weights to a discrete cdf that can be more efficiently used to take a weighted random choice

(rawterm/begin &opt on-winch)

Begin raw terminal functionality. Return a stream that can be read from to get input.

(rawterm/buffer-traverse bytes index delta &opt skip-zerowidth)

Move to a new position in a buffer from index by incrementing by delta codepoints. Can also skip zero-width codepoints if desired.

(rawterm/ctrl-z)

A handler that a user can use to handle ctrl-z from input to suspend the current process.

(rawterm/end)

End raw terminal functionality.

(rawterm/getch &opt into)

Get a byte of input from stdin, without blocking if possible. Returns a buffer.

(rawterm/isatty)

Check if the current stdin is a tty.

(rawterm/monowidth bytes &opt start-index end-index)

Measure the monospace width of a string.

(rawterm/rune-monowidth rune)

Get the monospace width of a rune. Returns either 0, 1, or 2.

(rawterm/size)

Get the number of rows and columns visible in the terminal as tuple [rows cols]

(rawterm/slice-monowidth bytes columns &opt start-index into)

Get a byte slice that will fit into a number of columns.

(compile pattern)

Compile a subset of regex to a PEG if pattern is a string. If pattern is a PEG, will return the PEG as is.

(find reg text &opt start)

Similar to peg/find, but for regexes.

(find-all reg text &opt start)

Similar to peg/find-all, but for regexes.

(match reg text &opt start)

Similar to peg/match, but for regexes.

Peg used to generate peg source code from a regular expression string.

(replace reg rep text &opt start)

Similar to peg/replace, but for regexes.

(replace-all reg rep text &opt start)

Similar to peg/replace-all, but for regexes.

(source pattern)

Compile a subset of regex to PEG source code.

(client &opt host port name)

Create an RPC client. The default host is "127.0.0.1" and the default port is "9366". Returns a table of async functions that can be used to make remote calls. This table also contains a :close function that can be used to close the connection.

Default host to run server on and connect to.

Default port to run the net repl.

(server functions &opt host port workers-per-connection)

Create an RPC server. The default host is "127.0.0.1" and the default port is "9366". Also must take a dictionary of functions that clients can call.

(make-predicate schema)

Generate a function that can be used to validate a data structure. This is the function form of predicate.

(make-validator schema)

Generate a function that can be used to validate a data structure. This is the function form of validator.

(predicate pattern)

Make a validation predicate given a certain schema.

(validator pattern)

Make a validation function of one argument. A validation function will throw an error on validation failure, otherwise, it will return the argument.

The currently running service manager, if there is one

The currently running service, if there is one

(add-service service-name main-function & args)

Spawn a service

(all-services)

Get a list of running services

(get-manager)

Get the current manager. If no manager exists, create one.

(get-service)

Get the current service. If not in a service, raise an error

(make-manager &opt log-dir)

Group a number of fibers into a single object for structured concurrency. Also includes utilities for running services like servers in the background.

(print-all &opt filter-fn)

Print a table of all running services.

(remove-service service-name)

Remove a service

(set-title title)

Set a textual description of the service to describe what it is doing currently

(start-service service-name)

Start or restart a service

(stop-service service-name &opt reason)

Stop a running service

(wait)

Once a number of services have been spawned, call wait to block the fiber until the manager is canceled. This lets a manager fiber behave as a service itself.

(copy src dest)

Copy a file or directory recursively from one location to another. Expects input to be unix style paths

(copy-file src-path dst-path)

Copy a file from source to destination. Creates all directories in the path to the destination file if they do not exist.

(create-dirs dir-path)

Create all directories in path specified as string including itself.

(devnull)

get the /dev/null equivalent of the current platform as an open file

(escape & args)

Output a string with all arguments correctly quoted

(exec & args)

Execute command specified by args returning its exit code

(exec-fail & args)

Execute command specified by args, fails when command exits with non-zero exit code

(exec-slurp & args)

It executes args with os/spawn and throws an error if the process returns with non-zero exit code. If the process exits with zero exit code, this function trims standard output of the process and returns it. Before the function finishes, the spawned process is closed for resource control.

(exec-slurp-all & args)

It executes args with os/spawn and returns a struct which has the following keys.

• :out - trimmed standard output of the process
• :err - trimmed standard error of the process
• :status - the exit code of the process

Before the function finishes, the spawned process is closed for resource control.

(exists? path)

Check if the given file or directory exists. (Follows symlinks)

(list-all-files dir &opt into)

List the files in the given directory recursively. Return the paths to all files found, relative to the current working directory if the given path is a relative path, or as an absolute path otherwise.

(make-new-file file-path &opt mode)

Create and open a file, creating all the directories leading to the file if they do not exist, and return it. By default, open as a writable file (mode is :w).

(rm path)

Remove a directory and all sub directories recursively.

(scan-directory dir func)

Scan a directory recursively, applying the given function on all files and directories in a depth-first manner. This function has no effect if the directory does not exist.

(split s)

Split a string into 'sh like' tokens, returns nil if unable to parse the string.

(lines stream &named separator)

Returns a fiber that yields each line from a core/stream value. If separator is not specified, the default separator is \n. After the fiber yields the last line, it returns nil. If the fiber is resumed after the stream is closed or after the fiber returns nil, an error is thrown.

(tarray/buffer array|size)

Return typed array buffer or create a new buffer.

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

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

(tarray/length array|buffer)

Return typed array or buffer size.

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

Create new typed array.

(tarray/properties array)

Return typed array properties as a struct.

(tarray/slice tarr &opt start end)

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

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

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

(all-tasks tasker &opt detailed)

Get an array of all task ids for which there is still data on disk. If detailed is truthy, return full task metadata instead of ids.

(cancel-task tasker task-id)

Cancel a queued or running task.

(close-queues tasker)

Prevent any tasks from being added to queues. When an executor finishes its current job, if there are any, it will terminate. When all executors complete, the call to run-executors will complete.

Default expiration time (1 day)

Default task priority

Default location of task records

Name of the file for logging errors

Maximum allowed priority (lower priority tasks will execute first)

Minimum allowed priority (lower priority tasks will execute first)

(new-tasker &opt task-directory queues queue-size)

Create queues and various settings to run tasks. Create a new tasker table.

Name of the file for general logging

(queue-task tasker argv &opt note priority qname timeout expiration input)

Add a task specification to a queue. Supply an argv string array that will be used to invoke a subprocess. The optional note parameter is just a textual note for task tracking. The priority parameter should be an integer between 0 and 9 inclusive, default is 4. Lower priority jobs in the same queue will be executed by higher priority. Use input to pass in generic, unstructured input to a task.

(run-cleanup tasker)

Delete old expired jobs saved on disk

(run-executors tasker &opt workers-per-queue pre-task post-task)

Start a number of executors to run tasks as with tasker/spawn-executors, and then wait for all executors to complete.

(spawn-executors tasker &opt qnames workers-per-queue pre-task post-task)

Start a number of executors to run tasks. Tasks can be added to a queue by calling queue-task. A single tasker object can make multiple calls to spawn-executors.

A tuple of all possible statuses that a task can have.

(task-file tasker task-id &opt file-name)

Get a log file for a path. By default, will get a path to out.log.

Name of the task metadata file

(task-status tasker task-id)

Look up the status of a given task by id.

(add-loader)

Adds the custom template loader to Janet's module/loaders and update module/paths.

Base environment for rendering

(compile str)

Compile a Temple template into a function which will return a rendered buffer.

The resulting function should receive the template arguments in the &keys format.

(create source &opt where)

Compile a template string into a function. Optionally provide a location where the source is from to improve debugging. Returns the template function.

(assert x &opt e)

Overrides the default assert with some nice error handling.

(assert-docs path)

Assert that all symbols have proper docstring when module on the path is required.

(assert-error msg & forms)

Test passes if forms error.

(assert-no-error msg & forms)

Test passes if forms do not error.

(assert-not x &opt e)

Invert assert.

(capture-stderr & body)

Runs the form and captures stderr. Returns tuple with result of the form and a string with captured stderr.

(capture-stdout & body)

Runs the form and captures stdout. Returns tuple with result of the form and a string with captured stdout.

(end-suite)

Ends test suite, prints summary and exits if any tests have failed.

(start-suite &opt name)

Starts test suite.

(suppress-stderr & body)

Suppreses stderr from the body

(suppress-stdout & body)

Suppreses stdout from the body

(timeit form &opt tag)

Time the execution of form using os/clock before and after, and print the result to stdout. Returns result of executing form. Uses tag (default "Elapsed time:") to tag the printout.

(timeit-loop head & body)

Similar to loop, but outputs performance statistics after completion. Additionally defines a :timeout verb to iterate continuously for a given number of seconds. If the first form of body is a bytes, it will be taken as a custom tag.

(utf8/decode-rune buf &opt start)

Read a UTF-8 encoded Unicode codepoint from the buffer which starts at the given index. Returns a tuple [value width], where width = number of bytes consumed. If at the end of buffer or the buffer contains malformed UTF-8, returns [nil 0].

(utf8/encode-rune rune &opt buf)

Encode a Unicode codepoint into the end of a buffer.

(utf8/prefix->width c)

Given the first byte in an UTF-8 sequence, get the number of bytes that the codepoint sequence takes up, including the prefix byte.

(zip/add-bytes writer path data &opt comment flags)

Add a byte sequence to the zip writer.

(zip/add-file writer path filename &opt comment flags)

Add a file to the zip writer.

(zip/compress bytes &opt level into)

Compress data and write to a buffer. Different compression levels can be used - higher compression levels trade smaller output with longer compression times. Returns into. If into not provided, a new buffer is created.

(zip/decompress bytes &opt into)

Decompress data and write to a buffer. If an into buffer is not provided, a new buffer will be created.

(zip/extract reader idx-or-filename &opt into flags)

Extract a file from the zip archive, either to memory or to a file on disk.

(zip/file-directory? reader idx)

Check if a file index is a directory.

(zip/file-encrypted? reader idx)

Check if a file is encrypted inside an archive.

(zip/file-supported? reader idx)

Check if a file is supported with this verstion of miniz.

(zip/get-filename reader idx)

Convert a file index index in the archive to a filename.

(zip/locate-file reader path &opt comment flags)

Get the index of a particular filename in the archive.

(zip/read-bytes bytes &opt flags)

Read a byte sequence as a zip archive. Returns a new zip reader.

(zip/read-file filename &opt flags)

Read a file as a zip archive. Returns a new zip reader.

(zip/reader-close reader)

Close a reader and free related memory.

(zip/reader-count reader)

Get the number of files inside the zip archive. The files can be indexed

(zip/stat reader idx)

Get stat information of file. Returns a new struct with the following fields:

• :index - integer index in master directory
• :version-made-by - zip verstion
• :version-needed - zip version needed to unzip
• :bit-flag
• :method - compression method
• :time - file time
• :crc32 - checksum of file contents
• :comp-size - size of file when compressed
• :uncomp-size - size of file when uncompressed
• :filename
• :comment
• :internal-attr
• :external-attr

(zip/version)

Get the version string of the underlying miniz library.

(zip/write-buffer)

Create a new zip archive writer that write to memory.

(zip/write-file dest-path)

Create a new zip archive writer that will write into an archive file.

(zip/writer-close writer)

Close a ZipWriter.

(zip/writer-finalizer writer)

Finalize a writer, writing any zip files to disk. Return the writer.