Radicle Reference

This is the radicle reference document, with documentation for all functions which come as part of the standard distribution.

Primitive functions

Primitive functions are those that are built into the compiler. They are available on all machines but may be shadowed by later definitions. Those that end in a ! are only available locally, not on ‘pure’ machines.

*

Multiplies two numbers together.

+

Adds two numbers together.

-

Substracts one number from another.

/

Divides one number by another. Throws an exception if the second argument is 0.

<

Checks if a number is strictly less than another.

>

Checks if a number is strictly greater than another.

eq?

Checks if two values are equal.

apply

Calls the first argument (a function) using as arguments the elements of the the second argument (a list).

show

Returns a string representing the argument value.

throw

Throws an exception. The first argument should be an atom used as a label for the exception, the second can be any value.

exit!

Exit the interpreter immediately with the given exit code.

read-annotated

(read-anotated label s) parses the string s into a radicle value. The resulting value is not evaluated. The label argument is a string which is used to annotate the value with line numbers.

read-many-annotated

(read-many-annotated label s) parses a string into a vector of radicle values. The resulting values are not evaluated. The label argument is a string which is used to annotate the values with line numbers.

base-eval

The default evaluation function. Expects an expression and a radicle state. Return a list of length 2 consisting of the result of the evaluation and the new state.

ref

Creates a ref with the argument as the initial value.

read-ref

Returns the current value of a ref.

write-ref

Given a reference r and a value v, updates the value stored in r to be v and returns v.

match-pat

The most basic built-in pattern-matching dispatch function.

cons

Adds an element to the front of a sequence.

first

Retrieves the first element of a sequence if it exists. Otherwise throws an exception.

rest

Given a non-empty sequence, returns the sequence of all the elements but the first. If the sequence is empty, throws an exception.

add-right

Adds an element to the right side of a vector.

<>

Merges two structures together. On vectors and lists this performs concatenation. On dicts this performs the right-biased merge.

list

Turns the arguments into a list.

list-to-vec

Transforms lists into vectors.

vec-to-list

Transforms vectors to lists.

zip

Takes two sequences and returns a sequence of corresponding pairs. In one sequence is shorter than the other, the excess elements of the longer sequence are discarded.

map

Given a function f and a sequence (list or vector) xs, returns a sequence of the same size and type as xs but with f applied to all the elements.

length

Returns the length of a vector, list, or string.

foldl

Given a function f, an initial value i and a sequence (list or vector) xs, reduces xs to a single value by starting with i and repetitively combining values with f, using elements of xs from left to right.

foldr

Given a function f, an initial value i and a sequence (list or vector) xs, reduces xs to a single value by starting with i and repetitively combining values with f, using elements of xs from right to left.

drop

Returns all but the first n items of a sequence, unless the sequence is empty, in which case an exception is thrown.

sort-by

Given a sequence xs and a function f, returns a sequence with the same elements x of xs but sorted according to (f x).

take

Returns the first n items of a sequence, unless the sequence is too short, in which case an exception is thrown.

nth

Given an integral number n and xs, returns the nth element (zero indexed) of xs when xs is a list or a vector. If xs does not have an n-th element, or if it is not a list or vector, then an exception is thrown.

seq

Given a structure s, returns a sequence. Lists and vectors are returned without modification while for dicts a vector of key-value-pairs is returned: these are vectors of length 2 whose first item is a key and whose second item is the associated value.

dict

Given an even number of arguments, creates a dict where the 2i-th argument is the key for the 2i+1th argument. If one of the even indexed arguments is not hashable then an exception is thrown.

lookup

Given a value k (the ‘key’) and a dict d, returns the value associated with k in d. If the key does not exist in d then () is returned instead. If d is not a dict then an exception is thrown.

insert

Given k, v and a dict d, returns a dict with the same associations as d but with k associated to d. If d isn’t a dict or if k isn’t hashable then an exception is thrown.

delete

Given k and a dict d, returns a dict with the same associations as d but without the key k. If d isn’t a dict then an exception is thrown.

member?

Given v and structure s, checks if x exists in s. The structure s may be a list, vector or dict. If it is a list or a vector, it checks if v is one of the items. If s is a dict, it checks if v is one of the keys.

