Bass

stdlib

The standard library is the set of modules that come with Bass.

ground module

The ground module is inherited by all modules. It provides basic language constructs and the standard toolkit for running thunks.

index

*/-

$ constructs a thunk with args
* multiplies numbers
+ sums numbers
- subtracts ys from x
-> passes a value through a series of function calls
< returns true if the numbers are in ascending order
<= returns true if the numbers are in ascending or equal order
= returns true if the values are all equal
> returns true if the numbers are in descending order
>= returns true if the numbers are in descending or equal order

a

across returns a pipe source that yields a list of values across all the given sources
addr returns an address for a port provided by the thunk
always returns a function that returns x for any value
and returns a truthy value if none of the conds return a falsy value
append joins all given lists into one listdeprecated
applicative? returns true if the value is an applicative
apply call an applicative's underlying operative with a list of arguments
assert evaluates the form and raises an error if it's not true
assoc assoc(iate) keys with values in a clone of a scope

b

bind attempts to bind values in the scope
binds? returns true if the scope has a value bound to the given symbol
boolean? returns true if the value is true or false

c

cache-dir returns a cache directory corresponding to the string identifier
case evaluates the branch that successfully binds the given value
cd chain a sequence of thunks with a given working directory
collect returns (f value) for every value read from the source
combiner? returns true if the value is a combiner
concat joins all given lists into one list
cond if-then-else, but with many clauses
conj conjoins values onto the end of a list
cons construct a pair from the given values
current-scope returns the scope of the caller
curryfn returns a fn which accepts args one value at a time

d

def bind symbols to values in the current scope
defn construct a function and bind it to a symbol
defop construct an operative and bind it to a symbol
do evaluate a sequence, returning the last value
doc print docs for symbols
dump encodes a value as JSON to stderr

e

each calls f for every value read from the source
emit emits a value to a sink
empty? returns true if the value is an empty list, a zero-length string, an empty scope, or null
error errors with the given message
eval evaluate a value in a scope

f

filter returns only values from xs which satisfy the predicate
first return the first value in a pair
fn construct a function
foldl reduces xs, leftmost values first, with initial value z
foldr reduces xs, rightmost values first, with initial value z
for loops over values from sources
from chain a sequence of thunks starting from an initial image

i

id identity function; returns its argument
if if then else (branching logic)
ignore? returns true if the value is _ ("ignore")
import binds symbols in the current scope to their values from the source scope
insecure! sets the :insecure field of the thunk to true

j

json returns a string containing val encoded as JSON

k

keys collects the bindings from a scope

l

last returns the last value from the source
length return the length of the given list
let binds values in a child scope
linux a path root for resolving Linux images
list construct a list from a sequence of values
list* prepend a sequence of values to a list given as the final argument
list->scope constructs an object from a list of flat keyword/value pairs
list->source creates a pipe source from a list of values in chronological order
list? returns true if the value is a linked list
load load a thunk as a module
log logs a string message or arbitrary value to stderr

m

make-scope construct a scope with the given parents
map returns a list containing the result of applying f to each member of xs
map-pairs calls a function with alternating pairs in a flat list (i.e. with pairs ungrouped)
mask shrouds a string in secrecy
max returns the largest number
memo memo(ize)s a function
merge returns a scope containing the union of the given scopes
meta returns the meta attached to the value
min returns the smallest number
mkfile returns an in-memory file with the given content
mkfs returns a dir path backed by an in-memory filesystem
module returns a scope with only the specified bindings from a child scope

n

next receive the next value from a source
not negates the given bool-ish value
now returns the current UTC time truncated to the given seconds
null? returns true if the value is null
number? returns true if the value is a number

o

op construct an operative
operative? returns true if the value is an operative
or returns the first truthy value returned by evaluating conds

p

pair? returns true if the value is a pair
path-base returns the path-name converted into a file path
path-name returns the base name of the path
path-stem returns the base name of the path, without any extension
path? returns true if the value is a path
provide provide bindings to the current scope from a nested scope

q

quot quot(ient) of dividing num by denum
quote returns the unevaluated form

r

read returns a stream producing values read from a thunk's output or a file's content
recall-memo fetches the result of a memoized function call
reduce-kv reduces a scope
resolve resolve an image reference to its most exact form
rest return the second value in a pair, i.e. the rest of a linked list
run runs a thunk

s

scope->list returns a flat list alternating a scope's keys and values
scope? returns true if the value is a scope
second return the second member of a linked list
sink? returns true if the value is a sink
source? returns true if the value is a source
start starts running a thunk asynchronously
store-memo stores the result of a memoized function call
str returns the concatenation of all given strings or values
string->cmd-path converts a string to a command or file path
string->dir converts a string to a directory path
string->fs-path parses a string value into a file or directory path
string->symbol convert a string to a symbol
string? returns true if the value is a string
subpath extend path with another path
substring returns a portion of a string
succeeds? returns true if the thunk successfully runs (i.e. exit code 0)
symbol->string convert a symbol to a string
symbol? returns true if the value is a symbol

t

take reads the next n values from the source into a list
take-all reads all values from the source into a list
third return third member of a linked list
thunk-args returns the thunk's args
thunk-cmd returns the thunk's command
thunk? returns true if the value is a valid thunk
trim removes whitespace from both ends of a string

u

unwrap returns an applicative's underlying combiner
use loads each thunk and binds it as the name from the thunk's command path

v

vals collects the values from a scope

w

wait waits for all started thunks to finish
when evaluates the body if test returns true
with-args returns thunk with args set to args
with-cmd returns thunk with cmd set to cmd
with-dir returns thunk with the working directory set to dir
with-env returns thunk with env set to the given env
with-image returns thunk with the base image set to image
with-insecure returns thunk with the insecure flag set to bool
with-label returns thunk with the label set to val
with-meta returns val with the given scope as its metadata
with-mount returns thunk with a mount from source to the target path
with-port returns thunk with a named port appended to its ports
with-stdin returns thunk with stdin set to vals
with-tls returns thunk with paths to a TLS certificate and key to generate
wrap construct an applicative from a combiner (typically an operative)
wrap-cmd prepend a command + args to a thunk's command + args

bindings

(def binding value) operative? combiner?
𝄢

bind symbols to values in the current scope

𝄢

Supports destructuring assignment.

(def abc "it's easy as")
result
abc 
(def [a b c] [1 2 3])
result
(
  1. a
  2. b
  3. c
)
[abc a b c]
result
(
  1. "it's easy as"
  2. 1
  3. 2
  4. 3
)
(if cond yes no) operative? combiner?
𝄢

if then else (branching logic)

𝄢

Evaluates the cond form. If the result is truthy (not false or null), evaluates the yes form. Otherwise, evaluates the no form.

(if false (error "bam") :phew)
result
phew
(dump val) applicative? combiner?
𝄢

encodes a value as JSON to stderr

𝄢

Returns the given value.

(dump {:foo-bar "baz"})
stderr: 3 lines 
{
  "foo-bar": "baz"
}
result
{
:foo-bar "baz"
}
(mkfs & file-content-kv) applicative? combiner?
𝄢

returns a dir path backed by an in-memory filesystem

𝄢

Takes alternating file paths and their content, which must be a text string, and returns the root directory of an in-memory filesystem containing the specified files.

𝄢

All embedded files have 0644 Unix file permissions and a zero (Unix epoch) mtime.

(def fs (mkfs ./file "hey" ./sub/file "im in a subdir"))
result
fs 
(next (read (from (linux/alpine) ($ cat fs/file)) :raw))
stderr: 10 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.02s]
=> mkfile /file CACHED [0.00s]
=> cat <fs>/file [0.24s]
=> exporting to client directory [0.00s]
-> copying files 29B [0.00s]
result
"hey"
(json val) applicative? combiner?
𝄢

returns a string containing val encoded as JSON

(json {:foo-bar "baz"})
result
"{\"foo-bar\":\"baz\"}"
(log val & fields) applicative? combiner?
𝄢

