Crush Builtin Reference

295 commands · 45 namespaces

$comp

$global.comp

Comparison operators.

The commands behind the <, <=, >, >=, ==, and != operators in expression mode -- $a < $b is exactly $comp.lt $a $b under the hood. Each one works on any pair of comparable values, not just numbers (strings, times, durations, and more all support ordering). Imported into the global scope, so both forms are always available.

$comp.eq

$comp.eq left=any right=any

$true if left side is equal to right side.

In expression mode, this method can be used via the == operator.

Input signature

This command accepts the following arguments:

  • left (any) the left side of the comparison.

  • right (any) the right side of the comparison.

Examples

eq 10 5
(10 == 5)

Output signature

bool

$comp.gt

$comp.gt left=any right=any

$true if left side is greater than right side.

In expression mode, this method can be used via the > operator.

Input signature

This command accepts the following arguments:

  • left (any) the left side of the comparison.

  • right (any) the right side of the comparison.

Examples

gt 10 5
(10 > 5)

Output signature

bool

$comp.gte

$comp.gte left=any right=any

$true if left side is greater than or equal right side.

In expression mode, this method can be used via the >= operator.

Input signature

This command accepts the following arguments:

  • left (any) the left side of the comparison.

  • right (any) the right side of the comparison.

Examples

gte 10 5
(10 >= 5)

Output signature

bool

$comp.lt

$comp.lt left=any right=any

$true if left side is less than right side.

In expression mode, this method can be used via the < operator.

Input signature

This command accepts the following arguments:

  • left (any) the left side of the comparison.

  • right (any) the right side of the comparison.

Examples

lt 10 5
(10 < 5)

Output signature

bool

$comp.lte

$comp.lte left=any right=any

$true if left side is less than or equal than right side.

In expression mode, this method can be used via the <= operator.

Input signature

This command accepts the following arguments:

  • left (any) the left side of the comparison.

  • right (any) the right side of the comparison.

Examples

lte 10 5
(10 <= 5)

Output signature

bool

$comp.neq

$comp.neq left=any right=any

$true if left side is not equal to right side.

In expression mode, this method can be used via the != operator.

Input signature

This command accepts the following arguments:

  • left (any) the left side of the comparison.

  • right (any) the right side of the comparison.

Examples

ne 10 5
(10 != 5)

Output signature

bool

$comp.not

$comp.not argument=bool

Negates the argument.

In expression mode, this method can be used via the ! operator.

Input signature

This command accepts the following arguments:

  • argument (bool) the value to negate.

Examples

not $true
(!$true)

Output signature

bool

$cond

$global.cond

Logical operators (and and or).

The commands behind the and and or operators in expression mode -- $a and $b is exactly $cond.and $a $b under the hood. Both are short-circuiting and accept booleans or commands that return a boolean; see help $cond.and or help $cond.or for the full semantics and examples. Imported into the global scope, so both forms are always available.

$cond.and

and condition:(bool|command)... -> boolean

$true if all arguments are true.

Every argument to and must be either a boolean or a command that returns a boolean. The and command will check all arguments in order, and if any of them are false, and will return false. If all conditions are true, and returns true.

Do note that and is a short circuiting command, meaning that if one of the conditions is found to be false, and will not evaluate any remaining closures.

In expression mode, this method can be used via the and operator.

Examples

# true, if $file exists and is a symlink
and $($file.exists) {$(stat $file)[0].is_symlink}

# true, if $file exists and is a symlink
($file.exists() and {stat($file)[0].is_symlink})

$cond.or

or condition:(bool|command)... -> boolean

$true if any argument is true.

Every argument to or must be either a boolean or a command that returns a boolean. The or command will check all arguments in order, and if any of them are true, or will return true. If all conditions are false, or returns false.

Do note that or is a short circuiting command, meaning that if one of the conditions is found to be true, or will not evaluate any remaining closures.

In expression mode, this method can be used via the or operator.

Examples

$stat_out := $(stat $file)[0]

# true, if $file is either a symlink or a directory
or $stat_out.is_symlink $stat_out.is_dir

# true, if $file is either a symlink or a directory
($stat_out.is_symlink or $stat_out.is_dir)

$constants

$global.constants

Language constants.

$control

$global.control

Commands to control crush behavior.

The language's control-flow and process-execution builtins: conditionals and loops (if, match, while, loop, for, break, and continue), error handling (try, throw), job control (bg, fg, sleep, timeout, pause, terminate), running external commands (cmd), and script-level utilities like source, which, jobs, exit, and help itself.

Imported into the global scope, so e.g. $control.if and bare if are the same command. In practice everything here is almost always written bare, since these are effectively the language's own keywords.

$control.assert

$control.assert condition=bool [message=string]

Error out if the condition is false.

Unlike assertions in some other languages, crush assert simply stops execution through by erroring out. This can be caught using a try-command; the error's type (as seen via catch {|$e| ...}'s $e.type) is always AssertionError, so a catch clause can filter on it specifically with catch AssertionError {...} (see try's own help for more on catch filters).

Input signature

This command accepts the following arguments:

  • condition (bool) the condition to check.

  • message (default: "Assertion failed") the message to show if the condition is false.

Examples

assert (1 + 1 == 2)
assert ($x > 0) "x must be positive"
try { assert ($x > 0) } catch AssertionError {|$e| echo ("not positive: {}".format($e.message))}

Output signature

empty

$control.bg

$control.bg job=integer

Resume a paused job, letting it continue running in the background.

Unlike a job started with a trailing & (which is in the background from the moment it starts), bg acts on a job that already exists and is currently paused (e.g. via pause) -- it resumes it without putting it in the foreground the way fg would.

Input signature

This command accepts the following arguments:

  • job (integer) the job id of the paused job to resume in the background.

Output signature

empty

$control.break

$control.break

Break execution of a loop.

Output signature

empty

$control.cmd

$control.cmd command=file [<any>=any...] [arguments=any...]

Execute an external command.

Globs are file-expanded. Argument and switch order is preserved.

Input signature

This command accepts the following arguments:

  • command (file) the file path to the command to execute.

  • <any>=$any (any) Switches to pass in to the command. The name will be prepended with a double dash '--', unless it is a single character name, in which case a single dash '-' will be prepended

  • arguments (any) arguments to pass in to the command.

Output signature

binary_stream

$control.commands

$control.commands

List currently executing commands.

All commands currently executing, one row per command rather than per job -- see jobs for the job-level view a pipeline's several commands share.

Output signature

A table input stream with the following columns

  • job_id (integer) the id of the job this command is running as part of.

  • command_id (integer) the id of this specific command invocation.

  • definition (string) this command's own invocation, as source text -- distinct from its job's definition, which is the whole job's text.

  • type (string) whether this command is a builtin, an external process, or a closure.

  • status (string) whether this command's job is running, paused, or terminated -- a command has no independent status of its own.

$control.continue

$control.continue

Break execution of the current iteration of a loop and continue to the next lap.

Output signature

empty

$control.eval

$control.eval input=$(one_of $string $file $binary)

Evaluate a string or binary blob of crush code.

The return value of eval is the value of the last command actually executed in input -- either the last top-level statement, or an earlier return (which also stops the rest of the input from running, same as inside a closure). Every other statement's value is discarded.

Input signature

This command accepts the following arguments:

  • input (one_of $string $file $binary) the code to evaluate.

Examples

eval "echo hello"

$control.exit

$control.exit [status=integer] [--force]

Exit the shell.

If other jobs are still running, exit fails with an error unless force is set, in which case those jobs are terminated first.

Input signature

This command accepts the following arguments:

  • status (default: 0) the exit status to set for the process.

  • force (default: false) terminate all running jobs.

Output signature

empty

$control.fg

$control.fg [job=integer]

Return the output of a background pipeline.

A job started with a trailing & runs in the background and registers its eventual result for later retrieval; fg waits for and returns that result.

Input signature

This command accepts the following arguments:

  • job (integer) the job id of the background job to put into the foreground.

Examples

# Create a pipe
$pipe := $($(table_input_stream value=$integer).pipe)
# Create a job that writes 100_000 integers to the pipe and put this job in the background
seq 100_000 | $pipe.write &
# Create a second job that reads from the pipe and sums all the integers and put this job in the background
$sum_job_handle := $($pipe.read | sum &)
# Close the pipe so that the second job can finish
$pipe.close
# Put the sum job in the foreground
fg $sum_job_handle

$control.for

$control.for [<any>=any...] body=command

Execute a command once for each element in a stream.

Input signature

This command accepts the following arguments:

  • <any>=$any (any) the name to bind each element to, as name=stream (exactly one pair).

  • body (command) the block to execute once per element, with the bound name available as a variable.

Examples

# Iterate over the processes on the host
for i=$($host.procs) {
  echo $("Iterating over process {}".format $i.name)
}
# Print ten messages
for i=$(seq to=10) {
  echo $("Lap #{}".format $i)
}
# for looks the same in expression mode, thanks to some syntectic sugar
(
    $sum := 0
    for $i = seq(5) {
        $sum = $sum + $i
    }
    $sum
)

Output signature

empty

$control.help

$control.help [topic=any] [format=string]

Show help on the specified value.

The help command will show you help about a thing that you pass in. If you, for example pass in an integer (e.g. help 3), then you will see a help message about how crush represents integers and what methods an integer holds. You can also pass in any command to help (e.g. help $files for help on the files command). Note that you will need to prepend the $ sigil to the command name, since you're not using it as the command name.

If help's input is a pipeline, help shows help on the value in the pipeline. Otherwise, if a topic argument is given, help shows help on that value instead. With neither, help shows this introductory message.

Input signature

This command accepts the following arguments:

  • topic (any) the topic you want help on.

  • format (default: terminal, allowed: html, markdown, terminal) output format. The default, terminal, will render the help directly into the terminal. The other formats return a string containing either an html fragment or markdown.

Examples

# Show this message
help $help
# Show help on the root namespace
help $global

Output signature

empty

$control.if

$control.if condition=bool true_clause=command [else=string] [false_clause=command]

Conditionally execute a command once.

Input signature

This command accepts the following arguments:

  • condition (bool) the condition to filter on.

  • true_clause (command) the command to invoke if the condition is true.

  • false_clause (command) the (optional) command to invoke if the condition is false.

Examples

if ($a > 10) {
  echo big
} else {
  echo small
}
# if is real grammar in expression mode too, with the exact same syntax
assert (if $a > 10 { "big" } else { "small" } == "big")

$control.jobs

$control.jobs

List running jobs.

All currently running jobs

Output signature

A table input stream with the following columns

  • id (integer) the job's id.

  • parent (one_of $integer $empty) the id of the job this job is nested inside, if any.

  • definition (string) the job's definition, i.e. the invocation that started it, as source text.

  • type (string) whether the job is running interactively or in the background.

  • status (string) whether the job is running, paused, or terminated.

$control.loop

$control.loop body=command

Repeatedly execute the body until the break command is called.

Input signature

This command accepts the following arguments:

  • body (command) the command to repeatedly invoke.

Examples

loop {
  if $(i_am_tired) {
    break
  }
  echo Working
}
# loop is real grammar in expression mode too, with the exact same syntax
assert ((
    $i := 0
    $sum := 0
    loop {
        if $i >= 5 { break }
        $sum = $sum + $i
        $i = $i + 1
    }
    $sum
) == 10)

Output signature

empty

$control.match

$control.match subject=any body=command

Branch on a value against a sequence of cases.

The body is a block containing a sequence of arms, where each arm is one of:

  • case <value> {<body>} matches if the subject equals <value>.

  • any <stream> {<body>} matches if the subject equals any individual value produced by reading <stream> (e.g. $(seq 5 10) or a list).

  • is <type> {<body>} matches if the subject's type is <type>.

  • default {<body>} always matches.

Arms are tried in order; the first one that matches runs, and the rest are skipped. If nothing matches, match errors.

Input signature

This command accepts the following arguments:

  • subject (any) the value to match against.

  • body (command) a block containing the match's arms.

Examples

match $x {
    case 2 {echo "$x is 2"}
    any $(seq 5 10) {echo "$x is between 5 and 10"}
    is $string {echo "$x is a string"}
    default {echo "I don't know what $x is"}
}
# match is real grammar in expression mode too, with the exact same syntax
assert (match $x {
    case 2 {"two"}
    any $(seq 5 10) {"between 5 and 10"}
    is $string {"a string"}
    default {"something else"}
} == "two")

$control.pause

$control.pause jid=integer

Pause the given job.

Input signature

This command accepts the following arguments:

  • jid (integer) the job id for the job to pause.

Output signature

empty

$control.resume

$control.resume jid=integer

Resume the given job.

Input signature

This command accepts the following arguments:

  • jid (integer) the job id for the job to resume.

Output signature

empty

$control.return

$control.return [value=any]

Break execution of a closure command and optionally return a value.

The return command can only be used when inside of a closure command. Closure blocks can not break early using the return command. Do note that you can use the return command inside of a closure block which is nested arbitrarily deeply inside of a closure command, which will stop execution of all inner blocks and return the closure command.

Input signature

This command accepts the following arguments:

  • value (any) the value to return.

Examples

# Define a factorial command
$factorial := {
  |$number: $integer|
  if ($number == 1) {
    return 1
  } else {
    return ($number * factorial($number - 1))
  }
}
# Call the command
factorial 5

Output signature

empty

$control.schedule

$control.schedule interval=duration [initial_delay=duration] [command=command] [--schedule_at_fixed_rate] [--once]

Schedule events at specified time intervals.

  • If a command is specified, timer will run the command at the specified cadence.

  • If timer is used inside a pipeline, it will read one row of input at the specified cadence and write it out again. This allows you to set the pace of the output of another command.

  • Otherwise, timer will simply write an empty row at the specified cadence. This empty row can then act as a heartbeat, allowing a downstream command to get woken up at the right interval.

If a command fails, the timer will stop.

Input signature

This command accepts the following arguments:

  • interval (duration) the interval between heartbeats.

  • initial_delay (duration) the delay for the first heartbeat. If no initial delay is specified, use the interval parameter.

  • command (command) a command to run at each heartbeat.

  • schedule_at_fixed_rate (default: false) if heart beat delivery starts blocking, catch up by sending more heartbeats afterwards.

  • once (default: false) only schedule a single heartbeat. After that, exit.

Examples

# Show one row of the pipeline output every second
files / --recursive | schedule 1s
# Wait for a second and then print hello once
schedule 1s command={ echo hello } --once
# Print Hello to the screen once per second
schedule 1s | each {echo Hello}

$control.sleep

$control.sleep duration=duration

Pause execution of commands for the specified amount of time.

Input signature

This command accepts the following arguments:

  • duration (duration) the time to sleep for.

Examples

sleep 10s

Output signature

empty

$control.source

$control.source [files=one_of $string $file $glob $re...]

Evaluate one or more files into current crush session.

The return value of source is the value of the last command actually executed in the sourced file(s) -- either the last top-level statement, or an earlier return (which also stops the rest of the input from running, same as inside a closure). Every other statement's value is discarded.

When sourcing multiple files in one call, only the very last one's own return value (by the same rule) becomes source's return value -- every earlier file is still run to completion (including any of its own side effects), but its own return value is discarded. A glob or regex argument counts each file it matches separately for this purpose: the last file matched wins, not the last argument given.

Input signature

This command accepts the following arguments:

  • files (one_of $string $file $glob $re) the files to source.

Examples

source *.crush

$control.terminate

$control.terminate jid=integer

Terminate the given job.

A job may continue running for some time after receiving a termination notification. Output pipelines produced by the job will still be readable and will contain any buffered IO already sent to the job before it received the termination notification.

Input signature

This command accepts the following arguments:

  • jid (integer) the job id for the job to terminate.

Examples

# Create a job that produces a lot of output
$all_files := $(files --recursive /)
# Read a few lines of output
$all_files | head
# Find the job id of the job we want to terminate
jobs
# Ask the job to terminate.
terminate 1
# This will output the number of buffered rows that were buffered
$all_files | count

Output signature

empty

$control.throw

$control.throw error_type=string message=string

Raise a custom error, catchable and discriminable by its own error type.

Unlike every other error in Crush, a thrown error's type (as seen via catch {|$e| ...}'s $e.type) is error_type itself, not a fixed name tied to whatever went wrong internally -- so a script or library can define and catch its own error categories.

Input signature

This command accepts the following arguments:

  • error_type (string) the error's type, e.g. "NotFound". Visible to a catch block as $e.type.

  • message (string) the error's message. Visible to a catch block as $e.message.

Examples

try { throw "NotFound" "no such user" } catch {|$e| assert ($e.type == "NotFound")}

Output signature

empty

$control.timeit

$control.timeit it=command [number=integer] [repeat=integer] [--verbose]

Execute a command many times and estimate the execution time.

Every run's own output is discarded by default -- it's the timing that matters, and printing (or even draining) it once per run, possibly thousands of times over, would either flood the terminal or cost real time of its own. Pass --verbose to print every run's output instead, the same way echo would.

Input signature

