Shadowenv

https://shopify.github.io/shadowenv/
Admin
Shadowenv is a tool that performs project-local environment variable shadowing, automatically...
Tokens:4,442
Snippets:72
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example of a complex Shadowlisp program

Source: https://shopify.github.io/shadowenv/shadowlisp

Demonstrates environment variable manipulation using conditional bindings and path list modifications.

```lisp
(when-let ((rroot (env/get "RUBY_ROOT")))
 (env/remove-from-pathlist "PATH" (path-concat rroot "bin"))
 (when-let ((groot (env/get "GEM_ROOT")))
   (env/remove-from-pathlist "PATH" (path-concat groot "bin"))
   (env/remove-from-pathlist "GEM_PATH" groot))
 (when-let ((ghome (env/get "GEM_HOME")))
   (env/remove-from-pathlist "PATH" (path-concat ghome "bin"))
   (env/remove-from-pathlist "GEM_PATH" ghome)))
```

--------------------------------

### Advertise features with provide

Source: https://shopify.github.io/shadowenv/shadowlisp

Advertises a feature and an optional version to the user. Multiple features can be provided.

```lisp
(provide "ruby") ; activated shadowenv (ruby)
(provide "ruby" "2.3.7") ; activated shadowenv (ruby:2.3.7)
```

--------------------------------

### Prepend to a pathlist with env/prepend-to-pathlist

Source: https://shopify.github.io/shadowenv/shadowlisp

Removes the entry if present, then prepends it to the front of a colon-delimited pathlist.

```lisp
(env/prepend-to-pathlist "PATH" "/opt/mytool/bin") ; ()
```

--------------------------------

### Configure nested Shadowenv inheritance

Source: https://shopify.github.io/shadowenv/getting-started

Create a symlink named 'parent' within a .shadowenv.d directory to inherit environment configurations from a higher-level directory.

```bash
ln -s /a/.shadowenv.d /a/b/c/.shadowenv.d/parent
```

--------------------------------

### provide

Source: https://shopify.github.io/shadowenv/shadowlisp

Advertises a feature and optional version to the user.

```APIDOC
## (provide feature [ version ])

### Description
Allows a script to advertise to the user which feature it is providing, with an optional version number.

### Parameters
- **feature** (String) - Required - Name of the provided feature.
- **version** (String) - Optional - Version of the provided feature.

### Returns
- **None** - Always returns ().
```

--------------------------------

### Execute scripts with shadowenv exec

Source: https://shopify.github.io/shadowenv/getting-started

Use this command to load Shadowenv environments from the current directory and its ancestors before running a specific program.

```bash
#!/bin/sh
cd /path/to/thing/with/dot-shadowenv

shadowenv exec -- nginx -g 'daemon off;'
```

--------------------------------

### env/prepend-to-pathlist

Source: https://shopify.github.io/shadowenv/shadowlisp

Prepends an entry to a colon-delimited pathlist variable.

```APIDOC
## (env/prepend-to-pathlist name entry)

### Description
Prepends an item to a colon-delimited path variable. If the item is already present, it is removed before being prepended to the front.

### Parameters
- **name** (String) - Required - The name of the environment variable to change.
- **entry** (String) - Required - The string to prepend.

### Returns
- **None** - Always returns ().
```

--------------------------------

### expand-path

Source: https://shopify.github.io/shadowenv/shadowlisp

Resolves a path to a canonicalized path, handling relative references and home directory shortcuts.

```APIDOC
## (expand-path path)

### Description
Resolves a path to a canonicalized path, resolving relative references from the present working directory and '~'.

### Parameters
- **path** (String) - Required - Path to expand.

### Returns
- **String** - The expanded, canonicalized path.
```

--------------------------------

### path-concat

Source: https://shopify.github.io/shadowenv/shadowlisp

Joins two or more strings representing directories with slashes.

```APIDOC
## (path-concat [ strings ... ])

### Description
Joins two or more strings (representing directories) with slashes. This is useful for taking a subdirectory of a path found from another variable.

### Parameters
- **strings** (String) - Required - Any number of strings to conjoin with '/'.

### Returns
- **String** - The joined path.
```

--------------------------------

### env/get

Source: https://shopify.github.io/shadowenv/shadowlisp

Retrieves the current value of an environment variable.