logs a string message or arbitrary value to stderr

𝄢

Returns the given value.

𝄢

Accepts key-value fields for structured logging data.

(log "hello, world!")
stderr: 1 lines 
info    hello, world!
result
"hello, world!" 
(log "doing something" :a 1 :since {:day 1})
stderr: 1 lines 
info    doing something {"a": 1, "since": {"day": 1}}
result
"doing something"
(error msg & fields) applicative? combiner?
𝄢

errors with the given message

𝄢

Accepts key-value fields for structured error data.

(error "oh no!")
stderr: 7 lines 
error! call trace (oldest first):
   ┆ <fs>/literate-4:1:0..1:16
 1 │ (error "oh no!")
     ^^^^^^^^^^^^^^^^
oh no!
(error "oh no!" :exit-code 2)
stderr: 9 lines 
error! call trace (oldest first):
   ┆ <fs>/literate-4:1:0..1:29
 1 │ (error "oh no!" :exit-code 2)
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
oh no!
:exit-code 2
(now seconds) applicative? combiner?
𝄢

returns the current UTC time truncated to the given seconds

𝄢

Typically used to influence caching for thunks whose result may change over time.

(now 60)
result
"2022-11-28T01:28:00Z"
(do & body) operative? combiner?
𝄢

evaluate a sequence, returning the last value

(do (def abc 123) (+ abc 1))
result
124 
abc
result
123
(cons a d) applicative? combiner?
𝄢

construct a pair from the given values

(cons 1 [2 3])
result
(
  1. 1
  2. 2
  3. 3
)
(cons 1 2)
result
(1 & 2)
(wrap comb) applicative? combiner?
𝄢

construct an applicative from a combiner (typically an operative)

𝄢

When called, an applicative evaluates its arguments before passing them along to the underlying combiner.

(defop log-quote [x] _ (log x) x)
result
log-quote 
(log-quote (* 6 7))
stderr: 1 lines 
info    (* 6 7)
result
(
  1. *
  2. 6
  3. 7
)
((wrap log-quote) (* 6 7))
stderr: 1 lines 
info    42
result
42
(unwrap app) applicative? combiner?
𝄢

returns an applicative's underlying combiner

𝄢

You probably won't use this a lot. It's used to implement higher level abstractions like apply.

(op formals eformal & body) operative? combiner?
𝄢

construct an operative

𝄢

An operative is a combiner that is called with unevaluated arguments and the caller's dynamic scope.

𝄢

Operatives are used to define new syntax forms.

(def quote (op [x] _ x))
result
quote 
(quote abc)
result
abc
(eval form scope) applicative? combiner?
𝄢

evaluate a value in a scope

(eval :abc {:abc 123})
result
123 
(eval [* :x :y] {:x 6 :y 7})
result
42
(make-scope & parents) applicative? combiner?
𝄢

construct a scope with the given parents

(make-scope {:a 1} {:b 2})
result
{
{
:a 1
}
{
:b 2
}
}
(eval [+ :a :b] (make-scope {:a 1} {:b 2}))
result
3
(bind scope formals val) applicative? combiner?
𝄢

attempts to bind values in the scope

𝄢

Returns true if the binding succeeded, otherwise false.

(if (bind (current-scope) :abc 123) abc :mismatch)
result
123 
(if (bind (current-scope) [] 123) _ :mismatch)
result
mismatch
(meta val) applicative? combiner?
𝄢

returns the meta attached to the value

𝄢

Returns null if the value has no metadata.

(meta meta) ; whoa
result
{
:column 0
:doc "returns the meta attached to the value\n\nReturns null if the value has no metadata.\n\n=> (meta meta) ; whoa"
:file <fs>/bass/ground.go
:line 218
}
(with-meta val meta) applicative? combiner?
𝄢

returns val with the given scope as its metadata

(meta (with-meta _ {:a 1}))
result
{
:a 1
}
(meta (with-meta (with-meta _ {:a 1}) {:b 2}))
result
{
:b 2
}
(doc & symbols) operative? combiner?
𝄢

print docs for symbols

𝄢

Prints the documentation for the given symbols resolved from the current scope.

(doc doc)
stderr: 9 lines 
--------------------------------------------------
doc operative? combiner?
args: symbols
print docs for symbols
Prints the documentation for the given symbols resolved from the current scope.
=> (doc doc)
result
null
(null? val) applicative? combiner?
𝄢

returns true if the value is null

(null? null)
result
true 
(null? _)
result
false 
(null? false)
result
false
(ignore? val) applicative? combiner?
𝄢

returns true if the value is _ ("ignore")

(ignore? _)
result
true 
(ignore? null)
result
false
(boolean? val) applicative? combiner?
𝄢

returns true if the value is true or false

(boolean? null)
result
false 
(boolean? true)
result
true 
(boolean? false)
result
true
(number? val) applicative? combiner?
𝄢

returns true if the value is a number

(number? 123)
result
true 
(number? "123")
result
false
(string? val) applicative? combiner?
𝄢

returns true if the value is a string

(string? "abc")
result
true 
(string? :abc)
result
false
(symbol? val) applicative? combiner?
𝄢

returns true if the value is a symbol

(symbol? :abc)
result
true 
(symbol? "abc")
result
false
(scope? val) applicative? combiner?
𝄢

returns true if the value is a scope

𝄢

A scope is a mapping from symbols to values.

(scope? {})
result
true 
(scope? (current-scope))
result
true 
(scope? [])
result
false
(sink? val) applicative? combiner?
𝄢

returns true if the value is a sink

𝄢

A sink is a type that you can send values to using emit.

(sink? *stdout*)
result
true 
(sink? *stdin*)
result
false
(source? val) applicative? combiner?
𝄢

returns true if the value is a source

𝄢

A source is a type that you can read values from using next.

(source? *stdin*)
result
true 
(source? *stdout*)
result
false
(list? val) applicative? combiner?
𝄢

returns true if the value is a linked list

𝄢

A linked list is a pair whose second value is another list or empty.

(list? [])
result
true 
(list? {})
result
false
(pair? val) applicative? combiner?
𝄢

returns true if the value is a pair

(pair? [])
result
false 
(pair? [1])
result
true 
(pair? [1 & 2])
result
true 
(pair? (quote [1 & 2]))
result
true
(applicative? val) applicative? combiner?
𝄢

returns true if the value is an applicative

𝄢

An applicative is a combiner that wraps another combiner.

𝄢

When an applicative is called, it evaluates its operands in the caller's evironment and passes them to the underlying combiner.

(applicative? applicative?)
result
true 
(applicative? op)
result
false
(operative? val) applicative? combiner?
𝄢

returns true if the value is an operative

𝄢

An operative is a combiner that is given the caller's scope.

𝄢

An operative may decide whether and how to evaluate its arguments. They are typically used to define new syntactic constructs.

(operative? applicative?)
result
false 
(operative? op)
result
true
(combiner? val) applicative? combiner?
𝄢

returns true if the value is a combiner

𝄢

A combiner takes sequence of values as arguments and returns another value.

(combiner? applicative?)
result
true 
(combiner? op)
result
true
(path? val) applicative? combiner?
𝄢

returns true if the value is a path

𝄢

A path is a reference to a file, directory, or command.

(path? ./foo)
result
true 
(path? .foo)
result
true 
(path? (subpath (.tests) ./coverage.html))
result
true
(empty? val) applicative? combiner?
𝄢

returns true if the value is an empty list, a zero-length string, an empty scope, or null

(empty? [])
result
true 
(empty? "")
result
true 
(empty? {})
result
true 
(empty? null)
result
true 
(empty? :my-soul)
result
false
(thunk? val) applicative? combiner?
𝄢

returns true if the value is a valid thunk

(thunk? (.yep))
result
true 
(thunk? [.nope])
result
false 
(thunk? {:not-even "close"})
result
false
(+ & nums) applicative? combiner?
𝄢

