Antoine Stevan 2492165fcb FEATURE: print example command results in the help (#8189) ... 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 😌 # 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 11666bc715) # User-Facing Changes the output of the `help <command>` 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*'}] ```		2023-02-26 21:05:11 +01:00
..
commands	special-case ExternalStream in bytes starts-with (#8203)	2023-02-26 15:17:44 +01:00
format_conversions	FEATURE: print example command results in the help (#8189)	2023-02-26 21:05:11 +01:00
main.rs	Expand Nushell's help system (#7611)	2022-12-30 17:44:37 +02:00