This command accepts the following arguments:

  • it (command) the command to time.

  • number (integer) the number of runs in each repeat. If unspecified, timeit will repeat enough times for each batch to take roughly 0.4 seconds.

  • repeat (default: 5) repeat count. The average speed in the fastest repeat will be returned.

  • verbose (default: false) print every run's own output instead of silently discarding it.

Examples

timeit {files|sort size}
timeit --verbose {ls}

$control.timeout

$control.timeout duration=duration command=command

Run a command, terminating it if it hasn't finished within the given duration.

If command finishes before duration elapses, timeout returns its result normally. Otherwise, a termination signal is sent to it -- the same cooperative mechanism terminate uses, which only a command that actually checks for it (like sleep) will actually stop for; most builtins don't, and will keep running in the background regardless -- and timeout itself fails with a timeout error.

A command left running this way isn't just background noise: crush waits for every spawned thread to finish before the whole session exits, so a command that never cooperates and never finishes on its own (an infinite loop, for example) will keep the script -- or the whole interactive session -- from exiting cleanly, even though timeout itself already returned its error.

Input signature

This command accepts the following arguments:

  • duration (duration) how long to let the command run before terminating it.

  • command (command) the command to run.

Examples

timeout 5s {sleep 30s}

$control.timer

$control.timer it=command [--verbose]

Execute a command once and return the execution time.

The command's own output is discarded by default, the same way and for the same reason timeit's own is -- pass --verbose to print it instead.

Input signature

This command accepts the following arguments:

  • it (command) the command to time.

  • verbose (default: false) print the command's own output instead of silently discarding it.

Examples

timer {files|sort size}

Output signature

duration

$control.try

$control.try body=command [catches=any...]

Execute a command, recovering from any error it produces.

If body fails, execution of body stops at the failing statement. Zero or more catch <filter>? {...} clauses may follow body, each the literal word catch, an optional filter (a string, glob, or regex -- anything implementing __is__, same as like/=~/match's is arm), and a block.

On failure, clauses are tried in order; the first one whose filter matches the error's type field (see below) -- or that has no filter at all -- runs, and the rest are skipped. Its block receives a struct describing the error as its single unnamed argument: message (the error text), type (the internal error variant's name, e.g. IOError, or a custom type set via throw), and command (the name of the command that failed, if known -- empty otherwise).

If no clause's filter matches, the error propagates normally, exactly as if try had no catch clauses of its own. With no catch clauses at all, an error is recovered from silently -- execution continues normally with whatever comes after try.

Input signature

This command accepts the following arguments:

  • body (command) the command to attempt.

  • catches (any) zero or more catch <filter>? {...} clauses: the literal word catch, an optional filter pattern, and a block to run if that filter matches the error's type (or always, if no filter is given).

Examples

try {
  $risky.command
} catch {
  |$error| echo ("Recovered: {}".format($error.message))
}
try {
  $risky.command
} catch ^(Serde) {
  |$e| echo ("Serialization error: {}".format($e.message))
} catch Dns* {
  |$e| echo ("DNS error: {}".format($e.message))
}
# try/catch is real grammar in expression mode too, with the exact same syntax
# -- except a glob filter like Dns* above needs $(...) there, since glob literals
# only parse in command mode
assert (try {
    throw("DnsTimeout", "no response")
} catch ^(Serde) {
    |$e| "serde"
} catch $(Dns*) {
    |$e| "dns"
} == "dns")

$control.which

$control.which command=string

Find the path of an executable.

which searches the directories of the $crush.end[PATH] enivornment variable list for the specified command and returns the path to the first match.

Input signature

This command accepts the following arguments:

  • command (string) the name of the command to find.

Examples

# Returns '/bin/ps'
which ps

Output signature

file

$control.while

$control.while condition=command [body=command]

Repeatedly execute the body for as long the condition is met.

The loop body is optional. If not specified, the condition is executed until it returns false. This effectively means that the condition becomes the body, and the loop break check comes at the end of the loop.

Input signature

This command accepts the following arguments:

  • condition (command) the condition.

  • body (command) the command to invoke as long as the condition is true.

Examples

while {'./some_file'.exists} {echo "hello"}
# while is real grammar in expression mode too -- the condition is a bare
# expression there, not wrapped in its own {...} block like in command mode
assert ((
    $i := 0
    $sum := 0
    while $i < 5 {
        $sum = ($sum + $i)
        $i = ($i + 1)
    }
    $sum
) == 10)

Output signature

empty

$crush

$global.crush

Information about this Crush session.

The crush namespace holds information about this particular Crush process, as distinct from state about the external world (which lives in the host namespace) or the data flowing through a pipeline. This is where you configure the prompt and title, where you emit or read warning, configure syntax highlighting, read and write OS environment variables, and inspect running threads. See docs/config.md for a guided tour of what's configurable here.

$crush.history

$crush.history

List previous commands.

All previous invocation

Output signature

A table input stream with the following columns

  • idx (integer) the command's position in the history, counting back from the most recent.

  • command (string) the command line as it was entered.

$crush.language_mode

$crush.language_mode

Returns the current language mode, either command or expression.

Command mode is the default mode.

Output signature

string

$crush.run_mode

$crush.run_mode

Returns how crush is currently running, either interactive or non-interactive.

In interactive mode, the prompt is shown and commands are entered interactively with access to history, keyboard shortcuts, etc. In non-interactive mode, no prompt is shown and commands are read from a file. The run mode can not be changed while crush is running. It is decided by how crush was started.

Output signature

string

$crush.threads

$crush.threads

All the subthreads crush is currently running.

Output signature

A table input stream with the following columns

  • job_id (integer) the id of the job this thread is running as part of.

  • command_id (integer) the id of the specific command invocation this thread is running.

  • created (time) when this thread was created.

  • name (string) the thread's name.

$crush.byte_unit

$global.crush.byte_unit

Formatting style for table columns containing byte sizes.

$crush.byte_unit.get

$crush.byte_unit.get

Get the current byte unit.

Output signature

string

$crush.byte_unit.list

$crush.byte_unit.list

List all available byte units.

Output signature

A table input stream with the following columns

  • name (string) the byte unit's name.

$crush.byte_unit.set

$crush.byte_unit.set byte_unit=string

Set the current byte unit.

Input signature

This command accepts the following arguments:

  • byte_unit (string) the new byte unit.

Output signature

empty

$crush.cmdcache

$global.crush.cmdcache

The cached list of runnable external $PATH commands, kept to avoid rescanning $PATH repeatedly.

$crush.cmdcache.evict

$crush.cmdcache.evict

Forget the cached list of runnable external $PATH commands.

The list of runnable $PATH entries is scanned from disk once and cached for the rest of this session, the same way a real shell's own command hash table works -- avoiding a full $PATH rescan (real filesystem I/O) every time it's needed is the reason this cache exists; whatever currently reads it (right now, only "did you mean" suggestions for an unknown command) would otherwise pay that cost every single time instead of once per session. The tradeoff this evicts: an executable installed into $PATH after this session started won't show up in the cache until either this is called or the process restarts. Has no effect on how commands are actually resolved or run -- only on this cached list.

Examples

$crush.cmdcache.evict

Output signature

empty

$crush.cmdcache.list

$crush.cmdcache.list

Every external command name currently cached, mapped to its resolved full path.

This is the same cache $crush.cmdcache.evict clears and both resolve_external_command (actually running an external command) and "did you mean" suggestions read -- populated with a fresh $PATH scan first if it's currently missing or stale, the same population any other reader triggers, so this always reflects what this session would currently resolve or suggest, never a stale or empty result.

Examples

$crush.cmdcache.list

Output signature

dict $string $file

$crush.env

$global.crush.env

Environment variables.

$crush.locale

$global.crush.locale

Locale data for Crush.

$crush.locale.get

$crush.locale.get

Get the current locale.

Output signature

string

$crush.locale.list

$crush.locale.list

List all available locales.

Output signature

A table input stream with the following columns

  • name (string) the locale's name.

$crush.locale.set

$crush.locale.set locale=string

Set the current locale.

Input signature

This command accepts the following arguments:

  • locale (string) the new locale.

Output signature

empty

$crush.prompt

$global.crush.prompt

Prompt data for Crush.

$crush.prompt.get

$crush.prompt.get

Get the current prompt command.

Output signature

one_of $command $empty

$crush.prompt.set

$crush.prompt.set [prompt=command]

Set a new prompt command.

Input signature

This command accepts the following arguments:

  • prompt (command) the new command to invoke in order to produce a prompt.

Output signature

empty

$crush.title

$global.crush.title

Title data for Crush.

$crush.title.get

$crush.title.get

Get the current title command

Output signature

one_of $command $empty

$crush.title.set

$crush.title.set [title=command]

Set a new title command.

Input signature

This command accepts the following arguments:

  • title (command) the new command to invoke in order to produce a title.

Output signature

empty

$crush.warn

$global.crush.warn

Warnings reported by commands that experienced a partial failure.

$crush.warn.list

$crush.warn.list

List recent warnings reported by commands that experienced a partial failure.

Commands that continue past a partial failure (e.g. one bad row out of a stream) report it as a warning rather than aborting. A bounded number of the most recent warnings are kept here (see $crush.warn.limit); in interactive mode, they are also printed as soon as they happen, unless disabled (see $crush.warn.print).

Output signature

A table input stream with the following columns

  • timestamp (time) when the warning was recorded.

  • command (one_of $string $empty) the name of the command that reported the warning, if known.

  • message (string) the warning message.

  • file (one_of $string $empty) the source file the warning was reported from, if known.

  • location (one_of $string $empty) the location within the source file the warning was reported from, if known.

$crush.warn.new

$crush.warn.new message=string

Report a warning to the bounded log $crush.warn.list keeps.

Every builtin that presses on past a partial failure (each/where/group/files, and others) reports it through this exact same mechanism instead of aborting; this is that mechanism made directly callable, for a script or closure that wants to flag something without stopping.

Input signature

This command accepts the following arguments:

  • message (string) the warning message to report.

Examples

$crush.warn.new "something looked off, continuing anyway"

Output signature

empty

$crush.warn.limit

$global.crush.warn.limit

How many warnings $crush.warn.list keeps before evicting the oldest.

$crush.warn.limit.get
$crush.warn.limit.get

Get how many warnings $crush.warn.list keeps before evicting the oldest.

Output signature

integer
$crush.warn.limit.set
$crush.warn.limit.set limit=integer

Set how many warnings $crush.warn.list keeps before evicting the oldest.

Input signature

This command accepts the following arguments:

  • limit (integer) the new warning limit.

Output signature

empty

$crush.warn.print

$global.crush.warn.print

Whether warnings are printed to the screen as they happen.

$crush.warn.print.get
$crush.warn.print.get

Get whether warnings are printed to the screen as they happen.

Output signature

bool
$crush.warn.print.set
$crush.warn.print.set print=bool

Set whether warnings are printed to the screen as they happen.

Only takes effect in interactive mode -- a warning is always recorded in $crush.warn.list either way, this only controls whether it's also printed immediately. Defaults to true.

Input signature

This command accepts the following arguments:

  • print (bool) whether to print warnings to the screen as they happen.

Examples

$crush.warn.print.set $false

Output signature

empty

$dns

$global.dns

DNS querying and metadata.

