ExCmd is an alternative for beam ports with back-pressure and non-blocking IO.

Quick Start

Run a command and read from stdout

iex> ExCmd.stream!(~w(echo Hello))
...> |> Enum.into("") # collect as string
"Hello\n"

Run a command with list of strings as input

iex> ExCmd.stream!(~w(cat), input: ["Hello", " ", "World"])
...> |> Enum.into("") # collect as string
"Hello World"

Run a command with input as Stream

iex> input_stream = Stream.map(1..10, fn num -> "#{num} " end)
iex> ExCmd.stream!(~w(cat), input: input_stream)
...> |> Enum.into("")
"1 2 3 4 5 6 7 8 9 10 "

Run a command with input as infinite stream

# create infinite stream
iex> input_stream = Stream.repeatedly(fn -> "A" end)
iex> binary =
...>   ExCmd.stream!(~w(cat), input: input_stream, ignore_epipe: true) # we need to ignore epipe since we are terminating the program before the input completes
...>   |> Stream.take(2) # we must limit since the input stream is infinite
...>   |> Enum.into("")
iex> is_binary(binary)
true
iex> "AA" <> _ = binary # we might get more than 2 "A" due to buffering

Run a command with input Collectable

# ExCmd calls the callback with a sink where the process can push the data
iex> ExCmd.stream!(~w(cat), input: fn sink ->
...>   Stream.map(1..10, fn num -> "#{num} " end)
...>   |> Stream.into(sink) # push to the external process
...>   |> Stream.run()
...> end)
...> |> Stream.take(100) # we must limit since the input stream is infinite
...> |> Enum.into("")
"1 2 3 4 5 6 7 8 9 10 "

When the command wait for the input stream to close

# base64 command wait for the input to close and writes data to stdout at once
iex> ExCmd.stream!(~w(base64), input: ["abcdef"])
...> |> Enum.into("")
"YWJjZGVm\n"

stream!/2 raises non-zero exit as error

iex> ExCmd.stream!(["sh", "-c", "echo 'foo' && exit 10"])
...> |> Enum.to_list()
** (ExCmd.Stream.AbnormalExit) program exited with exit status: 10

stream/2 variant returns exit status as last element

iex> ExCmd.stream(["sh", "-c", "echo 'foo' && exit 10"])
...> |> Enum.to_list()
[
  "foo\n",
  {:exit, {:status, 10}} # returns exit status of the program as last element
]

You can fetch exit_status from the error for stream!/2

iex> try do
...>   ExCmd.stream!(["sh", "-c", "exit 10"])
...>   |> Enum.to_list()
...> rescue
...>   e in ExCmd.Stream.AbnormalExit ->
...>     e.exit_status
...> end
10

With max_chunk_size set

iex> data =
...>   ExCmd.stream!(~w(cat /dev/urandom), max_chunk_size: 100, ignore_epipe: true)
...>   |> Stream.take(5)
...>   |> Enum.into("")
iex> byte_size(data)
500

When input and output run at different rate

iex> input_stream = Stream.map(1..1000, fn num -> "X #{num} X\n" end)
iex> ExCmd.stream!(~w(grep 250), input: input_stream)
...> |> Enum.into("")
"X 250 X\n"

With stderr set to :disable (default)

iex> ExCmd.stream!(["sh", "-c", "echo foo; echo bar >&2"])
...> |> Enum.to_list()
["foo\n"]

With stderr set to :redirect_to_stdout

iex> ExCmd.stream!(["sh", "-c", "echo foo; echo bar >&2"], stderr: :redirect_to_stdout)
...> |> Enum.into("")
"foo\nbar\n"

With stderr set to :console

ExCmd.stream!(["sh", "-c", "echo foo; echo bar >&2"], stderr: :console)
|> Enum.to_list()
# STDERR output will be written to the console

For more details about stream API, see ExCmd.stream!/2 and ExCmd.stream/2.

For more details about inner working, please check ExCmd.Process documentation.