child_process/stdio

Types

Mode

I/O mode configuration for a child process port.

pub type Mode =
  @internal Mode

Stdio

</>

Describes how to handle I/O for a spawned process.

A Stdio bundles an I/O mode (how the port is configured) with callbacks (how data is consumed). Create one with lines(), chunks(), collect(), exit(), or ignore().

pub type Stdio =
  @internal Stdio

Values

capture

</>

pub fn capture(capture_stderr capture_stderr: Bool) -> Mode

Capture the process’s stdout (and optionally stderr) so it can be read.

When used with run(), output is automatically collected and returned.

capture_stderr

</>

pub fn capture_stderr(
  stdio: Stdio,
  capture capture: Bool,
) -> Stdio

Override whether stderr is captured in addition to stdout for this Stdio.

collect

</>

pub fn collect(
  on_finish callback: fn(String, Int) -> Nil,
) -> Stdio

Collect all output and call the callback when the process finishes.

The callback receives the complete output as a String and the exit status code. This is useful when you want to process all output at once rather than streaming it.

Captures stderr by default. Use capture_stderr(False) to override.

collect_bits

</>

pub fn collect_bits(
  on_finish callback: fn(BitArray, Int) -> Nil,
) -> Stdio

Collect all output and call the callback when the process finishes.

The callback receives the complete output as a BitArray and the exit status code. This is useful when you want to process all output at once rather than streaming it.

Captures stderr by default. Use capture_stderr(False) to override.

custom

</>

pub fn custom(
  initial state: state,
  on_data on_data: fn(state, BitArray) -> state,
  on_exit on_exit: fn(state, Int) -> Nil,
) -> Stdio

Create a custom data handler. Most of the time, you would want to use one of the predefined handlers instead.

inherit

</>

pub fn inherit() -> Mode

Inherit stdio streams from the parent process. The child process will share stdin, stdout, and stderr with the parent.

This is useful for interactive programs like text editors, REPLs, or any program that needs direct terminal access. When using inherit() with run(), the captured output will be empty since output goes directly to the terminal.

Important: On the Erlang target, you must start your application with the -noshell flag for inherited stdio to work properly with interactive programs.

For example: erl -noshell -pa build/dev/erlang/*/ebin -run module main

lines

</>

pub fn lines(on_line callback: fn(String) -> Nil) -> Stdio

Stream output line-by-line.

The callback receives complete lines as Strings, including their newline character. When the process exits, any remaining buffered data is delivered as a final callback without a trailing newline.

Captures stderr by default. Use capture_stderr(False) to override.

null

</>

pub fn null() -> Mode

Discard all output from the process.

on_exit

</>

pub fn on_exit(
  stdio: Stdio,
  on_exit callback: fn(Int) -> Nil,
) -> Stdio

Add a callback when the process exits with its status code.

select

</>

pub fn select(
  selector: process.Selector(msg),
  process: @internal Process,
  on_data: fn(BitArray) -> msg,
  on_exit: fn(Int) -> msg,
) -> process.Selector(msg)

Select messages from a running process started with spawn_raw.

The process must be spawned with a mode of capture(_) to receive data.

Example

let assert Ok(proc) =
  child_process.from_file("my_program")
  |> child_process.spawn_raw(stdio.capture(True))

let selector =
  process.new_selector()
  |> stdio.select(proc, HandleData, HandleExit)

stream

</>

pub fn stream(on_data callback: fn(String) -> Nil) -> Stdio

Stream output data as it arrives. The callback receives chunks of data as Strings.

Captures stderr by default. Use capture_stderr(False) to override.

stream_bits

</>

pub fn stream_bits(
  on_data callback: fn(BitArray) -> Nil,
) -> Stdio

Stream raw binary data as it arrives. The callback receives chunks of data as BitArrays.

Captures stderr by default. Use capture_stderr(False) to override.