Commands v0.1.0

Describing a program to start: its arguments, environment, working directory and standard streams.

`Stdio`

pub enum Stdio: uint8 {
    Inherit = 0,
    Null = 1,
    Pipe = 2
}

What a child's standard stream is connected to. Copy.

Source

Cases

Name	Value	Description
`Inherit`	`0`	The stream this process has, which the child shares.
`Null`	`1`	Nothing: reads find the end at once and writes are discarded.
`Pipe`	`2`	A new pipe, whose other end the parent takes from the `Child`.

`Command`

pub struct Command {
    // private fields
}

A program to start, with its arguments, working directory, environment changes and standard streams. Build it up and then Spawn it, or Run it to completion, or Capture what it writes. A command can be started more than once. A command is not copied.

Source

Constructors

`Command`

pub func Command(
    allocator: Allocator,
    program: char8[..]
) -> Command

A command to start program, found through PATH when it names no directory. The program is also the child's first argument, as every system expects. Its streams start as Stdio::Inherit.

Name	Type	Description
`allocator`	`Allocator`	what the command's parts are kept in
`program`	`char8[..]`	the program's name or path, as UTF-8 text

Returns: the command

Source

Associated functions

`FromNative`

pub func FromNative(
    allocator: Allocator,
    program: OsStringView
) -> Command

A command to start program given in native form, such as this process's own first argument.

Name	Type	Description
`allocator`	`Allocator`	what the command's parts are kept in
`program`	`OsStringView`	the program's name or path

Returns: the command

Source

Methods

`Capture`

pub func Capture(
    self: &Command,
    allocator: Allocator
) -> CapturedOutput ! IoError

Starts the program with its output and error piped, keeps everything it writes, and waits for it to finish. Its input is what the command says, which is this process's own unless changed.

Name	Type	Description
`allocator`	`Allocator`	what the captured bytes are kept in

Returns: the output, the error and how the program finished

Source

`Argument`

pub func Argument(self: &var Command, value: char8[..])

Adds an argument, as UTF-8 text.

Name	Type	Description
`value`	`char8[..]`	the argument

Source

`NativeArgument`

pub func NativeArgument(
    self: &var Command,
    value: OsStringView
)

Adds an argument already in native form, such as one of this process's own arguments.

Name	Type	Description
`value`	`OsStringView`	the argument

Source

`Directory`

pub func Directory(self: &var Command, path: char8[..])

Starts the child in path rather than in this process's working directory.

Name	Type	Description
`path`	`char8[..]`	the directory, as UTF-8 text

Source

`SetVariable`

pub func SetVariable(
    self: &var Command,
    name: char8[..],
    value: char8[..]
)

Gives the child the variable name set to value, whatever this process's environment holds.

Name	Type	Description
`name`	`char8[..]`	the variable's name, which may not be empty or contain `=`
`value`	`char8[..]`	its value

Source

`RemoveVariable`

pub func RemoveVariable(self: &var Command, name: char8[..])

Leaves the variable name out of the child's environment.

Name	Type	Description
`name`	`char8[..]`	the variable's name

Source

`ClearEnvironment`

pub func ClearEnvironment(self: &var Command)

Starts the child with no variables but those set on the command.

Source

`StandardInput`

pub func StandardInput(self: &var Command, stdio: Stdio)

Connects the child's standard input.

Name	Type	Description
`stdio`	`Stdio`	what it reads from

Source

`StandardOutput`

pub func StandardOutput(self: &var Command, stdio: Stdio)

Connects the child's standard output.

Name	Type	Description
`stdio`	`Stdio`	what it writes to

Source

`StandardError`

pub func StandardError(self: &var Command, stdio: Stdio)

Connects the child's standard error.

Name	Type	Description
`stdio`	`Stdio`	what it writes to

Source

`Spawn`

pub func Spawn(self: &Command) -> Child ! IoError

Starts the program as a child process.

Returns: the child, or fails: with a part of the command the system could not take, with NotFound for a program that is not there, or with the system's reason

Source

`Run`

pub func Run(self: &Command) -> ExitStatus ! IoError

Starts the program and waits for it to finish.

Returns: how it finished

Source

Child processes

A started program: waiting for it, killing it, and its standard streams.

Arguments

The command-line arguments the process was started with.

Edit this page on GitHub