std/shell

Types

Shell

@unsafeGuarantee(Copy, Send, Sync)
pub type Shell

Ability to run external commands, obtained from host.shell(). Safety: a stateless capability marker; every command it runs is independent, so sharing or duplicating it is free.

Item

pub type Item =
    | Text(String)
    | Word
    | Pipe
    | Redirect(Int, Int)
    | Grep(String)

One piece of a plan; a $"..." literal pushes them in source order.

Plan

pub type Plan = {
    // private fields omitted
}

Command pipeline built from $"..." literals; nothing runs until it is piped into run or capture.

PipelineResult

pub type PipelineResult = {
    // private fields omitted
}

Exit statuses of every stage of a pipeline that was run.

Captured

pub type Captured = {
    pub stdout Bytes
    pub stderr Bytes
}

Output collected by capture.

Stage

pub type Stage = {
    pub argv Array[String]
    pub redirs Array[Redir]
    pub grep String?
}

A stage of a plan: an external command, or a grep filter.

Redir

pub type Redir = {
    pub op Int
    pub fd Int
    pub target String
}

A redirection of one stage: op is the < (1), > (2), >> (3), <& (4) or >& (5) form.

Failure

pub type Failure = {
    pub text String
}

Error from running a pipeline.

Failure.message

pub fn Failure.message(self) -> String

The failure text.

Functions

grepProblem

pub pure fn grepProblem(pattern: &String) -> String

Why pattern is not a valid coreutil.grep pattern, or "" when it is: only syntax that POSIX ERE and RE2 read alike is accepted (literals, groups, |, * + ? {m,n} up to 100, brackets, \ before a metacharacter).

planNew

pub pure fn planNew() -> Plan

An empty plan; the compiler starts every $"..." literal with one.

planPush

pub pure fn planPush(mut p: Plan, item: Item) -> Plan

Appends one piece to a plan.

check

pub pure fn check(result: PipelineResult) -> Void!

Fails when any stage exited with a non-zero status.

stages

pub pure fn stages(plan: &Plan) -> Array[Stage]

Splits a plan into its stages, joining the text pieces of each word.

capture

pub fn capture(plan: Plan, sh: Shell) -> Captured!

Runs the plan and collects its stdout and stderr (plan |> capture(sh)); fails when a command cannot start.

run

pub fn run(plan: Plan, sh: Shell) -> PipelineResult!

Runs the plan with inherited stdout and stderr (plan |> run(sh)) and returns the exit statuses; fails when a command cannot start.