std::process
Processes: how the running program ends, and the programs it starts.
A main that returns Err(Exit{code: 2, message: "usage: count <file>"}) prints the message to stderr and exits with status 2. There
is no function that exits on the spot: returning Exit through ? ends
the program the way returning from main does, so defers run and
supervisors drain first.
A Command names a program and its arguments, with no shell between:
nothing in an argument is expanded, split or quoted, so an argument
holding a space or a * reaches the program as it is. output runs it
to the end and returns what it wrote. run runs it with its output
going to the program’s own. spawn starts it with its three streams to
read and write, and defer Child.kill(child) stops it when the function
that started it ends. A program that ends with a non-zero code is a
Status to inspect, not an error; an Err means it could not be
started.
import std::io.Error std::process.{self, Command, Status} end fn main() -> Result<Unit, Error> listed = process.output(Command{program: "git", args: ["status", "--short"]})? dbg Status.is_success(listed.status) Ok(Unit) end
Tests run commands against std::process::testing’s fake, which starts
nothing. A WebAssembly target has no processes: nomi build for
js/wasm or wasip1 refuses a program that starts one.
Import with import std::process.
Exports
Section titled “Exports”struct Exit
Section titled “struct Exit”struct Exit code: ExitCode = 1 message: String = "" end
What a main or an entry boot returns in its Err to end the program
with a status of its choosing. The program prints message and a
newline to stderr when it is not empty, with no error: before it, and
exits with code. An Exit with code 0 ends the program successfully,
its message printed all the same.
import std::process.Exit fn main() -> Result<Unit, Exit> Err(Exit{code: 2, message: "usage: count <file>"}) end
failed = Exit{message: "no input"}
assert failed.code == 1
assert Exit{} == Exit{code: 1, message: ""}
Exit.inspect
Section titled “Exit.inspect”impl Debug for Exit
fn inspect(value: Exit) -> String
impl Debug.inspect
type ExitCode
Section titled “type ExitCode”subtype ExitCode Int when fn code -> code >= 0 and code <= 255
A status a program can exit with: 0 to 255. A literal outside it does
not compile; a computed code goes through ExitCode.try_from.
subtype: ExitCode is a subtype of Int. A literal where a ExitCode is expected is checked when the program is compiled; ExitCode.try_from(...) checks a value when it runs.
assert ExitCode.try_from(255) == Some(255)
assert ExitCode.try_from(256) == None
assert ExitCode.try_from(-1) == None
ExitCode.try_from
Section titled “ExitCode.try_from”fn try_from(value: Int) -> Maybe<ExitCode>
type function on ExitCode
Some of the value when it satisfies ExitCode’s rules, None when it does not.
struct Command
Section titled “struct Command”struct Command program: String args: List<String> = [] env: Map<String, String> = {} clear_env: Bool = False dir: Maybe<String> = None stdin: Stdin = Stdin.Null end
A program to start and how: an immutable value, so one command can be run any number of times.
command = Command{program: "git", args: ["log", "-1"], dir: Some("repo")}
assert command.env == {}
assert not command.clear_env
Command.inspect
Section titled “Command.inspect”impl Debug for Command
fn inspect(value: Command) -> String
impl Debug.inspect
enum Stdin
Section titled “enum Stdin”enum Stdin Null Inherit Text String Bytes Bytes From Reader end
What a started program reads on its standard input.
Variants
-
NullNothing: the program reads the end of its input at once.
-
InheritThe running program’s own standard input.
-
TextThe text, then the end of the input.
-
BytesThe bytes, then the end of the input.
-
FromWhat the reader reads, to its end.
Stdin.inspect
Section titled “Stdin.inspect”impl Debug for Stdin
fn inspect(value: Stdin) -> String
impl Debug.inspect
enum Status
Section titled “enum Status”enum Status Exited { code: Int } Signaled { signal: Int } end
How a started program ended.
Variants
-
ExitedIt exited with
code, 0 for success. -
SignaledA signal ended it (on Unix), as a kill does.
Status.is_success
Section titled “Status.is_success”fn is_success(status: Status) -> Bool
type function on Status
Whether the program exited with code 0.
assert Status.is_success(Status.Exited{code: 0})
assert not Status.is_success(Status.Exited{code: 1})
assert not Status.is_success(Status.Signaled{signal: 9})
Status.code
Section titled “Status.code”fn code(status: Status) -> Maybe<Int>
type function on Status
The exit code, or None when a signal ended the program.
assert Status.code(Status.Exited{code: 3}) == Some(3)
assert Status.code(Status.Signaled{signal: 9}) == None
Status.to_string
Section titled “Status.to_string”impl Display for Status
fn to_string(status: Status) -> String
impl Display.to_string
assert "${Status.Exited{code: 2}}" == "exited with code 2"
assert "${Status.Signaled{signal: 9}}" == "ended by signal 9"
Status.inspect
Section titled “Status.inspect”impl Debug for Status
fn inspect(value: Status) -> String
impl Debug.inspect
Status.equal
Section titled “Status.equal”impl Equatable for Status
fn equal(a: Status, b: Status) -> Bool
impl Equatable.equal
struct Output
Section titled “struct Output”struct Output status: Status stdout: Bytes stderr: Bytes end
What output returns: how the program ended and everything it wrote.
Output.inspect
Section titled “Output.inspect”impl Debug for Output
fn inspect(value: Output) -> String
impl Debug.inspect
Output.equal
Section titled “Output.equal”impl Equatable for Output
fn equal(a: Output, b: Output) -> Bool
impl Equatable.equal
process.output
Section titled “process.output”fn output(command: Command) -> Result<Output, Error>
Runs command to its end and returns its status and everything it
wrote to its standard output and error. A non-zero exit is in the
status; an Err means the program could not be started (NotFound
when nothing on the PATH has its name). A task that is cancelled, or
whose deadline passes, while it waits kills the program.
import std::process::testing.{self, Answer}
ran = testing.run([Answer{program: "echo", stdout: "hi\n"}], fn ->
output(Command{program: "echo", args: ["hi"]})
end)
assert ran.value == Ok(
Output{
status: Status.Exited{code: 0},
stdout: String.to_bytes("hi\n"),
stderr: String.to_bytes(""),
}
)
process.run
Section titled “process.run”fn run(command: Command) -> Result<Status, Error>
Runs command to its end with its standard output and error going to
the running program’s own (and so to an io.capture in force), and
returns its status.
import std::process::testing.{self, Answer}
import std::io
ran = testing.run([Answer{program: "make", stdout: "built\n"}], fn ->
io.capture("", fn -> run(Command{program: "make"}))
end)
assert ran.value.value == Ok(Status.Exited{code: 0})
assert ran.value.output == "built\n"
process.spawn
Section titled “process.spawn”fn spawn(command: Command) -> Result<Child, Error>
Starts command with the program’s standard input to write and its
standard output and error to read (Child.stdin, Child.stdout,
Child.stderr; the command’s stdin is not used). Defer Child.kill
on the next line, so a program still running when the function ends,
returns, traps or is cancelled, is killed and none outlives it.
Child.wait closes the input and waits for the program to end. An
Err means the program could not be started.
child = process.spawn(Command{program: "sort"})? defer Child.kill(child)
import std::process::testing.{self, Answer, Call}
fn sorted(text: String) -> Result<String, Error>
child = spawn(Command{program: "sort"})?
defer Child.kill(child)
Writer.write_text(Child.stdin(child), text)?
_ = Child.wait(child)?
Reader.read_all_text(Child.stdout(child))
end
ran = testing.run([Answer{program: "sort", stdout: "a\nb\n"}], fn -> sorted("b\na\n"))
assert ran.value == Ok("a\nb\n")
assert ran.calls == [Call{program: "sort", input: String.to_bytes("b\na\n")}]
struct Child
Section titled “struct Child”struct Child
opaque — construction surface is private to its defining module
A program spawn started.
Child.kill
Section titled “Child.kill”fn kill(child: Child) -> Unit
type function on Child
Kills the program if it is still running, and does nothing once it
has ended: the form for a defer after process.spawn.
Child.stdin
Section titled “Child.stdin”fn stdin(child: Child) -> Writer
type function on Child
The writer to the program’s standard input. Writes are buffered:
Writer.flush sends them on, and Child.wait or Writer.close
ends the input.
Child.stdout
Section titled “Child.stdout”fn stdout(child: Child) -> Reader
type function on Child
The reader over the program’s standard output. Read it before waiting when the program writes more than a pipe holds, or it stops until something reads.
Child.stderr
Section titled “Child.stderr”fn stderr(child: Child) -> Reader
type function on Child
The reader over the program’s standard error.
Child.wait
Section titled “Child.wait”fn wait(child: Child) -> Result<Status, Error>
type function on Child
Ends the program’s standard input and waits for it to end. A second wait returns the first’s status.
Child.release
Section titled “Child.release”impl Release for Child
fn release(child: Child) -> Unit
impl Release.release
Child.inspect
Section titled “Child.inspect”impl Debug for Child
fn inspect(value: Child) -> String
impl Debug.inspect