sums numbers

(+ 1 2 3)
result
6
(* & nums) applicative? combiner?
𝄢

multiplies numbers

(* 2 3 7)
result
42
(quot num denom) applicative? combiner?
𝄢

quot(ient) of dividing num by denum

(quot 84 2)
result
42
(- num & nums) applicative? combiner?
𝄢

subtracts ys from x

𝄢

If only x is given, returns the negation of x.

(- 10 4)
result
6 
(- 10 4 1)
result
5 
(- 6)
result
-6
(max num & nums) applicative? combiner?
𝄢

returns the largest number

(max 6 42 7)
result
42
(min num & nums) applicative? combiner?
𝄢

returns the smallest number

(min 6 42 7)
result
6
(= val & vals) applicative? combiner?
𝄢

returns true if the values are all equal

(= 1 1 1 1)
result
true 
(= :hello :hello :goodbye)
result
false 
(= {:a 1} {:a 1})
result
true
(> num & nums) applicative? combiner?
𝄢

returns true if the numbers are in descending order

(> 9 8 7)
result
true 
(> 9 8 8)
result
false
(>= num & nums) applicative? combiner?
𝄢

returns true if the numbers are in descending or equal order

(> 9 8 7)
result
true 
(> 9 8 8)
result
false
(< num & nums) applicative? combiner?
𝄢

returns true if the numbers are in ascending order

(< 7 8 9)
result
true 
(> 8 8 9)
result
false
(<= num & nums) applicative? combiner?
𝄢

returns true if the numbers are in ascending or equal order

(< 7 8 9)
result
true 
(> 8 8 9)
result
false
(list->source list) applicative? combiner?
𝄢

creates a pipe source from a list of values in chronological order

(list->source [1 2 3])
result
<source: 1 2 3>
(across & sources) applicative? combiner?
𝄢

returns a pipe source that yields a list of values across all the given sources

𝄢

Each list has the last value for each source. Values from each source are never skipped, but not every combination will be produced.

(def evens (list->source [0 2 4]))
result
evens 
(def odds (list->source [1 3 5]))
result
odds 
(def combined (across evens odds))
result
combined 
[(next combined) (next combined)]
result
(
  1. (
    1. 0
    2. 1
    )
  2. (
    1. 0
    2. 3
    )
)
(emit val sink) applicative? combiner?
𝄢

emits a value to a sink

(emit {:a 1} *stdout*)
stdout 
{
  "a": 1
}
result
null
(next src & default) applicative? combiner?
𝄢

receive the next value from a source

𝄢

If the source has ended, no value will be available. A default value may be provided, otherwise an error is raised.

(next (list->source [1]) :eof)
result
1 
(next *stdin* :eof)
result
eof
(reduce-kv f init kv) applicative? combiner?
𝄢

reduces a scope

𝄢

Takes a 3-arity function, an initial value, and a scope. If the scope is empty, the initial value is returned. Otherwise, calls the function for each key-value pair, with the current value as the first argument.

(reduce-kv assoc {:d 4} {:a 1 :b 2 :c 3})
result
{
:d 4
:a 1
:b 2
:c 3
}
(assoc obj & kvs) applicative? combiner?
𝄢

assoc(iate) keys with values in a clone of a scope

𝄢

Takes a scope and a flat pair sequence alternating symbols and values.

𝄢

Returns a clone of the scope with the symbols fields set to their associated value.

(assoc {:a 1} :b 2 :c 3)
result
{
:a 1
:b 2
:c 3
}
(symbol->string sym) applicative? combiner?
𝄢

convert a symbol to a string

(symbol->string :hello!)
result
"hello!"
(string->symbol str) applicative? combiner?
𝄢

convert a string to a symbol

(string->symbol "hello!")
result
hello!
(str & vals) applicative? combiner?
𝄢

returns the concatenation of all given strings or values

(str "abc" 123 "def" 456)
result
"abc123def456"
(substring str start & end) applicative? combiner?
𝄢

returns a portion of a string

𝄢

With one number supplied, returns the portion from the offset to the end.

𝄢

With two numbers supplied, returns the portion between the first offset and the last offset, exclusive.

(substring "abcdef" 2 4)
result
"cd"
(trim str) applicative? combiner?
𝄢

removes whitespace from both ends of a string

(trim " hello world!\n ")
result
"hello world!"
(scope->list obj) applicative? combiner?
𝄢

returns a flat list alternating a scope's keys and values

𝄢

The returned list is the same form accepted by assoc.

(scope->list {:a 1 :b 2 :c 3})
result
(
  1. a
  2. 1
  3. b
  4. 2
  5. c
  6. 3
)
(apply assoc (cons {:d 4} (scope->list {:a 1 :b 2 :c 3})))
result
{
:d 4
:a 1
:b 2
:c 3
}
(string->fs-path str) applicative? combiner?
𝄢

parses a string value into a file or directory path

(string->fs-path "./file")
result
./file 
(string->fs-path "file")
result
./file 
(string->fs-path "dir/")
result
./dir/
(string->cmd-path str) applicative? combiner?
𝄢

converts a string to a command or file path

𝄢

If the value contains a /, it is converted into a file path.

𝄢

Otherwise, the given value is converted into a command path.

(string->cmd-path "scripts/foo")
result
./scripts/foo 
(string->cmd-path "bash")
result
.bash
(string->dir str) applicative? combiner?
𝄢

converts a string to a directory path

𝄢

A trailing slash is not required; the path is always assumed to be a directory.

(string->dir "dir")
result
./dir/ 
(string->dir "dir/")
result
./dir/
(subpath parent-dir child-path) applicative? combiner?
𝄢

extend path with another path

(subpath ./dir/ ./file)
result
./dir/file 
(subpath (.tests) ./coverage.html)
result
.tests
{
:cmd .tests
}
./coverage.html
(path-name path) applicative? combiner?
𝄢

returns the base name of the path

𝄢

For a command path, this returns the command name.

𝄢

For a file or dir path, it returns the file or dir name.

𝄢

For a file path, it returns the file name.

𝄢

For a thunk, it returns the thunk's hash.

(path-name .bash)
result
"bash" 
(path-name ./some/file)
result
"file" 
(path-name ./some/dir/)
result
"dir" 
(path-name (.tests))
result
"GQBK30H7BF254"
(path-stem path) applicative? combiner?
𝄢

returns the base name of the path, without any extension

(path-stem .bash)
result
"bash" 
(path-stem ./some/file.bass)
result
"file" 
(path-stem ./some/dir/)
result
"dir" 
(path-stem (.tests))
result
"GQBK30H7BF254"
(with-image thunk image) applicative? combiner?
𝄢

returns thunk with the base image set to image

𝄢

Image is either a thunk? or an image ref.

𝄢

Recurses when thunk's image is another thunk, setting the deepest ref or unset image.

𝄢

See also from.

(with-image ($ go test ./...) (linux/golang))
result
.go
{
:image
{
:repository "golang"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:dc76ef03e54c34a00dcdca81e55c242d24b34d231637776c4bb5c1a8e8514253"
}
:cmd .go
:args
(
  1. "test"
  2. ./...
)
}
(from (linux/golang) ($ go test ./...))
result
.go
{
:image
{
:repository "golang"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:dc76ef03e54c34a00dcdca81e55c242d24b34d231637776c4bb5c1a8e8514253"
}
:cmd .go
:args
(
  1. "test"
  2. ./...
)
}
(with-dir thunk dir) applicative? combiner?
𝄢

returns thunk with the working directory set to dir

𝄢

Unlike cd, the value of with-dir is resolved at runtime, meaning it can use container-local paths.

𝄢

If the thunk needs to write to its output directory, the output path passed to the command must be relative to the given dir. Thunk paths and other mounts will always be 1 level deep in the output directory, so use ../ to refer to back to the output directory, repeated for each additional level of depth. If the depth is unknown, you should use cd instead.