DNS, the Domain Name System (https://en.wikipedia.org/wiki/Domain_Name_System), is the internet's distributed naming system -- it translates human-readable domain names like example.com into the numeric IP addresses computers actually use to connect to each other, along with a handful of other record types (mail servers, text records, service discovery, ...).

It's hierarchical and distributed rather than a single lookup table: no one server holds every record. A name is resolved by delegating from root servers down through top-level-domain servers to the domain's own authoritative servers, though in practice a query is usually answered by a caching resolver (see $dns.nameserver) long before it needs to walk that whole chain.

$dns.domain

$dns.domain

DNS domain, if any.

Reads the local domain configured in /etc/resolv.conf's domain line, if any -- no network query is made. Returns $empty if none is configured.

Output signature

any

$dns.nameserver

$dns.nameserver

List of default nameservers.

Reads the nameservers configured in /etc/resolv.conf -- no network query is made. This is exactly what $dns.query/$dns.query_reverse themselves fall back to when their own nameserver argument is left unset (specifically, the first one listed).

Output signature

list $string

$dns.query

$dns.query name=string [record_type=string] [--tcp] [nameserver=string] [port=integer] [--no_follow_cname] [timeout=duration]

Look up a DNS record.

The columns of the returned table depend on record_type:

  • A, AAAA, NS, PTR, and CNAME: target (string) and ttl (duration).

  • MX: target, preference (integer), and ttl.

  • SRV: target, priority, weight, port (all integer), and ttl.

  • TXT: text (binary) and ttl.

  • SOA: mname, rname (strings), serial (integer), and refresh, retry, expire, and ttl (all durations).

If a response's first answer is a CNAME record, it's followed transparently and the query is retried against the alias's target -- up to 8 hops, after which a chain that still hasn't resolved is a hard error rather than being followed forever (a spoofed or compromised nameserver could otherwise cause unbounded recursion, since plain UDP DNS has no cryptographic integrity). Set no_follow_cname=$true, or query for the CNAME record type directly, to see the alias itself instead of following it.

If nameserver isn't given, the first nameserver listed in /etc/resolv.conf is used (see $dns.nameserver). name is always looked up exactly as given -- unlike most system resolvers, this does not consult /etc/resolv.conf's search domains (see $dns.search_paths) to expand an unqualified name.

Input signature

This command accepts the following arguments:

  • name (string) DNS record to look up.

  • record_type (default: A, allowed: A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, TXT) DNS record type.

  • tcp (default: false) use TCP as the transport instead of UDP.

  • nameserver (string) the nameserver to talk to. If none is given, use the nameservers configured in /etc/resolv.conf.

  • port (default: 53) port to talk to the nameserver on.

  • no_follow_cname (default: false) if a CNAME record is encountered, do not follow it. Show the actual CNAME record instead.

  • timeout (default: 5s) connection timeout.

Examples

$dns.query "www.google.com" AAAA
$dns.query "example.com" MX
# See the alias itself instead of transparently following it
$dns.query "www.example.com" CNAME

$dns.query_reverse

$dns.query_reverse address=string [--tcp] [nameserver=string] [port=integer] [timeout=duration]

Perform a reverse DNS lookup on a given IP address.

Looks up the hostname associated with address via a PTR record, automatically building the reverse-lookup name DNS uses for this (e.g. under in-addr.arpa for IPv4, ip6.arpa for IPv6) -- address should be given as a plain, forward IP address, not already reversed. Returns the hostname as a plain string, or nothing if no PTR record exists for that address. Unlike $dns.query, this never follows a CNAME; a reverse zone is not expected to contain one.

Input signature

This command accepts the following arguments:

  • address (string) IP address to look up. Can be either IPv4 or IPv6.

  • tcp (default: false) use TCP connection instead of UDP.

  • nameserver (string) override the nameserver to talk to.

  • port (default: 53) DNS port.

  • timeout (default: 5s) connection timeout.

Examples

$dns.query_reverse "127.0.0.1"

Output signature

string

$dns.search_paths

$dns.search_paths

List of DNS search paths.

Reads the DNS search domains configured in /etc/resolv.conf -- no network query is made. A system resolver normally appends these, in order, to an unqualified hostname before giving up (e.g. trying host.example.com when asked to resolve plain host); $dns.query does not apply this itself -- name is always looked up exactly as given.

Output signature

list $string

$fs

$global.fs

File system functionality.

Commands for working with the filesystem: listing and stat-ing files (files, stat), changing directory (cd), computing disk usage (usage), listing mount points (mounts), and watching a path for changes (watch). Imported into the global scope, so e.g. $fs.cd and bare cd are the same command.

$fs.cd

$fs.cd destination=one_of $string $file $glob $re

Change to the specified working directory.

Input signature

This command accepts the following arguments:

  • destination (one_of $string $file $glob $re) the new working directory.

Output signature

empty

$fs.chmod

$fs.chmod [files=one_of $string $file $glob $re...] [permissions=string...] [follow_symlinks=bool] [--recursive]

Change permissions of one or more files.

Permissions are strings of the form [classes...][adjustment][modes..].

  • A class is one of u, g, o, a, signifying file owner, file group, other users and all users, respectively.

  • The adjustment must be one of +, -, and =, signifying added permissions, removed permissions and set permissions, respectively.

  • A mode is one of r w, x, signifying read, write and execute permissions.

Input signature

This command accepts the following arguments:

  • files (one_of $string $file $glob $re) the files to change the permissions of.

  • permissions (list $string) the set of permission adjustments to apply, in order.

  • follow_symlinks (default: true) if a target is a symlink, affect what it points to instead of the symlink itself.

  • recursive (default: false) if a target is a directory, recursively change permissions of its contents as well.

Examples

chmod foo.txt permissions="a=" permissions="u+r" # First strip all rights for all users, then re-add read rights for the owner
files --recursive | select file | chmod permissions="a+r" # Make everything in the current directory world-readable

Output signature

empty

$fs.chown

$fs.chown [files=one_of $string $file $glob $re...] [user=string] [group=string] [follow_symlinks=bool] [--recursive]

Change owner of one or more files.

Input signature

This command accepts the following arguments:

  • files (one_of $string $file $glob $re) the files to change the owner of.

  • user (string) the owning user for the files.

  • group (string) the owning group for the files.

  • follow_symlinks (default: true) if a target is a symlink, affect what it points to instead of the symlink itself.

  • recursive (default: false) if a target is a directory, recursively change the owner of its contents as well.

Examples

chown foo.txt user="root" group="wheel"
files --recursive | select file | chown user="root"

Output signature

empty

$fs.files

$fs.files [directory=one_of $string $file $glob $re...] [--recursive] [permissions=bool] [--inode] [links=bool] [user=bool] [group=bool] [size=bool] [--blocks] [modified=bool] [--accessed] [type=bool] [file=bool]

Show information about files and directories.

If given no arguments, list the contents to the current working directory. If given any unnamed arguments, those will be the files and directories to list.

By default, files will not recurse into subdirectories. You can override this using the --recursive switch.

Input signature

This command accepts the following arguments:

  • directory (one_of $string $file $glob $re) directories and files to list.

  • recursive (default: false) recurse into subdirectories.

  • permissions (default: true) show permissions.

  • inode (default: false) show inode number.

  • links (default: true) show link count.

  • user (default: true) show username.

  • group (default: true) show group name.

  • size (default: true) show file size.

  • blocks (default: false) show block count.

  • modified (default: true) show modification time.

  • accessed (default: false) show time of last file access.

  • type (default: true) show file type.

  • file (default: true) show file name.

$fs.mkdir

$fs.mkdir [files=one_of $string $file $glob $re...] [--ignore_existing]

Create one or more directories.

Input signature

This command accepts the following arguments:

  • files (one_of $string $file $glob $re) the directories to create.

  • ignore_existing (default: false) do not throw an error if a directory already exists.

Examples

mkdir foo
mkdir foo bar baz

Output signature

empty

$fs.mounts

$fs.mounts

List filesystem mount points.

Output signature

A table input stream with the following columns

  • size (one_of $integer $empty) size in bytes, if known.

  • available (one_of $integer $empty) available space in bytes, if known.

  • usage (one_of $float $empty) usage percentage, if known.

  • format (one_of $string $empty) filesystem type (ntfs, ext4, etc.), if known.

  • readonly (one_of $bool $empty) whether the filesystem is mounted readonly, if known.

  • name (one_of $string $empty) name assigned to this mountpoint, if any.

  • path (file) the mount location.

$fs.pwd

$fs.pwd

Return the current working directory.

Output signature

file

$fs.rm

$fs.rm [files=one_of $string $file $glob $re...] [--recursive] [--verbose]

Delete one or more files.

Returns a stream of deletion failures (or, with --verbose, successes too).

Input signature

This command accepts the following arguments:

  • files (one_of $string $file $glob $re) the files to delete.

  • recursive (default: false) if a target is a directory, recursively delete files and subdirectories.

  • verbose (default: false) if true, emit status updates for deleted files, not just errors.

Examples

rm foo.txt
files --recursive | select file | rm --verbose

Output signature

A table input stream with the following columns

  • file (file) the file this row describes.

  • deleted (bool) true if the file was successfully deleted.

  • status (string) "Deleted", or the error that prevented deletion.

$fs.stat

$fs.stat [destination=one_of $string $file $glob $re...] [--symlink]

Return a row with information about each file.

The return value contains the following columns:

  • is_socket (bool) is the file is a socket.

  • is_symlink (bool) is the file a symbolic link.

  • is_block (bool) is the file a block device.

  • is_dir (bool) is the file is a directory.

  • is_char (bool) is the file a character_device.

  • is_fifo (bool) is the file a fifo.

  • inode (integer) the inode number of the file.

  • nlink (integer) the number of hardlinks to the file.

  • uid (integer) The user id of the file owner.

  • gid (integer) The group id of the file owner.

  • size (integer) File size in bytes.

  • block_size (integer) The size of a single block on the device storing this file.

  • blocks (integer) The number of blocks used to store this file.

  • access_time (time) The last time this file was accessed.

  • modification_time (time) The last time this file was modified.

  • creation_time (time) The time this file was created.

  • file (path) The filename.

Input signature

This command accepts the following arguments:

  • destination (one_of $string $file $glob $re) the files to show the status for.

  • symlink (default: false) stat symlinks, not the files they point to.

Output signature

A table input stream with the following columns

  • is_socket (bool) true if the file is a Unix domain socket.

  • is_symlink (bool) true if the file is a symbolic link.

  • is_file (bool) true if the file is a regular file.

  • is_block (bool) true if the file is a block device.

  • is_dir (bool) true if the file is a directory.

  • is_char (bool) true if the file is a character device.

  • is_fifo (bool) true if the file is a named pipe (FIFO).

  • inode (integer) the file's inode number.

  • nlink (integer) the number of hard links to the file.

  • uid (integer) the id of the file's owning user.

  • gid (integer) the id of the file's owning group.

  • size (integer) the file's size in bytes.

  • block_size (integer) the size of the filesystem blocks the file is stored in.

  • blocks (integer) the number of blocks allocated to the file.

  • access_time (time) when the file was last accessed.

  • modification_time (time) when the file's contents were last modified.

  • creation_time (time) when the file was created.

  • file (file) the file this row describes.

$fs.touch

$fs.touch [files=one_of $string $file $glob $re...] [--no_create] [follow_symlinks=bool] [--recursive]

Set the modification and access times of one or more files.

If a file doesn't exist, it is created.

Input signature

This command accepts the following arguments:

  • files (one_of $string $file $glob $re) the files to touch.

  • no_create (default: false) do not create a file if it doesn't exist.

  • follow_symlinks (default: true) if a target is a symlink, affect what it points to instead of the symlink itself.

  • recursive (default: false) if a target is a directory, recursively touch its contents as well.

Examples

touch foo.txt
files --recursive | select file | touch

Output signature

empty

$fs.usage

$fs.usage [directory=one_of $string $file $glob $re...] [--silent] [--all]

Calculate the recursive directory space usage.

Input signature

This command accepts the following arguments:

  • directory (one_of $string $file $glob $re) the files to calculate the recursive size of.

  • silent (default: false) do not show directory sizes for subdirectories.

  • all (default: false) write sizes for all files, not just directories.

Output signature

A table input stream with the following columns

  • size (integer) the recursive size of the file or directory, in bytes.

  • blocks (integer) the recursive number of blocks allocated to the file or directory.

  • file (file) the file or directory this row describes.

$fs.watch

$fs.watch path=one_of $string $file $glob $re [--recursive]

Watch a path for filesystem changes and stream them as rows.

Uses the operating system's native filesystem notification API (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows), so what counts as a change and how quickly it is reported is a best-effort property of the host OS, not a cross-platform guarantee -- rapid changes may be coalesced, and exact granularity differs by platform.

Input signature

This command accepts the following arguments:

  • path (one_of $string $file $glob $re) the path to watch.

  • recursive (default: false) also watch subdirectories.

Examples

$fs.watch . --recursive | where {kind == "Create(File)"}

Output signature

A table input stream with the following columns

  • path (file) the file or directory the change was observed on.

  • kind (string) the kind of change, e.g. create, modify, or remove.

  • timestamp (time) when the change was observed.

$groups

$global.groups

User group commands.

Commands for querying user groups on this system -- $groups.list for every group and its gid, and lookup by name via groups[name]. Sibling to users, but for groups rather than individual accounts.

$grpc

$global.grpc

gRPC connection.

$grpc.connect connects to a gRPC service and returns a struct with one method per RPC the service exposes, tab-completable and self-documenting via help. See help $grpc.connect for the full connection and calling conventions, including streaming.

$grpc.connect

$grpc.connect host=string @ $(one_of $string $glob $re) [--plaintext] [timeout=duration] [port=integer]

Create a connection to a gRPC service.

gRPC (https://grpc.io) is Google's open-source, high-performance RPC framework, built on HTTP/2 and Protocol Buffers.

To send RPC calls to a server, you must first create a grpc connection, writing something like $conn := $($grpc.connect host=localhost service=* --plaintext).

The resulting connection struct will have one method for each endpoint on the chosen services of the host you connected to. When calling a method, there are two different ways to pass in input parameters.

If you want to pass exactly one message to the endpoint, e.g. because the endpoint does not use client streaming, you have the option of passing the fields of the message as arguments to the method call, e.g. $conn.ReverseString input=hello. The grpc methods support tab completion of argument names. They also come with help messages (e.g. help $conn.ReverseString) that describes the input and output format.

If you want to pass multiple messages to the endpoint, you must do so by piping in a table_input_stream, where the column names of the stream are identical to the field names of the message, e.g. $list.of foo bar baz | select input={$value} | $conn.ReverseString.

Output from a gRPC method call is always a $table_input_stream, with one row per message. If an endpoint does not use server side streaming, the output always has one row.

Once you are done with a gRPC connection, you should close it to free up resources. Do so by calling the close method, e.g. $conn.close.

Input signature

This command accepts the following arguments:

  • host (string) the host to connect to.

  • service (one_of $string $glob $re) the service to connect to on this host. This can be a string, a glob or a regular expression, in order to allow you to easily specify multiple services, e.g. use * to connect to all available services.

  • plaintext (default: false) use plaintext instead of TLS to connect.

  • timeout (default: 5s) the timeout for making calls.

  • port (default: 50051) the port to connect to.

Examples

$conn := $($grpc.connect host=localhost service=* --plaintext)
# Returns "olleh"
$conn.ReverseString input="hello"
# Returns a stream with the values "oof", "rab", and "zab"
$list.of foo bar baz | select input={$value} | $conn.ReverseString
# Close the connection once you're done
$conn.close

$host

$global.host

Information about the host this crush session is running on.

Information about the machine this Crush session is running on: memory, battery, uptime, process and thread tables, and (nested further) $host.os and $host.cpu for operating-system and CPU-specific metadata. Contrast with crush, which is about the Crush process itself, not the machine underneath it.

$host.battery

$host.battery

List all batteries in the system and their status

Output signature

A table input stream with the following columns

  • vendor (one_of $string $empty) the battery's manufacturer, if known.

  • model (one_of $string $empty) the battery's model name, if known.

  • technology (string) the battery's chemistry, e.g. lithium-ion.

  • cycle_count (one_of $integer $empty) the number of charge cycles the battery has gone through, if known.

  • temperature (one_of $float $empty) the battery's current temperature, if known.

  • voltage (float) the battery's current voltage.

  • health (float) the battery's remaining capacity relative to when it was new.

  • state (string) the battery's current charging state, e.g. charging or discharging.

  • charge (float) the battery's current charge level.

  • time_to_full (one_of $duration $empty) how long until the battery is fully charged, if known.

  • time_to_empty (one_of $duration $empty) how long until the battery is fully depleted, if known.

$host.memory

$host.memory

Memory usage of this host.

The output struct contains the following fields:

  • total, total amount of memory available to the host.

  • free, unused memory.

  • avail, available memory.

  • swap_total, total amount of swap available to the host.

  • swap_free, unused swap.

Output signature

struct

$host.name

$host.name

name of this host

Output signature

string

$host.procs

$host.procs

Return a table stream containing information on all running processes on this host.

$host.procs accepts no arguments.

Output signature

A table input stream with the following columns

  • pid (integer) the process id.

  • ppid (one_of $integer $empty) the parent process's id, if known.

  • user (string) the name of the user running the process.

  • rss (integer) the process's resident set size, i.e. physical memory in use.

  • vms (integer) the process's virtual memory size.

  • cpu (duration) the total CPU time the process has used.

  • status (string) the OS-level process state (e.g. "Runnable", "Sleeping", "Stopped", "Zombie") -- see sysinfo's ProcessStatus.

  • name (string) the process's executable path, or its name if the path isn't known.

$host.signal

$host.signal [pid=integer...] [signal=string]

Send a signal to a set of processes.

The set of existing signals is platform dependent, but common signals include SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGBUS, SIGFPE, SIGKILL, SIGUSR1, SIGSEGV, SIGUSR2, SIGPIPE, SIGALRM, SIGTERM, SIGCHLD, SIGCONT and SIGWINCH.

Input signature

This command accepts the following arguments:

  • pid (integer) the id of the process to send to.

  • signal (default: SIGTERM) the name of the signal to send.

Examples

# Create a `killall` command that kills any process whose name matches the specified pattern
# The pattern can be a an exact string, a wildcard, or a regex
$killall := { |$victim| $host.signal @$($host.procs|where {$name =~ $victim}|select pid | $list.collect) signal=SIGKILL}
# Kill all crush commands
killall ^(crush)

Output signature

empty

$host.threads

$host.threads

Return a table stream containing information on all running threads on this host.

$host.threads accepts no arguments.

Output signature

A table input stream with the following columns

  • tid (integer) the thread id.

  • pid (integer) the id of the process this thread belongs to.

  • priority (integer) the thread's scheduling priority.

  • user (duration) the CPU time the thread has spent in user mode.

  • system (duration) the CPU time the thread has spent in kernel mode.

  • name (string) the thread's name.

$host.uptime

$host.uptime

uptime of this host

Output signature

duration

$host.cpu

$global.host.cpu

Metadata about the CPUs of this host.

$host.cpu.arch

$host.cpu.arch

the name of the CPU architecture

Output signature

string

$host.cpu.count

$host.cpu.count

number of CPU cores

Output signature

integer

$host.cpu.load

$host.cpu.load

current CPU load

Output signature

struct

$host.os

$global.host.os

Metadata about the operating system this host is running.

$host.os.name

$host.os.name

name of the operating system

Output signature

string

$host.os.version

$host.os.version

Version of the operating system kernel.

Output signature

string

$io

$global.io

Data serialization I/O.

Reading and writing structured data in specific wire formats -- json, yaml, toml, csv, hex, base64, and percent encoding, and Crush's own native pup format, each its own to/from pair. Also home to a few general-purpose I/O commands that don't belong to any one format: http, echo, and readline. Imported into the global scope, so e.g. $io.json.from and bare $json.from are the same command.

$io.echo

$io.echo [values=any...] [--raw]

Prints all arguments directly to standard output.

If no arguments are passed to the values parameter, print the input pipeline value instead.

This command may at first appear pointless, since values entered on the prompt are printed to standard output by default. But that is only true when running a command interactively. When executing a file or running a closure, results are either completely ignored or returned as the return value of the block. In these situations, the echo command is useful for making sure a given value is written to standard output.

Input signature

This command accepts the following arguments:

  • values (any) the values to print.

  • raw (default: false) do not escape control characters in string values.

Examples

# These command invocations are equivalent
echo "Hello, world!"
"Hello, world!" | echo

Output signature

empty

$io.http

$io.http uri=string [method=string] [form=one_of $file $string $binary $binary_input_stream $glob $re] [header=string...] [timeout=duration]

Make a http request.

Returns a struct with the following fields:

  • status_code (integer) the http status code of the reply.

  • status_name (string) the name associated with the http status code.

  • header (list) the http headers of the reply.

  • body (binary_stream) the content of the reply.

The http status codes and corresponding names are defined in https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml.

Input signature

This command accepts the following arguments:

  • uri (string) URI to request.

  • method (default: GET, allowed: GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, PATCH, TRACE) the HTTP method to use in this request.

  • form (one_of $file $glob $re $string $binary $binary_stream) form content, if any.

  • header (list $string) HTTP headers, must be on the form "key:value".

  • timeout (default: 5s) connection timeout.

Examples

http "https://example.com/" header=$("Authorization: Bearer {}".format $token)

$io.readline

$io.readline [prompt=string] [history=string]

Read a string of input from the user.

The readline command uses the same keyboard shortcuts as crush itself uses internally.

Input signature

This command accepts the following arguments:

  • prompt (default: "crush# ") the prompt to show the user.

  • history (string) load and save history under specified name.

Examples

# Ask the user for their name
echo "What is your name?"
$name := $(readline prompt="name: ")
echo $("Hello, {}!".format $name)

Output signature

string

$io.base64

$global.io.base64

Base64 conversions.

Base64 text encoding of binary data, in either the standard or URL-safe alphabet -- $base64.to encodes, $base64.from decodes.

$io.base64.from

$io.base64.from [files=one_of $file $string $binary $binary_input_stream $glob $re...] [alphabet=string]

Read a Base64 value and decode it.

If no file is specified, use the input, which must be a binary or a string.

The standard alphabet follows RFC 4648, and uses a-z, A-Z, 0-9, +, and /. The urlsafe alphabet uses a-z, A-Z, 0-9, -, and .. Both use = for padding.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) the files to read from. Read from input if no file is specified.

  • alphabet (default: standard) base64 encoding style to use.

Examples

# Will output hello, world!
"aGVsbG8sIHdvcmxkIQ==" | $base64.from

Output signature

binary_stream

$io.base64.to

$io.base64.to [file=one_of $string $file $glob $re] [alphabet=string]

Write specified binary or string as Base64.

If no file is specified, produce a binary stream as output.

The standard alphabet follows RFC 4648, and uses a-z, A-Z, 0-9, +, and /. The urlsafe alphabet uses a-z, A-Z, 0-9, -, and .. Both use = for padding.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) the file to write to. Write to output if no file is specified.

  • alphabet (default: standard) base64 encoding style to use.

