SHADOWLISP(5)

NAME
shadowlisp - a simple lisp dialect for writing shadowenv programs

SYNOPSIS
Shadowlisp is a simple Lisp dialect. It is a Lisp-1, meaning that all data types (functions and variables, notably) share a single namespace. To express nil/null/no-value in Shadowlisp, use an empty list (). This will be important to clear environment variables.

Environment Manipulation

  (env/get name)
The simplest function to interact with the environment is env/get. It returns the current value of the variable at the point in the script at which it's evaluated, not the initial value. If the variable has no current value, () is returned instead of a String.

name
    (String) Name of environment variable to look up

Return
    (Option<String>) Current value of variable, or () if unset

  (env/set name value)
The simplest form of mutation: env/set changes the value of an environment variable while a Shadowenv is active. The previous value will be preserved so that it can be reactivated upon deactivating the Shadowenv.

name
    (String) Name of environment variable to change

value
    (Option<String>) String to set the variable to, or () to unset it.

Return
    (None) Always returns ()

  (env/prepend-to-pathlist name entry)
It's common to want to prepend an item to a :-delimited path (such as PATH or MANPATH). env/prepend-to-pathlist does precisely this, first removing the item from the path if it was already present, before prepending it to the front of the pathlist. Strictly speaking, any variable can be treated as a pathlist by Shadowenv, but it only makes sense to do this for variables that other tools expect to contain multiple items. If there are no items in the list currently, env/prepend-to-pathlist will simply create the list with a single item.

name
    (String) Name of environment variable to change

entry
    (String) String to prepend

Return
    (None) Always returns ()

  (env/append-to-pathlist name entry)
While less common than prepending, it's sometimes desirable to append an item to a :-delimited path (such as PATH or MANPATH), to add it as a lower priority option. env/append-to-pathlist does precisely this, first removing the item from the path if it was already present, before appending it to the end of the pathlist. Strictly speaking, any variable can be treated as a pathlist by Shadowenv, but it only makes sense to do this for variables that other tools expect to contain multiple items. If there are no items in the list currently, env/append-to-pathlist will simply create the list with a single item.

name
    (String) Name of environment variable to change

entry
    (String) String to append

Return
    (None) Always returns ()

  (env/remove-from-pathlist name entry)
The counterpart to env/prepend-to-pathlist/env/append-to-pathlist is this, env-remove-from-pathlist. This won't be as useful, since Shadowenv always takes care of its own deactivation, but you may occasionally want to deactivate certain system-wide configuration upon entry into a Shadowenv. If, after removing the indicated item from the specified pathlist, the variable becomes empty, it is unset (equivalent to (env/set var ())).

name
    (String) Name of environment variable to change

entry
    (String) String to remove from pathlist

Return
    (None) Always returns ()

  (env/remove-from-pathlist-containing name substring)
A specialized version of env/remove-from-pathlist, env-remove-from-pathlist-containing will remove any items from the pathlist which contain the provided value as a substring.

name
    (String) Name of environment variable to change

substring
    (String) Remove pathlist items containing this as a substring

Return
    (None) Always returns ()

Utilities

  (path-concat [ strings ... ])
It's occasionally useful to take a subdirectory of a path found from some other variable. path-concat joins two or more strings (representing directories) with slashes.

:rest strings
    (String) Any number of strings to conjoin with /

Return
    (String) Joined path

  (expand-path path)
expand-path resolves a path to a canonicalized path, resolving any symlinks, relative references from the present working directory, and ~.

path
    (String) Path to expand

Return
    (String) Expanded path

  (provide feature [ version ])
Allows a script to advertise to the user which feature it is providing, with an optional version number. Multiple features with the same are allowed.

feature
    (String) Name of the provided feature

version
    (String) Version of the provided feature. Optional.

Return
    (None) Always returns ()

Control Flow

  (when condition [ then ... ])
when tests a condition, evaluating the rest of its forms if and only if the condition is true.

condition
    (Expr) If it evaluates to non-(), run *then*

:rest then
    (Expr) Evaluated if *condition* was true

Return
    (Any) Whatever the return value of the last form in *then* was

  (when-let ( ( name expression ) ) [ body ... ])
when-let evaluates some code if and only if a let binding, when run, assigns a non-() value to the name.

name
    (String) Name to assign

expression
    (Any) Value to assign to name

:rest body
    (Expr) Evaluated if *name* was assigned to something non-()

Return
    (Any) Whatever the return value of the last form in *body* was

  (if condition then-case [ else-case ])
The if operator evaluates its first argument, then evaluates only one of the given branches, depending on the result. The "else" branch may be omitted, in which case, if will yield () when the condition is false.

  (cond [ ( predicate branch ) ... ] [ ( else else-branch ) ] )
The cond operator evaluates a series of predicates and executes the branch for the first predicate which evaluates to true. The name else may be used for the last case, as a catch-all branch.

  (do [ expressions ... ])
The do operator executes multiple expressions and yields the value of the final expression. Useful for forms like let, which only accept one form to evaluate.

:rest expressions
    (Expr) Always evaluated

Return
    (Any) Whatever the return value of the last form in *expressions* was

Logic

  (eq a b)
Test whether two values are (weakly) equal. Shadowlisp does not support strict equality semantics.

  (ne a b)
Test whether two values are (weakly) unequal. Shadowlisp does not support strict equality semantics.

  (not a)
Boolean negation.

  (null expr)
Returns true if and only if the provided argument is ().

  (and [ expression ... ])
and evaluates its arguments, applying logical AND short-circuiting rules.

  (or [ expression ... ])
or evaluates its arguments, applying logical OR short-circuiting rules.

Lists

  (append list value)
append appends a value to a list.

  (elt list n)
elt returns the nth element of a list.

  (concat [ list ... ])
concat concatenates each given list value.

  (join sep [ list ... ])
join joins together a series of lists using the first argument as separator.

  (first list)
first returns the first element of a list.

  (last list)
last returns the last element of a list.

  (tail list)
tail returns all elements after the first element of a list.

  (list [ expr ... ])
list evaluates each of its arguments and return them as a list.

Functions and Macros

  (define name expression)
The define operator adds a value or compiled function to the global scope. When defining a function, if the keyword :optional is present in the argument list, all following arguments will be optional. If the keyword :key is present, all following arguments will be optional keyword arguments. If the keyword :rest is present, the following name will contain any free arguments remaining. Optional and keyword arguments may be omitted when calling a function. If an optional or keyword value is not supplied its value will be (). A default value can be given when the function is defined.

  (macro (name [ arguments ... ]) expression)
The macro operator defines a compile-time macro. A macro behaves in all respects as any other function, except that it is executed at compile time and is expected to return code which is then further compiled.

  (lambda ( [ arguments ... ] ) expression)
The lambda operator creates a function which may enclose one or more local value bindings from the surrounding scope.

  (apply function [ arguments ... ] argument-list)
The apply operator calls a function with a given series of arguments. The argument list consists of any positional arguments except for the last argument to apply, plus the final, required list argument, which is concatenated to positional arguments.

  (let ( [ ( name expression ) ... ] ) body)
The let operator defines a series of local bindings for the duration of the execution of its body expression.