(with-dir (.tests) ./src/)
result
.tests
{
:cmd .tests
:dir ./src/
}
(with-args thunk args) applicative? combiner?
𝄢

returns thunk with args set to args

(with-args (.go) ["test" "./..."])
result
.go
{
:cmd .go
:args
(
  1. "test"
  2. "./..."
)
}
(with-cmd thunk cmd) applicative? combiner?
𝄢

returns thunk with cmd set to cmd

(let [inner (with-args (.go) ["build"])] (with-args (with-cmd inner ./wrapped) (cons (thunk-cmd inner) (thunk-args inner))))
result
./wrapped
{
:cmd ./wrapped
:args
(
  1. .go
  2. "build"
)
}
(with-stdin thunk vals) applicative? combiner?
𝄢

returns thunk with stdin set to vals

(with-stdin ($ jq ".a") [{:a 1} {:a 2}])
result
.jq
{
:cmd .jq
:args
(
  1. ".a"
)
:stdin
(
  1. {
    :a 1
    }
  2. {
    :a 2
    }
)
}
(with-env thunk env) applicative? combiner?
𝄢

returns thunk with env set to the given env

(with-env ($ jq ".a") {:FOO "hello"})
result
.jq
{
:cmd .jq
:args
(
  1. ".a"
)
:env
{
:FOO "hello"
}
}
(with-insecure thunk bool) applicative? combiner?
𝄢

returns thunk with the insecure flag set to bool

𝄢

The insecure flag determines whether the thunk runs with elevated privileges, and is named to be indicate the reduced security assumptions.

(with-insecure (.boom) true)
result
.boom
{
:insecure true
:cmd .boom
}
(= (.boom) (with-insecure (.boom) false))
result
true
(with-label thunk name val) applicative? combiner?
𝄢

returns thunk with the label set to val

𝄢

Labels are typically used to control caching. Two thunks that differ only in labels will evaluate separately and produce independent results.

(with-label ($ sleep 10) :at (now 10))
result
.sleep
{
:cmd .sleep
:args
(
  1. 10
)
:labels
{
:at "2022-11-28T01:28:20Z"
}
}
(with-port thunk sym int) applicative? combiner?
𝄢

returns thunk with a named port appended to its ports

(with-port ($ godoc "-http=:6060") :godoc 6060)
result
.godoc
{
:cmd .godoc
:args
(
  1. "-http=:6060"
)
}
(with-tls thunk cert-path key-path) applicative? combiner?
𝄢

returns thunk with paths to a TLS certificate and key to generate

(with-tls ($ godoc "-http=:6060") ./cert.pem ./key.pem)
result
.godoc
{
:cmd .godoc
:args
(
  1. "-http=:6060"
)
}
(with-mount thunk source target) applicative? combiner?
𝄢

returns thunk with a mount from source to the target path

(with-mount ($ find ./inputs/) *dir*/inputs/ ./inputs/)
result
.find
{
:cmd .find
:args
(
  1. ./inputs/
)
:mounts
(
  1. {
    :source <host: /tmp/nix-shell.fUJHAA/bass-scope2061291740/inputs>
    :target ./inputs/
    }
)
}
(thunk-cmd thunk) applicative? combiner?
𝄢

returns the thunk's command

(thunk-cmd (.foo))
result
.foo 
(thunk-cmd (./foo))
result
./foo
(thunk-args thunk) applicative? combiner?
𝄢

returns the thunk's args

(thunk-args ($ foo abc))
result
(
  1. "abc"
)
(thunk-args ($ foo))
result
(
)
(load thunk) applicative? combiner?
𝄢

load a thunk as a module

𝄢

This is the primitive mechanism for loading other Bass code.

𝄢

Typically used in combination with *dir* to load paths relative to the current file's directory.

(load (.strings))
result
<scope: <thunk NFRAJLC6LDIDU: (.strings)>>
(resolve platform ref) applicative? combiner?
𝄢

resolve an image reference to its most exact form

(resolve {:platform {:os "linux"} :repository "golang" :tag "latest"})
stderr: 1 lines 
=> resolve image config for docker.io/library/golang:latest [0.16s]
result
{
:repository "golang"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:dc76ef03e54c34a00dcdca81e55c242d24b34d231637776c4bb5c1a8e8514253"
}
(start thunk handler) applicative? combiner?
𝄢

starts running a thunk asynchronously

𝄢

If the thunk errors or exits nonzero the handler is called with a combiner that raises the error when called.

𝄢

If the thunk runs succeeds the handler is called with null.

(start (from (linux/alpine) ($ banana)) null?)
result
(wrap <builtin: (<thunk PBRNK3TTJRLCQ: (.banana)>)>) 
((start (from (linux/alpine) ($ banana)) null?))
stderr: 10 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> banana ERROR [0.23s]
 ▕ start: exec: "banana": executable file not found in $PATH
!!! banana
6: [0.17s] start: exec: "banana": executable file not found in $PATH
result
false 
((start (from (linux/alpine) ($ echo)) null?))
stderr: 8 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> echo [0.22s]
 ▕
result
true 
(defn raiser [err] (and err (err)))
result
raiser 
((start (from (linux/alpine) ($ banana)) raiser))
stderr: 29 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> banana ERROR [0.21s]
 ▕ start: exec: "banana": executable file not found in $PATH
!!! banana
6: [0.15s] start: exec: "banana": executable file not found in $PATH
error! call trace (oldest first):
   ┆ <fs>/literate-9:1:0..1:49
 1 │ ((start (from (linux/alpine) ($ banana)) raiser))
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
build failed: exit code: 1
run summary:
  => docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e6
97984fba772b3976835194c6d4
  => resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e
480fef81e697984fba772b3976835194c6d4 [0.01s]
  => banana [0.21s]
  start: exec: "banana": executable file not found in $PATH
  ERROR: exit code: 1
for more information, refer to the full output above
((start (from (linux/alpine) ($ echo)) raiser))
stderr: 8 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> echo [0.21s]
 ▕
result
null
(addr thunk port & fmt) applicative? combiner?
𝄢

returns an address for a port provided by the thunk

𝄢

Takes an optional format argument which defaults to "$host:$port".

(def thunk (-> ($ python -m http.server) (with-port :http 8080)))
result
thunk 
(addr thunk :http)
result
.python
{
:cmd .python
:args
(
  1. "-m"
  2. "http.server"
)
}
http
(wait) applicative? combiner?
𝄢

waits for all started thunks to finish

𝄢

Returns an error if any of the thunk handlers error.

(defn echo-server [msg] (start (from (linux/alpine) ($ sleep 1 $msg)) null?))
result
echo-server 
(wait)
result
null
(read thunk-or-file protocol) applicative? combiner?
𝄢

returns a stream producing values read from a thunk's output or a file's content

(def echo-thunk (from (linux/alpine) ($ echo "42")))
result
echo-thunk 
(next (read echo-thunk :json))
stderr: 9 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.02s]
=> echo 42 [0.22s]
=> exporting to client directory [0.00s]
-> copying files 29B [0.00s]
result
42 
(def file-thunk (from (linux/alpine) ($ sh -c "echo 42 > file")))
result
file-thunk 
(next (read file-thunk/file :json))
stderr: 9 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> sh -c "echo 42 > file" [0.21s]
=> exporting to client tarball [0.00s]
-> sending tarball [0.00s]
result
42
(cache-dir id) applicative? combiner?
𝄢

returns a cache directory corresponding to the string identifier

𝄢

Cache directories may be mounted to thunks. Their content persists across thunk runs.

(binds? scope sym) applicative? combiner?
𝄢

returns true if the scope has a value bound to the given symbol

(binds? {:x 1} :x)
result
true 
(binds? {} :x)
result
false 
(binds? (current-scope) :binds?)
result
true
(recall-memo memos thunk binding input) applicative? combiner?
𝄢

fetches the result of a memoized function call

𝄢

