extern/nushell
1
0
Fork 1
mirror of https://github.com/nushell/nushell.git synced 2025-04-13 07:48:19 +02:00
Code Issues Packages Projects Releases Wiki Activity
c6e2607868
nushell/src
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
..
tests FEATURE: print example command results in the help (#8189) 2023-02-26 21:05:11 +01:00
command.rs Use imported names in Command::run signatures (#7967) 2023-02-05 22:17:46 +01:00
config_files.rs ensure that when nu evaluates files, it allows early returns (#7415) 2023-02-02 00:02:27 +01:00
logger.rs Use variable names directly in the format strings (#7906) 2023-01-29 19:37:54 -06:00
main.rs special-case ExternalStream in bytes starts-with (#8203) 2023-02-26 15:17:44 +01:00
README.md Remove old nushell/merge engine-q 2022-02-07 14:54:06 -05:00
run.rs Extract run blocks into functions (#7964) 2023-02-05 22:20:35 +01:00
signals.rs Cleanup of src/main.rs (#7801) 2023-01-20 10:44:49 -08:00
terminal.rs Move all functions of main.rs into modules (#7803) 2023-01-20 13:20:38 -08:00
test_bins.rs special-case ExternalStream in bytes starts-with (#8203) 2023-02-26 15:17:44 +01:00
tests.rs Use variable names directly in the format strings (#7906) 2023-01-29 19:37:54 -06:00

README.md

Nushell REPL

This directory contains the main Nushell REPL (read eval print loop) as part of the CLI portion of Nushell, which creates the nu binary itself.

Current versions of the nu binary will use the Nu argument parsing logic to parse the commandline arguments passed to nu, leaving the logic here to be a thin layer around what the core libraries.