Examples

# Will output aGVsbG8sIHdvcmxkIQ==
"hello, world!" | $base64.to

Output signature

binary_stream

$io.bin

$global.io.bin

Binary data I/O.

Reads and writes raw binary data unchanged -- the simplest of the io codecs, with no structure or transformation applied. Useful as a building block, or for commands that just need a binary_stream from a file or the pipeline.

$io.bin.from

$io.bin.from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Read specified files (or input) as a binary stream.

If no file is specified, the input must be either binary or a string which will be converted to a binary using utf-8.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Output signature

binary_stream

$io.bin.to

$io.bin.to [file=one_of $string $file $glob $re]

Write specified iterator of strings to a file (or convert to BinaryStream) separated by newlines.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) destination file to write to. If unspecified, output is returned as a binary_stream.

$io.csv

$global.io.csv

CSV I/O.

Comma-separated tabular text, a widely used plain-text interchange format for spreadsheets and databases. Unlike most other io formats, $csv.from needs the column names and types given explicitly, since a CSV file's header row (if any) carries only names, never types; the separator character defaults to , but can be any character.

$io.csv.from

$io.csv.from [files=one_of $file $string $binary $binary_input_stream $glob $re...] [<any>=type...] [separator=string] [head=integer] [trim=string]

Parse specified files as CSV files.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) source. If unspecified, will read from input, which must be a binary or binary_stream.

  • <any>=$type (type) name and type of all columns.

  • separator (default: ',') column separator.

  • head (default: 0) skip this many lines of input from the beginning.

  • trim (string) trim this character from start and end of every value.

Examples

$csv.from separator="," head=1 name=$string age=$integer nick=$string

$io.hex

$global.io.hex

Hexadecimal conversions.

Hexadecimal (base16) text encoding of binary data, using lowercase digits. Handy for viewing or embedding binary data as plain, copy-pasteable text.

$io.hex.from

$io.hex.from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Read a hexadecimal value and decode it.

If no file is specified, use the input, which must be a binary or a string.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) the files to read from (read from input if no file is specified).

Examples

"68656c6c6f2c20776f726c6421" | $hex.from

Output signature

binary_stream

$io.hex.to

$io.hex.to [file=one_of $string $file $glob $re]

Write specified binary or string as hexadecimal.

If no file is specified, produce a binary stream as output.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

"hello, world!" | $hex.to

Output signature

binary_stream

$io.json

$global.io.json

JSON I/O.

JSON, the ubiquitous structured text format used by most web APIs and config files. A few Crush types JSON has no equivalent for are squashed on the way out -- see help $json.to for the full list.

$io.json.from

$io.json.from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse json format.

When deserializing a list, $json.from will try to infer the type of the list. If all of the elements of the list are of the same type, the list will be parametrized to the same type. If all elements are objects, and all objects have the same set of fields with the same types, the list will be turned into a table.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

http "https://jsonplaceholder.typicode.com/todos/3"| member body | $json.from

$io.json.to

$io.json.to [file=one_of $string $file $glob $re] [--compact]

Serialize to json format.

When serializing a list, some types have to be squashed, because json does not have all the same types that Crush does:

  • time values are turned into strings in the RFC 3339 format.

  • duration values are turned into the integer number of seconds in the duration.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) destination file to write to. If unspecified, output is returned as a binary_stream.

  • compact (default: false) disable line breaking and indentation.

Examples

files | $json.to

$io.lines

$global.io.lines

Line based I/O.

The simplest possible table: one string column, one row per line of text, split on newlines.

$io.lines.from

$io.lines.from [files=one_of $file $string $binary $binary_input_stream $glob $re...] [--skip_empty_lines] [--strip_whitespace]

Read specified files (or input) as a table with one line of text per row.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) the files to read from (read from input if no file is specified).

  • skip_empty_lines (default: false) do not emit empty lines.

  • strip_whitespace (default: false) strip whitespace from beginning and end of lines.

Output signature

A table input stream with the following columns

  • line (string) one line of input.

$io.lines.to

$io.lines.to [file=one_of $string $file $glob $re]

Write specified stream of strings to a file (or convert to BinaryStream) separated by newlines.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) destination file to write to. If unspecified, output is returned as a binary_stream.

$io.percent

$global.io.percent

Percent-encoding (URL-style) conversions.

Percent-encoding (%XX), the escaping scheme used in URLs and query strings -- every character outside the unreserved alphanumeric set is escaped on the way out.

$io.percent.from

$io.percent.from [input=string]

Decode a percent-encoded string.

Replaces every %XX escape with the byte it represents. Errors if the decoded bytes aren't valid UTF-8.

Input signature

This command accepts the following arguments:

  • input (string) the percent-encoded string to decode. Reads a string from input if unspecified.

Examples

# Returns "a b/c"
$percent.from "a%20b%2Fc"

Output signature

string

$io.percent.to

$io.percent.to [input=string]

Percent-encode a string for safe use in a URL.

Escapes every byte except the RFC 3986 unreserved set -- ASCII letters, digits, and -_.~ -- as %XX. This is the strictest common encoding, safe to use for a single path segment, query key, or query value. It does escape / and &, so don't apply it to an already-assembled path or query string, only to one component of one.

Input signature

This command accepts the following arguments:

  • input (string) the string to percent-encode. Reads a string from input if unspecified.

Examples

# Returns "a%20b%2Fc"
$percent.to "a b/c"

Output signature

string

$io.pup

$global.io.pup

Pup I/O.

Crush's own native binary serialization format, able to represent every Crush value exactly, including types the other io formats can't (like table_input_stream). Used internally to pass values between Crush processes, e.g. when sudo or $remote.exec runs a closure in another process.

$io.pup.from

$io.pup.from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse pup format.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

$pup.from serialized.pup

$io.pup.to

$io.pup.to [file=one_of $string $file $glob $re]

Serialize to pup format.

Pup is the native crush serialization format. All Crush types, including lambdas can be serialized to this format.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

files | $pup.to

$io.split

$global.io.split

Configurable word splitting I/O.

Like words, but with a configurable separator instead of whitespace -- splits input into a table with one string column, one row per field.

$io.split.from

$io.split.from [files=one_of $file $string $binary $binary_input_stream $glob $re...] separator=string [trim=string] [--allow_empty]

Read specified files (or input) as a table, split on the specified separator characters.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) the files to read from (read from input if no file is specified).

  • separator (string) characters to split on.

  • trim (string) characters to trim from start and end of each token.

  • allow_empty (default: false) allow empty tokens.

Output signature

A table input stream with the following columns

  • token (string) one token of the split input.

$io.toml

$global.io.toml

TOML I/O.

TOML, a structured text format designed to be easy for humans to read and write by hand, commonly used for configuration files.

$io.toml.from

$io.toml.from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse toml format.

Input can either be a binary stream or a file. All Toml types except datetime are supported. Datetime is not supported because the rust toml library currently doesn't support accessing the internal state of a datetime.

When deserializing a list, $toml.from will try to infer the type of the list. If all of the elements of the list are of the same type, the list will be parametrized to the same type. If all elements are objects, and all objects have the same set of fields with the same types, the list will be turned into a table.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

$toml.from Cargo.toml

$io.toml.to

$io.toml.to [file=one_of $string $file $glob $re]

Serialize to toml format.

If no file is specified, output is returned as a BinaryStream. The following Crush types are supported: File, string, integer, float, bool, list, table, table_input_stream, struct, time, duration, binary and binary_stream.

When serializing a list, some types have to be squashed, because toml does not have all the same types that Crush does:

  • time values are turned into strings in the RFC 3339 format.

  • duration values are turned into the integer number of seconds in the duration.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

$(files)[0] | $toml.to

$io.words

$global.io.words

Word splitting I/O.

Splits input on whitespace into a table with one string column, one row per word. See split for a configurable separator instead of whitespace.

$io.words.from

$io.words.from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Read input and split on word boundaries.

Input can be files or the input pipe, which must be a binary input stream, split on word boundaries, trim away punctuation and discard empty "words".

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) the files to read from (read from input pipe if no file is specified).

Output signature

A table input stream with the following columns

  • word (string) one word of the input.

$io.yaml

$global.io.yaml

YAML I/O.

YAML, a human-friendly structured text format commonly used for configuration files, with a less punctuation-heavy syntax than JSON and support for comments.

$io.yaml.from

$io.yaml.from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse yaml format.

When deserializing a list, $yaml.from will try to infer the type of the list. If all of the elements of the list are of the same type, the list will be parametrized to the same type. If all elements are objects, and all objects have the same set of fields with the same types, the list will be turned into a table.

Input signature

This command accepts the following arguments:

  • files (one_of $file $glob $re $string $binary $binary_stream) source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

(http "https://jsonplaceholder.typicode.com/todos/3").body | $yaml.from

$io.yaml.to

$io.yaml.to [file=one_of $string $file $glob $re]

Serialize to yaml format.

When serializing a list, some types have to be squashed, because yaml does not have all the same types that Crush does:

  • time values are turned into strings in the RFC 3339 format.

  • duration values are turned into the integer number of seconds in the duration.

Input signature

This command accepts the following arguments:

  • file (one_of $string $file $glob $re) destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

files | $yaml.to

$math

$global.math

Math commands.

Trigonometric (sin, cos, tan, asin, acos, atan), logarithmic and exponential (ln, log, exp, pow, sqrt), and rounding (floor, ceil, round, clamp, abs, sign) functions, plus the constants pi, tau, and e.

$math.abs

$math.abs number=$(one_of $float $integer)

The absolute value of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to take the absolute value of.

Examples

$math.abs -5

$math.acos

$math.acos number=$(one_of $float $integer)

The arc cosine of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the value, between -1 and 1, to take the arc cosine of.

Output signature

float

$math.asin

$math.asin number=$(one_of $float $integer)

The arc sine of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the value, between -1 and 1, to take the arc sine of.

Output signature

float

$math.atan

$math.atan number=$(one_of $float $integer)

The arc tangent of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the value to take the arc tangent of.

Output signature

float

$math.ceil

$math.ceil number=$(one_of $float $integer)

The smallest integer larger than number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to round up to the nearest integer.

Output signature

float

$math.clamp

$math.clamp number=$(one_of $float $integer) min=$(one_of $float $integer) max=$(one_of $float $integer)

Number restricted to the inclusive range [min, max].

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to clamp.

  • min (one_of $integer $float) the lower bound of the allowed range.

  • max (one_of $integer $float) the upper bound of the allowed range.

Examples

$math.clamp 15 min=0 max=10

$math.cos

$math.cos number=$(one_of $float $integer)

The cosine of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to take the cosine of, in radians.

Examples

$math.cos 1

Output signature

float

$math.exp

$math.exp number=$(one_of $float $integer)

