holm/nushell
1
1
Fork 0
forked from extern/nushell
Code Issues Pull Requests Packages Projects Releases Wiki Activity
2492165fcb
nushell/crates
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
..
nu_plugin_custom_values Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu_plugin_example Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu_plugin_formats Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu_plugin_gstat Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu_plugin_inc Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu_plugin_python update nu_plugin_python due to signature changes (#8107) 2023-02-18 13:27:24 +00:00
nu_plugin_query Added examples to query web plugin (#8171) 2023-02-22 19:01:15 +00:00
nu-cli Fixes autocomplete when using sudo (#8094) 2023-02-24 15:05:36 -08:00
nu-cmd-lang REFACTOR: format some example commands (#8223) 2023-02-26 06:50:05 -06:00
nu-color-config Display empty records and lists (#7925) 2023-02-22 16:18:33 +00:00
nu-command FEATURE: print example command results in the help (#8189) 2023-02-26 21:05:11 +01:00
nu-engine FEATURE: print example command results in the help (#8189) 2023-02-26 21:05:11 +01:00
nu-explore Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-glob Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-json Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-parser remove links to ShellError and ParseError docs - #8167 (#8193) 2023-02-24 09:26:31 -08:00
nu-path Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-plugin Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-pretty-hex Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-protocol Fixes autocomplete when using sudo (#8094) 2023-02-24 15:05:36 -08:00
nu-system Bump errno from 0.2.8 to 0.3.0 (#8131) 2023-02-22 12:56:31 +00:00
nu-table table --collapse dont do truncation return message instead (#8172) 2023-02-22 18:35:45 +00:00
nu-term-grid Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-test-support Update to 0.76.1 version for development (#8161) 2023-02-21 23:21:39 +00:00
nu-utils Compress $HOME into ~ in prompt (#8173) 2023-02-22 16:36:26 -06:00
README.md Remove old nushell/merge engine-q 2022-02-07 14:54:06 -05:00

README.md

Nushell core libraries and plugins

These sub-crates form both the foundation for Nu and a set of plugins which extend Nu with additional functionality.

Foundational libraries are split into two kinds of crates:

  • Core crates - those crates that work together to build the Nushell language engine
  • Support crates - a set of crates that support the engine with additional features like JSON support, ANSI support, and more.

Plugins are likewise also split into two types:

  • Core plugins - plugins that provide part of the default experience of Nu, including access to the system properties, processes, and web-connectivity features.
  • Extra plugins - these plugins run a wide range of different capabilities like working with different file types, charting, viewing binary data, and more.