SHADOWLISP(5)

💖 SHADOWLISP(5): a simple lisp dialect for writing shadowenv programs 💖

okay bestie, welcome to SHADOWLISP(5) from the File Formats Manual — it's the page for shadowlisp, a simple lisp dialect for writing shadowenv programs. Tiny Lisp, main-character energy, let's go. 🦋✨

✨ NAME ✨

shadowlisp — a simple lisp dialect for writing shadowenv programs. That's the whole description, and honestly? Iconic. 💅

🌸 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. One namespace, no cap. 💜

To express nil/null/no-value in Shadowlisp, use an empty list (). This will be important to clear environment variables. Remember it, bestie — () is the vibe check for "no value." 🫶

---

🦋 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. Yes: current value at evaluation time, not the OG 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. It remembers the old value for deactivation. 🎀

• 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. No duplicates before the glow-up. ✨

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. Lower priority, still cute. 🌸

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. System-wide config said bye for now. 👋

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. Substring match, not exact match. 🧚

• 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. Path glue, basically. 🎀

• :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 relative references from the present working directory and ~. Canonicalized and cozy. ✨

• 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. Advertise your feature, bestie. 📣

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. If true, do the rest. ✅

• 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. Binding got a value? Then body runs. 🦋

• 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. One branch only. Pick a lane. 💅

🧚 (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. Catch-all energy at the end. 🌸

🧚 (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. Multiple forms, one final value. ⭐

• :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. Weak equality only, no strictness here. 🫶

🧚 (ne a b)

Test whether two values are (weakly) unequal. Shadowlisp does not support strict equality semantics. Weak inequality, same deal. 💅

🧚 (not a)

Boolean negation. Flip it. 🔁

🧚 (null expr)

Returns true if and only if the provided argument is (). Is it ()? That's the whole question. 🧚

🧚 (and [ expression ... ])

and evaluates its arguments, applying logical AND short-circuiting rules. Short-circuit slay. ⚡

🧚 (or [ expression ... ])

or evaluates its arguments, applying logical OR short-circuiting rules. Short-circuit again, but OR. 🌈

🍓 Lists 🍓

🧚 (append list value)

append appends a value to a list. Add it to the end. 🍓

🧚 (elt list n)

elt returns the nth element of a list. Indexed and ready. 🔢

🧚 (concat [ list ... ])

concat concatenates each given list value. All the lists, joined up. 🧚

🧚 (join sep [ list ... ])

join joins together a series of lists using the first argument as separator. Separator first, lists after. ✨

🧚 (first list)

first returns the first element of a list. First! 👑

🧚 (last list)

last returns the last element of a list. Last but not least. 💖

🧚 (tail list)

tail returns all elements after the first element of a list. Everything after the first. 🦋

🧚 (list [ expr ... ])

list evaluates each of its arguments and return them as a list. Evaluate, then bundle into a list. 🎀

👑 Functions and Macros 👑

🧚 (define name expression)

The define operator adds a value or compiled function to the global scope. Global scope said hello. 👑

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. Defaults are optional-arg besties. 🫶

🧚 (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. Compile-time behavior, then more compiling. ⚡

🧚 (lambda ( [ arguments ... ] ) expression)

The lambda operator creates a function which may enclose one or more local value bindings from the surrounding scope. Function with surrounding-scope bindings in its bag. 🎀

🧚 (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. Last arg is a required list, and it gets concatenated. 💅

🧚 (let ( [ ( name expression ) ... ] ) body)

The let operator defines a series of local bindings for the duration of the execution of its body expression. Local bindings, temporary era. ✨

---

That's the whole SHADOWLISP(5) page, bestie! 🫶 The original footer didn't give a source/version or date — just the manual name again — so here's your cute sign-off instead: slay, go write some shadowenv programs, and may your env vars always be exactly what you meant. 💖✨