e (Euler's number) raised to the power of number.

The same result is available as $math.pow $math.e number, but exp doesn't require knowing about the e constant, and its dedicated implementation is generally more numerically precise than going through a general-purpose pow.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the exponent to raise e to.

Examples

# Returns 1, since e^0 is 1
$math.exp 0

Output signature

float

$math.floor

$math.floor number=$(one_of $float $integer)

The largest integer smaller than number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to round down to the nearest integer.

Output signature

float

$math.ln

$math.ln number=$(one_of $float $integer)

The natural logarithm of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to take the natural logarithm of.

Output signature

float

$math.log

$math.log number=$(one_of $float $integer) base=$(one_of $float $integer)

The logarithm of number in base.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to take the logarithm of.

  • base (one_of $integer $float) the base of the logarithm.

Output signature

float

$math.pow

$math.pow base=$(one_of $float $integer) n=$(one_of $float $integer)

Raise the number to n.

Input signature

This command accepts the following arguments:

  • base (one_of $integer $float) the base to raise to a power.

  • n (one_of $integer $float) the exponent to raise the base to.

Output signature

float

$math.round

$math.round number=$(one_of $float $integer)

Number rounded to the nearest whole number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to round to the nearest whole number.

Output signature

float

$math.sign

$math.sign number=$(one_of $float $integer)

-1, 0 or 1 depending on the sign of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to inspect the sign of.

Examples

$math.sign -5

$math.sin

$math.sin number=$(one_of $float $integer)

The sine of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to take the sine of, in radians.

Examples

$math.sin 1

Output signature

float

$math.sqrt

$math.sqrt number=$(one_of $float $integer)

The square root of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to take the square root of.

Output signature

float

$math.tan

$math.tan number=$(one_of $float $integer)

The tangent of number.

Input signature

This command accepts the following arguments:

  • number (one_of $integer $float) the number to take the tangent of, in radians.

Output signature

float

$pty

$global.pty

Pseudo-terminal sessions, for driving and inspecting a real interactive session from a script.

$pty.create spawns a command attached to a fresh virtual terminal and returns a struct for controlling it: write sends input as if typed at the keyboard, wait_for blocks until the rendered screen matches a pattern, screen reads the current rendered screen as plain text, and pid/is_alive/terminate manage the underlying process. Used by Crush's own test suite to drive and assert on interactive behavior (tab completion, job control, signal handling) end to end, but useful for scripting any terminal program that expects a human at the keyboard.

$pty.create

$pty.create command=$(one_of $string $file $binary) [arguments=string...] [rows=integer] [cols=integer]

Spawn a command attached to a fresh virtual terminal, for driving and inspecting a real interactive session from a script.

Returns a struct with one method per operation (write, wait_for, contents, close, plus pid/alive). Always call close once done, to release the underlying process. For control characters (e.g. Ctrl-Z), use the module-level $pty.control constants (see $pty.control), not a field on this struct.

Input signature

This command accepts the following arguments:

  • command (one_of $string $file $binary) the program to run, e.g. crush.

  • arguments (string) arguments to pass to the program.

  • rows (default: 24) the number of rows of the virtual terminal.

  • cols (default: 80) the number of columns of the virtual terminal.

Examples

$t := $($pty.create crush)
$t.write "echo hello\n"
$t.wait_for "hello"
$t.write $pty.control.z
$t.close

Output signature

struct

$random

$global.random

Random number generation.

Uniformly distributed random values: float/integer for a single value, or float_stream/integer_stream for an endless stream of them. Floats are drawn from [0, 1); integers default to 0 or 1 (an exclusive upper bound of 2) unless a different bound is given.

$random.float

$random.float to=$(one_of $float $integer)

Generate a random floating point number between 0 (inclusive) and 1 (exclusive).

Input signature

This command accepts the following arguments:

  • to (default: 1.0) upper bound (exclusive).

Output signature

float

$random.float_stream

$random.float_stream to=$(one_of $float $integer)

Generate a stream of random floating point numbers between 0 (inclusive) and 1 (exclusive).

Input signature

This command accepts the following arguments:

  • to (default: 1.0) upper bound (exclusive).

Examples

# Generate 20 floating point numbers between 0 and 100
random.float_stream 100 | head 20

Output signature

A table input stream with the following columns

  • value (float) a random floating point number.

$random.integer

$random.integer [to=integer]

Generate a random integer between 0 and 1 (or some other specified number).

Input signature

This command accepts the following arguments:

  • to (default: 2) upper bound (exclusive).

Output signature

integer

$random.integer_stream

$random.integer_stream [to=integer]

Generate a stream of random integer numbers between 0 (inclusive) and 2 (exclusive).

Input signature

This command accepts the following arguments:

  • to (default: 2) upper bound (exclusive).

Examples

# Generate 20 integers between 0 and 100
random.integer_stream 100 | head 20

Output signature

A table input stream with the following columns

  • value (integer) a random integer.

$remote

$global.remote

Remote code execution.

Commands for running code on other machines over SSH: $remote.exec runs a closure on one host, $remote.pexec runs it across several in parallel, and $remote.identity lists the identities your ssh-agent has loaded. $remote.host tracks known-hosts entries, the same trust store ssh itself uses.

$remote.exec

$remote.exec command=command host=string [username=string] [password=string] [host_file=one_of $string $file $glob $re] [--ignore_host_file] [--allow_not_found]

Execute a command on a remote host.

Serializes command (a closure), sends it over SSH to host, runs it there in a fresh crush process, and returns its result. The remote host's key is checked against host_file unless ignore_host_file is set. Security note: setting ignore_host_file disables that check entirely (no protection against a different host answering at that address); allow_not_found instead trusts an unrecognized host's key on first use and saves it, rather than erroring -- both weaken protection against a machine-in-the-middle impersonating the remote host.

Input signature

This command accepts the following arguments:

  • command (command) the command to execute.

  • host (string) host to execute the command on.

  • username (string) username on remote machines.

  • password (string) password on remote machines. If no password is provided, agent authentication will be used.

  • host_file (one_of $string $file $glob $re) (~/.ssh/known_hosts) known hosts file.

  • ignore_host_file (default: false) skip checking the know hosts file.

  • allow_not_found (default: false) allow missing hosts in the known hosts file. Missing hosts will be automatically added to the file.

Examples

$remote.exec {$host.name} "my-server.example.com" username="alice"

$remote.identity

$remote.identity

List all known ssh-agent identities.

Output signature

A table input stream with the following columns

  • identity (string) the identity's comment, usually describing which key it is.

  • public_key (binary) the identity's public key.

$remote.pexec

$remote.pexec command=command [host=string...] [parallel=integer] [username=string] [password=string] [host_file=one_of $string $file $glob $re] [--ignore_host_file] [--allow_not_found]

Execute a command on a set of hosts.

Like exec, but runs command on every host listed in host (up to parallel of them at a time). pexec always attempts every host in the list, regardless of whether earlier hosts failed to connect or authenticate -- it never fails outright just because some, or even all, of the hosts couldn't be reached. A host that succeeds contributes one row (host/result columns) to the output; a host that fails contributes no row at all. Instead, the failure is logged as a warning (see $crush.warn.list) naming the host and the underlying error. pexec's own exit status stays 0 either way, so the only way to tell whether every host succeeded is to compare the length of the output to the length of the host list you passed in -- fewer output rows than hosts means some connections failed. The same host-key verification applies independently to each host -- see exec for what ignore_host_file/allow_not_found mean for security.

Input signature

This command accepts the following arguments:

  • command (command) the command to execute.

  • host (string) hosts to execute the command on.

  • parallel (default: 32) maximum number of hosts to run on in parallel.

  • username (string) username on remote machines.

  • password (string) password on remote machines. If no password is provided, agent authentication will be used.

  • host_file (one_of $string $file $glob $re) (~/.ssh/known_hosts) known hosts file.

  • ignore_host_file (default: false) skip checking the know hosts file.

  • allow_not_found (default: false) allow missing hosts in the known hosts file. Missing hosts will be automatically added to the file.

Examples

$remote.pexec {$host.name} "web1.example.com" "web2.example.com" username="alice"

Output signature

A table input stream with the following columns

  • host (string) the host the command was run on.

  • result (any) the command's own output value from that host.

$remote.host

$global.remote.host

Known remote hosts.

$remote.host.list

$remote.host.list [host_file=one_of $string $file $glob $re]

List all known hosts.

If a given host key has no hostname, the host column will be $empty.

Input signature

This command accepts the following arguments:

  • host_file (one_of $string $file $glob $re) (~/.ssh/known_hosts) known hosts file.

Output signature

A table input stream with the following columns

  • host (one_of $string $empty) the hostname, if the key has one.

  • public_key (string) the host's public key.

$remote.host.remove

$remote.host.remove [host_file=one_of $string $file $glob $re] @ $(one_of $string $glob $re) @ $(one_of $string $glob $re)

Remove hosts from known_hosts file.

Remove all hosts that match both the host and the key filters. Returns the number of host entries deleted.

Input signature

This command accepts the following arguments:

  • host_file (one_of $string $file $glob $re) (~/.ssh/known_hosts) known hosts file.

  • host (one_of $string $glob $re) host filter.

  • key (one_of $string $glob $re) key filter.

Output signature

integer

$sockets

$global.sockets

List opened sockets.

Lists the TCP and UDP sockets currently open on this machine -- the same information tools like netstat or ss report. Read-only: this namespace can tell you what's listening or connected, but (unlike $grpc.connect or $io.http) has no way to open a connection of its own.

$sockets.tcp

$sockets.tcp

List open TCP sockets.

Output signature

A table input stream with the following columns

  • local_address (string) the local IP address the socket is bound to.

  • local_port (integer) the local port the socket is bound to.

  • remote_address (string) the remote peer's IP address.

  • remote_port (integer) the remote peer's port.

  • pids (list $integer) the ids of the processes that own the socket.

  • state (string) the connection's current TCP state, e.g. listen or established.

$sockets.udp

$sockets.udp

List open UDP sockets.

Output signature

A table input stream with the following columns

  • local_address (string) the local IP address the socket is bound to.

  • local_port (integer) the local port the socket is bound to.

  • pids (list $integer) the ids of the processes that own the socket.

$stream

$global.stream

Stream handling commands.

Crush's pipes carry typed streams of rows, not bytes -- stream is where the SQL-like operations on those streams live: filtering (where), sorting, grouping, aggregating, joining two streams, deduplicating, and more. This namespace is imported into the global scope, so every command here works equally well as $stream.sort or the bare word sort -- most Crush pipelines are built by chaining these together with |.

$stream.all_match

$stream.all_match condition=command

True if condition is true for every row of input.

Stops reading input as soon as one non-matching row is found, rather than always consuming the whole stream. True for an empty input, same as an empty and chain would be. The columns of the row are exported to condition by name, exactly like where.

Input signature

This command accepts the following arguments:

  • condition (command) the condition to check for each row.

Examples

# Are all processes owned by root?
$host.procs | all_match {($user == "root")}

Output signature

bool

$stream.any_match

$stream.any_match condition=command

True if condition is true for at least one row of input.

Stops reading input as soon as one matching row is found, rather than always consuming the whole stream. The columns of the row are exported to condition by name, exactly like where.

Input signature

This command accepts the following arguments:

  • condition (command) the condition to check for each row.

Examples

# Is there any process using more than 50% of a CPU core?
$host.procs | any_match {($cpu > 50)}

Output signature

bool

$stream.avg

$stream.avg [field=string]

Calculate the average for the specific column across all rows.

If the input only has one column, the column name is optional. The column type must be numeric or a duration.

Input signature

This command accepts the following arguments:

  • field (string) the name of the column to find the average of.

Examples

$host.procs | avg cpu

$stream.concat

$stream.concat [field=string] [separator=string]

Concatenate all values of the specified column across all rows.

If the input only has one column, the column name is optional. The column can be numeric, or textual.

Input signature

This command accepts the following arguments:

  • field (string) the name of the column to concatenate.

  • separator (default: ", ") the separator to insert between each element.

Examples

$host.procs | concat name ":"

$stream.count

$stream.count

Count the number of rows in the input.

The input type can be any type that can be streamed, such as a table, a list, etc. If the input type is not a materialized type, such as a $table_input_stream, the whole stream will be consumed by this operation. Materialized types, i.e. $table, $list and $dict, have a know size, and count will not need to iterate over them to find it.

Examples

# Returns the number of processes on the system
$host.procs | count

Output signature

integer

$stream.drop

$stream.drop [drop=string...]

Drop specified columns from input stream, copy content of remaining columns into output.

This command is does the opposite of the select command. It copies all columns except the ones specified from input to output.

Input signature

This command accepts the following arguments:

  • drop (string) the columns to remove from the stream.

Examples

# Drop memory usage columns from output of ps
$host.procs | drop vms rss

$stream.each

$stream.each body=command

Runs a command one for each row of input.

The columns of the row are exported to the environment using the column names.

Input signature

This command accepts the following arguments:

  • body (command) the command to run.

Examples

$host.procs | where {$status != "Sleeping"} | each {echo ("{} is sleepy".format $name)}

Output signature

empty

$stream.fold

$stream.fold initial=any body=command

Accumulate a single result across all rows of input using a user-supplied closure.

body is called once per input row, with the accumulator available as acc and the row's own columns exported by name, exactly like where/each. Its return value becomes the accumulator for the next row; once the input is exhausted, the final accumulator is fold's own output. This is the general escape hatch for one-off aggregations that don't have (or don't need) their own dedicated command like sum or max.

Input signature

This command accepts the following arguments:

  • initial (any) the accumulator's value before the first row is processed.

  • body (command) called once per row with the accumulator (acc) and the row's own columns as named arguments; its return value is the next accumulator.

Examples

# Sum 1 through 5 by hand
seq 1 6 | fold {($acc + $value)} initial=0
# Build a comma separated string from a column
files | fold {("{}, {}".format($acc, $file))} initial=""

$stream.group

$stream.group [group_by=string...] [<any>=command...]

Group stream by the specified column(s).

Input signature

This command accepts the following arguments:

  • group_by (string) the column(s) to group by and copy into the output stream.

  • <any>=$command (command) create additional columns by aggregating the grouped rows using the supplied aggregation command. The supplied command will be called once for each group, with a table_input_stream containing all rows within that group. Whatever the command outputs will be the value for the specified column for that group.

Examples

# Group files in current tree by the number of hardlinks pointing to them, show
# the number of files and the sum total file size for each link count. Sort results
# by size.
files --recursive | group links file_count=$count size={sum size} | sort size

$stream.head

$stream.head [rows=integer]

Return the first row(s) of the input.

Input signature

This command accepts the following arguments:

  • rows (default: 10) the number of rows to return.

Output signature

A stream with the same columns as the input

$stream.join

$stream.join [<any>=any...]

Join two streams together on the specified keys.

Input signature

This command accepts the following arguments:

  • <any>=$any (any) fields to join.

Examples

join user=$(files) name=$($users.list)

$stream.max

$stream.max [field=string]

Calculate the maximum for the specific column across all rows.

If the input only has one column, the column name is optional. The column can be numeric, temporal, a string or a file.

Input signature

This command accepts the following arguments:

  • field (string) the name of the column to find the maximum of.

Examples

$host.procs | max cpu

$stream.median

$stream.median [field=string]

Calculate the median for the specific column across all rows.

If the input only has one column, the column name is optional. The column type must be numeric or a duration. If the column contains a NaN float value, median fails with an error rather than silently including it in (or excluding it from) the calculation.

Input signature

This command accepts the following arguments:

  • field (string) the name of the column to find the median of.

Examples

$host.procs | median cpu

$stream.min

$stream.min [field=string]

Calculate the minimum for the specific column across all rows.

If the input only has one column, the column name is optional. The column can be numeric, temporal, a string or a file.

Input signature

This command accepts the following arguments:

  • field (string) the name of the column to find the minimum of.

Examples

$host.procs | min cpu

$stream.prod

$stream.prod [field=string]

Calculate the product of the specified column across all rows.

Specifying the column is optional if the stream only has one column. The column type must be numeric.

Input signature

This command accepts the following arguments:

  • field (string) the name of the column to find the product of.

Examples

seq 5 10 | prod

$stream.rename

$stream.rename [<any>=string...]

Rename one or more columns of a stream.

Every argument name is the current name of a column, and its value is the new name to give it. Columns not mentioned pass through unchanged.

Input signature

This command accepts the following arguments:

  • <any>=$string (string) mapping from current column name to new column name.

Examples

files | rename file=path

Output signature

A stream with the same columns as the input

$stream.reverse

$stream.reverse

Reverses the order of the rows in the input.

Output signature

A stream with the same columns as the input

$stream.sample

$stream.sample [rows=integer]

Reservoir-sample rows rows from the input.

Every row of input has an equal probability of ending up in the output, and the whole stream never has to be materialized to pick them -- only rows rows are ever held in memory at once. Output order is not the input order.

Input signature

This command accepts the following arguments:

  • rows (default: 10) the number of rows to sample.

Examples

# Pick 5 pseudo-random lines out of a huge file, without reading it all into memory
$lines.from big_log_file.txt | sample 5

Output signature

A stream with the same columns as the input

$stream.select

$stream.select [copy_fields:string...] [*] [new_field=command]

Pass on some old fields and calculate new ones for each line of input.

Examples

# Show only the filename and discard all other columns
files | select file

# Add an extra column to the output of files that shows the time passed since last modification
files | select * age={(time.now() - modified)}

$stream.seq

$stream.seq [args=integer...] [from=integer] [to=integer] [step=integer]

Return a stream of sequential numbers.

With no arguments, seq counts forever starting at 0. Given one to three unnamed numbers, they're interpreted the same way Python's range does: seq to counts from 0 up to (but not including) to; seq from to starts at from instead; seq from to step also sets the step size. The from, to, and step named arguments below are equivalent to the two- and three-number unnamed forms, spelled out -- but can't be mixed with the unnamed form in the same call, since e.g. seq 3 to=10 would leave it ambiguous which one actually sets the end of the sequence.

Input signature

This command accepts the following arguments:

  • args (integer) 1 to 3 numbers: to, from to, or from to step -- see the command's own long help. Can't be combined with the from/to/step named arguments.

  • from (integer) the first number in the sequence. Defaults to 0.

  • to (integer) the end of the sequence (exclusive). If not specified, the sequence will continue forever.

  • step (integer) the step size. Defaults to 1.

Examples

seq 3
# Prepend an index column to the output of the files command
zip $(seq) $(files)

$stream.skip

$stream.skip [rows=integer]

Skip the specified number of rows from the beginning of the stream and return the remainder.

If the stream has fewer than the specified number of rows, an empty stream will be returned.

Input signature

This command accepts the following arguments:

  • rows (default: 1) the number of rows to skip.

Output signature

A stream with the same columns as the input

$stream.sort

$stream.sort [field=string...] [--reverse] [--case_insensitive]

Sort input stream based on one or more of it's columns.

If any sort column contains a NaN float value, sort fails with an error rather than picking an arbitrary position for it, since NaN has no defined ordering relative to other floats.

Input signature

This command accepts the following arguments:

  • field (string) the columns to sort on. Optional if input only has one column.

  • reverse (default: false) reverse the sort order.

  • case_insensitive (default: false) ignore case when sorting textual columns.

Examples

# Show the contents of the current directory, sorted first on type and then on filename
files | sort type file

Output signature

A stream with the same columns as the input

$stream.sum

$stream.sum [field=string]

Calculate the sum for the specific column across all rows.

If the input only has one column, the column name is optional.

The column contents must be exactly one of the types $integer, $float, or $duration.

Normally, sum expects the type of the column to be the type to sum over, but sum can also sum over a column of type any, so long as there is at least one row in the table, and all the rows are actually of the same type.

Input signature

This command accepts the following arguments:

  • field (string) the name of the column to find the sum of.

Examples

$host.procs | sum cpu

$stream.tail

$stream.tail [rows=integer]

Return the last row(s) of the input.

Input signature

This command accepts the following arguments:

  • rows (default: 10) the number of rows to return.

Output signature

A stream with the same columns as the input

$stream.tee

$stream.tee [branches=command...]

Duplicate the input stream into one or more side pipelines, passing the original stream through unchanged.

Each branches block receives its own independent copy of every row and runs to completion as its own pipeline, in parallel with the others; its own output is discarded, so a branch is only useful for its side effects (writing to a file, counting, etc). tee's own output is the untouched original stream, so it composes directly into a larger pipeline. If a branch fails, the failure is reported via $crush.warn.list rather than aborting tee or the other branches.

Input signature

This command accepts the following arguments:

  • branches (command) one or more pipelines to send an independent copy of the stream through.

Examples

# Write a snapshot to disk while continuing to filter the live stream
$host.procs | tee {$json.to snapshot.json} | where {($cpu > 50)}

Output signature

A stream with the same columns as the input

$stream.union

$stream.union [streams=any...]

Concatenate two or more streams with identical column types into one.

Every row of the first stream is output, in order, followed by every row of the second stream, and so on. All streams must have identical column types.

Input signature

This command accepts the following arguments:

  • streams (any) the streams to concatenate.

Examples

union $(seq 0 3) $(seq 10 13)

$stream.uniq

$stream.uniq [field=string]

Only output the first row whenever multiple rows has the same value for the specified column.

If no column is given, the entire rows are compared.

This command does not just remove consecutive repeated column values, any repeated column values over the entire stream are removed.

Input signature

This command accepts the following arguments:

  • field (string) the field to compare.

Examples

$host.procs | uniq user

Output signature

A stream with the same columns as the input

$stream.where

$stream.where condition=command

Filter out rows from input based on condition.

The columns of the row are exported to the environment using the column names, i.e. if the table the where command is applied to has columns a and b, then the environment will have variables type and name, the variables $type and $name will be set to the values of the columns in the current row on each execution of the closure.

Input signature

This command accepts the following arguments:

  • condition (command) the condition to filter on.

Examples

# List all subdirectories to the current working directory
files | where {$type == directory}

Output signature

A stream with the same columns as the input

$stream.zip

$stream.zip first=any second=any

Combine two streams of data into one containing one row of each input stream in each row of output.

If the two streams have different numbers of rows, the longer stream will be truncated to the length of the shorter one.

Input signature

This command accepts the following arguments:

  • first (any) the first stream.

  • second (any) the second stream.

Examples

# Prepend an index column to the output of the files command
zip $(seq) $(files)

$term

$global.term

Constants useful for manipulating the terminal, such as changing text color and text weight.

ANSI escape code constants for styling terminal output -- colors ($term.red, $term.green, ...), $term.bold, $term.underline, and $term.normal to reset. These are plain string values, not commands -- interpolate them directly into a string, e.g. via .format, most often to build a colorful $crush.prompt.

$types

$global.types