Returns null if no result is found.

𝄢

See memo for the higher-level interface.

(store-memo memos thunk binding input result) applicative? combiner?
𝄢

stores the result of a memoized function call

𝄢

See memo for the higher-level interface.

(mask secret name) applicative? combiner?
𝄢

shrouds a string in secrecy

𝄢

Prevents the string from being revealed when the value is displayed.

𝄢

Prevents the string from being revealed in a serialized thunk or thunk path.

𝄢

Does NOT currently prevent the string's value from being displayed in log output; you still have to be careful there.

(mask "super secret" :github-token)
result
<secret: github-token (12 bytes)>
(list & values) applicative? combiner?
𝄢

construct a list from a sequence of values

(list 1 2 3)
result
(
  1. 1
  2. 2
  3. 3
)
(list* & args) applicative? combiner?
𝄢

prepend a sequence of values to a list given as the final argument

(list* 1 2 3 [4 5])
result
(
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
)
(first (f & _)) applicative? combiner?
𝄢

return the first value in a pair

(first [1 2 3])
result
1
(rest (_ & r)) applicative? combiner?
𝄢

return the second value in a pair, i.e. the rest of a linked list

(rest [1 2 3])
result
(
  1. 2
  2. 3
)
(length xs) applicative? combiner?
𝄢

return the length of the given list

(length [1 2 3])
result
3
(defop name formals eformal & body) operative? combiner?
𝄢

construct an operative and bind it to a symbol

𝄢

Returns the bound symbol. Write a comment before or after to provide documentation.

(defop quote [x] _ x) ; returns x
result
quote 
(quote abc)
result
abc 
(doc quote)
stderr: 5 lines 
--------------------------------------------------
quote operative? combiner?
args: [x]
returns x
result
null
(fn formals & body) operative? combiner?
𝄢

construct a function

𝄢

Functions are applicative combiners that take a list of arguments.

(def times-7 (fn [x] (* x 7)))
result
times-7 
(times-7 6)
result
42
(defn name formals & body) operative? combiner?
𝄢

construct a function and bind it to a symbol

𝄢

Returns the bound symbol. Write a comment before or after to provide documentation.

(defn times-7 [x] (* x 7)) ; multiplies by 7
result
times-7 
(times-7 6)
result
42 
(doc times-7)
stderr: 5 lines 
--------------------------------------------------
times-7 applicative? combiner?
args: [x]
multiplies by 7
result
null
(second (_ x & _)) applicative? combiner?
𝄢

return the second member of a linked list

(second [1 2 3])
result
2
(third (_ _ x & _)) applicative? combiner?
𝄢

return third member of a linked list

(third [1 2 3])
result
3
(current-scope) operative? combiner?
𝄢

returns the scope of the caller

(current-scope)
result
{
:*memos* <host: bass.lock>
{
:*dir* <host: /tmp/nix-shell.fUJHAA/bass-scope679293626>
:*env*
{
}
:*stdin* <source: empty>
:*stdout* <sink: empty>
:main (wrap <builtin: (main)>)
<scope: ground>
}
}
(eval [current-scope] {:a 1})
result
{
:a 1
}
(quote form) operative? combiner?
𝄢

returns the unevaluated form

(quote abc)
result
abc
(map f xs) applicative? combiner?
𝄢

returns a list containing the result of applying f to each member of xs

(map (fn [x] (* x 7)) [5 6 7])
result
(
  1. 35
  2. 42
  3. 49
)
(map-pairs f ps) applicative? combiner?
𝄢

calls a function with alternating pairs in a flat list (i.e. with pairs ungrouped)

𝄢

Takes 2-arity function and a flat pair sequence. Walks the sequence and calls f with 2 values at a time.

𝄢

Raises an error if the list has uneven length.

(map-pairs cons [:a 1 :b 2 :c 3])
result
(
  1. (a & 1)
  2. (b & 2)
  3. (c & 3)
)
(let bindings & body) operative? combiner?
𝄢

binds values in a child scope

𝄢

Takes a list alternating bindings and their values. Creates a child scope, and binds and evaluates each value in sequence. Later bindings may to refer to earlier bindings.

𝄢

Returns the result of evaluating the body in the child scope.

(let [x 6 y 7] (* 6 7))
result
42
(import source & symbols) operative? combiner?
𝄢

binds symbols in the current scope to their values from the source scope

(import {:x 6 :y 7} x)
result
(
  1. x
)
x ; y is not bound
result
6
(provide symbols & body) operative? combiner?
𝄢

provide bindings to the current scope from a nested scope

𝄢

Allows for modularity in code, selectively providing bindings while encapsulating bindings that they use.

(provide [y] (def x 6) (def y 7))
result
(
  1. y
)
y ; x is not bound
result
7
(foldr f z xs) applicative? combiner?
𝄢

reduces xs, rightmost values first, with initial value z

(foldr cons [4 5] [1 2 3])
result
(
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
)
(foldl f z xs) applicative? combiner?
𝄢

reduces xs, leftmost values first, with initial value z

(foldl conj [4 5] [1 2 3])
result
(
  1. 4
  2. 5
  3. 1
  4. 2
  5. 3
)
(concat & xss) applicative? combiner?
𝄢

joins all given lists into one list

(concat [1] [2 3] [4 5 6])
result
(
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
)
(append & xss)deprecated applicative? combiner?
𝄢

Use concat instead.

𝄢

joins all given lists into one list

(concat [1] [2 3] [4 5 6])
result
(
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
)
(filter predicate xs) applicative? combiner?
𝄢

returns only values from xs which satisfy the predicate

(filter symbol? [:abc 123 :def "456"])
result
(
  1. abc
  2. def
)
(conj xs y & ys) applicative? combiner?
𝄢

conjoins values onto the end of a list

(conj [123] 4 5 6)
result
(
  1. 123
  2. 4
  3. 5
  4. 6
)
(list->scope kwargs) applicative? combiner?
𝄢

constructs an object from a list of flat keyword/value pairs

(list->scope [:a 1 :b 2 :c 3])
result
{
:a 1
:b 2
:c 3
}
(merge & scopes) applicative? combiner?
𝄢

returns a scope containing the union of the given scopes

𝄢

Constructs a scope with all of the given scopes as parents, in reverse order.

(merge {:a 1 :b 2} {:c 3} {:b :two})
result
{
{
:b two
}
{
:c 3
}
{
:a 1
:b 2
}
}
(module bindings & body) operative? combiner?
𝄢

returns a scope with only the specified bindings from a child scope

(def mod (module [foo] (def bar 6) (defn foo [n] (* n bar))))
result
mod 
mod
result
{
:foo (fn [n] (* n bar))
}
(mod:foo 7)
result
42
(use & thunks) operative? combiner?
𝄢

loads each thunk and binds it as the name from the thunk's command path

(use (.strings) (.time))
result
(
  1. strings
  2. time
)
(strings:upper-case "hallelujah")
result
"HALLELUJAH" 
(time:weekly)
result
"2022-11-28T00:00:00Z"
(cond & clauses) operative? combiner?
𝄢

if-then-else, but with many clauses

𝄢

Takes a flat pair sequence alternating tests to evaluate and an expression to evaluate if the test returns a truthy value.

𝄢

Returns the result of the evaluated branch, or null if no tests were true.

𝄢

By convention, :else is used as the final catch-all test, though any truthy value works.

(cond false :a false :b :else :c)
result
c 
(cond true :a false :b :else :c)
result
a
(or & conds) operative? combiner?
𝄢

returns the first truthy value returned by evaluating conds

𝄢

Short-circuits when it encounters a truthy value.

𝄢

Returns false if no values are given.

(or false null :yep)
result
yep 
(or)
result
false
(and & conds) operative? combiner?
𝄢

returns a truthy value if none of the conds return a falsy value

𝄢

Short-circuits when it encounters a falsy value.

𝄢

Returns true if no values are given.

