Home Explore Blog CI



nushell

5th chunk of `book/pipelines.md`
35160708d05f6708056276bdbd083c74ef991d644d2f13b00000000100001202
As another example, the [`ls` command](/commands/docs/ls.md) supports output but not input:

```nu
help ls
# => […]
# => Input/output types:
# =>   ╭───┬─────────┬────────╮
# =>   │ # │  input  │ output │
# =>   ├───┼─────────┼────────┤
# =>   │ 0 │ nothing │ table  │
# =>   ╰───┴─────────┴────────╯
```

This means, for example, that attempting to pipe into `ls` (`echo .. | ls`) leads to unintended results.
The input stream is ignored, and `ls` defaults to listing the current directory.

To integrate a command like `ls` into a pipeline, you have to explicitly reference the input and pass it as a parameter:

```nu
echo .. | ls $in
```

Note that this only works if `$in` matches the argument type. For example, `[dir1 dir2] | ls $in` will fail with the error `can't convert list<string> to string`.

Other commands without default behavior may fail in different ways, and with explicit errors.

For example, `help sleep` tells us that [`sleep`](/commands/docs/sleep.md) supports no input and no output types:

```nu
help sleep
# => […]
# => Input/output types:
# =>   ╭───┬─────────┬─────────╮
# =>   │ # │  input  │ output  │
# =>   ├───┼─────────┼─────────┤
# =>   │ 0 │ nothing │ nothing │
# =>   ╰───┴─────────┴─────────╯
```

When we erroneously pipe into it, instead of unintended behavior like in the `ls` example above, we receive an error:

```nu
echo 1sec | sleep
# => Error: nu::parser::missing_positional
# => 
# =>   × Missing required positional argument.
# =>    ╭─[entry #53:1:18]
# =>  1 │ echo 1sec | sleep
# =>    ╰────
# =>   help: Usage: sleep <duration> ...(rest) . Use `--help` for more information.
```

While there is no steadfast rule, Nu generally tries to copy established conventions in command behavior,
or do what 'feels right'.
The `sleep` behavior of not supporting an input stream matches Bash `sleep` behavior for example.

Many commands do have piped input/output however, and if it's ever unclear, check their `help` documentation as described above.

## Rendering Display Results

In interactive mode, when a pipeline ends, the [`display_output` hook configuration](https://www.nushell.sh/book/hooks.html#changing-how-output-is-displayed) defines how the result will be displayed.
The default configuration uses the [`table` command](/commands/docs/table.md) to render structured data as a visual table.

The following example shows how the `display_output` hook can render

- an expanded table with `table -e`
- an unexpanded table with `table`
- an empty closure `{||}` and empty string `''` lead to simple output
- `null` can be assigned to clear any customization, reverting back to default behavior

```nu
$env.config.hooks.display_output = { table -e }
[1,2,3,[4,5,6]]
# => ╭───┬───────────╮
# => │ 0 │         1 │
# => │ 1 │         2 │
# => │ 2 │         3 │
# => │ 3 │ ╭───┬───╮ │
# => │   │ │ 0 │ 4 │ │
# => │   │ │ 1 │ 5 │ │
# => │   │ │ 2 │ 6 │ │
# => │   │ ╰───┴───╯ │
# => ╰───┴───────────╯

$env.config.hooks.display_output = { table }
[1,2,3,[4,5,6]]
# => ╭───┬────────────────╮
# => │ 0 │              1 │
# => │ 1 │              2 │
# => │ 2 │              3 │
# => │ 3 │ [list 3 items] │
# => ╰───┴────────────────╯

$env.config.hooks.display_output = {||}
[1,2,3,[4,5,6]]
# => 1
# => 2
# => 3
# => [4
# => 5
# => 6]

$env.config.hooks.display_output = ''
[1,2,3,[4,5,6]]
# => 1
# => 2
# => 3
# => [4
# => 5
# => 6]

# clear to default behavior
$env.config.hooks.display_output = null
[1,2,3,[4,5,6]]
# => ╭───┬────────────────╮
# => │ 0 │              1 │
# => │ 1 │              2 │
# => │ 2 │              3 │
# => │ 3 │ [list 3 items] │
# => ╰───┴────────────────╯
```

## Output Result to External Commands

Sometimes you want to output Nushell structured data to an external command for further processing. However, Nushell's default formatting options for structured data may not be what you want.

Title: Nu Command Input/Output Types, Error Handling, and Rendering Display Results
Summary
This section discusses how commands like `ls` and `sleep` handle input, highlighting the importance of checking command documentation using `help`. It demonstrates how incorrect piping can lead to errors or unintended behavior. Additionally, it explains how the `display_output` hook configures how results are rendered in interactive mode, showing examples of using `table` to display structured data and customizing the output with closures and strings. Finally, it hints at the topic of outputting Nushell structured data to external commands.