From 2216f66aed274460686fbfa84db880a5484269fa Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sun, 17 Nov 2024 16:18:28 +0100 Subject: [PATCH 1/4] Replace Pipelines "Behind the Scenes" with "Result Display Rendering" The previous "Behind the Scenes" docs has some problems: * The title is not descriptive * Confusing context reference: The "You may have wondered" references `ls` output despite no applicable example in front of it - and is not stable against other docs section changes either way * Confusing false equivalence: Claims "one and the same" and then explains how they are not in fact the same The section is being replaced with a "Result Display Rendering", which * Mentions and explains the existence of a display output hook * Begins with establishing context: The section is about interactive shell pipeline result display output --- I kept the section small as not to duplicate content from the Hooks documentation page. Adding examples for current, different, or simplified displaying may be reasonable here, but would duplicate the hooks "Changing how Output is Displayed" and "Filtering or Diverting Command Output" sections. --- book/pipelines.md | 30 +++--------------------------- 1 file changed, 3 insertions(+), 27 deletions(-) diff --git a/book/pipelines.md b/book/pipelines.md index c23939e3b83..356c06ec3b4 100644 --- a/book/pipelines.md +++ b/book/pipelines.md @@ -379,34 +379,10 @@ The `sleep` behavior of not supporting an input stream matches Bash `sleep` beha Many commands do have piped input/output however, and if it's ever unclear, check their `help` documentation as described above. -## Behind the Scenes +## Result Display Rendering -You may have wondered how we see a table if [`ls`](/commands/docs/ls.md) is an input and not an output. Nu adds this output for us automatically using another command called [`table`](/commands/docs/table.md). The [`table`](/commands/docs/table.md) command is appended to any pipeline that doesn't have an output. This allows us to see the result. - -In effect, the command: - -```nu -ls -``` - -And the pipeline: - -```nu -ls | table -``` - -Are one and the same. - -::: tip Note -The phrase _"are one and the same"_ above only applies to the graphical output in the shell, it does not mean the two data structures are the same: - -```nushell -(ls) == (ls | table) -# => false -``` - -`ls | table` is not even structured data! -::: +In interactive mode, when a pipeline ends, the [`display_output` hook configuration](hooks.md#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. ## Output Result to External Commands From 126d25d4bd86849a4971059e10a222baf8721cf5 Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sun, 17 Nov 2024 16:27:57 +0100 Subject: [PATCH 2/4] Use absolute link for headline anchor Matching link elsewhere in the file --- book/pipelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/pipelines.md b/book/pipelines.md index 356c06ec3b4..59018a3dd6a 100644 --- a/book/pipelines.md +++ b/book/pipelines.md @@ -381,7 +381,7 @@ Many commands do have piped input/output however, and if it's ever unclear, chec ## Result Display Rendering -In interactive mode, when a pipeline ends, the [`display_output` hook configuration](hooks.md#changing-how-output-is-displayed) defines how the result will be displayed. +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. ## Output Result to External Commands From 22e5e0dd14cca8abc61ca77a8ec01bfd7b8cc1f1 Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sun, 2 Feb 2025 17:10:22 +0100 Subject: [PATCH 3/4] Take over suggested headline Co-authored-by: Douglas <32344964+NotTheDr01ds@users.noreply.github.com> --- book/pipelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/pipelines.md b/book/pipelines.md index 59018a3dd6a..de57cc6f413 100644 --- a/book/pipelines.md +++ b/book/pipelines.md @@ -379,7 +379,7 @@ The `sleep` behavior of not supporting an input stream matches Bash `sleep` beha Many commands do have piped input/output however, and if it's ever unclear, check their `help` documentation as described above. -## Result Display Rendering +## 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. From cfe9430422b81a2aa232924adb79786beb888e62 Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sun, 2 Feb 2025 17:27:00 +0100 Subject: [PATCH 4/4] Add examples of display_output hooks --- book/pipelines.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/book/pipelines.md b/book/pipelines.md index de57cc6f413..08aa13e8ae6 100644 --- a/book/pipelines.md +++ b/book/pipelines.md @@ -384,6 +384,65 @@ Many commands do have piped input/output however, and if it's ever unclear, chec 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.