(*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.
-->
# Description
This PR allows our custom commands to show up in `$nu.scope.commands`
better. It still needs work because this PR hard code the input and
output types as `Type::Any` but the reason they're being missed in the
first place is that they are not assigned an input and output type.
This allows things like this now. Note the `where is_custom == true`
Another example.
# User-Facing Changes
<!-- List of all changes that impact the user experience here. This
helps us keep track of breaking changes. -->
# 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` 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
> 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.
-->
# Description
`help externs` - command, which list external commands
Closes https://github.com/nushell/nushell/issues/8301
# User-Facing Changes
```nu
$ help externs
╭───┬──────────────┬─────────────┬───────────────────────────────────────────────────╮
│ # │ name │ module_name │ usage │
├───┼──────────────┼─────────────┼───────────────────────────────────────────────────┤
│ 0 │ git push │ completions │ Push changes │
│ │ │ │ │
│ 1 │ git fetch │ completions │ Download objects and refs from another repository │
│ │ │ │ │
│ 2 │ git checkout │ completions │ Check out git branches and files │
│ │ │ │ │
╰───┴──────────────┴─────────────┴───────────────────────────────────────────────────╯
```
# 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` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
# 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.
Related to #8189.
Should close#8302.
Important to:
- have a complete `$nu` structure with all available information
- generate an accurate website, because the `make_docs.nu` script of
`nushell.github.io` uses `$nu.scope.command` to generate the pages of
https://nushell.sh/commands/
> **Note**
> i was looking for "scope" in the source of `nushell` to augment
`$nu.scope` and i found `crates/nu-engine/src/scope.rs` that defines
`nu_engine::scope::create_scope` which lead me to
`nu_engine::scope::ScopeData.collect_commands`.
> i hope this is the right file 😌
# Description
this PR slightly modifies
`nu_engine::scope::ScopeData.collect_commands`:
- add the "result" column to `$nu.scope.commands.examples`
- put the result of the example when a valid `Option(Value)`
- put a `Value::Nothing` when the result is set to `None` in the source
of the command
# User-Facing Changes
users can now access the results of all examples in
```bash
$nu.scope.commands | where name == <command> | get examples.0.result
```
## example...
### ...with a command that defines examples: `merge`
```bash
>_ $nu.scope.commands | where name == merge | get examples.0 | reject description | table --expand
╭───┬────────────────────────────────────────────────────────┬───────────────────────────╮
│ # │ example │ result │
├───┼────────────────────────────────────────────────────────┼───────────────────────────┤
│ 0 │ [a b c] | wrap name | merge ( [1 2 3] | wrap index ) │ ╭───┬──────╮ │
│ │ │ │ # │ name │ │
│ │ │ ├───┼──────┤ │
│ │ │ │ 1 │ a │ │
│ │ │ │ 2 │ b │ │
│ │ │ │ 3 │ c │ │
│ │ │ ╰───┴──────╯ │
│ 1 │ {a: 1, b: 2} | merge {c: 3} │ ╭───┬───╮ │
│ │ │ │ a │ 1 │ │
│ │ │ │ b │ 2 │ │
│ │ │ │ c │ 3 │ │
│ │ │ ╰───┴───╯ │
│ 2 │ [{columnA: A0 columnB: B0}] | merge [{columnA: 'A0*'}] │ ╭───┬─────────┬─────────╮ │
│ │ │ │ # │ columnA │ columnB │ │
│ │ │ ├───┼─────────┼─────────┤ │
│ │ │ │ 0 │ A0* │ B0 │ │
│ │ │ ╰───┴─────────┴─────────╯ │
╰───┴────────────────────────────────────────────────────────┴───────────────────────────╯
```
and we can check that these are "true" results and not just string, e.g.
```bash
>_ $nu.scope.commands | where name == merge | get examples.0.result.0 | describe
table<name: string, index: int>
```
### ...with a command without any example: `open`
```bash
>_ $nu.scope.commands | where name == open | get examples.0 | reject description | table --expand
╭───┬──────────────────────────────────────┬────────╮
│ # │ example │ result │
├───┼──────────────────────────────────────┼────────┤
│ 0 │ open myfile.json │ │
│ 1 │ open myfile.json --raw │ │
│ 2 │ 'myfile.txt' | open │ │
│ 3 │ open myfile.txt --raw | decode utf-8 │ │
╰───┴──────────────────────────────────────┴────────╯
```
and same thing, we can check that there is `$nothing` in this last
command
```bash
>_ $nu.scope.commands | where name == open | get examples.0.result.0 | describe
table<name: string, index: int>
```
# Tests + Formatting
- ✔️ `cargo fmt --all`
- ✔️ `cargo clippy --workspace -- -D warnings -D
clippy::unwrap_used -A clippy::needless_collect`
- ✔️ `cargo test --workspace` (~~currently running~~)
# After Submitting
the documentation would have to be regenerated!
# Description
Relative:
`https://github.com/nushell/nushell/pull/7889#issuecomment-1407503567`
Make `search_terms` return empty string rather than nothing, so some
other command can handle it better
# User-Facing Changes
_(List of all changes that impact the user experience here. This helps
us keep track of breaking changes.)_
# 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` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
# 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.
* Add input and output types to $nu.scope.commands
This commit changes the schema: instead of
command.signature: table
we now have
command.signatures: list<table>
with one signature for every input-output type pair.
* Represent signatures as a map from input_type to signature
* Sort signature entries
* Drop command name from signature tables
* Don't use "rest" as name of rest parameter; use empty string instead
* Bug fix: was creating records with repeated keys
E.g.
$nu.scope.commands | where name == 'hash sha256' | get signatures.0 | table -e
$nu.scope.commands | where name == 'transpose' | get signatures.0 | table -e