(or false null :yep)
result
yep
(apply appv arg & opt) applicative? combiner?
𝄢

call an applicative's underlying operative with a list of arguments

𝄢

A scope may be provided as the third argument. If not specified, the operative will be called in a new empty scope.

𝄢

Used to call an applicative with pre-evaluated arguments, skipping the normal evaluation the applicative would perform prior to calling the underlying operative.

(apply * [1 2 3])
result
6
(-> x f & fs) operative? combiner?
𝄢

passes a value through a series of function calls

𝄢

Given an input value and a series of functions, calls the first function with the input value, passing the output to the second function, and so on, returning the final value. Typically used to flatten a deeply nested function call to make it easier to read.

𝄢

Functions are either a single form (i.e. a symbol) or a pair. A single form is called with the input value as the only argument. A pair is called with the input value prepended to the rest of the pair, i.e. inserted as the first argument.

(-> (.boom) insecure! (with-env {:BAM "hi"}))
result
.boom
{
:insecure true
:cmd .boom
:env
{
:BAM "hi"
}
}
(-> 6 (* 7) (- 2) (quot 4))
result
10
(case v & bs) operative? combiner?
𝄢

evaluates the branch that successfully binds the given value

𝄢

Bindings are set in an child scope.

(case [] [] :empty [x] :one _ :more)
result
empty 
(case [1] [] :empty [x] :one _ :more)
result
one 
(case [1 2] [] :empty [x] :one _ :more)
result
more
(id x) applicative? combiner?
𝄢

identity function; returns its argument

(id 42)
result
42 
(id id)
result
(fn [x] x) 
((id id) id)
result
(fn [x] x) 
(((id id) id) id)
result
(fn [x] x)
(always x) applicative? combiner?
𝄢

returns a function that returns x for any value

((always 42) :never)
result
42 
(((always always) :never) :never)
result
(fn [_] x) 
((((always always) :never) :unless?) :never)
result
unless?
(vals scope) applicative? combiner?
𝄢

collects the values from a scope

(vals {:a 1 :b 2})
result
(
  1. 1
  2. 2
)
(keys scope) applicative? combiner?
𝄢

collects the bindings from a scope

(keys {:a 1 :b 2})
result
(
  1. a
  2. b
)
(memo memos thunk binding) applicative? combiner?
𝄢

memo(ize)s a function

𝄢

Returns a function equivalent to the binding from the loaded thunk which caches its results to/from memos, a path to a file on the host (read-write) or from a thunk (read-only).

𝄢

This is a utility for caching dependency version resolution, such as image tags and git refs. It is technically the only way to perform writes against the host filesystem.

𝄢

The intended practice is to commit memos into source control to facilitate reproducible builds.

(def memos *dir*/bass.lock)
result
memos 
(def upper-cache (memo memos (.strings) :upper-case))
result
upper-cache 
(upper-cache "hello")
result
"HELLO" 
(run (from (linux/alpine) ($ cat $memos)))
stderr: 38 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> local:///tmp/nix-shell.fUJHAA/bass-scope2951821946 [0.01s]
-> transferring /tmp/nix-shell.fUJHAA/bass-scope2951821946: 417B [0.00s]
=> copy /bass.lock /bass.lock CACHED [0.00s]
=> cat <host: /tmp/nix-shell.fUJHAA/bass-scope2951821946/bass.lock> [0.26s]
 ▕ memos: {
 ▕   module: {
 ▕     cmd: {
 ▕       command: {
 ▕         name: "strings"
 ▕       }
 ▕     }
 ▕   }
 ▕   calls: {
 ▕     binding: "upper-case"
 ▕     results: {
 ▕       input: {
 ▕         array: {
 ▕           values: {
 ▕             string: {
 ▕               value: "hello"
 ▕             }
 ▕           }
 ▕         }
 ▕       }
 ▕       output: {
 ▕         string: {
 ▕           value: "HELLO"
 ▕         }
 ▕       }
 ▕     }
 ▕   }
 ▕ }
result
null
(curryfn args & body) operative? combiner?
𝄢

returns a fn which accepts args one value at a time

(succeeds? thunk) applicative? combiner?
𝄢

returns true if the thunk successfully runs (i.e. exit code 0)

𝄢

returns false if it fails (i.e. exit code nonzero)

𝄢

Used for running a thunk as a conditional instead of erroring when it fails.

(succeeds? (from (linux/alpine) (.false)))
stderr: 8 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> false ERROR [0.23s]
!!! false
result
false 
(succeeds? (from (linux/alpine) (.true)))
stderr: 7 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.01s]
=> true [0.23s]
result
true
(run thunk) applicative? combiner?
𝄢

runs a thunk

𝄢

Raises an error if the thunk's command fails (i.e. exit code 0)

𝄢

Returns null.

(run (from (linux/alpine) ($ echo "Hello, world!")))
stderr: 8 lines 
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.02s]
=> echo "Hello, world!" [0.25s]
 ▕ Hello, world!
result
null
(when test & body) operative? combiner?
𝄢

evaluates the body if test returns true

𝄢

Returns the body's result, or null if the test is false.

(when true (def x :a) (log "hello") (log "world") x)
stderr: 2 lines 
info    hello
info    world
result
a 
x
result
a 
(when false (def x :b))
result
null 
x
result
a
(assert form) operative? combiner?
𝄢

evaluates the form and raises an error if it's not true

(assert (= (+ 2 2) 4))
result
null 
(assert (= (+ 2 2) 5))
stderr: 7 lines 
error! call trace (oldest first):
   ┆ <fs>/literate-3:1:0..1:22
 1 │ (assert (= (+ 2 2) 5))
     ^^^^^^^^^^^^^^^^^^^^^^
assertion failed: (= (+ 2 2) 5)
(last source & default) applicative? combiner?
𝄢

returns the last value from the source

𝄢

As with next, a default may be provided to be returned when the source is empty. If not provided, an error will be raised if the source is empty.

(last (list->source [1 2 3]))
result
3
(each source f) applicative? combiner?
𝄢

calls f for every value read from the source

𝄢

Returns null.

(each (list->source [1 2 3]) log)
stderr: 3 lines 
info    1
info    2
info    3
result
null
(for bindings & body) operative? combiner?
𝄢

loops over values from sources

𝄢

Takes a list alternating bindings and their sources, similar to let. Reads values across all sources and evaluates the body for each set of values as they are read with next.

𝄢

Returns null when the source reaches its end.

(def evens (list->source [0 2 4]))
result
evens 
(def odds (list->source [1 3 5]))
result
odds 
(for [a evens b odds] (log "got" :a a :b b))
stderr: 3 lines 
info    got {"a": 0, "b": 1}
info    got {"a": 2, "b": 3}
info    got {"a": 4, "b": 5}
result
null
(take n source) applicative? combiner?
𝄢

reads the next n values from the source into a list

(take 2 (list->source [1 2 3]))
result
(
  1. 1
  2. 2
)
(collect f source) applicative? combiner?
𝄢

returns (f value) for every value read from the source

(collect (fn [n] (+ n 1)) (list->source [1 2 3]))
result
(
  1. 2
  2. 3
  3. 4
)
(take-all source) applicative? combiner?
𝄢

reads all values from the source into a list

(take-all (list->source [1 2 3]))
result
(
  1. 1
  2. 2
  3. 3
)
(insecure! thunk) applicative? combiner?
𝄢

sets the :insecure field of the thunk to true

(insecure! (.boom))
result
.boom
{
:insecure true
:cmd .boom
}
($ cmd & args) operative? combiner?
𝄢

constructs a thunk with args

𝄢

Symbol arguments are automatically converted to strings. Symbols beginning with $ are resolved to their binding with the leading $ removed.

($ sh -c "echo Hello, world!")
result
.sh
{
:cmd .sh
:args
(
  1. "-c"
  2. "echo Hello, world!"
)
}
(from image & thunks) applicative? combiner?
𝄢

