Mirrors/nushell
2
0
Fork 0
mirror of https://github.com/nushell/nushell synced 2024-11-16 09:47:57 +00:00
Code Issues Projects Releases Packages Wiki Activity
nushell/crates/nu-command/tests/format_conversions
History
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
..
bson.rs Remove old nushell/merge engine-q 2022-02-07 14:54:06 -05:00
csv.rs To csv fix (#7850) 2023-01-25 08:42:53 -06:00
html.rs FEATURE: print example command results in the help (#8189) 2023-02-26 21:05:11 +01:00
json.rs allow Range to expand to array-like when converting to json (#8047) 2023-02-24 15:31:33 -06:00
markdown.rs Remove old nushell/merge engine-q 2022-02-07 14:54:06 -05:00
mod.rs Move some from xxx commands to plugin (#7942) 2023-02-13 12:42:08 +00:00
nuon.rs Test more datatypes in nuon (#8211) 2023-02-25 19:26:34 +01:00
ods.rs refactor: change column names from 'Column*' to 'column*' (#4556) 2022-02-19 19:26:47 -05:00
ssv.rs refactor: change column names from 'Column*' to 'column*' (#4556) 2022-02-19 19:26:47 -05:00
toml.rs Fix typos by codespell (#7600) 2022-12-26 02:31:26 -05:00
tsv.rs make first behave same way as last: always return list when with number argument (#6616) 2022-09-28 17:08:17 -05:00
url.rs Rename to url command to url build-query (#7702) 2023-01-15 10:16:29 -08:00
xlsx.rs refactor: change column names from 'Column*' to 'column*' (#4556) 2022-02-19 19:26:47 -05:00
xml.rs Remove old nushell/merge engine-q 2022-02-07 14:54:06 -05:00
yaml.rs Fix and Allow Number and Boolean type to be key in from yaml (#7607) 2022-12-27 08:28:24 -08:00