# std.process

Process execution for running subprocesses and capturing their output.

```tea
use process from "std.process"
```

Examples may be fragments requiring the module import or additional setup.

## std.process.new_run_options_with

```tea
pub def new_run_options_with(env: Dict[String, String], cwd: String?, stdin: String?, check_enabled: Bool) -> RunOptions
```

Create run options with explicit env, cwd, stdin, and check settings.

## std.process.new_run_options

```tea
pub def new_run_options() -> RunOptions
```

Create default run options with no env/cwd/stdin overrides.

## std.process.new_run_bytes_options_with

```tea
pub def new_run_bytes_options_with(env: Dict[String, String], cwd: String?, stdin: List[Int]?, check_enabled: Bool) -> RunBytesOptions
```

Create byte-oriented run options with explicit env, cwd, stdin, and check settings.

## std.process.new_run_bytes_options

```tea
pub def new_run_bytes_options() -> RunBytesOptions
```

Create default byte-oriented run options with no env/cwd/stdin overrides.

## std.process.new_spawn_options_with

```tea
pub def new_spawn_options_with(env: Dict[String, String], cwd: String?) -> SpawnOptions
```

Create spawn options with explicit env and cwd settings.

## std.process.new_spawn_options

```tea
pub def new_spawn_options() -> SpawnOptions
```

Create default spawn options with no env or cwd overrides.

## std.process.run

```tea
pub def run(command: String, args: List[String]) -> ProcessResult ! ProcessError
```

Run a command synchronously and wait for it to complete.

```tea
const result = process.run("ls", ["-la"])
@println(result.stdout)

const result = process.run_with_options("npm", ["install"], {}, "/path/to/project", "")
```

## std.process.run_bytes

```tea
pub def run_bytes(command: String, args: List[String]) -> ProcessBytesResult ! ProcessError
```

Run a command synchronously and capture stdout/stderr as raw bytes.

## std.process.run_with

```tea
pub def run_with(command: String, args: List[String], options: RunOptions) -> ProcessResult ! ProcessError
```

Run a command with Tea-native options.

```tea
use process from "std.process"

# Requires the Unix sort command.
const options = process.new_run_options_with({}, nil, "banana\napple\n", true)
const result = process.run_with("sort", [], options)
@println(process.stdout_lines(result)) # [apple, banana]
```

## std.process.run_bytes_with

```tea
pub def run_bytes_with(command: String, args: List[String], options: RunBytesOptions) -> ProcessBytesResult ! ProcessError
```

Run a command with Tea-native byte-oriented options.

## std.process.run_with_options

```tea
pub def run_with_options(command: String, args: List[String], env: Dict[String, String], cwd: String, stdin: String) -> ProcessResult ! ProcessError
```

Run a command with full options (env, cwd, stdin).

## std.process.run_bytes_with_options

```tea
pub def run_bytes_with_options(command: String, args: List[String], env: Dict[String, String], cwd: String, stdin: List[Int]) -> ProcessBytesResult ! ProcessError
```

Run a command with full byte-oriented options (env, cwd, stdin bytes).

## std.process.spawn

```tea
pub def spawn(command: String, args: List[String]) -> Int ! ProcessError
```

Start a command without waiting for it to complete.

```tea
const handle = process.spawn("long-running-command", [])
# ... do other work ...
const result = process.wait(handle)
```

## std.process.spawn_with

```tea
pub def spawn_with(command: String, args: List[String], options: SpawnOptions) -> Int ! ProcessError
```

Spawn a command with Tea-native options.

## std.process.spawn_with_options

```tea
pub def spawn_with_options(command: String, args: List[String], env: Dict[String, String], cwd: String) -> Int ! ProcessError
```

Spawn a command with full options (env, cwd).

## std.process.wait

```tea
pub def wait(handle: Int) -> ProcessResult ! ProcessError
```

Wait for a spawned process to complete and return its result.

```tea
const handle = process.spawn("command", [])
const result = process.wait(handle)
@println(result.exit)
```

## std.process.kill

```tea
pub def kill(handle: Int) -> Bool ! ProcessError
```

Terminate a spawned process.

```tea
const handle = process.spawn("command", [])
process.kill(handle)
```

## std.process.read_stdout

```tea
pub def read_stdout(handle: Int) -> String ! ProcessError
```

Read data from a spawned process's stdout.

```tea
const handle = process.spawn("command", [])
const output = process.read_stdout(handle)
```

## std.process.read_stdout_bytes