```APIDOC
## (env/get name)

### Description
Returns the current value of the environment variable. If the variable is unset, it returns an empty list ().

### Parameters
- **name** (String) - Required - The name of the environment variable to look up.

### Returns
- **Option<String>** - The current value of the variable, or () if unset.
```

--------------------------------

### env/set

Source: https://shopify.github.io/shadowenv/shadowlisp

Sets the value of an environment variable.

```APIDOC
## (env/set name value)

### Description
Changes the value of an environment variable while a Shadowenv is active. The previous value is preserved for restoration upon deactivation.

### Parameters
- **name** (String) - Required - The name of the environment variable to change.
- **value** (Option<String>) - Required - The string to set the variable to, or () to unset it.

### Returns
- **None** - Always returns ().
```

--------------------------------

### Append to a pathlist with env/append-to-pathlist

Source: https://shopify.github.io/shadowenv/shadowlisp

Removes the entry if present, then appends it to the end of a colon-delimited pathlist.

```lisp
(env/append-to-pathlist "PATH" "/opt/mytool/bin") ; ()
```

--------------------------------

### Expand paths with expand-path

Source: https://shopify.github.io/shadowenv/shadowlisp

Resolves relative paths and tilde references to their canonical absolute paths.

```lisp
(expand-path "~/.gem") ; "/Users/you/.gem"
(expand-path "./bin") ; "/Users/you/src/project/bin"
```

--------------------------------

### Retrieve environment variables with env/get

Source: https://shopify.github.io/shadowenv/shadowlisp

Returns the current value of an environment variable. Returns () if the variable is unset.

```lisp
(env/get "PATH")  ; "/usr/bin:/usr/sbin:/bin:/sbin"
(env/get "DEBUG") ; () -- not set => null
```

--------------------------------

### Trust a shadowenv directory

Source: https://shopify.github.io/shadowenv/getting-started

Command to mark the current shadowenv directory as trusted, allowing the execution of contained Shadowlisp programs.

```bash
shadowenv trust
```

--------------------------------

### Sequential expression evaluation with do

Source: https://shopify.github.io/shadowenv/shadowlisp

Executes multiple expressions and returns the value of the final one.

```lisp
(let ((a b) (c d))
  (do ; necessary in order to call both (f a) and (f c)
    (f a)
    (f c)))
```

--------------------------------

### env/append-to-pathlist

Source: https://shopify.github.io/shadowenv/shadowlisp

Appends an entry to a colon-delimited pathlist variable.

```APIDOC
## (env/append-to-pathlist name entry)

### Description
Appends an item to a colon-delimited path variable. If the item is already present, it is removed before being appended to the end.

### Parameters
- **name** (String) - Required - The name of the environment variable to change.
- **entry** (String) - Required - The string to append.

### Returns
- **None** - Always returns ().
```

--------------------------------

### Variable Binding

Source: https://shopify.github.io/shadowenv/shadowlisp

Operator for defining local variable bindings.

```APIDOC
## (let ( [ ( name expression ) ... ] ) body)
Defines a series of local bindings for the duration of the execution of its body expression.
```

--------------------------------

### Conditional binding with when-let

Source: https://shopify.github.io/shadowenv/shadowlisp

Executes a body only if the expression evaluates to a non-empty value.

```lisp
(when-let ( ( name expression ) )
  [ body ... ])
```

```lisp
(env/set "RUBY_ROOT" ())
(when-let ((root (env/get "RUBY_ROOT")))
  (env/remove-from-pathlist "PATH" root)) ; not run

(env/set "RUBY_ROOT" "/opt/ruby-1")
(when-let ((root (env/get "RUBY_ROOT")))
  (env/remove-from-pathlist "PATH" root)) ; this time, it runs.
```

--------------------------------

### Logic Operators

Source: https://shopify.github.io/shadowenv/shadowlisp

Functions for boolean logic and equality testing.

```APIDOC
## (eq a b)
Test whether two values are (weakly) equal.

## (ne a b)
Test whether two values are (weakly) unequal.

## (not a)
Boolean negation.

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

## (and [ expression ... ])
Evaluates arguments applying logical AND short-circuiting rules.

## (or [ expression ... ])
Evaluates arguments applying logical OR short-circuiting rules.
```

--------------------------------

### Define local variable bindings

Source: https://shopify.github.io/shadowenv/shadowlisp

Uses the let operator to define local variables for the duration of the body expression.

