extern/nushell
1
0
Fork 1
mirror of https://github.com/nushell/nushell.git synced 2025-04-10 22:18:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

FEATURE: print example command results in the help (#8189)

Browse Source 
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*'}]
```
This commit is contained in:
Antoine Stevan 2023-02-26 21:05:11 +01:00 committed by GitHub
parent c602b5a1e8
commit 2492165fcb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 29 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
crates/nu-command/tests/format_conversions/html.rs
View File

@ -57,7 +57,7 @@ fn test_cd_html_color_flag_dark_false() {
); );
assert_eq!( assert_eq!(
actual.out, actual.out,
r"<html><style>body { background-color:white;color:black; }</style><body>Change directory.<br><br>Usage:<br> &gt; cd (path) <br><br>Flags:<br> -h, --help<br> Display the help message for this command<br><br>Parameters:<br> (optional) path &lt;directory&gt;: the path to change to<br><br>Examples:<br> Change to your home directory<br> &gt; <span style='color:#037979;font-weight:bold;'>cd<span style='color:black;font-weight:normal;'> </span></span><span style='color:#037979;'>~<span style='color:black;font-weight:normal;'><br><br> Change to a directory via abbreviations<br> &gt; </span><span style='color:#037979;font-weight:bold;'>cd<span style='color:black;font-weight:normal;'> </span></span></span><span style='color:#037979;'>d/s/9<span style='color:black;font-weight:normal;'><br><br> Change to the previous working directory ($OLDPWD)<br> &gt; </span><span style='color:#037979;font-weight:bold;'>cd<span style='color:black;font-weight:normal;'> </span></span></span><span style='color:#037979;'>-<span style='color:black;font-weight:normal;'><br><br></body></html></span></span>" r"<html><style>body { background-color:white;color:black; }</style><body>Change directory.<br><br><span style='color:green;'>Usage<span style='color:black;font-weight:normal;'>:<br> &gt; cd (path) <br><br></span></span><span style='color:green;'>Flags<span style='color:black;font-weight:normal;'>:<br> </span></span><span style='color:#037979;'>-h</span>,<span style='color:black;font-weight:normal;'> </span><span style='color:#037979;'>--help<span style='color:black;font-weight:normal;'> - Display the help message for this command<br><br></span><span style='color:green;'>Signatures<span style='color:black;font-weight:normal;'>:<br> &lt;nothing&gt; | cd &lt;string?&gt; -&gt; &lt;nothing&gt;<br> &lt;string&gt; | cd &lt;string?&gt; -&gt; &lt;nothing&gt;<br><br></span></span><span style='color:green;'>Parameters<span style='color:black;font-weight:normal;'>:<br> (optional) </span></span></span><span style='color:#037979;'>path<span style='color:black;font-weight:normal;'> &lt;</span><span style='color:blue;font-weight:bold;'>directory<span style='color:black;font-weight:normal;'>&gt;: the path to change to<br><br></span></span><span style='color:green;'>Examples<span style='color:black;font-weight:normal;'>:<br> Change to your home directory<br> &gt; </span><span style='color:#037979;font-weight:bold;'>cd<span style='color:black;font-weight:normal;'> </span></span></span></span><span style='color:#037979;'>~<span style='color:black;font-weight:normal;'><br><br> Change to a directory via abbreviations<br> &gt; </span><span style='color:#037979;font-weight:bold;'>cd<span style='color:black;font-weight:normal;'> </span></span></span><span style='color:#037979;'>d/s/9<span style='color:black;font-weight:normal;'><br><br> Change to the previous working directory ($OLDPWD)<br> &gt; </span><span style='color:#037979;font-weight:bold;'>cd<span style='color:black;font-weight:normal;'> </span></span></span><span style='color:#037979;'>-<span style='color:black;font-weight:normal;'><br><br></body></html></span></span>"
); );
} }

28
crates/nu-engine/src/documentation.rs
View File

@ -1,7 +1,7 @@
use nu_protocol::{ use nu_protocol::{
ast::Call, ast::Call,
engine::{EngineState, Stack}, engine::{EngineState, Stack},
Example, IntoPipelineData, Signature, Span, SyntaxShape, Value, Example, IntoPipelineData, PipelineData, Signature, Span, SyntaxShape, Value,
}; };
use std::fmt::Write; use std::fmt::Write;
@ -209,6 +209,32 @@ fn get_documentation(
} else { } else {
let _ = write!(long_desc, "\n > {}\n", example.example); 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'); long_desc.push('\n');

2
src/tests/test_engine.rs
View File

@ -53,7 +53,7 @@ fn in_and_if_else() -> TestResult {
#[test] #[test]
fn help_works_with_missing_requirements() -> TestResult { fn help_works_with_missing_requirements() -> TestResult {
run_test(r#"each --help | lines | length"#, "43") run_test(r#"each --help | lines | length"#, "65")
} }
#[test] #[test]