chain a sequence of thunks starting from an initial image

(from (linux/alpine) ($ echo "Hello, world!"))
result
.echo
{
:image
{
:repository "alpine"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
}
:cmd .echo
:args
(
  1. "Hello, world!"
)
}
(cd dir thunk & thunks) applicative? combiner?
𝄢

chain a sequence of thunks with a given working directory

𝄢

Shorthand for using with-mount to mount ./ on the first thunk and chaining the rest using from. The working directory will propagate between them.

𝄢

Typically used within an outer from which sets the first thunk's image in order to join it into the chain.

(from (linux/alpine) (cd *dir* ($ find ./)))
result
.find
{
:image
{
:repository "alpine"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
}
:cmd .find
:args
(
  1. ./
)
:mounts
(
  1. {
    :source <host: /tmp/nix-shell.fUJHAA/bass-scope3706449381>
    :target ./
    }
)
}
(wrap-cmd thunk cmd & args) applicative? combiner?
𝄢

prepend a command + args to a thunk's command + args

𝄢

Replaces the thunk's run path sets its args to and prepend-args prepended to the original cmd + args.

(wrap-cmd ($ go test "./...") .strace "-f")
result
.strace
{
:cmd .strace
:args
(
  1. "-f"
  2. .go
  3. "test"
  4. "./..."
)
}
(linux & args) operative? combiner?
𝄢

a path root for resolving Linux images

𝄢

Memoizes image resolution into the caller's *memos*, if set.

(linux/ubuntu)
result
{
:repository "ubuntu"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:4b1d0c4a2d2aaf63b37111f34eb9fa89fa1bf53dd6e4ca954d47caebca4005c2"
}
(linux/ubuntu :18.04)
stderr: 1 lines 
=> resolve image config for docker.io/library/ubuntu:18.04 [0.47s]
result
{
:repository "ubuntu"
:platform
{
:os "linux"
}
:tag "18.04"
:digest "sha256:ca70a834041dd1bf16cc38dfcd24f0888ec4fa431e09f3344f354cf8d1724499"
}
(linux/docker.io/library/ubuntu :18.04)
stderr: 1 lines 
=> resolve image config for docker.io/library/ubuntu:18.04 [0.09s]
result
{
:repository "docker.io/library/ubuntu"
:platform
{
:os "linux"
}
:tag "18.04"
:digest "sha256:ca70a834041dd1bf16cc38dfcd24f0888ec4fa431e09f3344f354cf8d1724499"
}
(mkfile name content) applicative? combiner?
𝄢

returns an in-memory file with the given content

(mkfile ./hi "hello world!")
result
<fs>/hi 
(mkfile ./hey "hello world!")
result
<fs>/hey
(path-base path) applicative? combiner?
𝄢

returns the path-name converted into a file path

(path-base ./foo/bar)
result
./bar 
(path-base .cmd)
result
./cmd 
(path-base ./foo/dir/)
result
./dir
(not x) applicative? combiner?
𝄢

negates the given bool-ish value

𝄢

Returns true for false and null. Returns false otherwise.

(not true)
result
false 
(not null)
result
true 
(not false)
result
true

script bindings

Bass modules always run as commands. Either a user runs the script with the bass command, or another Bass module runs it as a thunk.

When a module is run as a script, the values reflect the system values available to the bass command, and main is called with the arguments passed to bass.

When a module is run as a thunk, the values reflect the values set in the thunk, and main is called with the thunk's args.

index

*/-

*dir* current working directory
*env* environment variables
*stdin* standard input stream
*stdout* standard output sink

m

main script entrypoint

bindings

*dir* applicative? combiner? path?
𝄢

current working directory

𝄢

This value is always set to the directory containing the script being run.

𝄢

It can and should be used to load sibling/child paths, e.g. *dir*/foo to load the 'foo.bass' file in the same directory as the current file.

<host: .>
*env* scope?
𝄢

environment variables

𝄢

System environment variables are only available to the entrypoint script. To propagate them further they must be explicitly passed to thunks using with-env.

𝄢

System environment variables are unset from the physical OS process as part of initialization to ensure they cannot be leaked.

{
:SECRET_TOKEN "im a spooky value"
}
*stdin* source?
𝄢

standard input stream

𝄢

Values read from *stdin* will be parsed from the process's stdin as a JSON stream.

<source: empty>
*stdout* sink?
𝄢

standard output sink

𝄢

Values emitted by a script to *stdout* will be encoded as a JSON stream to the process's stdout.

<sink: empty>
(main) applicative? combiner?
𝄢

script entrypoint

𝄢

The [script:main] function is called with any provided command-line args when running a Bass script.

𝄢

Scripts should define it to capture system arguments and run the script's desired effects.

𝄢

Putting effects in [script:main] instead of running them at the toplevel makes the Bass language server happier.

.strings module

Simple functions for manipulating UTF-8 encoded strings.

(load (.strings))
result
<scope: <thunk NFRAJLC6LDIDU: (.strings)>>

index

i

includes? returns true if str includes substr

j

join joins a list of strings together with delim in between

l

length returns the string's length

s

split split a string on a delimiter

u

upper-case capitalizes all letters in the string

bindings

(join delim strs) applicative? combiner?
𝄢

joins a list of strings together with delim in between

(use (.strings))
result
(
  1. strings
)
(strings:join ", " ["Hello", "World"])
result
"Hello, World"
(split delim str) applicative? combiner?
𝄢

split a string on a delimiter

(use (.strings))
result
(
  1. strings
)
(strings:split "a=b" "=")
result
(
  1. "a"
  2. "b"
)
(upper-case str) applicative? combiner?
𝄢

capitalizes all letters in the string

(use (.strings))
result
(
  1. strings
)
(strings:upper-case "hallelujah")
result
"HALLELUJAH"
(includes? str substr) applicative? combiner?
𝄢

returns true if str includes substr

(use (.strings))
result
(
  1. strings
)
(strings:includes? "team" "i")
result
false 
(strings:includes? "racecar" "car")
result
true
(length str) applicative? combiner?
𝄢

returns the string's length

(use (.strings))
result
(
  1. strings
)
(strings:length "hello")
result
5

.git module

Bare essentials for fetching Git repositories, using the git CLI from an image passed on stdin.

This module is limited to functions necessary for fetching other Bass scripts, i.e. bootstrapping.

(load (.git (linux/alpine/git)))
result
<scope: <thunk C286M0DF4QNSA: (.git)>>

index

c

checkout returns the repo checked out to the given ref

g

github a path root for repos hosted at github.com

l

ls-remote resolves a ref to a sha at the remote repo

p

path returns a path root for repos at the given base URL

bindings

(ls-remote repo ref & timestamp) applicative? combiner?
𝄢

resolves a ref to a sha at the remote repo

𝄢

Does not cache. Used to resolve the ref at a point in time.

(use (.git (linux/alpine/git)))
result
(
  1. git
)
(git:ls-remote "https://github.com/vito/bass" "main")
stderr: 9 lines 
=> resolve image config for docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b3
71a6cbe2630a4b37d23275658bd3f2 [0.02s]
=> docker-image://docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe263
0a4b37d23275658bd3f2 CACHED [0.00s]
-> resolve docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d
23275658bd3f2 [0.00s]
=> git ls-remote https://github.com/vito/bass main [0.64s]
=> exporting to client directory [0.00s]
-> copying files 83B [0.00s]
result
"836efe1a4b59be0c148ae4cbc25f7eff581d9dde"
(checkout repo ref) applicative? combiner?
𝄢

returns the repo checked out to the given ref

𝄢

The thunk for cloning the repo is labeled with the given ref. If the ref refers to a branch, you may want to resolve it to a sha first with [git:ls-remote] so that it's not cached forever.

𝄢

Submodules are always initialized.