Crush built in types and type related builtins.

Every value type Crush knows about, and the methods you can call on instances of it -- string, integer, list, dict, time, duration, table, re, glob, and the rest, each its own sub-namespace of methods (e.g. "hello".upper, $my_list.push value). Also home to the type system's own cross-cutting machinery: class (defining new types), convert, typeof, like (pattern matching), materialize, and dir/member/members (generic value introspection). Imported into the global scope, so both $types.string and bare string refer to the same type.

$types.class

$types.class [parent=struct]

Create an empty new class.

Input signature

This command accepts the following arguments:

  • parent (struct) the parent type to inherit members from (if any).

Examples

# Create a class that represents a point in 2D space
$Point := $(class)
$Point.__short_help__ = "A point in 2D space"
$Point.__signature__ = "class Point"
$Point.__long_help__ = "Uses floating point numbers to represent the x and y coordinates"
$Point.__example__ = "$p := ($Point.new(1.0, 2.0))"
# Constructor takes two arguments, x and y
$Point.__init__ = {
  |$x:$float $y:$float|
  $this.x = $x
  $this.y = $y
}

$Point.len = {
  |
  short_help = "Returns the distance from the origin"
  |
  ($math.sqrt($this.x*$this.x + $this.y*$this.y))
}
# Overload the `+` operator to add two points. (Only available in expression mode)
$Point.__add__ = {
  |
  short_help = "Add two points together"
  $other : $struct "the other point."
  |
  ($Point.new(x=($this.x+$other.x), y=($this.y+$other.y)))
}
$p := $($Point.new x=1.0 y=2.0)
$p.len
$p2 := ($Point.new(x=-1.0, y=2.0))
$p3 := ($p + $p2)

Output signature

struct

$types.convert

$types.convert target_type=type [value=any]

Convert the value to the specified type.

Converting a value to the type it already holds always works and returns the original value. Most other conversions take the input value, convert it to a string and then attempt to parse that string as the desired type.

The following short cut conversions exist that do not go via a string representation:

  • $float to $integer the value is truncated to its integer part.

  • $integer to $bool 0 is false, all other values are true.

If convert's input is a pipeline, convert converts the value in the pipeline. Otherwise, convert requires a value to be provided as an argument, and converts that value instead.

Input signature

This command accepts the following arguments:

  • target_type (type) the type to convert the value to.

  • value (any) the value to convert.

Examples

convert $integer 1.8

$types.definition

$types.definition command=command

Returns the definition of the specified closure as a text string.

Returns nothing if the command is not a closure.

Note that the outputted of the definition builtin may reformatted, including switching code between expression mode and command mode.

Input signature

This command accepts the following arguments:

  • command (command) the closure to show the definition of.

Examples

# returns { $files --recursive '/'}
$all_the_files := {files --recursive /}
definition $all_the_files

Output signature

string

$types.dir

$types.dir [value=any]

List the member names of a value.

Works on any value -- a struct's own fields, a scope's local variables, or (for anything else, including a type value like $float) the methods its type declares.

If dir's input is a pipeline, dir lists the members of the value in the pipeline. Otherwise, dir requires a value to be provided as an argument, and lists the members of that value instead.

Pair with member to fetch one of the listed names -- member's own name argument, unlike the . operator, can be a runtime value instead of a fixed word in the source, so the two together let you enumerate and read members whose names aren't known ahead of time.

Input signature

This command accepts the following arguments:

  • value (any) the value to list the members of.

Examples

dir .
# The full help text of every method float has
dir $float | each {|$name| help ($float | member $name)}

Output signature

list $string

$types.like

$types.like value=any [pattern=any...]

Check if the specified value matches one or more patterns.