```lisp
(let ((a 1)
      (b 2))
  (+ a b))

```

--------------------------------

### Concatenate paths with path-concat

Source: https://shopify.github.io/shadowenv/shadowlisp

Joins multiple strings into a single path using slashes. Useful for constructing absolute paths from environment variables.

```lisp
(path-concat "/" "usr" "bin") ; "/usr/bin"
```

```lisp
(when-let ((root (env/get "RUBY_ROOT")))
  (env/remove-from-pathlist (path-concat root "bin")))
```

--------------------------------

### List Manipulation

Source: https://shopify.github.io/shadowenv/shadowlisp

Functions for creating and modifying lists.

```APIDOC
## (append list value)
Appends a value to a list.

## (elt list n)
Returns the nth element of a list.

## (concat [ list ... ])
Concatenates each given list value.

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

## (first list)
Returns the first element of a list.

## (last list)
Returns the last element of a list.

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

## (list [ expr ... ])
Evaluates each of its arguments and returns them as a list.
```

--------------------------------

### Multi-branch conditional with cond

Source: https://shopify.github.io/shadowenv/shadowlisp

Evaluates a series of predicates and executes the branch corresponding to the first true predicate.

```lisp
(cond
  ((< n 0) 'negative)
  ((> n 0) 'positive)
  (else    'zero))
```

--------------------------------

### Conditional execution with when

Source: https://shopify.github.io/shadowenv/shadowlisp

Evaluates the provided forms only if the condition is true.

```lisp
(when (= 1 2) (env/set "NEVER" "happens")) ; ()
```

--------------------------------

### Modify environment variables with env/set

Source: https://shopify.github.io/shadowenv/shadowlisp

Sets an environment variable to a specific value or unsets it using ().

```lisp
(env/set "PATH" "/bin") ; ()
(env/get "PATH") ; "/bin"
```

--------------------------------

### env/remove-from-pathlist

Source: https://shopify.github.io/shadowenv/shadowlisp

Removes an entry from a colon-delimited pathlist variable.

```APIDOC
## (env/remove-from-pathlist name entry)

### Description
Removes a specific item from a colon-delimited path variable. If the variable becomes empty after removal, it is unset.

### Parameters
- **name** (String) - Required - The name of the environment variable to change.
- **entry** (String) - Required - The string to remove from the pathlist.

### Returns
- **None** - Always returns ().
```

--------------------------------

### Remove from a pathlist with env/remove-from-pathlist

Source: https://shopify.github.io/shadowenv/shadowlisp

Removes a specific entry from a colon-delimited pathlist. Unsets the variable if it becomes empty.

```lisp
(env/remove-from-pathlist name entry)
```

```lisp
(env/set "PATH" "/usr/bin:/opt/system-default-ruby/bin:/bin") ; ()
(env/remove-from-pathlist "PATH" "/opt/system-default-ruby/bin") ; ()
(env/get "PATH") ; "/usr/bin:/bin"
```

--------------------------------

### Conditional branching with if

Source: https://shopify.github.io/shadowenv/shadowlisp

Evaluates one of two branches based on the result of a condition.

```lisp
(if (< a b)
  a
  b)
```

--------------------------------

### Perform boolean negation

Source: https://shopify.github.io/shadowenv/shadowlisp

Negates a boolean value using the not operator.

```lisp
(not true) ; false

```

--------------------------------

### Remove pathlist items by substring with env/remove-from-pathlist-containing

Source: https://shopify.github.io/shadowenv/shadowlisp

Removes any items from a pathlist that contain the specified substring.

```lisp
(env/set "PATH" "/usr/bin:/root/.rvm/bin:/bin") ; ()
(env/remove-from-pathlist-containing "PATH" "/.rvm/") ; ()
(env/get "PATH") ; "/usr/bin:/bin"
```

--------------------------------

### env/remove-from-pathlist-containing

Source: https://shopify.github.io/shadowenv/shadowlisp

Removes items from a pathlist that contain a specific substring.

```APIDOC
## (env/remove-from-pathlist-containing name substring)

### Description
Removes any items from the specified pathlist that contain the provided value as a substring.

### Parameters
- **name** (String) - Required - The name of the environment variable to change.
- **substring** (String) - Required - The substring to match against pathlist items.

### Returns
- **None** - Always returns ().
```
Tokens:
Raw