(use (.git (linux/alpine/git)))
result
(
  1. git
)
(git:checkout "https://github.com/vito/bass" "ea8cae6d4c871cb14448d7254843d86dbab8505f")
result
.git
{
:image
.git
{
:image
.git
{
:image
.git
{
:image
{
:repository "alpine/git"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d23275658bd3f2"
}
:cmd .git
:args
(
  1. "clone"
  2. "https://github.com/vito/bass"
  3. ./
)
}
:cmd .git
:args
(
  1. "fetch"
  2. "origin"
  3. "ea8cae6d4c871cb14448d7254843d86dbab8505f"
)
}
:cmd .git
:args
(
  1. "checkout"
  2. "ea8cae6d4c871cb14448d7254843d86dbab8505f"
)
}
:cmd .git
:args
(
  1. "submodule"
  2. "update"
  3. "--init"
  4. "--recursive"
)
}
./
(path root memos) applicative? combiner?
𝄢

returns a path root for repos at the given base URL

𝄢

Please omit the trailing slash. (TODO: would be nice to just strip it or somehow make it a non-issue.)

(use (.git (linux/alpine/git)))
result
(
  1. git
)
(def gh (git:path "https://github.com" null))
result
gh 
gh/vito/bass/ref/main/
stderr: 9 lines 
=> resolve image config for docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b3
71a6cbe2630a4b37d23275658bd3f2 [0.01s]
=> docker-image://docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe263
0a4b37d23275658bd3f2 CACHED [0.00s]
-> resolve docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d
23275658bd3f2 [0.00s]
=> git ls-remote https://github.com/vito/bass main [0.52s]
=> exporting to client directory [0.00s]
-> copying files 83B [0.00s]
result
.git
{
:image
.git
{
:image
.git
{
:image
.git
{
:image
{
:repository "alpine/git"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d23275658bd3f2"
}
:cmd .git
:args
(
  1. "clone"
  2. "https://github.com/vito/bass"
  3. ./
)
}
:cmd .git
:args
(
  1. "fetch"
  2. "origin"
  3. "836efe1a4b59be0c148ae4cbc25f7eff581d9dde"
)
}
:cmd .git
:args
(
  1. "checkout"
  2. "836efe1a4b59be0c148ae4cbc25f7eff581d9dde"
)
}
:cmd .git
:args
(
  1. "submodule"
  2. "update"
  3. "--init"
  4. "--recursive"
)
}
./
(github & args) operative? combiner?
𝄢

a path root for repos hosted at github.com

𝄢

Memoizes ref resolution into the caller's *memos*, if set.

(use (.git (linux/alpine/git)))
result
(
  1. git
)
git:github/vito/bass/sha/ea8cae6d4c871cb14448d7254843d86dbab8505f/
result
.git
{
:image
.git
{
:image
.git
{
:image
.git
{
:image
{
:repository "alpine/git"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d23275658bd3f2"
}
:cmd .git
:args
(
  1. "clone"
  2. "https://github.com/vito/bass"
  3. ./
)
}
:cmd .git
:args
(
  1. "fetch"
  2. "origin"
  3. "ea8cae6d4c871cb14448d7254843d86dbab8505f"
)
}
:cmd .git
:args
(
  1. "checkout"
  2. "ea8cae6d4c871cb14448d7254843d86dbab8505f"
)
}
:cmd .git
:args
(
  1. "submodule"
  2. "update"
  3. "--init"
  4. "--recursive"
)
}
./
(git:github/vito/bass/sha/ "ea8cae6d4c871cb14448d7254843d86dbab8505f")
result
.git
{
:image
.git
{
:image
.git
{
:image
.git
{
:image
{
:repository "alpine/git"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d23275658bd3f2"
}
:cmd .git
:args
(
  1. "clone"
  2. "https://github.com/vito/bass"
  3. ./
)
}
:cmd .git
:args
(
  1. "fetch"
  2. "origin"
  3. "ea8cae6d4c871cb14448d7254843d86dbab8505f"
)
}
:cmd .git
:args
(
  1. "checkout"
  2. "ea8cae6d4c871cb14448d7254843d86dbab8505f"
)
}
:cmd .git
:args
(
  1. "submodule"
  2. "update"
  3. "--init"
  4. "--recursive"
)
}
./
git:github/vito/bass/ref/main/
stderr: 9 lines 
=> resolve image config for docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b3
71a6cbe2630a4b37d23275658bd3f2 [0.02s]
=> docker-image://docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe263
0a4b37d23275658bd3f2 CACHED [0.00s]
-> resolve docker.io/alpine/git@sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d
23275658bd3f2 [0.01s]
=> git ls-remote https://github.com/vito/bass main [0.47s]
=> exporting to client directory [0.00s]
-> copying files 83B [0.00s]
result
.git
{
:image
.git
{
:image
.git
{
:image
.git
{
:image
{
:repository "alpine/git"
:platform
{
:os "linux"
}
:tag "latest"
:digest "sha256:66b210a97bc07bfd4019826bcd13a488b371a6cbe2630a4b37d23275658bd3f2"
}
:cmd .git
:args
(
  1. "clone"
  2. "https://github.com/vito/bass"
  3. ./
)
}
:cmd .git
:args
(
  1. "fetch"
  2. "origin"
  3. "836efe1a4b59be0c148ae4cbc25f7eff581d9dde"
)
}
:cmd .git
:args
(
  1. "checkout"
  2. "836efe1a4b59be0c148ae4cbc25f7eff581d9dde"
)
}
:cmd .git
:args
(
  1. "submodule"
  2. "update"
  3. "--init"
  4. "--recursive"
)
}
./

.time module

(load (.time))
result
<scope: <thunk TOCE8LOG569JE: (.time)>>

index

d

daily returns a timestamp of the current day
day 24 hours

e

every-minute returns a timestamp of the current minute

h

hour 60 minutes
hourly returns a timestamp of the current hour

m

measure evaluates a form and and logs the time it took
minute 60 seconds
monthly returns a timestamp of the current month

w

week 7 days
weekly returns a timestamp of the current week

y

yearly returns a timestamp of the current year

bindings

minute number?
𝄢

60 seconds

60
hour number?
𝄢

60 minutes

3600
day number?
𝄢

24 hours

86400
week number?
𝄢

7 days

604800
(every-minute) applicative? combiner?
𝄢

returns a timestamp of the current minute

(hourly) applicative? combiner?
𝄢

returns a timestamp of the current hour

(daily) applicative? combiner?
𝄢

returns a timestamp of the current day

(weekly) applicative? combiner?
𝄢

returns a timestamp of the current week

(monthly) applicative? combiner?
𝄢

returns a timestamp of the current month

(yearly) applicative? combiner?
𝄢

returns a timestamp of the current year

(measure form) operative? combiner?
𝄢

evaluates a form and and logs the time it took

𝄢

Returns the value returned by the form.

(use (.time))
result
(
  1. time
)
(defn sleep [duration] (run (from (linux/alpine) ($ sleep (str duration)))))
result
sleep 
(time:measure (sleep 1))
stderr: 8 lines 
debug   (time (sleep 1)) => null took 1.381675131s
=> docker-image://docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697
984fba772b3976835194c6d4 CACHED [0.00s]
-> resolve docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba7
72b3976835194c6d4 [0.01s]
=> resolve image config for docker.io/library/alpine@sha256:8914eb54f968791faf6a8638949e48
0fef81e697984fba772b3976835194c6d4 [0.02s]
=> sleep 1 [1.24s]
result
null

.regexp module

(load (.regexp))
result
<scope: <thunk 34KM6DJUQ7I80: (.regexp)>>

index

c

case matches a string against regexp callback pairs

bindings

(case str & re-fn-pairs) operative? combiner?
𝄢

matches a string against regexp callback pairs

𝄢

Ignore (_) may be used to implement a catch-all branch.

𝄢

Raises an error if none of the branches match.

(use (.regexp))
result
(
  1. regexp
)
(regexp:case "foo bar" "foo (\\w+)" $1)
result
"bar"