From b685a315623c76ded8f614266335904fdda8c903 Mon Sep 17 00:00:00 2001
From: akash-akya <akashh246@gmail.com>
Date: Mon, 8 Jul 2024 20:18:52 +0530
Subject: [PATCH] Update docs and readme

---
 lib/exile.ex         | 26 +++++++++++++++++++++-----
 lib/exile/process.ex | 13 +++++++------
 2 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/lib/exile.ex b/lib/exile.ex
index 2354dd6..b5d3d3a 100644
--- a/lib/exile.ex
+++ b/lib/exile.ex
@@ -119,10 +119,18 @@ defmodule Exile do
   "X 250 X\n"
   ```
 
+  With stderr set to :redirect_to_stdout
+
+  ```
+  iex> Exile.stream!(["sh", "-c", "echo foo; echo bar >> /dev/stderr"], stderr: :redirect_to_stdout)
+  ...> |> Enum.into("")
+  "foo\nbar\n"
+  ```
+
   With stderr set to :consume
 
   ```
-  iex> Exile.stream!(["sh", "-c", "echo foo\necho bar >> /dev/stderr"], stderr: :consume)
+  iex> Exile.stream!(["sh", "-c", "echo foo; echo bar >> /dev/stderr"], stderr: :consume)
   ...> |> Enum.to_list()
   [{:stdout, "foo\n"}, {:stderr, "bar\n"}]
   ```
@@ -130,7 +138,7 @@ defmodule Exile do
   With stderr set to :disable
 
   ```
-  iex> Exile.stream!(["sh", "-c", "echo foo\necho bar >> /dev/stderr"], stderr: :disable)
+  iex> Exile.stream!(["sh", "-c", "echo foo; echo bar >> /dev/stderr"], stderr: :disable)
   ...> |> Enum.to_list()
   ["foo\n"]
   ```
@@ -195,7 +203,7 @@ defmodule Exile do
   Chunk size can be less than the `max_chunk_size` depending on the amount of
   data available to be read. Defaults to `65_535`
 
-    * `stderr`  -  different ways to handle stderr stream. possible values `:console`, `:disable`, `:stream`.
+    * `stderr`  -  different ways to handle stderr stream. possible values `:console`, `:redirect_to_stdout`, `:disable`, `:stream`.
         1. `:console`  -  stderr output is redirected to console (Default)
         2. `:redirect_to_stdout`  -  stderr output is redirected to stdout
         3. `:disable`  -  stderr output is redirected `/dev/null` suppressing all output
@@ -222,6 +230,14 @@ defmodule Exile do
   |> Stream.run()
   ```
 
+  Stream with stderr redirected to stdout
+
+  ```
+  Exile.stream!(["sh", "-c", "echo foo; echo bar >> /dev/stderr"], stderr: :redirect_to_stdout)
+  |> Stream.map(&IO.write/1)
+  |> Stream.run()
+  ```
+
   Stream with stderr
 
   ```
@@ -258,7 +274,7 @@ defmodule Exile do
   @spec stream!(nonempty_list(String.t()),
           input: Enum.t() | collectable_func(),
           exit_timeout: timeout(),
-          stderr: :console | :disable | :consume,
+          stderr: :console | :redirect_to_stdout | :disable | :consume,
           ignore_epipe: boolean(),
           max_chunk_size: pos_integer()
         ) :: Exile.Stream.t()
@@ -279,7 +295,7 @@ defmodule Exile do
   @spec stream(nonempty_list(String.t()),
           input: Enum.t() | collectable_func(),
           exit_timeout: timeout(),
-          stderr: :console | :disable | :consume,
+          stderr: :console | :redirect_to_stdout | :disable | :consume,
           ignore_epipe: boolean(),
           max_chunk_size: pos_integer()
         ) :: Exile.Stream.t()
diff --git a/lib/exile/process.ex b/lib/exile/process.ex
index ba8b3b2..9744fc5 100644
--- a/lib/exile/process.ex
+++ b/lib/exile/process.ex
@@ -106,11 +106,13 @@ defmodule Exile.Process do
 
   Pipe owner can read or write date to the owned pipe. `:stderr` by
   default is connected to console, data written to stderr will appear on
-  the console. You can enable reading stderr by passing `stderr: :consume`
-  during process creation.
+  the console.
 
-  Special function `Exile.Process.read_any/2` can be used to read
-  from either stdout or stderr whichever has the data available.
+  If you want to read stderr you have two options
+
+  * `:redirect_to_stdout`: stderr data will be redirected to stdout. This is similar to `:stderr_to_stdout` option present in [Ports](https://www.erlang.org/doc/apps/erts/erlang.html#open_port/2). With this option when you read stdout you will see both stdout & stderr combined and you won't be able differentiate streams separately
+
+  * `:consume`: stderr data can be consumed separately using `Exile.Process.read_stderr/2`. Special function `Exile.Process.read_any/2` can be used to read from either stdout or stderr whichever has the data available. See the examples for more details.
 
   All Pipe operations blocks the caller to have blocking as natural
   back-pressure and to make the API simple. This is an important
@@ -300,8 +302,7 @@ defmodule Exile.Process do
     * `env`  -  a list of tuples containing environment key-value.
   These can be accessed in the external program
 
-    * `stderr`  -  different ways to handle stderr stream.
-  possible values `:console`, `:disable`, `:stream`.
+    * `stderr`  -  different ways to handle stderr stream. Possible values `:console`, `:redirect_to_stdout`, `:disable`, `:stream`.
         1. `:console`  -  stderr output is redirected to console (Default)
         2. `:redirect_to_stdout`  -  stderr output is redirected to stdout
         3. `:disable`  -  stderr output is redirected `/dev/null` suppressing all output