Bash.Sink (Bash v0.3.0)

Output sink functions for streaming command output.

A sink is a function that receives {:stdout, binary} or {:stderr, binary} chunks. Sinks enable streaming output without accumulating in memory.

Sink Types

collector/1 - Writes to an OutputCollector GenServer (default for sessions)
stream/2 - Writes to a File.Stream or any Collectable
passthrough/1 - Forwards chunks to a callback function
file/2 - Writes directly to a file path
null/0 - Discards all output (for /dev/null)

Builtin Helpers

write/3 - Write to stdout/stderr sink from session_state
write_stdout/2 - Write to stdout sink
write_stderr/2 - Write to stderr sink

Usage

# Create a collector-backed sink
{:ok, collector} = OutputCollector.start_link()
sink = Sink.collector(collector)
sink.({:stdout, "hello"})

# Create a File.Stream sink
stream = File.stream!("/tmp/output.txt")
sink = Sink.stream(stream)
sink.({:stdout, "hello"})

# In builtins, use the helpers:
Sink.write_stdout(session_state, "output\n")
Sink.write_stderr(session_state, "error\n")

Summary

Types

chunk()

t()

Functions

collector(pid)

Creates a sink that writes to an OutputCollector GenServer.

write_stderr(session_state, data)

Write data to stderr sink if available.

write_stdout(session_state, data)

Write data to stdout sink if available.

Types

chunk()

@type chunk() :: {:stdout, binary()} | {:stderr, binary()}

t()

@type t() :: (chunk() -> :ok | {:error, term()})

Functions

collector(pid)

@spec collector(pid()) :: t()

Creates a sink that writes to an OutputCollector GenServer.

This is the default sink type used by sessions. Output is accumulated as iodata in the collector and retrieved at the end of execution.

Examples

{:ok, collector} = OutputCollector.start_link()
sink = Sink.collector(collector)
sink.({:stdout, "hello\n"})
sink.({:stderr, "warning\n"})

# Later, retrieve output
{stdout, stderr} = OutputCollector.output(collector)

write_stderr(session_state, data)

@spec write_stderr(map(), binary()) :: :ok | :no_sink

Write data to stderr sink if available.

Returns :ok if written to sink, :no_sink if no sink configured.

Examples

case Sink.write_stderr(session_state, "error\n") do
  :ok -> {:ok, %CommandResult{exit_code: 0}}
  :no_sink -> :no_sink
end

write_stdout(session_state, data)

@spec write_stdout(map(), binary()) :: :ok | :no_sink

Write data to stdout sink if available.

Returns :ok if written to sink, :no_sink if no sink configured. Builtins should check the return value to decide whether to include output in the CommandResult.

Examples

case Sink.write_stdout(session_state, "hello\n") do
  :ok -> {:ok, %CommandResult{exit_code: 0}}
  :no_sink -> :no_sink
end