add pipeline examples (#1748)

* add pipeline examples * Update lang-guide/chapters/pipelines.md Co-authored-by: Darren Schroeder <[email protected]> * Update lang-guide/chapters/pipelines.md Co-authored-by: Darren Schroeder <[email protected]> * Update lang-guide/chapters/pipelines.md Co-authored-by: Darren Schroeder <[email protected]> * update example --------- Co-authored-by: Darren Schroeder <[email protected]>
nushell · Jan 15, 2025 · fde4cba · fde4cba
1 parent e686771
commit fde4cba
Showing 1 changed file with 158 additions and 0 deletions.
diff --git a/lang-guide/chapters/pipelines.md b/lang-guide/chapters/pipelines.md
@@ -81,3 +81,161 @@ nu demo.nu o> file.txt o+e>| str upcase
 ```
 
 Also note that `complete` is special, it doesn't work with `e>|`, `o+e>|`.
+
+## Stdio and redirection behavior examples
+
+Pipeline and redirection behavior can be hard to follow when they are used with subexpressions, or custom commands.  Here are some examples that show intended stdio behavior.
+
+### Examples for subexpression
+
+- (^cmd1 | ^cmd2; ^cmd3 | ^cmd4)
+
+| Command | Stdout     | Stderr     |
+| ------- | --------   | ---------- |
+| cmd1    | Piped      | Terminal   |
+| cmd2    | *Terminal* | Terminal   |
+| cmd3    | Piped      | Terminal   |
+| cmd4    | Terminal   | Terminal   |
+
+- (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) | ^cmd5
+
+It runs `(^cmd1 | ^cmd2; ^cmd3 | ^cmd4)` first, then pipes *stdout* to `^cmd5`, where both stdout and stderr are directed to the Terminal.
+
+| Command | Stdout     | Stderr     |
+| ------- | --------   | ---------- |
+| cmd1    | Piped      | Terminal   |
+| cmd2    | *Terminal* | Terminal   |
+| cmd3    | Piped      | Terminal   |
+| cmd4    | Piped      | Terminal  |
+
+- (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) e>| ^cmd5
+
+It runs `(^cmd1 | ^cmd2; ^cmd3 | ^cmd4)` first, then pipes *stderr* to `^cmd5`, where both stdout and stderr are directed to the Terminal.
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | Terminal |
+| cmd2    | Terminal | Terminal |
+| cmd3    | Piped    | Terminal |
+| cmd4    | Terminal | Piped   |
+
+- (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) o+e>| ^cmd5
+
+It runs `(^cmd1 | ^cmd2; ^cmd3 | ^cmd4)` first, then pipes *stdout and stderr* to `^cmd5`, where both stdout and stderr are directed to the Terminal.
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | Terminal |
+| cmd2    | Terminal | Terminal |
+| cmd3    | Piped    | Terminal |
+| cmd4    | Piped    | Piped   |
+
+- (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) o> test.out
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | Terminal |
+| cmd2    | File | Terminal |
+| cmd3    | Piped    | Terminal |
+| cmd4    | File    | Terminal   |
+
+- (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) e> test.out
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | File |
+| cmd2    | Terminal | File |
+| cmd3    | Piped    | File |
+| cmd4    | Terminal    | File   |
+
+- (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) o+e> test.out
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | File |
+| cmd2    | File | File |
+| cmd3    | Piped    | File |
+| cmd4    | File    | File   |
+
+### Examples for custom command
+Given the following custom commands
+
+```nushell
+def custom-cmd [] {
+    ^cmd1 | ^cmd2
+    ^cmd3 | ^cmd4
+}
+```
+
+The custom command stdio behavior is the same as the previous section.
+
+In the examples below the body of `custom-cmd` is `(^cmd1 | ^cmd2; ^cmd3 | ^cmd4)`.
+
+- custom-cmd
+
+| Command | Stdout     | Stderr     |
+| ------- | --------   | ---------- |
+| cmd1    | Piped      | Terminal   |
+| cmd2    | *Terminal* | Terminal   |
+| cmd3    | Piped      | Terminal   |
+| cmd4    | Terminal   | Terminal   |
+
+- custom-cmd | ^cmd5
+
+It runs `custom-cmd` first, then pipes *stdout* to `^cmd5`, where both stdout and stderr are directed to the Terminal.
+
+| Command | Stdout     | Stderr     |
+| ------- | --------   | ---------- |
+| cmd1    | Piped      | Terminal   |
+| cmd2    | *Terminal* | Terminal   |
+| cmd3    | Piped      | Terminal   |
+| cmd4    | Piped      | Terminal  |
+
+- custom-cmd e>| ^cmd5
+
+It runs `custom-cmd` first, then pipes *stderr* to `^cmd5`, where both stdout and stderr are directed to the Terminal.
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | Terminal |
+| cmd2    | Terminal | Terminal |
+| cmd3    | Piped    | Terminal |
+| cmd4    | Terminal | Piped   |
+
+- custom-cmd o+e>| ^cmd5
+
+It runs `custom-cmd` first, then pipes *stdout and stderr* to `^cmd5`, where both stdout and stderr are directed to the Terminal.
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | Terminal |
+| cmd2    | Terminal | Terminal |
+| cmd3    | Piped    | Terminal |
+| cmd4    | Piped    | Piped   |
+
+- custom-cmd o> test.out
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | Terminal |
+| cmd2    | File | Terminal |
+| cmd3    | Piped    | Terminal |
+| cmd4    | File    | Terminal   |
+
+- custom-cmd e> test.out
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | File |
+| cmd2    | Terminal | File |
+| cmd3    | Piped    | File |
+| cmd4    | Terminal    | File   |
+
+- custom-cmd o+e> test.out
+
+| Command | Stdout   | Stderr   |
+| ------- | -------- | -------- |
+| cmd1    | Piped    | File |
+| cmd2    | File | File |
+| cmd3    | Piped    | File |
+| cmd4    | File    | File   |