nushell/crates
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
..
nu-cli Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
nu-cmd-lang Allow creating modules from directories (#9066) 2023-05-06 21:39:54 +03:00
nu-color-config Bump tabled dependency to 0.11 (#8922) 2023-04-26 13:56:10 -05:00
nu-command Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
nu-engine Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
nu-explore nu-explore: Fix repeated char issue in cmdline (#9139) 2023-05-08 12:38:42 -05:00
nu-glob update nu-glob based on latest glob 0.3.1 changes (#9099) 2023-05-08 09:07:01 -05:00
nu-json Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu-parser Reuse parsed modules (#9125) 2023-05-07 14:41:40 +03:00
nu-path Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu-plugin Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
nu-pretty-hex Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu-protocol Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
nu-std Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
nu-system Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu-table Fix #9038 (#9042) 2023-04-28 12:50:42 -05:00
nu-term-grid Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu-test-support Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu-utils FEATURE: highlight some prompt parts (#9094) 2023-05-03 16:36:27 -05:00
nu_plugin_custom_values Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu_plugin_example Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu_plugin_formats Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu_plugin_gstat Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu_plugin_inc Bump to 0.79.1 dev version (#8998) 2023-04-26 01:05:23 +02:00
nu_plugin_python update nu_plugin_python due to signature changes (#8107) 2023-02-18 13:27:24 +00:00
nu_plugin_query Parameter defaults to $nu.scope.commands (#9152) 2023-05-11 13:59:56 -05:00
README.md Remove old nushell/merge engine-q 2022-02-07 14:54:06 -05:00

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.