```tea
pub def read_stdout_bytes(handle: Int, bytes: Int) -> List[Int] ! ProcessError
```

Read up to the specified number of bytes from a spawned process's stdout.

## std.process.read_stderr

```tea
pub def read_stderr(handle: Int) -> String ! ProcessError
```

Read data from a spawned process's stderr.

```tea
const handle = process.spawn("command", [])
const errors = process.read_stderr(handle)
```

## std.process.read_stderr_bytes

```tea
pub def read_stderr_bytes(handle: Int, bytes: Int) -> List[Int] ! ProcessError
```

Read up to the specified number of bytes from a spawned process's stderr.

## std.process.write_stdin

```tea
pub def write_stdin(handle: Int, data: String) -> Void ! ProcessError
```

Write data to a spawned process's stdin.

```tea
const handle = process.spawn("cat", [])
process.write_stdin(handle, "hello world")
```

## std.process.write_stdin_bytes

```tea
pub def write_stdin_bytes(handle: Int, data: List[Int]) -> Void ! ProcessError
```

Write raw bytes to a spawned process's stdin.

## std.process.close_stdin

```tea
pub def close_stdin(handle: Int) -> Void ! ProcessError
```

Close a spawned process's stdin pipe.

```tea
const handle = process.spawn("sort", [])
process.write_stdin(handle, "banana\napple\ncherry")
process.close_stdin(handle)
const result = process.wait(handle)
```

## std.process.close

```tea
pub def close(handle: Int) -> Void ! ProcessError
```

Close a spawned process handle without waiting for it.

## std.process.check

```tea
pub def check(result: ProcessResult) -> ProcessResult ! ProcessError
```

Require a process result to have exited successfully.

## std.process.check_bytes

```tea
pub def check_bytes(result: ProcessBytesResult) -> ProcessBytesResult ! ProcessError
```

Require a byte-oriented process result to have exited successfully.

## std.process.require

```tea
pub def require(result: ProcessResult) -> ProcessResult ! ProcessError.CommandFailed
```

Require a process result to have exited successfully with a typed error.

## std.process.run_checked

```tea
pub def run_checked(command: String, args: List[String]) -> ProcessResult ! ProcessError
```

Run a command and fail when it exits with a non-zero status.

## std.process.run_bytes_checked

```tea
pub def run_bytes_checked(command: String, args: List[String]) -> ProcessBytesResult ! ProcessError
```

Run a command as bytes and fail when it exits with a non-zero status.

## std.process.run_checked_with

```tea
pub def run_checked_with(command: String, args: List[String], options: RunOptions) -> ProcessResult ! ProcessError
```

Run a command with Tea-native options and fail when it exits non-zero.

## std.process.run_bytes_checked_with

```tea
pub def run_bytes_checked_with(command: String, args: List[String], options: RunBytesOptions) -> ProcessBytesResult ! ProcessError
```

Run a command with Tea-native byte-oriented options and fail when it exits non-zero.

## std.process.run_checked_with_options

```tea
pub def run_checked_with_options(command: String, args: List[String], env: Dict[String, String], cwd: String, stdin: String) -> ProcessResult ! ProcessError
```

Run a command with full options and fail when it exits with a non-zero status.

## std.process.run_bytes_checked_with_options

```tea
pub def run_bytes_checked_with_options(command: String, args: List[String], env: Dict[String, String], cwd: String, stdin: List[Int]) -> ProcessBytesResult ! ProcessError
```

Run a command with full byte-oriented options and fail on non-zero exit.

## std.process.run_required

```tea
pub def run_required(command: String, args: List[String]) -> ProcessResult ! ProcessError
```

Run a command and return a typed error when it exits non-zero.

```tea
use process from "std.process"

def demonstrate() -> Void
  # Requires a shell; this command deliberately exits with status 7.
  try process.run_required("sh", ["-c", "exit 7"]) catch err
    case is process.ProcessError.CommandFailed
      @println(err.exit) # 7
      return
    case _
      @panic("unexpected process error")
  end
  return
end

demonstrate()
```

## std.process.run_required_with

```tea
pub def run_required_with(command: String, args: List[String], options: RunOptions) -> ProcessResult ! ProcessError
```

Run a command with Tea-native options and return a typed error on failure.

## std.process.stdout_lines

```tea
pub def stdout_lines(result: ProcessResult) -> List[String]
```

Split captured stdout into lines.

## std.process.stderr_lines

```tea
pub def stderr_lines(result: ProcessResult) -> List[String]
```

Split captured stderr into lines.