map-keys

Given a function f and a dict d, returns a dict with the same values as d but f applied to all the keys. If f maps two keys to the same thing, the greatest key and value are kept.

map-values

Given a function f and a dict d, returns a dict with the same keys as d but f applied to all the associated values.

string-append

Concatenates a variable number of string arguments. If one of the arguments isn’t a string then an exception is thrown.

string-length

DEPRECATED Use length instead. Returns the length of a string.

string-replace

Replace all occurrences of the first argument with the second in the third.

foldl-string

A left fold on a string. That is, given a function f, an initial accumulator value init, and a string s, reduce s by applying f to the accumulator and the next character in the string repeatedly.

type

Returns a keyword representing the type of the argument; one of: :atom, :keyword, :string, :number, :boolean, :list, :vector, :function, :dict, :ref.

atom?

Checks if the argument is a atom.

keyword?

Checks if the argument is a keyword.

boolean?

Checks if the argument is a boolean.

string?

Checks if the argument is a string.

number?

Checks if the argument is a number.

integral?

Checks if a number is an integer.

vector?

Checks if the argument is a vector.

list?

Checks if the argument is a list.

dict?

Checks if the argument is a dict.

file-module!

Given a file whose code starts with module metadata, creates the module. That is, the file is evaluated as if the code was wrapped in (module ...).

find-module-file!

Find a file according to radicle search path rules. These are: 1) If RADPATH is set, first search there; 2) If RADPATH is not set, search in the distribution directory 3) If the file is still not found, search in the current directory.

import

