2020-03-15 03:04:44 +00:00
use nu_test_support ::{ nu , pipeline } ;
#[ test ]
fn out_html_simple ( ) {
let actual = nu! (
cwd : " . " , pipeline (
r #"
2020-05-04 08:44:33 +00:00
echo 3 | to html
2020-03-15 03:04:44 +00:00
" #
) ) ;
2020-07-16 13:19:29 +00:00
assert_eq! (
actual . out ,
2020-07-20 12:57:29 +00:00
r "<html><style>body { background-color:white;color:black; }</style><body>3</body></html>"
2020-07-16 13:19:29 +00:00
) ;
2020-03-15 03:04:44 +00:00
}
2020-08-02 20:47:54 +00:00
#[ test ]
fn out_html_partial ( ) {
let actual = nu! (
cwd : " . " , pipeline (
r #"
echo 3 | to html - p
" #
) ) ;
assert_eq! (
actual . out ,
" <div style= \" background-color:white;color:black; \" >3</div> "
) ;
}
2020-03-15 03:04:44 +00:00
#[ test ]
fn out_html_table ( ) {
let actual = nu! (
cwd : " . " , pipeline (
r #"
2020-07-20 12:57:29 +00:00
echo ' { " name " : " darren " } ' | from json | to html
2020-03-15 03:04:44 +00:00
" #
) ) ;
assert_eq! (
2020-05-07 11:03:43 +00:00
actual . out ,
2022-06-02 22:34:31 +00:00
r "<html><style>body { background-color:white;color:black; }</style><body><table><thead><tr><th>name</th></tr></thead><tbody><tr><td>darren</td></tr></tbody></table></body></html>"
2020-07-20 12:57:29 +00:00
) ;
}
#[ test ]
2022-08-31 08:15:03 +00:00
#[ ignore ]
2020-07-20 12:57:29 +00:00
fn test_cd_html_color_flag_dark_false ( ) {
let actual = nu! (
cwd : " . " , pipeline (
r #"
2022-02-17 14:55:17 +00:00
cd - - help | to html - - html - color
2020-07-20 12:57:29 +00:00
" #
)
) ;
assert_eq! (
actual . out ,
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 :relieved:
# 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
11666bc71526b31a27105a362ce11cf94a55b8b6)
# 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 20:05:11 +00:00
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> > 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> <nothing> | cd <string?> -> <nothing><br> <string> | cd <string?> -> <nothing><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;'> <</span><span style='color:blue;font-weight:bold;'>directory<span style='color:black;font-weight:normal;'>>: 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> > </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> > </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> > </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>"
2020-07-20 12:57:29 +00:00
) ;
}
#[ test ]
fn test_no_color_flag ( ) {
let actual = nu! (
cwd : " . " , pipeline (
r #"
2022-02-17 14:55:17 +00:00
cd - - help | to html - - no - color
2020-07-20 12:57:29 +00:00
" #
)
) ;
assert_eq! (
actual . out ,
Parameter defaults to $nu.scope.commands (#9152)
(*third* try at posting this PR, #9104, like #9084, got polluted with
unrelated commits. I'm never going to pull from the github feature
branch again!)
# Description
<!--
Thank you for improving Nushell. Please, check our [contributing
guide](../CONTRIBUTING.md) and talk to the core team before making major
changes.
Description of your pull request goes here. **Provide examples and/or
screenshots** if your changes affect the user experience.
-->
Show parameter defaults in scope command signature, where they're
available for display by help.
per https://github.com/nushell/nushell/issues/8928.
I found unexpected ramifications in one completer (NuHelpCompleter) and
plugins, which both use the flag-formatting routine from builtin help.
For the moment I made the minimum necessary changes to get the mainline
scenario to pass tests and run. But we should circle back on what to do
with plugins and help completer..
# User-Facing Changes
<!-- List of all changes that impact the user experience here. This
helps us keep track of breaking changes. -->
1. New `parameter_default` column to `signatures` table in
`$nu.scope.commands`
It is populated with whatever parameters can be defaulted: currently
positional args and named flags.
2. Built in help (both `help <command>` and `<command> --help` will
display the defaults
3. Help completer will display defaults for flags, but not for
positionals.
Example:
A custom command with some default parameters:
```
〉cat ~/work/dflts.nu
# sample function to show defaults in help
export def main [
arg1: string # mandatory positional
arg2:string=abc # optional positional
--switch # no default here
--named:int # named flag, no default
--other:string=def # flag
--hard:record<foo:int bar:string, bas:bool> # default can be compound type
= {foo:22, bar:"other worlds", bas:false}
] { {arg1: $arg1,
arg2: $arg2,
switch: $switch,
named: $named,
other: $other,
hard: $hard, }
}
〉use ~/work/dflts.nu
〉$nu.scope.commands | where name == 'dflts' | get signatures.0.any | reject short_flag description custom_completion
╭───┬────────────────┬────────────────┬──────────────────────────────────────────┬─────────────┬───────────────────────────╮
│ # │ parameter_name │ parameter_type │ syntax_shape │ is_optional │ parameter_default │
├───┼────────────────┼────────────────┼──────────────────────────────────────────┼─────────────┼───────────────────────────┤
│ 0 │ │ input │ any │ false │ │
│ 1 │ arg1 │ positional │ string │ false │ │
│ 2 │ arg2 │ positional │ string │ true │ abc │
│ 3 │ switch │ switch │ │ true │ │
│ 4 │ named │ named │ int │ true │ │
│ 5 │ other │ named │ string │ true │ def │
│ 6 │ hard │ named │ record<foo: int, bar: string, bas: bool> │ true │ ╭───────┬───────────────╮ │
│ │ │ │ │ │ │ foo │ 22 │ │
│ │ │ │ │ │ │ bar │ other worlds │ │
│ │ │ │ │ │ │ bas │ false │ │
│ │ │ │ │ │ ╰───────┴───────────────╯ │
│ 7 │ │ output │ any │ false │ │
╰───┴────────────────┴────────────────┴──────────────────────────────────────────┴─────────────┴───────────────────────────╯
〉help dflts
sample function to show defaults in help
Usage:
> dflts {flags} <arg1> (arg2)
Flags:
--switch - switch -- no default here
--named <Int> - named flag, typed, but no default
--other <String> - flag with default (default: 'def')
--hard <Record([("foo", Int), ("bar", String), ("bas", Boolean)])> - default can be compound type (default: {foo: 22, bar: 'other worlds', bas: false})
-h, --help - Display the help message for this command
Parameters:
arg1 <string>: mandatory positional
arg2 <string>: optional positional (optional, default: 'abc')
```
Compared to (relevant bits of) help output previously:
```
Flags:
-h, --help - Display the help message for this command
-, --switch - no default here
-, --named <int> - named flag, no default
-, --other <string> - flag
-, --hard <record<foo: int, bar: string, bas: bool>> - default can be compound type
Signatures:
<any> | dflts <string> <string> -> <any>
Parameters:
arg1 <string>: mandatory positional
(optional) arg2 <string>: optional positional
```
# Tests + Formatting
<!--
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect -A clippy::result_large_err` to check that
you're using the standard code style
- `cargo test --workspace` to check that all tests pass
- `cargo run -- crates/nu-std/tests/run.nu` to run the tests for the
standard library
> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> [x] toolkit check pr
> ```
-->
# After Submitting
<!-- If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
-->
2023-05-11 18:59:56 +00:00
r "<html><style>body { background-color:white;color:black; }</style><body>Change directory.<br><br>Usage:<br> > cd (path) <br><br>Flags:<br> -h, --help - Display the help message for this command<br><br>Signatures:<br> <nothing> | cd <string?> -> <nothing><br> <string> | cd <string?> -> <nothing><br><br>Parameters:<br> path <directory>: the path to change to (optional)<br><br>Examples:<br> Change to your home directory<br> > cd ~<br><br> Change to a directory via abbreviations<br> > cd d/s/9<br><br> Change to the previous working directory ($OLDPWD)<br> > cd -<br><br></body></html>"
)
2020-03-15 03:04:44 +00:00
}
2022-11-15 17:12:56 +00:00
#[ test ]
fn test_list ( ) {
let actual = nu! (
cwd : " . " ,
r # "to html --list | where name == C64 | get 0 | to nuon"#
) ;
assert_eq! (
actual . out ,
2022-11-19 11:09:39 +00:00
r ## "{name: "C64", black: "#090300", red: "#883932", green: "#55a049", yellow: "#bfce72", blue: "#40318d", purple: "#8b3f96", cyan: "#67b6bd", white: "#ffffff", brightBlack: "#000000", brightRed: "#883932", brightGreen: "#55a049", brightYellow: "#bfce72", brightBlue: "#40318d", brightPurple: "#8b3f96", brightCyan: "#67b6bd", brightWhite: "#f7f7f7", background: "#40318d", foreground: "#7869c4"}"##
2022-11-15 17:12:56 +00:00
) ;
}