A pattern can be a string (exact match), a glob, a regular expression, a type (checks value's type), or any other value that implements an __is__ method -- like simply calls it. If multiple patterns are given, they're checked in order and like returns true as soon as one of them matches.

In expression mode, a single pattern can also be checked via the =~ operator (or !~ for the negation).

Input signature

This command accepts the following arguments:

  • value (any) the value to test.

  • pattern (any) the pattern(s) to test the value against.

Examples

# Match the string "fooo" against the regex ^(ooo)
like fooo ^(ooo)
# Same, in expression mode
(fooo =~ ^(ooo))
# A value matches if it equals any of several patterns
like fooo ^(ooo) *.txt "fooo"

Output signature

bool

$types.materialize

$types.materialize

Recursively convert all streams in io to materialized form.

Examples

# Put a table of files in the current directory into the variable $f
$f := $(files | materialize)
# Because we materialized the table stream into a table, counting the elements is not a destructive operation.
$f | count

$types.member

$types.member field=string [value=any]

Extract one named member from a value.

Works like the . member operator, except the member name is a runtime value (e.g. a variable) rather than a fixed word in the source -- use this when the name to look up isn't known until the script runs. Pair with dir to discover a value's member names first.

If member's input is a pipeline, member extracts the named member from the value in the pipeline. Otherwise, member requires a value to be provided as an argument, and extracts the named member from that value instead.

Input signature

This command accepts the following arguments:

  • field (string) the member to extract.

  • value (any) the value to extract the member from.

Examples

$uri := "https://raw.githubusercontent.com/liljencrantz/crush/refs/heads/master/example_data/dinosaurs.json"
http $uri | member body | $json.from
# member also takes its value as an argument instead of a pipe
member __neg__ 5
# dir lists a value's member names; member fetches one by name -- together
# they let you enumerate members whose names aren't known ahead of time
for name=$(dir 5) { echo (member $name 5) }

$types.members

$types.members

List the columns of any streamable input value as name/type pairs.

Works on anything that can be read as a stream of rows -- a table, a list, a dict, a struct, a scope -- and reports that stream's shape without consuming any of its actual rows.

Examples

$my_dict | members

Output signature

A table input stream with the following columns

  • name (string) the column's name.

  • type (type) the column's type.

$types.typeof

$types.typeof [value=any]

Return the type of the specified value.

If typeof's input is a pipeline, typeof returns the type of the value in the pipeline. Otherwise, typeof requires a value to be provided as an argument, and returns the type of that value instead.

Input signature

This command accepts the following arguments:

  • value (any) the value to provide the type of.

Examples

# Returns float
typeof 1.8

Output signature

type

$types.val

$types.val value=any

Return value.

This command is useful if you want to pass a command as input in a pipeline instead of executing it. It is different from the echo command in that val sends the value through the pipeline, whereas echo prints it to screen.

Input signature

This command accepts the following arguments:

  • value (any) the value to pass as output.

Examples

val $val

Output signature

any

$types.any

type any

Any type.

This is a wildcard type, matching a value of any other type. It shows up as the declared type of a column or argument that intentionally imposes no type restriction -- it is not a type user code constructs values of directly.

$types.binary

type binary

Binary data.

A binary value can be created by converting another value, e.g. convert $binary "hi", or by reading a binary_stream to completion with materialize, e.g. $bin.from ./Cargo.toml | materialize.

Binary data is immutable once created, and unlike string or file it has no legality constraint at all -- it's simply an arbitrary sequence of bytes, the type to reach for when data isn't necessarily text or a path. See help string for how the three sequence-of-data types (string, file, binary) differ. The most similar type is binary_stream, its one-shot streaming form.

$types.binary.__getitem__

$types.binary.__getitem__[index=integer]

Returns the byte at the specified offset.

Input signature

This command accepts the following arguments:

  • index (integer) index.

Examples

$($bin.from Cargo.toml)[4]

Output signature

integer

$types.binary.len

$types.binary.len

The number of bytes in the binary.

Output signature

integer

$types.binary_stream

type binary_stream

A stream of binary data.

A binary_stream is obtained by reading binary data without fully loading it into memory first, e.g. $bin.from ./Cargo.toml, or the body of an HTTP response from $io.http.

Like table_input_stream, it can only be read once. Pipe it through materialize to get a reusable binary value instead.

$types.bool

type bool

True or false.

A boolean value is one of the two literals $true or $false -- there is no other way to construct one. Booleans are immutable, and are the result type of every comparison (==, <, ...) and logical (and, or) operator.

$types.command

type command

A piece fo code that can be called.

The most common way to create a command is a closure literal, e.g. {echo hello}, or with named parameters, {|$x| echo $x}. Builtin commands are themselves command values and can be captured into a variable the same way, e.g. $e := $echo.

A command value is immutable -- calling it runs its body, but that doesn't change the value itself. Reassigning the variable that holds a command is a separate operation from mutating the command.

$types.dict

type dict $empty $empty

A mutable mapping from one set of values to another.

Create a dict with the $dict.of command, e.g. $dict.of a=1 b=2, or by collecting key/value columns out of piped table input with $dict.collect.

Dicts are mutable: entries can be inserted, removed, or have their value replaced in place. The most similar type is struct, which is also a mapping from keys to values, but with a fixed set of keys chosen when the struct is created rather than a dynamic, mutable set of keys.

$types.duration

type duration

A difference between two points in time.

To create your own duration use a duration literal, an integer number combined with one of the suffixes h, m, s, ms, and ns. 5s means five seconds, for example.

If you want to create a duration object with of a size not known at the point of writing the code, use the $duration.of method, for example

$duration.of seconds=10

A duration instance has nanosecond precision. It is represented internally as two 64 bit numbers, one for the number of seconds, and one for the nanosecond remainder.

durations are signed, i.e. they can be used to denote a negative span of time. Durations are immutable values. duration instances are often osed together with time instances: subtracting one time from another produces a duration, and a duration can be added to or subtracted from a time instance.

In expression mode, you can multiply or divide a duration by an integer.

$types.duration.__add__

$types.duration.__add__ + delta=$(one_of $duration $time) # Only available in expression mode

Add the specified delta or time to this duration.

Input signature

This command accepts the following arguments:

  • delta (one_of $duration $time) the delta or time to add.

$types.duration.__div__

$types.duration.__div__ / divisor=integer # Only available in expression mode

Divide this duration by the specified divisor.

Input signature

This command accepts the following arguments:

  • divisor (integer) the divisor to divide by.

Output signature

duration

$types.duration.__mul__

$types.duration.__mul__ * factor=integer # Only available in expression mode

Multiply this duration by the specified factor.

Input signature

This command accepts the following arguments:

  • factor (integer) the factor to multiply by.

Output signature

duration

$types.duration.__neg__

$types.duration.__neg__

Negate this duration.

Output signature

duration

$types.duration.__sub__

$types.duration.__sub__ - delta=duration # Only available in expression mode

Remove the specified delta from this duration.

Input signature

This command accepts the following arguments:

  • delta (duration) the delta to subtract.

Output signature

duration

$types.duration.days

$types.duration.days

Returns the number of days in this duration, rounded towards zero.

Output signature

integer

$types.duration.hours

$types.duration.hours

Returns the number of hours in this duration, rounded towards zero.

Output signature

integer

$types.duration.milliseconds

$types.duration.milliseconds

Returns the number of milliseconds in this duration, rounded towards zero.

Output signature

integer

$types.duration.minutes

$types.duration.minutes

Returns the number of minutes in this duration, rounded towards zero.

Output signature

integer

$types.duration.nanoseconds_part

$types.duration.nanoseconds_part

Returns the nanosecond part of this duration.

Output signature

integer

$types.duration.of

$types.duration.of [nanoseconds=integer] [microseconds=integer] [milliseconds=integer] [seconds=integer] [minutes=integer] [hours=integer] [days=integer]

Create a new duration.

Durations are stored as a time span in number of seconds. Because of leap seconds and daylight saving time, adding for example exactly one day to a time value will not always do what you might think, if a leap second or a daylight savings time changeover happened in the interim. The most common way to create a duration is to use a duration literal, such as 1s for 1 second or 5m for five minutes. But the $duration.of command offers more flexibility.

Input signature

This command accepts the following arguments:

  • nanoseconds (default: 0) the number of nanoseconds in the duration.

  • microseconds (default: 0) the number of microseconds in the duration.

  • milliseconds (default: 0) the number of milliseconds in the duration.

  • seconds (default: 0) the number of seconds in the duration.

  • minutes (default: 0) the number of minutes in the duration.

  • hours (default: 0) the number of hours in the duration.

  • days (default: 0) the number of days in the duration. This is internally represented as the number of seconds in a standard day.

Examples

$duration.of minutes=1 seconds=10

Output signature

duration

$types.duration.seconds

$types.duration.seconds

Returns the number of seconds in this duration, rounded towards zero.

Output signature

integer

$types.empty

type empty

Nothing.

The instance of the empty type is returned by commands that don't return any value, e.g. echo. There is no way to construct it directly -- it only ever shows up as the natural result of a command that produces no output.

$types.file

type file

Any type of file.

A file value is usually written as a bareword or single-quoted path, e.g. ./Cargo.toml or 'my file.txt' -- crush recognizes these as files rather than plain strings based on their syntax. You can also convert an existing string explicitly, e.g. convert $file "./Cargo.toml".

A file value simply names a path; the value itself is immutable, though of course the file it points at on disk can change, be created, or be removed out from under it via methods like remove or commands like $fs.mkdir. See help string for exactly how file differs from string and binary, the other two types that represent a sequence of data rather than a single scalar value; glob is also related, matching a whole set of paths rather than naming a single one.

$types.file.__getitem__

$types.file.__getitem__[name=$(one_of $string $file $binary)]

Return a file or subdirectory in the specified base directory.

Input signature

This command accepts the following arguments:

  • name (one_of $string $file $binary) the name of the file or subdirectory.

Examples

$filename := foo.txt
$base_directory := .
$file := $base_directory[$filename]

Output signature

file

$types.file.exists

$types.file.exists

True if the file exists.

Output signature

bool

$types.file.name

$types.file.name

The name (excluding path) of this file, as a string.

Output signature

string

$types.file.parent

$types.file.parent

The parent directory of this file.

Output signature

file

$types.file.read

$types.file.read

A read source for binary_stream values.

Output signature

binary_stream

$types.file.write

$types.file.write

Write a binary_stream to this file. If no stream is given, input pipe must be one.

Output signature

empty

$types.float

type float

A numeric type representing any number with floating point precision.

A float literal is a bare number containing a decimal point, e.g. 5.0 or -3.25.

A Crush float is a IEEE 754 64-bit (double precision) floating point number. Floats are immutable values. The most similar type is integer; mixing the two in an arithmetic expression promotes the result to a float.

$types.float.__add__

$types.float.__add__ + term=$(one_of $float $integer) # Only available in expression mode

Add this number and the specified term and return the result.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to add.

Output signature

float

$types.float.__div__

$types.float.__div__ / term=$(one_of $float $integer) # Only available in expression mode

Divide this number by the specified factor.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to divide by.

Output signature

float

$types.float.__mul__

$types.float.__mul__ * term=$(one_of $float $integer) # Only available in expression mode

Multiply this number and the specified factor and return the result.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to multiply.

Output signature

float

$types.float.__neg__

$types.float.__neg__

Negate this float.

Output signature

float

$types.float.__sub__

$types.float.__sub__ - term=$(one_of $float $integer) # Only available in expression mode

Subtract the specified term from this number and return the result.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to subtract.

Output signature

float

$types.float.infinity

$types.float.infinity

Infinity.

Output signature

float

$types.float.is_infinite

$types.float.is_infinite

True if this float is positive or negative infinity.

Output signature

bool

$types.float.is_nan

$types.float.is_nan

True if this float is NaN.

Output signature

bool

$types.float.max

$types.float.max

Largest finite float value.

Output signature

float

$types.float.min

$types.float.min

Smallest finite float value.

Output signature

float

$types.float.nan

$types.float.nan

Not a number.

Output signature

float

$types.glob

type glob

A pattern containing wildcards.

Globs are usually created by writing an unescaped string containing a wildcard character (* or ?), like files *.toml.

If you want to construct a new glob from a string, use the $glob.new command, e.g. $glob.new "*.txt".

Globs are immutable. The most similar type is re, which supports much richer patterns at the cost of more complex syntax.

$types.glob.__is__

$types.r#type.__is__ needle=any

True if the needle's type is this type. Not meant to be called directly -- use the like command, the =~ operator, or the is arm of a match block.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$types.glob.__is_not__

$types.r#type.__is_not__ needle=any

False if the needle's type is this type. Not meant to be called directly -- use the like command or the !~ operator.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$types.glob.files

$types.glob.files [directory=file]

Perform file matching of this glob.

Input signature

This command accepts the following arguments:

  • directory (file) the directory to match in. Use current working directory if unspecified.

Output signature

list $file

$types.glob.filter

$types.glob.filter [columns=string...]

Filter input stream based on this glob.

Search all textual (string and file) columns for matches of the glob, and output the rows that match.

Input signature

This command accepts the following arguments:

  • columns (string) Columns to filter on. Column must be textual. If no columns are specified, all textual columns are used.

Examples

# Recursively search current directory for all files containing four `a` characters in a row
files --recursive | $(*aaaa*).filter

Output signature

A stream with the same columns as the input

$types.glob.new

$types.glob.new glob=string

Create a glob from a string.

Input signature

This command accepts the following arguments:

  • glob (string) the string representation of the glob.

Output signature

glob

$types.integer

type integer

A numeric type representing an integer number.

An integer literal is a bare number, e.g. 5 or -3. Underscores may be used as digit separators to make large numbers easier to read, e.g. 1_000_000.

A Crush integer uses signed 128 bit precision. This means that the highest number that can be represented is 170141183460469231731687303715884105727, and the lowest is -170141183460469231731687303715884105728.

Integers are immutable values. The most similar type is float, used for numbers that need a fractional part; mixing an integer and a float in an arithmetic expression promotes the result to a float.

$types.integer.__add__

$types.integer.__add__ + term=$(one_of $float $integer) # Only available in expression mode

Add this number and the specified term and return the result.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to add.

$types.integer.__div__

$types.integer.__div__ / term=$(one_of $float $integer) # Only available in expression mode

Divide this number by the specified factor.

Dividing an integer by an integer zero is an error. Dividing by a float zero follows IEEE 754 (producing infinity or NaN), since the result is a float.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to divide by.

$types.integer.__mod__

$types.integer.__mod__ term=integer

Least positive residue after integer division.

A divisor of zero is an error.

Input signature

This command accepts the following arguments:

  • term (integer) the number to divide by.

Output signature

integer

$types.integer.__mul__

$types.integer.__mul__ * term=$(one_of $float $integer) # Only available in expression mode

Multiply this number and the specified factor and return the result.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to multiply.

$types.integer.__neg__

$types.integer.__neg__

Negate this integer.

Output signature

integer

$types.integer.__rem__

$types.integer.__rem__ term=integer

Remainder after integer division.

A divisor of zero is an error.

Input signature

This command accepts the following arguments:

  • term (integer) the number to divide by.

Output signature

integer

$types.integer.__sub__

$types.integer.__sub__ - term=$(one_of $float $integer) # Only available in expression mode

Subtract the specified term from this number and return the result.

Input signature

This command accepts the following arguments:

  • term (one_of $integer $float) the number to subtract.

$types.integer.max

$types.integer.max

Largest integer value.

Output signature

integer

$types.integer.min

$types.integer.min

Smallest integer value.

Output signature

integer

$types.list

type list $any

A mutable list of items, usually of the same type.

Create a list with the $list.of command, e.g. $list.of 1 2 3, or by collecting a column out of piped table input with $list.collect.

Lists are mutable: elements can be appended, removed, or replaced in place. The most similar type is table, which is also an ordered sequence of items but where each item is a row of several named, differently-typed columns rather than a single value.

$types.one_of

type one_of

One of

A one_of value is constructed by calling one_of as a command with all the types as arguments, e.g. one_of $file $string $regex. It's used the same way an ordinary type is, most commonly to declare that a signature parameter accepts any one of several types:

$ls := {|$directory : $(one_of $file $string $re $glob)| files $directory | select file | sort $file}

$types.one_of.__call__

$types.one_of.__call__ [types=type...]

Construct a one_of value type with the specified allowed types.

Input signature

This command accepts the following arguments:

  • types (type) the allowed types.

Examples

$one_of.of $file $string $regex

Output signature

type

$types.re

type re

A regular expression is an advanced pattern that can be used for matching and replacing text.

Regular expressions are usually created by writing using regexp literal syntax, e.g. files ^(^...$).

If you want to construct a new glob from a string, use the $re.new command, e.g. $re.new "[a-z]*\.txt".

Regular expressions are immutable. The most similar type is glob, which supports only simple wildcard patterns but with much simpler syntax.

$types.re.__is__

$types.r#type.__is__ needle=any

True if the needle's type is this type. Not meant to be called directly -- use the like command, the =~ operator, or the is arm of a match block.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$types.re.__is_not__

$types.r#type.__is_not__ needle=any

False if the needle's type is this type. Not meant to be called directly -- use the like command or the !~ operator.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$types.re.filter

$types.re.filter [columns=string...]

Filter input stream based on this regex.

Search all textual (string and file) columns for matches of the regex, and output the rows that match.

Input signature

This command accepts the following arguments:

  • columns (string) Columns to filter on. Column must be textual. If no columns are specified, all textual columns are used.

Examples

# Recursively search current directory for all files containing four `a` characters in a row
files --recursive | ^(aaaa).filter

Output signature

A stream with the same columns as the input

$types.re.new

$types.re.new pattern=string

Compile a string into a new regular expression instance.

Input signature

This command accepts the following arguments:

  • pattern (string) the new regular expression as a string.

Output signature

re

$types.re.replace

$types.re.replace text=string replacement=string

Replace the first match of the regex in text with the replacement.

The replacement string may reference capture groups from the match: $0 for the whole match, $1, $2, ... for positional groups, or $name for a named group ((?P<name>...)). Use ${1} (or ${name}) instead of $1 when the reference is immediately followed by a character that would otherwise be read as part of the group number or name.

Input signature

This command accepts the following arguments:

  • text (string) the text to perform replacement on.

  • replacement (string) the replacement text; may reference capture groups, see above.

Examples

# Replaces the first run of digits
^([0-9]+).replace "a123b456" "X"
# Swap the two halves of a dash-separated pair, using capture groups
^((.*)-(.*)).replace "123-456" "$2-$1"

Output signature

string

$types.re.replace_all

$types.re.replace_all text=string replacement=string

Replace all matches of the regex in text with the replacement.

The replacement string may reference capture groups from each match: $0 for the whole match, $1, $2, ... for positional groups, or $name for a named group ((?P<name>...)). Use ${1} (or ${name}) instead of $1 when the reference is immediately followed by a character that would otherwise be read as part of the group number or name.

Input signature

This command accepts the following arguments:

  • text (string) the text to perform replacement on.

  • replacement (string) the replacement text; may reference capture groups, see above.

Examples

# Replaces every run of digits
^([0-9]+).replace_all "a123b456c789" "X"
# Swap key and value in every space-separated pair
^(([a-z]+)=([0-9]+)).replace_all "a=1 b=2 c=3" "$2=$1"

Output signature

string

$types.re.replace_all_with

$types.re.replace_all_with text=string body=command

Replace all matches of the regex in text, computing each match's replacement with a closure.

body is called once per match, with the whole match and each of its capture groups (in order) as positional arguments; a capture group that didn't participate in a particular match (an optional group matched via a different alternative) is passed as empty. Its return value -- which must be a string -- becomes that match's replacement; returning the first argument (the whole match) unchanged leaves that particular match untouched. Unlike replace_all, whose replacement is a single fixed template (literal text plus backreferences) applied identically to every match, body can decide per match -- e.g. replacing only matches found in a lookup table and leaving every other match exactly as it was, which replace_all has no way to express.

Input signature

This command accepts the following arguments:

  • text (string) the text to perform replacement on.

  • body (command) called once per match with the whole match and its capture groups as positional arguments; its return value is that match's replacement.

Examples

# Upper-case every run of letters
^([a-z]+).replace_all_with "ab12cd34" {|$whole| $whole.upper}

Output signature

string

$types.scope

type scope

A scope in the Crush namespace.

A scope is normally not constructed directly -- crush creates one implicitly for the root namespace ($global) and for every closure or block invocation. The scope currently executing can be obtained by calling __current_scope__ on any existing scope value, e.g. $global.__current_scope__.

Scopes are mutable: declaring a new variable (:=) or assignment (=) modifies the scope it's declared or resolved in.

$types.scope.__all__

$types.scope.__all__

The names of all variable visible from the current scope.

Output signature

list $string

$types.scope.__current_scope__

$types.scope.__current_scope__

The current scope.

Output signature

scope

$types.scope.__getitem__

$types.scope.__getitem__[name=string]

Return the specified member in the current scope.

Input signature

This command accepts the following arguments:

  • name (string) the name of the member to look up.

$types.scope.__local__

$types.scope.__local__

The names of all variables defined in the local scope.

Output signature

list $string

$types.scope.__name__

$types.scope.__name__

The name of this scope, or empty if unnamed.

Output signature

one_of $string $empty

$types.scope.__read_only__

$types.scope.__read_only__

True if this scope is write protected.

Output signature

bool

$types.scope.__resolve__

$types.scope.__resolve__ name=string

Resolve the specified member in the current scope.

This method looks at the current scope as well as all it parents to resolve the specified member.

Input signature

This command accepts the following arguments:

  • name (string) the name of the member to resolve.

$types.scope.__super__

$types.scope.__super__

The parent of this scope. The root (global) scope returns itself.

Output signature

scope

$types.scope.__use__

$types.scope.__use__

All use imports in this scope.

Output signature

list $scope

$types.string

type string

Textual data, stored as an immutable sequence of unicode code points.

A string literal is written between double quotes, e.g. "hello world". A string is a sequence of legal unicode characters -- nothing else can be represented, and every crush string is guaranteed to be valid text.

Strings are immutable -- every method that looks like it modifies a string (upper, replace, trim, ...) returns a new string rather than changing the receiver.

file and binary are the two other types that hold sequences of data rather than a single scalar value, and it's worth being precise about how they differ from string and from each other. A file represents an operating system path: a sequence of bytes that is a legal file name, a system-dependent notion of legality that usually allows byte sequences that aren't legal unicode (for example, a Latin-1-encoded name on a system whose text encoding is UTF-8). A binary is simply a sequence of bytes with no legality constraint at all -- the type to reach for when the data isn't necessarily text or a path. Because "legal file name" and "legal unicode text" are overlapping but different constraints, string and file have to be separate types: some strings can't be legal file names (most commonly one containing a zero byte -- many operating systems represent a path internally as a zero-terminated byte sequence, so a zero byte can never be part of one), and some legal file names can't be represented as a string at all.

For convenience, builtin commands that expect a file argument also accept a string, which crush converts automatically. That conversion doesn't validate the result up front, though -- passing a string containing a zero byte is accepted silently, and only fails once the resulting file value is actually used against the filesystem. This isn't just an implementation shortcut: neither crush nor the computer it's running on can actually know what does and doesn't constitute a legal file name ahead of time, because that's up to whatever filesystem the path eventually resolves into, and that can change from one path component to the next -- a network mount, for instance, can enforce completely different naming rules than the local filesystem it's mounted under, and crush has no general way to know a path crosses into one before it's used. Some obviously-illegal names could be rejected early (a zero byte, for example, is illegal everywhere), but the only way to be certain a given name is legal is to actually hand it to the operating system in a real syscall. Going the other way, a file whose bytes aren't valid unicode can't be losslessly converted to a string either; rather than erroring, crush falls back to displaying it as the placeholder text <invalid filename>.

$types.string.__getitem__

$types.string.__getitem__[idx=integer]

Extract a one character substring from this string.

Input signature

This command accepts the following arguments:

  • idx (integer) index.

Output signature

string

$types.string.__is__

$types.r#type.__is__ needle=any

True if the needle's type is this type. Not meant to be called directly -- use the like command, the =~ operator, or the is arm of a match block.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$types.string.__is_not__

$types.r#type.__is_not__ needle=any

False if the needle's type is this type. Not meant to be called directly -- use the like command or the !~ operator.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$types.string.bytes

$types.string.bytes

Returns the length (in number of bytes) of the string, as encoded using UTF-8.

Note that there are often different ways to generate identical looking strings of different lengths, as in the example below.

Examples

# Returns 2
"é".bytes
# Returns 3
"é".bytes

Output signature

integer

$types.string.ends_with

$types.string.ends_with suffix=string

True if this string ends with the specified suffix.

Input signature

This command accepts the following arguments:

  • suffix (string) suffix to check for.

Output signature

bool

$types.string.format

$types.string.format [<any>=any...] [unnamed=any...]

Format arguments into a string.

Input signature

This command accepts the following arguments:

  • <any>=$any (any) the named parameters to format into the pattern string.

  • unnamed (any) the unnamed parameters to format into the pattern string.

Examples

"Hello {name}".format name=$name

Output signature

string

$types.string.is_alphabetic

$types.string.is_alphabetic

True if every character of this string is alphabetic.

Output signature

bool

$types.string.is_alphanumeric

$types.string.is_alphanumeric

True if every character of this string is alphabetic or numeric.

Output signature

bool

$types.string.is_ascii

$types.string.is_ascii

True if every character of this string is part of the ascii character set.

Output signature

bool

$types.string.is_control

$types.string.is_control

True if every character of this string is a control character.

Output signature

bool

$types.string.is_digit

$types.string.is_digit [radix=integer]

True if every character of this string is a digit in the specified radix.

"123".is_digit # true

Input signature

This command accepts the following arguments:

  • radix (default: 10) radix to use.

Output signature

bool

$types.string.is_lowercase

$types.string.is_lowercase

True if every character of this string is lower case.

Output signature

bool

$types.string.is_uppercase

$types.string.is_uppercase

True if every character of this string is upper case.

Output signature

bool

$types.string.is_whitespace

$types.string.is_whitespace

True if every character of this string is a whitespace character.

Output signature

bool

$types.string.join

$types.string.join [elements=any...]

Join all arguments by the specified string.

Input signature

This command accepts the following arguments:

  • elements (any) the elements to join.

Examples

# Returns "1, 2, 3, 4"
", ".join 1 2 3 4

Output signature

string

$types.string.len

$types.string.len

Returns the length (in number of unicode characters) of the string.

Note that a unicode character is not always what a human would consider a character, and there are often different ways to generate identical looking strings with different numbers of characters, as in the example below.

Examples

# Returns 1
"é".len
# Returns 2
"é".len

Output signature

integer

$types.string.lower

$types.string.lower

Returns an identical string but in lower case

Output signature

string

$types.string.lpad

$types.string.lpad length=integer [padding=string]

Returns a string truncated or left-padded to be the exact specified length.

Input signature

This command accepts the following arguments:

  • length (integer) the length to pad to.

  • padding (default: " ") the character to pad with.

Examples

# Returns "     Hello"
"Hello".lpad 10
# Returns "He"
"Hello".lpad 2

Output signature

string

$types.string.repeat

$types.string.repeat times=integer

Returns this string repeated times times.

Input signature

This command accepts the following arguments:

  • times (integer) the number of times to repeat the string.

Examples

"Around the world\n".repeat 8

Output signature

string

$types.string.rpad

$types.string.rpad length=integer [padding=string]

Returns a string truncated or right-padded to be the exact specified length.

Input signature

This command accepts the following arguments:

  • length (integer) the length to pad to.

  • padding (default: " ") the character to pad with.

Examples

# Returns "Helloooooo"
"Hello".rpad length=10 padding=o
# Returns "He"
"Hello".rpad 2

Output signature

string

$types.string.split

$types.string.split separator=string

Splits a string using the specified separator.

Input signature

This command accepts the following arguments:

  • separator (string) the separator to split on.

Examples

# Returns ["Hello", "World"]
"Hello World".split " "

Output signature

list $string

$types.string.starts_with

$types.string.starts_with prefix=string

True if this string starts with the specified prefix.

Input signature

This command accepts the following arguments:

  • prefix (string) prefix to check for.

Output signature

bool

$types.string.substr

$types.string.substr [from=integer] [to=integer]

Extract a substring from this string.

Input signature

This command accepts the following arguments:

  • from (default: 0) starting index (inclusive). If unspecified, from start of string.

  • to (integer) ending index (exclusive). If unspecified, to end of string.

Output signature

string

$types.string.trim

$types.string.trim

Returns a string with all whitespace trimmed from both ends

Output signature

string

$types.string.upper

$types.string.upper

Returns an identical string but in upper case

Output signature

string

$types.struct

type struct

A mapping from name to value.

To create a simple immutable struct, use the $struct.of command, e.g. $struct.of x=1 y=2; its fields can be read ($s.x) but not reassigned.

To create a mutable struct that supports inheritance and methods, use the class command; instances created from a class ($MyClass.new ...) do support field reassignment ($instance.x = 5) from outside the class as well as from within its own methods.

The most similar type is dict, which is also a mapping from keys to values, but with keys chosen at runtime rather than fixed named fields, and no support for methods or inheritance.

$types.struct.join

$types.struct.join [structs=struct...]

Combine any number of structs into one containing all of their members.

On a name collision between two of the given structs, the later one's member is renamed by appending _2, _3, and so on (repeating until the generated name is unique) -- the same renaming join, zip and group already use when combining columns from more than one source, applied here to struct members instead.

Only each struct's own local members are used, not any inherited from a parent (e.g. via class) -- the same "data struct" semantics $struct.of itself uses.

Input signature

This command accepts the following arguments:

  • structs (struct) the structs to combine.

Examples

$struct.join ($struct.of a=1 b=2) ($struct.of b=3 c=4)

Output signature

struct

$types.struct.of

$types.struct.of [unnamed=any...] [<any>=any...]

Construct a struct with the specified members.

Unnamed arguments will be given the names _1, _2, _3, and so on.

Unlike a struct created via the class command, a struct created via $struct.of does not have a parent or a __setattr__ method. The lack of a __setattr__ method means that a "data struct" is immutable, though its members may potentially be modified, depending on their type.

Input signature

This command accepts the following arguments:

  • unnamed (any) unnamed values.

  • <any>=$any (any) named values.

Examples

$struct.of foo=5 bar="baz" false

Output signature

struct

$types.table

type table

A table of rows.

A table is created by piping a table_input_stream through materialize, e.g. files | materialize.

Unlike a table_input_stream, a table is a fixed snapshot: it can be read more than once, indexed by row number ($t[0]), and asked for its length ($t.len) -- but it has no methods for adding, removing, or replacing rows. The most similar type is table_input_stream, the one-shot, streaming form it's materialized from.

$types.table.__call__

$types.table_input_stream.__call__ [<any>=type...]

Return the table_input_stream type with the specified column signature.

You usually do this in order to create a pipe specialized to a specific column signature.

Input signature

This command accepts the following arguments:

  • <any>=$type (type) the columns of the stream.

Examples

$pipe := $($(table_input_stream value=$integer).pipe)

Output signature

type

$types.table.__getitem__

$types.table_input_stream.__getitem__[index=integer]

Returns the specified row of the table stream as a struct.

Input signature

This command accepts the following arguments:

  • index (integer) the row index to return.

Examples

$(files)[4]

Output signature

struct

$types.table_input_stream

type table_input_stream

An input stream of table rows.

A table_input_stream is produced by any streaming command -- for example, the output of files or seq -- or by reading the read member of a pipe object (see (table_input_stream ...).pipe, under help pipe).

It can only be traversed once: each row is consumed as it's read, so a second pass over the same stream sees nothing. If you need to read the same rows more than once, pipe the stream through materialize to turn it into a reusable table. table_output_stream is the writable counterpart of the same rows.

$types.table_input_stream.__call__

$types.table_input_stream.__call__ [<any>=type...]

Return the table_input_stream type with the specified column signature.

You usually do this in order to create a pipe specialized to a specific column signature.

Input signature

This command accepts the following arguments:

  • <any>=$type (type) the columns of the stream.

Examples

$pipe := $($(table_input_stream value=$integer).pipe)

Output signature

type

$types.table_input_stream.__getitem__

$types.table_input_stream.__getitem__[index=integer]

Returns the specified row of the table stream as a struct.

Input signature

This command accepts the following arguments:

  • index (integer) the row index to return.

Examples

$(files)[4]

Output signature

struct

$types.table_input_stream.pipe

$types.table_input_stream.pipe

Returns a pipe consisting of a read end and a write end.

Each row of data in the pipe must have the columns specified by this table_input_stream specialization. A pipe is usually created by specializing table_input_stream e.g. like:

$pipe := $($(table_input_stream value=$integer).pipe)

The pipe object has three methods:

  • $pipe.write write sink for this pipe. Put this method at the end of a pipeline that produces data for the pipe.

  • $pipe.read read source for this pipe. Put this method at the start of a pipeline that consumes data from the pipe.

  • $pipe.close call this method once all readers and writers have been created in order to close the pipe.

A pipe object can have arbitrarily many write jobs producing data into the pipe. Each writer simply pipes rows into the $pipe.write method.

A pipe object can have arbitrarily many read jobs consuming data from the pipe. Each reader simply consumes rows from the $pipe.read method.

Each row written to the pipe will be consumed by exactly one reader job.

In order for the consumer jobs to finish, all the writer jobs must end and the $pipe.close method must be called. Once this has happened and all the rows have been processed, the consumer job(s) will finish.

Note that the $pipe.close method does not interrupt currently existing read or write jobs, but it does prevent new read and write jobs from being started.

Always fg every writer job before calling $pipe.close (readers don't need this -- only writers). $pipe.write reads the pipe's internal state on its own worker thread whenever it happens to get scheduled, with no synchronization against $pipe.close; calling $pipe.close before a writer job has actually had a chance to run can silently drop that writer's entire contribution.

Examples

# Create a pipe
$pipe := $($(table_input_stream value=$integer).pipe)
# Create a job that writes 100_000 integers to the pipe and put this job in the background
$write_job_handle := $(seq 0 100_000 | $pipe.write &)
# Create a second job that reads from the pipe and sums all the integers and put this job in the background
$sum_job_handle := $($pipe.read | sum &)
# Put the writer job in the foreground so it fully finishes before the pipe is closed
fg $write_job_handle
# Close the pipe so that the second job can finish
$pipe.close
# Put the sum job in the foreground
fg $sum_job_handle

Output signature

struct

$types.table_output_stream

type table_output_stream

An output stream of table rows.

A table_output_stream is obtained from the output member of a pipe object, created by calling :pipe on a table_input_stream type, e.g. $p := $($(table_input_stream value=$integer).pipe); $p.output is then a table_output_stream that rows can be written to, and $p.read is the matching table_input_stream those same rows can be read back from.

Rows are written with the write method (see help $pipe.write). The most similar type is table_input_stream, its read-side counterpart.

$types.table_output_stream.__call__

$types.table_output_stream.__call__ [<any>=type...]

Return the table_output_stream type with the specified column signature.

Input signature

This command accepts the following arguments:

  • <any>=$type (type) the columns of the stream.

Output signature

type

$types.table_output_stream.write

$types.table_output_stream.write

Write input to this output stream.

Output signature

empty

$types.time

type time

A point in time with nanosecond precision.

To get the current time, use $time.now. To parse a time from text, use $time.parse.

All time instances use the local time zone.

A time instance has nanosecond precision. It is represented internally as two 64 bit numbers, one for the number of seconds since the Unix epoc, and one for the nanosecond remainder.

Times are immutable values -- arithmetic methods like adding a duration (using the + operator in expression mode) return a new time rather than changing the receiver. time instances are often used together with duration, which is used to represent the difference between two points in time.

$types.time.__add__

$types.time.__add__ + term=duration # Only available in expression mode

Add the specified delta to this time.

Input signature

This command accepts the following arguments:

  • term (duration) the number to add.

Output signature

time

$types.time.__sub__

$types.time.__sub__ - term=$(one_of $duration $time) # Only available in expression mode

Remove the specified duration from this time to produce an earlier time, or calculate the difference between two points in time.

Input signature

This command accepts the following arguments:

  • term (one_of $duration $time) the duration or time to subtract.

$types.time.format

$types.time.format format=string

Format this time using a strftime-style pattern string.

Date specifiers:

  • %Y year with century.

  • %y year without century, zero padded.

  • %C century, zero padded.

  • %m month, zero padded.

  • %b abbreviated month name.

  • %h abbreviated month name.

  • %B full month name.

  • %d day of month, zero padded.

  • %e day of month, space padded.

  • %a weekday as abbreviated name.

  • %A weekday as full name.

  • %w weekday as a number, where 0 is Sunday and 6 is Saturday.

  • %u weekday as a number, where 1 is Monday and 7 is Sunday.

  • %U week number of the year (Sunday as first day of week), zero padded.

  • %W week number of the year (Monday as first day of week), zero padded.

  • %G same to %Y but uses the year number in ISO 8601 week date.

  • %g same to %y but uses the year number in ISO 8601 week date.

  • %V same to %U but uses the year number in ISO 8601 week date.

  • %j day of the year, zero-padded.

  • %D month-day-year format. Same to %m/%d/%y.

  • %x month-day-year format. Same to %m/%d/%y.

  • %F year-month-day format (ISO 8601). Same to %Y-%m-%d.

  • %v day-month-year format. Same to %e-%b-%Y. Time specifiers:

  • %H hour (24-hour clock) as a zero-padded number.

  • %k hour (24-hour clock) as a space-padded number.

  • %I hour (12-hour clock) as a zero-padded number.

  • %l hour (12-hour clock) as a space-padded number.

  • %P locale’s equivalent of either am or pm.

  • %p locale’s equivalent of either AM or PM.

  • %M minute as a zero-padded number.

  • %S second as a zero-padded number.

  • %f fractional nanoseconds since last whole seconds, zero-padded.

  • %R hour-minute format. Same to %H:%M.

  • %T hour-minute-second format. Same to %H:%M:%S.

  • %X hour-minute-second format. Same to %H:%M:%S.

  • %r hour-minute-second format in 12-hour clocks. Same to %I:%M:%S %p. Time zone specifiers:

  • %z UTC offset in the form +HHMM or -HHMM.

  • %Z time zone name.

  • %:z a colon, followed by UTC offset in the form +HHMM or -HHMM. Special characters:

  • %c ctime date & time format. Same to %a %b %e %T %Y sans \n.

  • %+ ISO 8601 / RFC 3339 date & time format.

  • %s UNIX timestamp, the number of seconds since 1970-01-01 00:00 UTC.

  • %t a literal tab character.

  • %n a literal newline character.

  • %% a literal % character.

Input signature

This command accepts the following arguments:

  • format (string) the format of the time.

Examples

$time.now.format "%s"

Output signature

string

$types.time.now

$types.time.now

The current point in time.

Examples

$time.now

Output signature

time

$types.time.parse

$types.time.parse format=string time=string

Parse a time string using a strptime-style pattern string.

After parsing the date, it will be converted to the local time zone. Date specifiers:

  • %Y year with century.

  • %y year without century, zero padded.

  • %C century, zero padded.

  • %m month, zero padded.

  • %b abbreviated month name.

  • %h abbreviated month name.

  • %B full month name.

  • %d day of month, zero padded.

  • %e day of month, space padded.

  • %a weekday as abbreviated name.

  • %A weekday as full name.

  • %w weekday as a number, where 0 is Sunday and 6 is Saturday.

  • %u weekday as a number, where 1 is Monday and 7 is Sunday.

  • %U week number of the year (Sunday as first day of week), zero padded.

  • %W week number of the year (Monday as first day of week), zero padded.

  • %G same to %Y but uses the year number in ISO 8601 week date.

  • %g same to %y but uses the year number in ISO 8601 week date.

  • %V same to %U but uses the year number in ISO 8601 week date.

  • %j day of the year, zero-padded.

  • %D month-day-year format. Same to %m/%d/%y.

  • %x month-day-year format. Same to %m/%d/%y.

  • %F year-month-day format (ISO 8601). Same to %Y-%m-%d.

  • %v day-month-year format. Same to %e-%b-%Y. Time specifiers:

  • %H hour (24-hour clock) as a zero-padded number.

  • %k hour (24-hour clock) as a space-padded number.

  • %I hour (12-hour clock) as a zero-padded number.

  • %l hour (12-hour clock) as a space-padded number.

  • %P locale’s equivalent of either am or pm.

  • %p locale’s equivalent of either AM or PM.

  • %M minute as a zero-padded number.

  • %S second as a zero-padded number.

  • %f fractional nanoseconds since last whole seconds, zero-padded.

  • %R hour-minute format. Same to %H:%M.

  • %T hour-minute-second format. Same to %H:%M:%S.

  • %X hour-minute-second format. Same to %H:%M:%S.

  • %r hour-minute-second format in 12-hour clocks. Same to %I:%M:%S %p. Time zone specifiers:

  • %z UTC offset in the form +HHMM or -HHMM.

  • %Z time zone name.

  • %:z a colon, followed by UTC offset in the form +HHMM or -HHMM. Special characters:

  • %c ctime date & time format. Same to %a %b %e %T %Y sans \n.

  • %+ ISO 8601 / RFC 3339 date & time format.

  • %s UNIX timestamp, the number of seconds since 1970-01-01 00:00 UTC.

  • %t a literal tab character.

  • %n a literal newline character.

  • %% a literal % character.

Input signature

This command accepts the following arguments:

  • format (string) the format of the time.

  • time (string) the time string to parse.

Examples

$time.parse format="%s" time="1234567890"

Output signature

time

$types.type

type type

A type.

A type value names one of crush's builtin types, e.g. $string or $integer. The typeof command returns a value of this kind. Types are mostly used to declare what kind of value a signature parameter or table column accepts, e.g. via convert or a closure argument declaration, rather than being manipulated directly by everyday scripts.

$types.type.__is__

$types.r#type.__is__ needle=any

True if the needle's type is this type. Not meant to be called directly -- use the like command, the =~ operator, or the is arm of a match block.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$types.type.__is_not__

$types.r#type.__is_not__ needle=any

False if the needle's type is this type. Not meant to be called directly -- use the like command or the !~ operator.

Input signature

This command accepts the following arguments:

  • needle (any) the value whose type to check.

Output signature

bool

$users

$global.users

User commands.

Commands for querying user accounts and login sessions on this system: $users.me for the current user, $users.current for everyone currently logged in (tty, login time, ...), $users.list for every account that exists, and users[username] to look one up by name -- the resulting struct has a do method to run a closure as that user, e.g. users[root].do {rm foo.txt}. This reads local system account data, not any particular authentication or identity provider.

$var

$global.var

Commands related to variables.

Commands for working with variables and scopes directly, as values rather than through $name/:=/= syntax: declaring, setting, unsetting, reading, and destructuring, plus $var.use/$var.unuse for importing a scope's contents into the current one and $var.list/$var.local for introspecting what's currently in scope. Unlike most other builtin namespaces, var is not imported into the global scope -- its commands always need the $var. prefix, e.g. $var.let, never bare let.

$var.get

$var.get name=string

Returns the current value of a variable.

A variable by the specified name must already exist in some visible scope before calling the get builtin, or an error will result.

The get builtin is not normally called directly, simply prefix the $ sigil with the name of the variable you want to get.

Input signature

This command accepts the following arguments:

  • name (string) the name of the variable to return the value of.

Examples

# These two lines are equivalent
$x
$var.get x

$var.let

$var.let [<any>=any...]

Declare new variables in the current scope.

No variable can exist in the local scope, or an error will result.

The let builtin is not normally called directly, but via the syntactic sugar of the := operator.

Input signature

This command accepts the following arguments:

  • <any>=$any (any) the variables to declare. The value you supply will be the initial value of the variable.

Examples

# These two lines are equivalent
$x := 2
$var.let x=2

Output signature

empty

$var.let_destructure

$var.let_destructure [names=string...] value=any

Declare new variables in the current scope by destructuring a list, struct, or dict.

Not normally called directly, but via the syntactic sugar of the := operator applied to a bracketed list of names, e.g. [$a, $b] := $pair. value's elements -- a list's elements, or a struct's/dict's values in insertion order -- are declared positionally into names, in order. The number of elements must exactly match the number of names, or an error results.

Input signature

This command accepts the following arguments:

  • names (string) the names of the variables to declare, in order.

  • value (any) the list, struct, or dict to destructure.

Examples

# These two lines are equivalent
[$a, $b] := [1, 2]
$var.let_destructure a b value=[1, 2]

Output signature

empty

$var.list

$var.list

Returns a table containing all variable names currently in scope and their types.

A variable is in scope if it exists in the current scope, any of its parents, or any of the scopes used in any of those scopes.

Output signature

A table input stream with the following columns

  • name (string) the variable's name.

  • type (string) the variable's type.

$var.local

$var.local

Returns the current scope.

Output signature

scope

$var.set

$var.set [<any>=any...]

Reassign existing variables.

A variable by the specified name must already exist in some visible scope before calling the set builtin, or an error will result.

The set builtin is not normally called directly, but via the syntactic sugar of the = operator.

Input signature

This command accepts the following arguments:

  • <any>=$any (any) the variables to reassign. The value you supply will be the new value of the variable.

Examples

# These two lines are equivalent
$x = 2
$var.set x=2

Output signature

empty

$var.set_destructure

$var.set_destructure [names=string...] value=any

Reassign existing variables by destructuring a list, struct, or dict.

Not normally called directly, but via the syntactic sugar of the = operator applied to a bracketed list of names, e.g. [$a, $b] = $pair. Every name must already exist in some visible scope, exactly like set. value's elements -- a list's elements, or a struct's/dict's values in insertion order -- are assigned positionally into names, in order. The number of elements must exactly match the number of names, or an error results.

Input signature

This command accepts the following arguments:

  • names (string) the names of the variables to reassign, in order.

  • value (any) the list, struct, or dict to destructure.

Examples

# These two lines are equivalent
[$a, $b] = [1, 2]
$var.set_destructure a b value=[1, 2]

Output signature

empty

$var.unset

$var.unset [name=string...]

Removes variables from the namespace.

Input signature

This command accepts the following arguments:

  • name (string) the name of the variables to unset.

Examples

# Remove the variable x
$var.unset x

Output signature

empty

$var.unuse

$var.unuse [name=scope...]

Make specified scopes not searched by default during scope resolution.

The unuse builtin will recursively go through all parent scopes and remove all uses of the provided scopes through the entire chain.

Input signature

This command accepts the following arguments:

  • name (scope) the scopes to unuse.

Examples

# Stop using the stream scope
$var.unuse $stream
# This command will now fail, because stream::select is not in scope
select

Output signature

bool

$var.use

$var.use [name=scope...]

Make specified scopes searched by default during scope resolution.

Input signature

This command accepts the following arguments:

  • name (scope) the scopes to use.

Examples

# Import the math scope
$var.use $math
sqrt 2

Output signature

empty