From 2492165fcbcac631064273c5fc739fe6b903d013 Mon Sep 17 00:00:00 2001 From: Antoine Stevan <44101798+amtoine@users.noreply.github.com> Date: Sun, 26 Feb 2023 21:05:11 +0100 Subject: [PATCH] FEATURE: print example command results in the `help` (#8189) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Should close #8035. > **Note** > this is my first technical PR for `nushell` > - i might very well miss things > - i tried to be as complete as possible about the changes > - please require further changes if i did something wrong, i'm open to any remark :relieved: # Description this PR adds, when it is defined in the `examples` method of the `Command` implementations, the output of the examples to the output of the `help` command. this PR - only modifies `crates/nu-engine/src/documentation.rs` and the `get_documentation` function - defines a new `WD` constant to print a **W**hite **D**immed `...` - a `match` statement at the end of the example loop to - print a white dimmed `...` when the example is not set, i.e. set to `None` in the `examples` method of the `Command` implementation of a command - pretty print the output of the associated example `Value` when it has been defined > **Warning** > LIMITATIONS: > - i use snippets from `crates/nu-protocol/src/pipeline_data.rs` > - the table creation from `pub PipelineData::print`, i.e. the `let decl_id = ...;` and `let table = ...;` in the change > - the table item printing from `PipelineData::write_all_and_flush`, i.e. the `for item in table { ... }` > > ADDRESSED: > - ~~the formatting of the output is not perfect and has to be fully left aligned with the first column for now~~ (fixed with [`5abeefd558c34ba9bae15e2f183ff4625442921e`..`a62be1b5a2c730959da5dbc028bb91ffe5093f63`](5abeefd558c34ba9bae15e2f183ff4625442921e..a62be1b5a2c730959da5dbc028bb91ffe5093f63)) > - ~~i'm using `.unwrap()` on both the changes above, not sure how to handle this for now~~ (fixed for now thanks to 49f1dc080) > - ~~the tests and `clippy` checks do not pass for now, see below~~ (`clippy` now is happy with 49f1dc080 and the tests pass with 11666bc71526b31a27105a362ce11cf94a55b8b6) # User-Facing Changes the output of the `help ` command is now augmented with the outputs of the examples, when they are defined. - `with-env` ```bash > help with-env ... Examples: Set the MYENV environment variable > with-env [MYENV "my env value"] { $env.MYENV } my env value Set by primitive value list > with-env [X Y W Z] { $env.X } Y Set by single row table > with-env [[X W]; [Y Z]] { $env.W } Z Set by key-value record > with-env {X: "Y", W: "Z"} { [$env.X $env.W] } ╭───┬───╮ │ 0 │ Y │ │ 1 │ Z │ ╰───┴───╯ ``` instead of the previous ```bash > help with-env ... Examples: Set the MYENV environment variable > with-env [MYENV "my env value"] { $env.MYENV } Set by primitive value list > with-env [X Y W Z] { $env.X } Set by single row table > with-env [[X W]; [Y Z]] { $env.W } Set by key-value record > with-env {X: "Y", W: "Z"} { [$env.X $env.W] } ``` - `merge` ```bash > help merge ... Examples: Add an 'index' column to the input table > [a b c] | wrap name | merge ( [1 2 3] | wrap index ) ╭───┬──────╮ │ # │ name │ ├───┼──────┤ │ 1 │ a │ │ 2 │ b │ │ 3 │ c │ ╰───┴──────╯ Merge two records > {a: 1, b: 2} | merge {c: 3} ╭───┬───╮ │ a │ 1 │ │ b │ 2 │ │ c │ 3 │ ╰───┴───╯ Merge two tables, overwriting overlapping columns > [{columnA: A0 columnB: B0}] | merge [{columnA: 'A0*'}] ╭───┬─────────┬─────────╮ │ # │ columnA │ columnB │ ├───┼─────────┼─────────┤ │ 0 │ A0* │ B0 │ ╰───┴─────────┴─────────╯ ``` instead of the previous ```bash > help merge ... Examples: Add an 'index' column to the input table > [a b c] | wrap name | merge ( [1 2 3] | wrap index ) Merge two records > {a: 1, b: 2} | merge {c: 3} Merge two tables, overwriting overlapping columns > [{columnA: A0 columnB: B0}] | merge [{columnA: 'A0*'}] ``` --- .../tests/format_conversions/html.rs | 2 +- crates/nu-engine/src/documentation.rs | 28 ++++++++++++++++++- src/tests/test_engine.rs | 2 +- 3 files changed, 29 insertions(+), 3 deletions(-) diff --git a/crates/nu-command/tests/format_conversions/html.rs b/crates/nu-command/tests/format_conversions/html.rs index 1fdf41bbdc..9a1e18c6a2 100644 --- a/crates/nu-command/tests/format_conversions/html.rs +++ b/crates/nu-command/tests/format_conversions/html.rs @@ -57,7 +57,7 @@ fn test_cd_html_color_flag_dark_false() { ); assert_eq!( actual.out, - r"Change directory.

Usage:
> cd (path)

Flags:
-h, --help
Display the help message for this command

Parameters:
(optional) path <directory>: the path to change to

Examples:
Change to your home directory
> cd ~

Change to a directory via abbreviations
> cd d/s/9

Change to the previous working directory ($OLDPWD)
> cd -

" + r"Change directory.

Usage:
> cd (path)

Flags:
-h, --help - Display the help message for this command

Signatures:
<nothing> | cd <string?> -> <nothing>
<string> | cd <string?> -> <nothing>

Parameters:
(optional) path <directory>: the path to change to

Examples:
Change to your home directory
> cd ~

Change to a directory via abbreviations
> cd d/s/9

Change to the previous working directory ($OLDPWD)
> cd -

" ); } diff --git a/crates/nu-engine/src/documentation.rs b/crates/nu-engine/src/documentation.rs index cdd5b82986..cec962e30a 100644 --- a/crates/nu-engine/src/documentation.rs +++ b/crates/nu-engine/src/documentation.rs @@ -1,7 +1,7 @@ use nu_protocol::{ ast::Call, engine::{EngineState, Stack}, - Example, IntoPipelineData, Signature, Span, SyntaxShape, Value, + Example, IntoPipelineData, PipelineData, Signature, Span, SyntaxShape, Value, }; use std::fmt::Write; @@ -209,6 +209,32 @@ fn get_documentation( } else { let _ = write!(long_desc, "\n > {}\n", example.example); } + + if let Some(result) = &example.result { + let table = engine_state + .find_decl("table".as_bytes(), &[]) + .and_then(|decl_id| { + engine_state + .get_decl(decl_id) + .run( + engine_state, + stack, + &Call::new(Span::new(0, 0)), + PipelineData::Value(result.clone(), None), + ) + .ok() + }); + + for item in table.into_iter().flatten() { + let _ = writeln!( + long_desc, + " {}", + item.into_string("", engine_state.get_config()) + .replace('\n', "\n ") + .trim() + ); + } + } } long_desc.push('\n'); diff --git a/src/tests/test_engine.rs b/src/tests/test_engine.rs index a8f7da2564..c47d559821 100644 --- a/src/tests/test_engine.rs +++ b/src/tests/test_engine.rs @@ -53,7 +53,7 @@ fn in_and_if_else() -> TestResult { #[test] fn help_works_with_missing_requirements() -> TestResult { - run_test(r#"each --help | lines | length"#, "43") + run_test(r#"each --help | lines | length"#, "65") } #[test]