nushell/crates/nu_plugin_query
Bob Hyman 9e9fe83bfd
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 13:59:56 -05:00
..
src Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
Cargo.toml Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
README.md remove the --encoding option from register in the examples (#8038) 2023-02-11 13:13:40 +00:00

Query plugin for Nushell

Note: this requires Nushell 0.60 or later

To install:

> cargo install --path .

To register (from inside Nushell):

> register <path to installed plugin>