Import a module, making all the definitions of that module available in the current scope. The first argument must be a module to import. Two optional arguments affect how and which symbols are imported. (import m :as 'foo) will import all the symbols of m with the prefix foo/. (import m '[f g]) will only import f and g from m. (import m '[f g] :as 'foo') will import f and g from m as foo/f and foo/g. To import definitions with no qualification at all, use (import m :unqualified).

pure-state

Returns a pure initial radicle state. This is the state of a radicle chain before it has processed any inputs.

get-current-state

Returns the current radicle state.

set-current-state

Replaces the radicle state with the one provided.

get-binding

Lookup a binding in a radicle env.

set-binding

Add a binding to a radicle env.

set-env

Sets the environment of a radicle state to a new value. Returns the updated state.

state->env

Extract the environment from a radicle state.

timestamp?

Returns true if the input is an ISO 8601 formatted CoordinatedUniversal Time (UTC) timestamp string. If the input isn’t a string, an exception is thrown.

unix-epoch

Given an ISO 8601 formatted Coordinated Universal Time (UTC) timestamp, returns the corresponding Unix epoch time, i.e., the number of seconds since Jan 01 1970 (UTC).

from-unix-epoch

Given an integer the represents seconds from the unix epock return an ISO 8601 formatted Coordinated Universal Time (UTC) timestamp representing that time.

now!

Returns a timestamp for the current Coordinated Universal Time (UTC), right now, formatted according to ISO 8601.

to-json

Returns a JSON formatted string representing the input value.

uuid!

Generates a random UUID.

uuid?

Checks if a string has the format of a UUID.

default-ecc-curve

Returns the default elliptic-curve used for generating cryptographic keys.

verify-signature

Given a public key pk, a signature s and a message (string) m, checks that s is a signature of m for the public key pk.

public-key?

Checks if a value represents a valid public key.

gen-key-pair!

Given an elliptic curve, generates a cryptographic key-pair. Use default-ecc-curve for a default value for the elliptic curve.

gen-signature!

Given a private key and a message (a string), generates a cryptographic signature for the message.

get-args!

Returns the list of the command-line arguments the script was called with

put-str!

Prints a string.

get-line!

Reads a single line of input and returns it as a string.

load!

Evaluates the contents of a file. Each seperate radicle expression is evaluated according to the current definition of eval.

cd!

Change the current working directory.

stdin!

A handle for standard in.

stdout!

A handle for standard out.

stderr!

A handle for standard error.

read-file!

Reads the contents of a file and returns it as a string.

read-line-handle!

Read a single line from a handle. Returns the string read, or the keyword :eof if an EOF is encountered.

open-file!

Open file in the specified mode (:read, :write, :append, :read-write).

close-handle!

Close a handle

system!

(system! proc) execute a system process. Returns the dict with the form { :stdin maybe-handle      :stdout maybe-handle      :stderr maybe-handle      :proc prochandle    } Where maybe-handle is either [:just handle] or :nothing. Note that this is quite a low-level function; higher-level ones are more convenient.

wait-for-process!

Block until process terminates.

write-handle!

Write a string to the provided handle.

subscribe-to!

Expects a dict s (representing a subscription) and a function f. The dict s should have a function getter at the key :getter. This function is called repeatedly (with no arguments), its result is then evaluated and passed to f.

doc

Returns the documentation string for a variable. To print it instead, use doc!.

doc!

Prints the documentation attached to a value and returns (). To retrieve the docstring as a value use doc instead.

apropos!

Prints documentation for all documented variables in scope.

Prelude modules

These are the modules included in the radicle prelude and the functions these modules expose.

prelude/basic

Basic function used for checking equality, determining the type of a value, etc.

(or x y)

Returns x if x is not #f, otherwise returns y

(some xs)

Checks that there is a least one truthy value in a list.

(empty-seq? xs)

Returns true if xs is an empty sequence (either list or vector).

length

Returns the length of a vector, list, or string.

(maybe->>= v f)

Monadic bind for the maybe monad.

(maybe-foldlM f i xs)

Monadic fold over the elements of a sequence xs, associating to the left (i.e. from left to right) in the maybe monad.

(elem? x xs)

Returns true if x is an element of the sequence xs

tail

Backwards compatible alias for rest.

(read s)

Reads a radicle value from a string.

(read-many s)

Reads many radicle values from a string.

prelude/patterns

Pattern matching is first-class in radicle so new patterns can easily be defined. These are the most essential.

(match-pat pat v)

The pattern matching dispatch function. This function defines how patterns are treated in match expressions. Atoms are treated as bindings. Numbers, keywords and strings are constant patterns. Dicts of patterns match dicts whose values at those keys match those patterns. Vectors of patterns match vectors of the same length, pairing the patterns and elements by index.

(_ v)

The wildcard pattern.

(/? p)

Predicate pattern. Takes a predicate function as argument. Values match against this pattern if the predicate returns a truthy value.

(/as var pat)

As pattern. Takes a variable and a sub-pattern. If the subpattern matches then the whole pattern matches and furthermore the variable is bound to the matched value.

(/cons x-pat xs-pat)

A pattern for sequences with a head and a tail.

(/nil v)

Empty-sequence pattern. Matches [] and (list)

(/just pat)

Pattern which matches [:just x].

(/member vs)

Matches values that are members of a structure.

prelude/strings

String manipulation functions.

(intercalate sep strs)

Intercalates a string in a list of strings

(unlines x)

Concatenate a list of strings, with newlines in between.

(unwords x)

Concatenate a list of strings, with spaces in between.

(split-by splitter? xs)

Splits a string xs into a list of strings whenever the function splitter? returns true for a character.

(words xs)

Splits a string xs into a list of strings by whitespace characters.

(lines xs)

Splits a string xs into a list of strings by linebreaks.

(map-string f xs)

Returns a string consisting of the results of applying f to each character of xs. Throws a type error if f returns something other than a string

prelude/dict

Functions for manipualting dicts.

(dict-from-seq xs)

Creates a dictionary from a list of key-value pairs.

(keys d)

Given a dict d, returns a vector of its keys.

(values d)

Given a dict d, returns a vector of its values.

(rekey old-key new-key d)

Change the key from old-key to new-key in a dict d. If new-key already exists, it is overwritten.

(modify-map k f d)

Given a key k, a function f and a dict d, applies the function to the value associated to that key.

(delete-many ks d)

Delete several keys ks from a dict d.

(lookup-default key default dict)

Like lookup but returns default if the key is not in the map.

(lookup-maybe key dict)

Like lookup but returns [:just x] if the key is not in the map and :nothing otherwise.

prelude/io

Some basic I/O functions.

(shell! command to-write)

Executes command using the shell with to-write as input. Stdout and stderr are inherited. WARNING: using shell! with unsanitized user input is a security hazard! Example: (shell! "ls -Glah" "").

(process! command args to-write)

Executes command using execvp with to-write as input. Stdout and stderr are inherited. See man exec for more information on execvp. Example: (process! "ls" ["-Glah"] "").

(read-line!)

Read a single line of input and interpret it as radicle data.

(read-file-value! file)

Read a single radicle value from a file.

(read-file-values! file)

Read many radicle values from a file.

(shell-with-stdout! command to-write)

Like shell!, but captures the stdout and returns it.

(shell-no-stdin! command to-write)

Like shell!, but inherits stdin. WARNING: using shell! with unsanitized user input is a security hazard! Example: (shell-no-stdin! "ls -Glah").

(process-with-stdout! command args to-write)

Like process!, but captures stdout.

(write-file! filename contents)

Write contents to file filename.

(init-file-dict! file)

Initiate a file with an empty dict, but only if the file doesn’t already exist.

(read-file-key! file k)

Read a file key. Assumes that the file contents is a serialised dict.

(write-file-key! file k v)

Write a key to a file. Assumes that the file contents is a serialised dict.

(ls!)

List the contents of the current working directory

(modify-file! file f)

Modified the value stored in a file according to the function f.

(install-fake-filesystem! files)

Installs a fake for read-file! that simulates the presence of files in the files dictionary.

If (read-file! path) is called andpathis a key infilesthen the value fromfilesis returned. Otherwise the originalread-file!` is used.

This requires the prelude/test/primitive-stub script to be loaded.

(process-with-stdout-stderr-exitcode! command args to-write)

Like process-with-stdout!, but returns a vec [stdout stderr exitcode].

(prompt! prompt)

Ask for user input with a prompt.

prelude/bool

Functions for dealing with truthiness and #f.

(not x)

True if x is #f, false otherwise.

(and x y)

Returns y if x is not #f, otherwise returns x

(all xs)

Checks that all the items of a list are truthy.

prelude/exception

Tests for exceptions.

prelude/list

Functions for creating lists. See also prelude/seq.

nil

The empty list.

(range from to)

Returns a list with all integers from from to to, inclusive.

prelude/seq

Functions for manipulating sequences, that is lists and vectors.

(empty? seq)

True if seq is empty, false otherwise.

(seq? x)

Returns #t if x is a list or a vector.

(reverse xs)

Returns the reversed sequence xs.

(filter pred ls)

Returns ls with only the elements that satisfy pred.

(take-while pred ls)

Returns all elements of a sequence ls until one does not satisfy pred

(starts-with? s prefix)

Returns #t if prefix is a prefix of the sequence s. Also works for strings

(/prefix prefix rest-pat)

Matches sequences that start with prefix and bind the rest of that sequence to rest-pat. Also works for strings.

prelude/set

Sets, built using dicts.

empty

An empty set.

(insert x s)

Insert a value into a set.

(delete x s)

Delete a value from a set.

member?

Query if a value is an element of a set.

(to-vec s)

Convert a set to a vector.

(from-seq xs)

Create a set from a sequence.

(key-set d)

The set of keys of a dict.

(subset? xs ys)

Checks if xs is a subset of ys.

prelude/ref

Functions for dealing with reference cells.

(modify-ref r f)

Modify r by applying the function f. Returns the new value.

prelude/lens

Functional references.

(make-lens g s)

Makes a lens out of a getter and a setter.

(view lens target)

View a value through a lens.

(set lens new-view target)

Set a value though a lens.

id-lens

The identity lens.

(.. lens1 lens2)

Compose two lenses.

(... lenses)

Compose multiple lenses.

(over lens f target)

Modify a value through a lens.

(@ k)

Returns a lens targetting keys of dicts.

(@def k default)

Returns a lens targetting keys of dicts with a default value for getting if the key does not exist in the target.

(@nth n)

Lenses into the nth element of a vector

(view-ref r lens)

Like view, but for refs.

(set-ref r lens v)

Like set, but for refs.

(over-ref r lens f)

Like over, but for refs.

prelude/key-management

Providing functions for creating and reading key pairs for signing send commands. Per default, key pairs are stored in $HOME/.config/radicle/my-keys.rad this can be adjusted by setting $XDG_CONFIG_HOME.

(read-keys!)

Reads the keys stored in my-keys.rad or returns :nothing if the file doesn’t exist.

(create-keys!)

Creates a new key pair and stores it in my-keys.rad. Returns the full absolute path of the created file.

(use-fake-keys!)

Bypass reading the keys from my-keys.rad. This is intended for testing.

prelude/machine

Functions for simulating remote machines.

(eval expr state)

Evaluation function that adds :test macro to register tests.

(updatable-eval sub-eval)

Given an evaluation function f, returns a new one which augments f with a new command (update expr) which evaluates arbitrary expression using base-eval.

(eval-fn-app state f arg cb)

Given a state, a function, an argument and a callback, returns the result of evaluating the function call on the arg in the given state, while also calling the callback on the result.

(send-prelude! machine-id)

Send the pure prelude to a machine.

(new-machine!)

Creates a new machine. Returns the machine name.

(send-code! machine-id filename)

Send code from a file to a remote machine.

(send! machine-id inputs)

Update a machine with the vector of inputs to evaluate. Returns a vector with the evaluation results.

(query! machine-id expr)

Send an expression to be evaluated on a machine. Does not alter the machine.

(install-remote-machine-fake)

Install test doubles for the send!, query!, and new-machine! primitives that use a mutable dictionary to store RSMs. Requiresrad/test/stub-primitives` to be loaded

(send-signed-command! machine machine-id cmd payload)

Send a command signed by the keys in my-keys.rad.

(catch-daemon! f)

Catches all radicle-daemon related errors and just prints them out to the user.

prelude/state-machine

An eval for running a state-machine with an updatable transition function.

prelude/validation

Functions for creating or combining validators, which are functions which return the input unchanged or throw with an error message. These can be used for checking data before accepting it onto a chain.

(= x)

Given x, returns a validator that checks for equality with x.

(member xs)

Given a structure, returns a validator which checks for membership in the structure.

(and vs)

Given a sequence of validators vs, returns a new validator which, given a value, checks if it conforms to all the validators in vs.

(or vs)

Given a vector of validators vs, returns a new validator which, given a value, checks if it conforms to at least one of the vs.

(type t)

Checks that a value has a type. Expects a keyword describing the type, as returned by the type function.

(pred name p)

Given a description and a predicate, returns a validator that checks if the predicate is true.

(integral n)

Validator for whole numbers.

(optional-key k v)

Given a key k and a validator v, returns a validator which checks that the value associated to k in a dict conforms to v. If the key is absent, the validator passes.

(contains k)

Given a value, returns a validator which checks for membership of that value.

(contains-all ks)

Given a vector of keys, returns a validator which checks that a structure contains all of them.

(contains-only ks)

Validator which checks that a dict only contains a subset of a vector of keys.

(key k v)

Combines existence and validity of a key in a dict.

(optional-keys ks)

Given a dict associating keys to validators, returns a validator which checks that the values associated to those keys in a dict conform to the corresponding validators.

(keys d)

Given a dict d, returns a validator which checks that a dict contains all the keys that d does, and that the associated values a valid according to the associated validators.

(every v)

Given a validator, creates a new validator which checks that all the items in a sequence conform to it.

(uuid x)

Validates UUIDs.

(signed x)

Checks that a value is a dict with :signature and :author keys, and that the signature is valid for the rest of the dict for that author. The rest of the dict is turned into a string according to show.

(timestamp x)

A validator which checks if a string is an ISO 8601 formatted Coordinated Universal Time (UTC) timestamp.

(string-of-max-length max-len)

A validator which checks that it’s argument is a string and less than the specified length.

prelude/util

Utility functions. For the moment just a counter.

(make-counter)

Creates a stateful counter. Returns a dict with two keys: the function at :next-will-be will return the next number (without incrementing it), while the function at :next increments the number and returns it.