From 5af385bc95e4ed6794885635bd81e4b94719d8a5 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:59:57 -0600 Subject: [PATCH 01/46] Fix doc statements that contradict Nushell 0.117.0 These passages described behavior that the 0.117.0 binary or source contradicts. Each was re-checked before editing. - configuration: assigning a record to $env.config merges; login.nu loads before the autoload dirs; -l with a script file loads no config - hooks: display_output and command_not_found run under -c and scripts - coloring_and_theming: drop bg_* names, which color_config ignores; every prompt variable accepts a closure - line_editor: keybindings and menus assignment replaces the list (#19418); fix Alt+C, add PageUp/PageDown, correct the `keybindings default` claim - types: inf/-inf/NaN literals; custom type names work as annotations - strings, globs, date, =~ engine, null comparisons, multi-line parameter comments, module path resolution, std/dirs vs std/log, error chaining from catch, load-env PATH conversion, nu -i -c, display_output default, tui and mcp defaults, explore config saving, background job exit warning, alias hoisting, match int/float equality, reduce closure parameter order Prettier re-padded the color table in coloring_and_theming.md after the bg_* rows were removed. --- book/background_jobs.md | 6 +- book/coloring_and_theming.md | 255 ++++++++---------- book/configuration.md | 17 +- book/creating_errors.md | 4 +- book/custom_commands.md | 2 +- book/environment.md | 2 +- book/explore.md | 2 +- book/hooks.md | 3 +- book/line_editor.md | 31 ++- book/loading_data.md | 2 +- book/mcp.md | 2 +- book/modules/creating_modules.md | 2 +- book/modules/using_modules.md | 2 +- book/moving_around.md | 2 + book/operators.md | 2 +- book/pipelines.md | 10 +- book/sorting.md | 2 +- book/special_variables.md | 2 +- book/standard_library.md | 6 +- book/tui.md | 2 +- book/types_of_data.md | 4 +- book/working_with_strings.md | 13 +- cookbook/direnv.md | 16 +- cookbook/foreign_shell_scripts.md | 7 +- lang-guide/chapters/flow_control/match.md | 7 + lang-guide/chapters/flow_control/try-catch.md | 4 +- .../chapters/types/basic_types/closure.md | 4 +- .../types/other_types/01_not_declarable.md | 18 +- .../types/other_types/custom_value.md | 2 +- lang-guide/chapters/variable_scope.md | 2 +- 30 files changed, 220 insertions(+), 213 deletions(-) diff --git a/book/background_jobs.md b/book/background_jobs.md index 6ea2217a3ad..9f6a00697e0 100644 --- a/book/background_jobs.md +++ b/book/background_jobs.md @@ -175,7 +175,11 @@ for spawning independent background processes (see [#15201](https://github.com/n Additionally, if the user is running an interactive Nushell session and runs [`exit`](/commands/docs/exit.md) while there are background jobs running, -the shell will warn about them before prompting the user to confirm `exit`. +the shell doesn't exit. It prints a `background_jobs_running` warning with the number of +running jobs and returns to the prompt. Running `exit` again as the next command kills the +jobs and exits; if you run any other command first, the next `exit` warns again. +Jobs started with `job spawn --auto-kill` don't count toward the warning and are killed +on exit without one. Pressing Ctrl+C at the REPL interrupts only the command running in the foreground. Background jobs and frozen jobs keep running. diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index 920fb9d559b..0e7c0a46443 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -95,141 +95,124 @@ The color and style-attributes can be declared in multiple alternative formats. ### Normal Colors and Abbreviations -| code | name | -| --------- | ------------------------- | -| `g` | `green` | -| `gb` | `green_bold` | -| `gu` | `green_underline` | -| `gi` | `green_italic` | -| `gd` | `green_dimmed` | -| `gr` | `green_reverse` | -| `bg_g` | `bg_green` | -| `lg` | `light_green` | -| `lgb` | `light_green_bold` | -| `lgu` | `light_green_underline` | -| `lgi` | `light_green_italic` | -| `lgd` | `light_green_dimmed` | -| `lgr` | `light_green_reverse` | -| `bg_lg` | `bg_light_green` | -| `r` | `red` | -| `rb` | `red_bold` | -| `ru` | `red_underline` | -| `ri` | `red_italic` | -| `rd` | `red_dimmed` | -| `rr` | `red_reverse` | -| `bg_r` | `bg_red` | -| `lr` | `light_red` | -| `lrb` | `light_red_bold` | -| `lru` | `light_red_underline` | -| `lri` | `light_red_italic` | -| `lrd` | `light_red_dimmed` | -| `lrr` | `light_red_reverse` | -| `bg_lr` | `bg_light_red` | -| `u` | `blue` | -| `ub` | `blue_bold` | -| `uu` | `blue_underline` | -| `ui` | `blue_italic` | -| `ud` | `blue_dimmed` | -| `ur` | `blue_reverse` | -| `bg_u` | `bg_blue` | -| `lu` | `light_blue` | -| `lub` | `light_blue_bold` | -| `luu` | `light_blue_underline` | -| `lui` | `light_blue_italic` | -| `lud` | `light_blue_dimmed` | -| `lur` | `light_blue_reverse` | -| `bg_lu` | `bg_light_blue` | -| `b` | `black` | -| `bb` | `black_bold` | -| `bu` | `black_underline` | -| `bi` | `black_italic` | -| `bd` | `black_dimmed` | -| `br` | `black_reverse` | -| `bg_b` | `bg_black` | -| `ligr` | `light_gray` | -| `ligrb` | `light_gray_bold` | -| `ligru` | `light_gray_underline` | -| `ligri` | `light_gray_italic` | -| `ligrd` | `light_gray_dimmed` | -| `ligrr` | `light_gray_reverse` | -| `bg_ligr` | `bg_light_gray` | -| `y` | `yellow` | -| `yb` | `yellow_bold` | -| `yu` | `yellow_underline` | -| `yi` | `yellow_italic` | -| `yd` | `yellow_dimmed` | -| `yr` | `yellow_reverse` | -| `bg_y` | `bg_yellow` | -| `ly` | `light_yellow` | -| `lyb` | `light_yellow_bold` | -| `lyu` | `light_yellow_underline` | -| `lyi` | `light_yellow_italic` | -| `lyd` | `light_yellow_dimmed` | -| `lyr` | `light_yellow_reverse` | -| `bg_ly` | `bg_light_yellow` | -| `p` | `purple` | -| `pb` | `purple_bold` | -| `pu` | `purple_underline` | -| `pi` | `purple_italic` | -| `pd` | `purple_dimmed` | -| `pr` | `purple_reverse` | -| `bg_p` | `bg_purple` | -| `lp` | `light_purple` | -| `lpb` | `light_purple_bold` | -| `lpu` | `light_purple_underline` | -| `lpi` | `light_purple_italic` | -| `lpd` | `light_purple_dimmed` | -| `lpr` | `light_purple_reverse` | -| `bg_lp` | `bg_light_purple` | -| `m` | `magenta` | -| `mb` | `magenta_bold` | -| `mu` | `magenta_underline` | -| `mi` | `magenta_italic` | -| `md` | `magenta_dimmed` | -| `mr` | `magenta_reverse` | -| `bg_m` | `bg_magenta` | -| `lm` | `light_magenta` | -| `lmb` | `light_magenta_bold` | -| `lmu` | `light_magenta_underline` | -| `lmi` | `light_magenta_italic` | -| `lmd` | `light_magenta_dimmed` | -| `lmr` | `light_magenta_reverse` | -| `bg_lm` | `bg_light_magenta` | -| `c` | `cyan` | -| `cb` | `cyan_bold` | -| `cu` | `cyan_underline` | -| `ci` | `cyan_italic` | -| `cd` | `cyan_dimmed` | -| `cr` | `cyan_reverse` | -| `bg_c` | `bg_cyan` | -| `lc` | `light_cyan` | -| `lcb` | `light_cyan_bold` | -| `lcu` | `light_cyan_underline` | -| `lci` | `light_cyan_italic` | -| `lcd` | `light_cyan_dimmed` | -| `lcr` | `light_cyan_reverse` | -| `bg_lc` | `bg_light_cyan` | -| `w` | `white` | -| `wb` | `white_bold` | -| `wu` | `white_underline` | -| `wi` | `white_italic` | -| `wd` | `white_dimmed` | -| `wr` | `white_reverse` | -| `bg_w` | `bg_white` | -| `dgr` | `dark_gray` | -| `dgrb` | `dark_gray_bold` | -| `dgru` | `dark_gray_underline` | -| `dgri` | `dark_gray_italic` | -| `dgrd` | `dark_gray_dimmed` | -| `dgrr` | `dark_gray_reverse` | -| `bg_dgr` | `bg_dark_gray` | -| `def` | `default` | -| `defb` | `default_bold` | -| `defu` | `default_underline` | -| `defi` | `default_italic` | -| `defd` | `default_dimmed` | -| `defr` | `default_reverse` | -| `bg_def` | `bg_default` | +These names set the foreground color. For a background color, use the record format, such as `{ bg: red }`. The `bg_*` names that the [`ansi`](/commands/docs/ansi.md) command accepts, such as `bg_red`, have no effect in `color_config`. + +| code | name | +| ------- | ------------------------- | +| `g` | `green` | +| `gb` | `green_bold` | +| `gu` | `green_underline` | +| `gi` | `green_italic` | +| `gd` | `green_dimmed` | +| `gr` | `green_reverse` | +| `lg` | `light_green` | +| `lgb` | `light_green_bold` | +| `lgu` | `light_green_underline` | +| `lgi` | `light_green_italic` | +| `lgd` | `light_green_dimmed` | +| `lgr` | `light_green_reverse` | +| `r` | `red` | +| `rb` | `red_bold` | +| `ru` | `red_underline` | +| `ri` | `red_italic` | +| `rd` | `red_dimmed` | +| `rr` | `red_reverse` | +| `lr` | `light_red` | +| `lrb` | `light_red_bold` | +| `lru` | `light_red_underline` | +| `lri` | `light_red_italic` | +| `lrd` | `light_red_dimmed` | +| `lrr` | `light_red_reverse` | +| `u` | `blue` | +| `ub` | `blue_bold` | +| `uu` | `blue_underline` | +| `ui` | `blue_italic` | +| `ud` | `blue_dimmed` | +| `ur` | `blue_reverse` | +| `lu` | `light_blue` | +| `lub` | `light_blue_bold` | +| `luu` | `light_blue_underline` | +| `lui` | `light_blue_italic` | +| `lud` | `light_blue_dimmed` | +| `lur` | `light_blue_reverse` | +| `b` | `black` | +| `bb` | `black_bold` | +| `bu` | `black_underline` | +| `bi` | `black_italic` | +| `bd` | `black_dimmed` | +| `br` | `black_reverse` | +| `ligr` | `light_gray` | +| `ligrb` | `light_gray_bold` | +| `ligru` | `light_gray_underline` | +| `ligri` | `light_gray_italic` | +| `ligrd` | `light_gray_dimmed` | +| `ligrr` | `light_gray_reverse` | +| `y` | `yellow` | +| `yb` | `yellow_bold` | +| `yu` | `yellow_underline` | +| `yi` | `yellow_italic` | +| `yd` | `yellow_dimmed` | +| `yr` | `yellow_reverse` | +| `ly` | `light_yellow` | +| `lyb` | `light_yellow_bold` | +| `lyu` | `light_yellow_underline` | +| `lyi` | `light_yellow_italic` | +| `lyd` | `light_yellow_dimmed` | +| `lyr` | `light_yellow_reverse` | +| `p` | `purple` | +| `pb` | `purple_bold` | +| `pu` | `purple_underline` | +| `pi` | `purple_italic` | +| `pd` | `purple_dimmed` | +| `pr` | `purple_reverse` | +| `lp` | `light_purple` | +| `lpb` | `light_purple_bold` | +| `lpu` | `light_purple_underline` | +| `lpi` | `light_purple_italic` | +| `lpd` | `light_purple_dimmed` | +| `lpr` | `light_purple_reverse` | +| `m` | `magenta` | +| `mb` | `magenta_bold` | +| `mu` | `magenta_underline` | +| `mi` | `magenta_italic` | +| `md` | `magenta_dimmed` | +| `mr` | `magenta_reverse` | +| `lm` | `light_magenta` | +| `lmb` | `light_magenta_bold` | +| `lmu` | `light_magenta_underline` | +| `lmi` | `light_magenta_italic` | +| `lmd` | `light_magenta_dimmed` | +| `lmr` | `light_magenta_reverse` | +| `c` | `cyan` | +| `cb` | `cyan_bold` | +| `cu` | `cyan_underline` | +| `ci` | `cyan_italic` | +| `cd` | `cyan_dimmed` | +| `cr` | `cyan_reverse` | +| `lc` | `light_cyan` | +| `lcb` | `light_cyan_bold` | +| `lcu` | `light_cyan_underline` | +| `lci` | `light_cyan_italic` | +| `lcd` | `light_cyan_dimmed` | +| `lcr` | `light_cyan_reverse` | +| `w` | `white` | +| `wb` | `white_bold` | +| `wu` | `white_underline` | +| `wi` | `white_italic` | +| `wd` | `white_dimmed` | +| `wr` | `white_reverse` | +| `dgr` | `dark_gray` | +| `dgrb` | `dark_gray_bold` | +| `dgru` | `dark_gray_underline` | +| `dgri` | `dark_gray_italic` | +| `dgrd` | `dark_gray_dimmed` | +| `dgrr` | `dark_gray_reverse` | +| `def` | `default` | +| `defb` | `default_bold` | +| `defu` | `default_underline` | +| `defi` | `default_italic` | +| `defd` | `default_dimmed` | +| `defr` | `default_reverse` | @@ -437,7 +420,7 @@ The Nushell prompt is configurable through these environment variables and confi - `PROMPT_MULTILINE_INDICATOR` = "::: " - `render_right_prompt_on_last_line`: Bool value to enable or disable the right prompt to be rendered on the last line of the prompt -Example: For a simple prompt one could do this. Note that `PROMPT_COMMAND` requires a `block` whereas the others require a `string`. +Example: For a simple prompt one could do this. Each `PROMPT_*` variable takes either a string or a closure that returns one, and Nushell runs the closure every time it draws the prompt. ```nu $env.PROMPT_COMMAND = { $"(date now | format date '%m/%d/%Y %I:%M:%S%.3f'): (pwd | path basename)" } diff --git a/book/configuration.md b/book/configuration.md index 848a3a11ed0..794caef496b 100644 --- a/book/configuration.md +++ b/book/configuration.md @@ -72,9 +72,9 @@ Nushell uses multiple, optional configuration files. These files are loaded in t 1. The first file loaded is `env.nu`, which was historically used to override environment variables. However, the current "best-practice" recommendation is to set all environment variables (and other configuration) using `config.nu` and the autoload directories below. 2. `config.nu` is typically used to override default Nushell settings, define (or import) custom commands, or run any other startup tasks. -3. `*.nu` files in `$nu.vendor-autoload-dirs` are loaded. These directories are intended for vendors' and package managers' startup files. -4. `*.nu` files in `$nu.user-autoload-dirs` are loaded. These files may be used for any startup tasks and are a good way to modularize the configuration. -5. `login.nu` runs commands or handles configuration that should only take place when Nushell is running as a login shell. +3. `login.nu` runs commands or handles configuration that should only take place when Nushell is running as a login shell. +4. `*.nu` files in `$nu.vendor-autoload-dirs` are loaded. These directories are intended for vendors' and package managers' startup files. +5. `*.nu` files in `$nu.user-autoload-dirs` are loaded. These files may be used for any startup tasks and are a good way to modularize the configuration. By default, `env.nu`, `config.nu`, and `login.nu` are read from the `$nu.default-config-dir` directory. For example: @@ -330,23 +330,24 @@ To avoid overwriting existing settings, it's best to simply assign updated value ```nu $env.config = { show_banner: false + color_config: { string: red } } ``` -This would reset any _other_ settings that had been changed, since the entire record would be overwritten. +Nushell merges a record assigned to `$env.config` into the current settings, so the keys it doesn't name keep their values. A key that holds a list or a free-form record is replaced whole, though. Here `color_config` ends up with only the `string` entry, and every other color setting is dropped. The same happens to `keybindings`, `menus`, `abbreviations`, `explore`, `tui`, `plugins`, `hooks.env_change`, and the `pre_prompt` and `pre_execution` hook lists. ::: ::: tip Right ```nu $env.config.show_banner = false +$env.config.color_config.string = 'red' ``` -This changes _only_ the `show_banner` key/value pair, leaving all other keys with their existing values. +This changes _only_ the `show_banner` and `color_config.string` values, leaving all other keys with their existing values. ::: -Certain keys are themselves also records. It's okay to overwrite these records, but it's best-practice -to set all values when doing so. For example: +Certain keys are themselves also records. Assigning a record to one of them merges it the same way, so you only need to list the values you want to change. For example: ```nu # In config.nu @@ -633,7 +634,7 @@ The following stages and their steps _may_ occur during startup, based on the fl | Normal Shell | `nu` (no flags) | All launch steps **_except_** those marked with **_(login)_** occur. | | Login Shell | `nu --login/-l` | All launch steps occur. | | Command-string | `nu --commands ` (or `-c`) | All Launch stages **_except_** those marked with **_(config files)_** or **_(repl)_** occur. However, **_(default_env.nu)_** and **_(plugin)_** do occur, so plugins can be used in the command-string. With `--login/-l`, the **_(env.nu)_**, **_(config.nu)_**, and **_(login)_** steps occur as well. | -| Script file | `nu ` | Same as with Command-string. | +| Script file | `nu ` | Same as with Command-string, except that `--login/-l` doesn't add the **_(env.nu)_**, **_(config.nu)_**, and **_(login)_** steps. | | No config | `nu -n` | **_(config files)_** stages do **_not_** occur, regardless of other flags. | | No Standard Library | `nu --no-std-lib` | Regardless of other flags, the steps marked **_(stdlib)_** will **_not_** occur. | | Force config file | `nu --config ` | Forces steps marked with **_(config.nu)_** above to run with the provided config ``, unless `-n` was also specified | diff --git a/book/creating_errors.md b/book/creating_errors.md index 72a71b8a430..478535fe8a6 100644 --- a/book/creating_errors.md +++ b/book/creating_errors.md @@ -125,7 +125,7 @@ In Nushell 0.113 and earlier, this information was available as a JSON string in ## Chaining Errors -If you call `error make` inside a `catch` block, the caught error becomes an inner error of the new one, and both are reported: +`error make` adds an error record that it receives as input to the new error's `inner` list. A `catch` block's input is the caught error, so when `error make` is the first command in the block, the caught error becomes an inner error of the new one, and both are reported: ```nu try { check-range 10 1 } catch { error make "could not build the range" } @@ -147,3 +147,5 @@ try { check-range 10 1 } catch { error make "could not build the range" } # => ╰──── # => help: swap the two arguments ``` + +After any other statement in the block, such as a `print`, the caught error is no longer the input, and `error make` reports only the new error. To keep the chain, pipe the error in with `$err | error make "..."`, or pass it with `inner`, as in `catch {|err| print 'cleaning up'; error make {msg: 'could not build the range', inner: [$err]} }`. diff --git a/book/custom_commands.md b/book/custom_commands.md index 1ce9b0555bb..1724f65e485 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -1166,7 +1166,7 @@ scope commands This will show the Help _record_ that Nushell creates. ::: -The comments following the parameters become their description. Only a single-line comment is valid for parameters. +The comments following the parameters become their description. A comment can continue on the lines below its parameter. Nushell adds each comment-only line, up to the next parameter, to that parameter's description as a new line. ::: tip Note A Nushell comment that continues on the same line for argument documentation purposes requires a space before the ` #` pound sign. diff --git a/book/environment.md b/book/environment.md index ee39de72557..96aeafb84e7 100644 --- a/book/environment.md +++ b/book/environment.md @@ -247,7 +247,7 @@ Because `nu` is an external program, Nushell translated the `[ a b c ]` list acc Running commands with `nu -c` does not load the config file, therefore the env conversion for `FOO` is missing and it is displayed as a plain string -- this way we can verify the translation was successful. You can also run this step manually by `do $env.ENV_CONVERSIONS.FOO.to_string [a b c]` -_(Important! The string -> value conversion happens only for variables that already exist when `$env.ENV_CONVERSIONS` is assigned, such as those inherited from the parent process. A variable that you set as a string afterwards stays a string. To convert it, set it before assigning `ENV_CONVERSIONS`, or assign `$env.ENV_CONVERSIONS` to itself again.)_ +_(Important! The string -> value conversion happens only for variables that already exist when `$env.ENV_CONVERSIONS` is assigned, such as those inherited from the parent process. A variable that you set as a string afterwards with `$env.FOO = ...` stays a string. To convert it, set it before assigning `ENV_CONVERSIONS`, or assign `$env.ENV_CONVERSIONS` to itself again. [`load-env`](/commands/docs/load-env.md), [`with-env`](/commands/docs/with-env.md) and `FOO=bar cmd` don't have this limit. They run each string they set through its `from_string` conversion and turn a string `PATH` into a list. Pass `--no-convert` to `load-env` or `with-env` to set the values as given.)_ ## Removing Environment Variables diff --git a/book/explore.md b/book/explore.md index 06863c5f818..64a045e0dfc 100644 --- a/book/explore.md +++ b/book/explore.md @@ -113,7 +113,7 @@ Remember you can combine it with `--peek`. ## Exploring Your Configuration -[`explore config`](/commands/docs/explore_config.md) opens your current `$env.config` as a tree with an editor pane. Use `Tab` to switch between the tree and the editor, the arrow keys to move and to expand or collapse nodes, and `Enter` to start editing a value. Press `Ctrl+S` to apply an edit. When you quit with `q`, your changes are applied to the running session; `Ctrl+C` quits without saving them. +[`explore config`](/commands/docs/explore_config.md) opens your current `$env.config` as a tree with an editor pane. Use `Tab` to switch between the tree and the editor, the arrow keys to move and to expand or collapse nodes, and `Enter` to start editing a value. Press `Ctrl+S` to apply an edit to the tree. After an edit, `q` won't quit and shows "Unsaved changes!" until you press `Ctrl+S` again while you aren't editing a value, which stages your changes. When `explore config` exits, every edit you applied to the tree is written to `$env.config` in the running session. That includes quitting with `Ctrl+C`, which skips the check and drops only an edit you haven't applied yet. ```nu # Browse and edit the running configuration diff --git a/book/hooks.md b/book/hooks.md index c632f0c3ec3..0f8d69c2b94 100644 --- a/book/hooks.md +++ b/book/hooks.md @@ -1,7 +1,8 @@ # Hooks Hooks allow you to run a code snippet at some predefined situations. -They are only available in the interactive mode ([REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)), they do not work if you run Nushell with a script (`nu script.nu`) or command (`nu -c "print foo"`) argument. +The `pre_prompt`, `pre_execution` and `env_change` hooks only run in the interactive mode ([REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)). They do not run if you run Nushell with a script (`nu script.nu`) or command (`nu -c "print foo"`) argument. +The `display_output` and `command_not_found` hooks work there too. `display_output` formats the value that the script or command returns, and `command_not_found` runs when it calls a command that doesn't exist. Currently, we support these types of hooks: diff --git a/book/line_editor.md b/book/line_editor.md index 9ef8ded2e6c..58ca050badd 100644 --- a/book/line_editor.md +++ b/book/line_editor.md @@ -114,7 +114,7 @@ $env.config.cursor_shape.vi_normal = 'block' ## Default Keybindings -Each of the three edit modes is built from a few shared sets of keybindings plus its own additions. The tables below follow Reedline's [keybinding reference](https://github.com/nushell/reedline/blob/main/KEYBINDINGS.md) for the Reedline version that ships with Nushell. Run [`keybindings default`](/commands/docs/keybindings_default.md) to list the built-in keybindings of every mode. +Each of the three edit modes is built from a few shared sets of keybindings plus its own additions. The tables below follow Reedline's [keybinding reference](https://github.com/nushell/reedline/blob/main/KEYBINDINGS.md) for the Reedline version that ships with Nushell. Run [`keybindings default`](/commands/docs/keybindings_default.md) to list Reedline's built-in key table for the `emacs`, `vi_normal`, `vi_insert`, `helix_normal` and `helix_insert` modes. It has no rows for `vi_visual` or `helix_select`, and it leaves out the plain-key Vi and Helix commands such as w and d, which Reedline handles outside that table. Some keys are a _fallback chain_: Reedline tries each step and takes the first one that applies. The tables write those with "otherwise". For example, → accepts a history hint if one is showing, otherwise moves right in an open menu, otherwise moves the cursor right. @@ -179,6 +179,8 @@ A mode without the editing set rebinds Backspace and Delete↑, Ctrl+P | Move up in an open menu, otherwise move one line up, walking back through the history from the first line | | ↓, Ctrl+N | Move down in an open menu, otherwise move one line down, walking forward through the history from the last line | +| PageUp | Move one page up in an open menu, otherwise jump to the oldest history entry | +| PageDown | Move one page down in an open menu, otherwise leave the history for the line you were typing | | ← | Move left in an open menu, otherwise move one character left | | → | Accept a history hint, otherwise move right in an open menu, otherwise move one character right | | Ctrl+← | Move one word left | @@ -237,7 +239,7 @@ Emacs mode is the default. It has all four [common sets](#common-keybindings), p | Ctrl+G | Redo | | Alt+U | Uppercase the word under the cursor | | Alt+L | Lowercase the word under the cursor | -| Alt+C | Capitalize the character under the cursor | +| Alt+C | Uppercase the first letter of the word under the cursor and lowercase the rest | ### Vi Mode @@ -561,13 +563,14 @@ $env.config.keybindings ++= [{ After loading this new `config.nu`, your new keybinding (`Ctrl + t`) will open the completion command. -Each keybinding requires the next elements: +Each keybinding has the next elements: -- name: A unique name for your keybinding. Assigning to `$env.config.keybindings` merges - the new entries into the existing bindings by name: an entry with the same name and key - as an existing binding replaces it, while an entry that reuses a name for a different key - is added as another binding and prints a `Multiple keybindings share a name` warning. - To clear every keybinding, assign an empty list (`$env.config.keybindings = []`). +- name: A label for your keybinding. It is optional, and Nushell doesn't use it to match + entries. Assigning a list to `$env.config.keybindings` replaces the whole list, including + the default bindings that open the menus (such as Tab for the completion menu), + so add your bindings with `++=` as in the example above. When two entries bind the same + mode, modifier and keycode, the later one wins. `$env.config.keybindings = []` removes + every binding in the list, but Reedline's built-in bindings for moving and editing stay. - modifier: A key modifier for the keybinding. The options are: - none - control @@ -931,13 +934,15 @@ Your terminal environment may not always propagate your key combinations on to N ## Menus Thanks to Reedline, Nushell has menus that can help you with your day to day -shell scripting. Next we present the default menus that are always available +shell scripting. Next we present the default menus that are available when using Nushell -Menus are configured in `$env.config.menus`. Assigning to this list merges your -entries into the default menus by `name`, so an entry named `completion_menu` -replaces the default completion menu instead of adding a second one, and -`$env.config.menus = []` does not remove the default menus. +Menus are configured in `$env.config.menus`. Assigning a list to it replaces every +menu, including the defaults, so `$env.config.menus = []` removes them all and +Tab no longer opens a completion menu. To add a menu or change a default +one, append it with `++=`. When two menus share a `name`, the later one replaces the +earlier one, so an appended `completion_menu` takes the place of the default +completion menu. Each menu sets `input_mode`, which controls the text that the menu searches: diff --git a/book/loading_data.md b/book/loading_data.md index 1bc2414d737..a2f69c63dbc 100644 --- a/book/loading_data.md +++ b/book/loading_data.md @@ -1,6 +1,6 @@ # Loading Data -Earlier, we saw how you can use commands like [`ls`](/commands/docs/ls.md), [`ps`](/commands/docs/ps.md), [`date`](/commands/docs/date.md), and [`sys host`](/commands/docs/sys_host.md) to load information about your files, processes, time of day, and the system itself. Each command gives us a table of information that we can explore. There are other ways we can load in a table of data to work with. +Earlier, we saw how you can use commands like [`ls`](/commands/docs/ls.md), [`ps`](/commands/docs/ps.md), [`date now`](/commands/docs/date_now.md), and [`sys host`](/commands/docs/sys_host.md) to load information about your files, processes, time of day, and the system itself. Each command gives us a table of information that we can explore. There are other ways we can load in a table of data to work with. ## Opening files diff --git a/book/mcp.md b/book/mcp.md index bff9f684a84..3a639274a52 100644 --- a/book/mcp.md +++ b/book/mcp.md @@ -67,7 +67,7 @@ Every result is also stored in the `$history` list, at the `history_index` given | Variable | Default | Effect | | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `NU_MCP_OUTPUT_LIMIT` | `10kb` | Larger results are left out of the response, which has a `note` field in place of `output`: `output truncated, full result in $history.0`. `0b` turns truncation off. | +| `NU_MCP_OUTPUT_LIMIT` | `10kib` | Larger results are left out of the response, which has a `note` field in place of `output`: `output truncated, full result in $history.0`. `0b` turns truncation off. | | `NU_MCP_HISTORY_LIMIT` | `100` | How many results `$history` keeps. Older results are dropped. | | `NU_MCP_PROMOTE_AFTER` | `120sec` | A call that runs longer than this becomes a [background job](./background_jobs.md). The response is an error with the job id, and the result can be collected later with `job recv`. | diff --git a/book/modules/creating_modules.md b/book/modules/creating_modules.md index 636f427da42..f0136edcc4c 100644 --- a/book/modules/creating_modules.md +++ b/book/modules/creating_modules.md @@ -384,7 +384,7 @@ Running this command changes the directory _locally_ in the module, but the chan ### `export-env` runs only when the `use` call is _evaluated_ ::: note -This scenario is commonly encountered when creating a module that uses `std/log`. +This scenario is commonly encountered when creating a module that uses `std/dirs`. ::: Attempting to import a module's environment within another environment may not work as expected. Let's create a new module `go.nu` that creates "shortcuts" to common directories. One of these will be the `$env.NU_MODULES_DIR` defined above in `my-utils`. diff --git a/book/modules/using_modules.md b/book/modules/using_modules.md index a87bf198273..b750a401d68 100644 --- a/book/modules/using_modules.md +++ b/book/modules/using_modules.md @@ -76,7 +76,7 @@ The path to the module can be: ::: ::: important Important! Importing modules from `$NU_LIB_DIRS` or `$env.NU_LIB_DIRS` - When importing a module via a relative path, Nushell first searches from the current directory. If a matching module is not found at that location, Nushell then searches each directory in the constant `$NU_LIB_DIRS` list, and then the environment variable version, `$env.NU_LIB_DIRS`. By default, both include the `scripts` directory in your Nushell configuration directory and the `completions` directory in your Nushell data directory. The constant is the recommended place to add your own directories. + When importing a module via a relative path, Nushell first searches from the directory of the file that contains the `use` (or `source`) call. For a command typed at the prompt or passed to `nu -c`, that is the current directory. If a matching module is not found at that location, Nushell then searches each directory in the constant `$NU_LIB_DIRS` list, and then the environment variable version, `$env.NU_LIB_DIRS`. By default, both include the `scripts` directory in your Nushell configuration directory and the `completions` directory in your Nushell data directory. The constant is the recommended place to add your own directories. This allows you to install modules to a location that is easily accessible via a relative path regardless of the current directory. ::: diff --git a/book/moving_around.md b/book/moving_around.md index c8ae80279a9..45ed6b2757c 100644 --- a/book/moving_around.md +++ b/book/moving_around.md @@ -110,6 +110,8 @@ The quoting techniques above are useful when constructing glob-literals, but you ls $glob_pattern ``` + An interpolated string written directly as the argument doesn't need `into glob`. Nushell expands it as a glob, so `ls $"*($current_month)*"` finds the same files. The conversion is needed when the pattern is stored in a variable first, as above, or comes from another command. + 2. The spread operator combined with the [`glob` command](/commands/docs/glob.html): The [`glob` command](/commands/docs/glob.html) (note: not the same as `into glob`) produces a [`list`](types_of_data.html#lists) of filenames that match the glob pattern. This list can be expanded and passed to filesystem commands using the [spread operator](operators.html#spread-operator): diff --git a/book/operators.md b/book/operators.md index cad2bceca63..0b4ac0d3569 100644 --- a/book/operators.md +++ b/book/operators.md @@ -125,7 +125,7 @@ For example: ls | where name =~ ^nu # returns all files whose names start with "nu" ``` -Both operators use [the Rust regex crate's `is_match()` function](https://docs.rs/regex/latest/regex/struct.Regex.html#method.is_match). +Both operators use the [`fancy-regex`](https://docs.rs/fancy-regex) crate, which adds look-around and backreferences to the syntax of Rust's `regex` crate. See [Regular Expressions](./regular_expressions.md) for the syntax. ## Case Sensitivity diff --git a/book/pipelines.md b/book/pipelines.md index d1aa258502f..c96a824fb42 100644 --- a/book/pipelines.md +++ b/book/pipelines.md @@ -404,15 +404,15 @@ Many commands do have piped input/output however, and if it's ever unclear, chec ## Rendering Display Results -In interactive mode, when a pipeline ends, the [`display_output` hook configuration](https://www.nushell.sh/book/hooks.html#changing-how-output-is-displayed) defines how the result will be displayed. -The default configuration uses the [`table` command](/commands/docs/table.md) to render structured data as a visual table. +When a pipeline typed at the prompt ends, or a script or `nu -c` command finishes, the [`display_output` hook configuration](https://www.nushell.sh/book/hooks.html#changing-how-output-is-displayed) defines how the result will be displayed. +The default hook is `if (term size).columns >= 100 { table -e } else { table }`, which uses the [`table` command](/commands/docs/table.md) to render structured data as a visual table, expanding nested data when the terminal is at least 100 columns wide. The following example shows how the `display_output` hook can render - an expanded table with `table -e` - an unexpanded table with `table` - an empty closure `{||}` and empty string `''` lead to simple output -- `null` can be assigned to clear any customization, reverting back to default behavior +- `null` removes the hook, and Nushell then renders results with a plain `table`, without the default's `-e` on wide terminals ```nu $env.config.hooks.display_output = { table -e } @@ -455,7 +455,7 @@ $env.config.hooks.display_output = '' # => 5 # => 6] -# clear to default behavior +# remove the hook: a plain `table`, even on a wide terminal $env.config.hooks.display_output = null [1,2,3,[4,5,6]] # => ╭───┬────────────────╮ @@ -466,6 +466,8 @@ $env.config.hooks.display_output = null # => ╰───┴────────────────╯ ``` +To restore the default, assign its string again: `$env.config.hooks.display_output = 'if (term size).columns >= 100 { table -e } else { table }'`. + ## Output Result to External Commands Sometimes you want to output Nushell structured data to an external command for further processing. However, Nushell's default formatting options for structured data may not be what you want. diff --git a/book/sorting.md b/book/sorting.md index 1f18b567be4..ba8166b6e1c 100644 --- a/book/sorting.md +++ b/book/sorting.md @@ -398,7 +398,7 @@ $incompatible | sort-by -c {|a, b| $a < $b | default ($a != null) } # => ╰──── ``` -Special handling is required for `null` values, since comparison between any value and `null` returns `null`. To instead reject `null` values, try the following: +Special handling is required for `null` values, since an ordering comparison (`<`, `<=`, `>`, `>=`) between any value and `null` returns `null`. `==` and `!=` still return a `bool`, so `1 == null` is `false`. To instead reject `null` values, try the following: ```nu let baddata = [8 3.2 null 58 2] diff --git a/book/special_variables.md b/book/special_variables.md index e0a067c885f..437c3a15639 100644 --- a/book/special_variables.md +++ b/book/special_variables.md @@ -43,7 +43,7 @@ The `$nu` constant is a record containing several useful values: # => true ``` - Note: When started as an interactive shell, startup config files are processed. When started as a non-interactive shell, no config files are read unless explicitly called via flag. + Note: When started as an interactive shell (the REPL), startup config files are processed. When started as a non-interactive shell, no config files are read unless explicitly called via flag. `--interactive (-i)` doesn't change that. `nu -i -c` and `nu -i script.nu` still read no config files, and they exit when they finish. - `is-login`: Indicates whether or not Nushell was started as a login shell. - `history-enabled`: History may be disabled via `nu --no-history`, in which case this constant will be `false`. diff --git a/book/standard_library.md b/book/standard_library.md index 304017810aa..3272074b5fd 100644 --- a/book/standard_library.md +++ b/book/standard_library.md @@ -161,10 +161,12 @@ nu -n -c "$nu.startup-time" You will not be able to import the library, any of its submodules, nor use any of its commands, when it is disabled in this way. This includes the `banner` and `pwd` commands from `std/prelude`. -## Using `std/log` in Modules +## Using `std/dirs` in Modules ::: warning Important! -`std/log` exports environment variables. To use the `std/log` module in your own module, please see [this caveat](./modules/creating_modules.md#export-env-runs-only-when-the-use-call-is-evaluated) in the "Creating Modules" Chapter. +`std/dirs` sets up its environment variables in an `export-env` block. If your own module imports it with a top-level `use std/dirs`, that block doesn't run when your module is imported, and `dirs` fails with `Cannot find column 'DIRS_LIST'`. To use the `std/dirs` module in your own module, please see [this caveat](./modules/creating_modules.md#export-env-runs-only-when-the-use-call-is-evaluated) in the "Creating Modules" Chapter. + +`std/log` doesn't need this. Its commands fall back to their default formats when its environment variables aren't set. ::: diff --git a/book/tui.md b/book/tui.md index 3893d10952a..576268334e3 100644 --- a/book/tui.md +++ b/book/tui.md @@ -867,7 +867,7 @@ Colors come from `$env.config.tui`, which has one entry per part of the interfac | `tab_active` / `tab_inactive` | The tab bar | `{ fg: cyan, attr: bu }` / `{ fg: dark_gray }` | | `progress` | The filled part of a progress bar | `{ fg: green }` | | `button` | Button labels | `{ fg: white, bg: blue }` | -| `surface` / `backdrop` | The fill behind widgets, and behind a `--dialog` (only `bg` is used) | unset (a near-black fill) | +| `surface` / `backdrop` | The fill behind widgets, and behind a `--dialog` (only `bg` is used) | `{ bg: default }`, the terminal's background | ```nu $env.config.tui.title_bar = { fg: black, bg: yellow, attr: b } diff --git a/book/types_of_data.md b/book/types_of_data.md index 2d5d6723cf6..c56ef5489b4 100644 --- a/book/types_of_data.md +++ b/book/types_of_data.md @@ -26,7 +26,7 @@ Each type below lists its _annotation_: the name you write after `:` to declare | Type | Example | | ------------------------------------- | --------------------------------------------------------------------- | | [Integers](#integers) | `-65535` | -| [Floats (decimals)](#floats-decimals) | `9.9999`, `Infinity` | +| [Floats (decimals)](#floats-decimals) | `9.9999`, `inf`, `-inf`, `NaN` | | [Strings](#text-strings) | "hole 18", 'hole 18', \`hole 18\`, hole18, r#'hole18'# | | [Booleans](#booleans) | `true` | | [Dates](#dates) | `2000-01-01` | @@ -439,7 +439,7 @@ $simple_record.c? == null | | | | --------------------- | ---------------------------------------------------------------------------------------------------------- | | **_Description:_** | A [semantic version](https://semver.org) number, such as `1.2.3` or `2.0.0-rc.1` | -| **_Annotation:_** | N/A - This is a custom value, which `describe` reports as `semver` | +| **_Annotation:_** | `semver`, a custom value type that `describe` also reports as `semver` | | **_Literal Syntax:_** | N/A - Convert a string or record with [`into semver`](/commands/docs/into_semver.md) | | **_See also:_** | [`semver bump`](/commands/docs/semver_bump.md), [`into semver-range`](/commands/docs/into_semver-range.md) | diff --git a/book/working_with_strings.md b/book/working_with_strings.md index 0f37e87ea57..df9724e6b0b 100644 --- a/book/working_with_strings.md +++ b/book/working_with_strings.md @@ -7,12 +7,12 @@ and much more. Strings are so common that Nushell offers multiple string formats | Format of string | Example | Escapes | Notes | | ---------------------------------------------------- | ----------------------- | ------------------------- | ---------------------------------------------------------------------- | -| [Single-quoted string](#single-quoted-strings) | `'[^\n]+'` | None | Cannot contain single quotes within the string | +| [Single-quoted string](#single-quoted-strings) | `'[^\n]+'` | None | Inner `'` only in pairs, kept as written: `'a''b'` is `a''b` | | [Double-quoted string](#double-quoted-strings) | `"The\nEnd"` | C-style backslash escapes | All literal backslashes must be escaped | | [Raw strings](#raw-strings) | `r#'Raw string'#` | None | May include single quotes | | [Bare word string](#bare-word-strings) | `ozymandias` | None | Can only contain "word" characters; Cannot be used in command position | | [Backtick string](#backtick-quoted-strings) | \`[^\n]+\` | None | Bare string that can include whitespace. Cannot contain any backticks | -| [Single-quoted interpolation](#string-interpolation) | `$'Captain ($name)'` | None | Cannot contain any `'` or unmatched `()` | +| [Single-quoted interpolation](#string-interpolation) | `$'Captain ($name)'` | None | Inner `'` only in pairs, as above. No unmatched `()` | | [Double-quoted interpolation](#string-interpolation) | `$"Captain ($name)"` | C-style backslash escapes | All literal backslashes and `()` must be escaped | ## Single-quoted Strings @@ -30,6 +30,15 @@ end' Single-quoted strings don't do anything to the text they're given, making them ideal for holding a wide range of text data. +There is no escape for `'` inside a single-quoted string. Inner single quotes work only in pairs, and only when the word ends with `'`. Nushell keeps them as written, so `''` is not read as one quote the way it is in SQL: + +```nu +'it''s' +# => it''s +``` + +For text with a lone `'`, such as `don't`, use a double-quoted string, a backtick string, or a [raw string](#raw-strings). + ## Double-quoted Strings For more complex strings, Nushell also offers double-quoted strings. These strings use the `"` character to surround text. They also support the ability to escape characters inside the text using the `\` character. diff --git a/cookbook/direnv.md b/cookbook/direnv.md index 19145259550..cb1020af83a 100644 --- a/cookbook/direnv.md +++ b/cookbook/direnv.md @@ -17,18 +17,15 @@ From [direnv.net](https://direnv.net): In Nushell, it's possible to run direnv each time the prompt displays (using a [`pre_prompt` hook](/book/hooks.html)). However, it's more efficient to update only when the directory is changed using an `env_change` hook along with: - [`from json`](/commands/docs/from_json.md) to convert the direnv output to structured data -- [`load-env`](/commands/docs/load-env.md) -- An `env-conversion` helper for the `PATH` from the [Standard Library](/book/standard_library.md) +- [`load-env`](/commands/docs/load-env.md), which also turns the `PATH` string that direnv exports into a list ::: note -The direnv configuration below requires Nushell 0.104 or later. +The direnv configuration below requires Nushell 0.117 or later. ::: ```nu -use std/config * - # Initialize the PWD hook as an empty list if it doesn't exist $env.config.hooks.env_change.PWD = $env.config.hooks.env_change.PWD? | default [] @@ -38,14 +35,7 @@ $env.config.hooks.env_change.PWD ++= [{|| return } - direnv export json - | from json - | default {} - | update cells { - # If direnv changes the PATH, it will become a string and we need to re-convert it to a list - do (env-conversions).path.from_string $in - } PATH - | load-env + direnv export json | from json | default {} | load-env }] ``` diff --git a/cookbook/foreign_shell_scripts.md b/cookbook/foreign_shell_scripts.md index 35810c80ac7..7cbad5325ba 100644 --- a/cookbook/foreign_shell_scripts.md +++ b/cookbook/foreign_shell_scripts.md @@ -140,9 +140,10 @@ A caveat for this approach is that it requires all changed environment variables not to include newline characters, as the UNIX `env` output is not cleanly parseable in that case. -Also beware that directly passing the output of `capture-foreign-env` to -`load-env` can result in changed variables like `PATH` to become strings again, -even if they have been converted to a list before. +Before Nushell 0.117.0, passing the output of `capture-foreign-env` directly to +`load-env` turned changed variables like `PATH` back into strings. Since 0.117.0, +`load-env` turns a string `PATH` into a list and applies `$env.ENV_CONVERSIONS` +to the other variables it sets. ::: ### Detailed Explanation of `capture-foreign-env` diff --git a/lang-guide/chapters/flow_control/match.md b/lang-guide/chapters/flow_control/match.md index 0ade5ee11c2..0f0bbf2b601 100644 --- a/lang-guide/chapters/flow_control/match.md +++ b/lang-guide/chapters/flow_control/match.md @@ -98,6 +98,13 @@ List and record patterns can be nested, and a pattern can be followed by an `if` # => string ``` + Ints and floats are the exception. They compare by numeric value, so the float `1.0` matches the pattern `1`: + + ```nu + match 1.0 { 1 => 'int pattern', 1.0 => 'float pattern' } + # => int pattern + ``` + 1. A list pattern without `..` must have exactly as many items as the list: ```nu diff --git a/lang-guide/chapters/flow_control/try-catch.md b/lang-guide/chapters/flow_control/try-catch.md index abc3900e1fa..193d8e234af 100644 --- a/lang-guide/chapters/flow_control/try-catch.md +++ b/lang-guide/chapters/flow_control/try-catch.md @@ -70,7 +70,7 @@ try { error make {msg: "disk full", help: "free some space"} } catch { $in.detai # => 1 ``` -1. Errors raised inside `catch` propagate normally. When `catch` raises a new error with `error make`, the original error is attached to it and printed after it: +1. Errors raised inside `catch` propagate normally. `error make` attaches an error record it receives as input to the new error, and the input of `catch` is the original error. So when `error make` is the first command in `catch`, the original error is attached to the new one and printed after it: ```nu try { error make {msg: a} } catch {|e| error make {msg: b} } @@ -90,6 +90,8 @@ try { error make {msg: "disk full", help: "free some space"} } catch { $in.detai # => ╰──── ``` + After any other statement, the original error is no longer the input. Pipe it in (`$e | error make {msg: b}`) or pass it as `inner` to keep it attached: `catch {|e| print "logging"; error make {msg: b, inner: [$e]} }`. + To log an error and re-raise it unchanged, return `$e.raw`: `catch {|e| print "logging"; $e.raw }`. 1. `finally` runs after the block succeeds, after `catch`, when an uncaught error is about to propagate, and when `break`, `continue`, `return` or `exit` leaves the `try` (only `exit --abort` skips it). It receives a value as its parameter and as `$in`: diff --git a/lang-guide/chapters/types/basic_types/closure.md b/lang-guide/chapters/types/basic_types/closure.md index 0ecf4ae6ac8..b7c382f5a35 100644 --- a/lang-guide/chapters/types/basic_types/closure.md +++ b/lang-guide/chapters/types/basic_types/closure.md @@ -204,9 +204,9 @@ The `sort-by` command sorts a list or table. The closure determines and returns # => ╰───┴────────╯ ``` -The `reduce` command processes a list to accumulate a single result. The closure defines how to combine the current item with the (intermediate) accumulated value. +The `reduce` command processes a list to accumulate a single result. The closure defines how to combine the current item with the (intermediate) accumulated value. It receives the current item first and the accumulated value second. ```nu -[1 2 3 4] | reduce {|accumulator, current_value| $accumulator + $current_value } +[1 2 3 4] | reduce {|current_value, accumulator| $accumulator + $current_value } # => 10 ``` diff --git a/lang-guide/chapters/types/other_types/01_not_declarable.md b/lang-guide/chapters/types/other_types/01_not_declarable.md index 0e610e96fad..c0bcff1d909 100644 --- a/lang-guide/chapters/types/other_types/01_not_declarable.md +++ b/lang-guide/chapters/types/other_types/01_not_declarable.md @@ -2,18 +2,14 @@ The following are valid Nushell data types which cannot be declared by the user. They are used by Nushell internally or by plugins or commands compiled in Nushell like Polars and SQLite database. -Besides `error` values and blocks (see their pages), this group includes [custom values](custom_value.md) such as `semver` and `semver-range` (from `into semver` and `into semver-range`), `matrix` (from `into matrix`), `SQLiteDatabase` (from `open` on a SQLite file or `stor open`), and Polars objects such as `polars_dataframe`. `describe` reports their names, but a name like `semver` cannot be used as a type annotation: +Besides `error` values and blocks (see their pages), this group includes [custom values](custom_value.md) such as `semver` and `semver-range` (from `into semver` and `into semver-range`), `matrix` (from `into matrix`), `SQLiteDatabase` (from `open` on a SQLite file or `stor open`), and Polars objects such as `polars_dataframe`. `describe` reports their names. Since Nushell 0.117.0, such a name also works as a type annotation when a command in scope declares that type in its signature. The built-in types above always qualify, and a plugin's types, such as `polars_dataframe`, do once the plugin is added: ```nu -let v: semver = ("1.2.3" | into semver) -# => Error: nu::parser::unknown_type -# => -# => × Unknown type. -# => ╭─[repl_entry #1:1:8] -# => 1 │ let v: semver = ("1.2.3" | into semver) -# => · ───┬── -# => · ╰── unknown type -# => ╰──── +def bump-minor [v: semver]: nothing -> semver { $v | semver bump minor } +bump-minor ("1.2.3" | into semver) +# => 1.3.0 ``` -Leave such a variable or parameter unannotated, or annotate it as `any`. +The parser checks the argument, so `bump-minor "1.2.3"` fails with `expected semver`. Convert the string with `into semver` first. + +A name that no command in scope declares, such as `polars_dataframe` without the Polars plugin, is an `unknown type` error. Leave such a variable or parameter unannotated, or annotate it as `any`. diff --git a/lang-guide/chapters/types/other_types/custom_value.md b/lang-guide/chapters/types/other_types/custom_value.md index 38ea5115d87..bfc7e61a514 100644 --- a/lang-guide/chapters/types/other_types/custom_value.md +++ b/lang-guide/chapters/types/other_types/custom_value.md @@ -4,7 +4,7 @@ | | | | --- | --- | | **_Description:_** | An opaque data type that is only used internally in Nushell by built-in commands or plugins. -| **_Annotation:_** | None +| **_Annotation:_** | The type name reported by `describe`, such as `semver`, when a command in scope declares it (see [Types which are not declarable](./01_not_declarable.md)) | **_Literal syntax:_** | None | **_Casts:_** | None diff --git a/lang-guide/chapters/variable_scope.md b/lang-guide/chapters/variable_scope.md index 76616a4dfec..90226ea51a6 100644 --- a/lang-guide/chapters/variable_scope.md +++ b/lang-guide/chapters/variable_scope.md @@ -85,7 +85,7 @@ g # => 1 ``` -`def` and `alias` definitions are scoped like variables: a command defined inside a block, closure or other command is not visible outside it. Unlike variables, definitions are available in their whole block, even before the line that defines them: +`def` and `alias` definitions are scoped like variables: a command defined inside a block, closure or other command is not visible outside it. An `alias` can only be used after its definition, but a `def` is available in its whole block, even before the line that defines it: ```nu print (greet); def greet [] { 'defined later' } From 2fbe7a35607acf0edf31e0ffc1504cc4a877655f Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 16:24:34 -0600 Subject: [PATCH 02/46] Document type, string, and operator features that had no docs Covers the rows rated `none` in the coverage checklist for data types, literals, operators, redirection, and Nushell's exit status: - quotes inside one word, nested interpolation, bare-word interpolation - inf/-inf/NaN, inclusive ranges, range bound and construction errors - list and record separators, parenthesized expressions in literals, combined cell-path modifiers, interpolated globs - subtyping and which values a type annotation accepts - unary minus, every redirection spelling including the append forms, where redirections are allowed, and nu's exit status after an error Examples were run with a 0.117.1-dev build and checked against 0.117.0. --- book/moving_around.md | 2 + book/navigating_structured_data.md | 2 + book/operators.md | 21 ++++ book/stdout_stderr_exit_codes.md | 102 ++++++++++++++++++ book/types_of_data.md | 4 +- book/working_with_strings.md | 77 ++++++++++++- lang-guide/chapters/operators.md | 1 + lang-guide/chapters/strings_and_text.md | 12 +++ .../chapters/types/basic_types/cellpath.md | 27 +++++ .../chapters/types/basic_types/float.md | 29 ++++- lang-guide/chapters/types/basic_types/glob.md | 13 +++ lang-guide/chapters/types/basic_types/list.md | 39 +++++++ .../chapters/types/basic_types/range.md | 56 ++++++++++ .../chapters/types/basic_types/record.md | 41 +++++++ lang-guide/chapters/types/type_signatures.md | 53 +++++++++ 15 files changed, 476 insertions(+), 3 deletions(-) diff --git a/book/moving_around.md b/book/moving_around.md index 45ed6b2757c..14d83722e6a 100644 --- a/book/moving_around.md +++ b/book/moving_around.md @@ -112,6 +112,8 @@ The quoting techniques above are useful when constructing glob-literals, but you An interpolated string written directly as the argument doesn't need `into glob`. Nushell expands it as a glob, so `ls $"*($current_month)*"` finds the same files. The conversion is needed when the pattern is stored in a variable first, as above, or comes from another command. + This only works when the interpolated string has at least one `( )` part. `ls $"*.txt"` has nothing to interpolate, so it is a plain string, and `ls` looks for a file literally named `*.txt`. A [bare word with `( )`](working_with_strings.md#interpolation-in-bare-words) expands as well: `ls *($current_month)*` finds the same files as the examples above. + 2. The spread operator combined with the [`glob` command](/commands/docs/glob.html): The [`glob` command](/commands/docs/glob.html) (note: not the same as `into glob`) produces a [`list`](types_of_data.html#lists) of filenames that match the glob pattern. This list can be expanded and passed to filesystem commands using the [spread operator](operators.html#spread-operator): diff --git a/book/navigating_structured_data.md b/book/navigating_structured_data.md index 37b54589b9c..50611f9ce34 100644 --- a/book/navigating_structured_data.md +++ b/book/navigating_structured_data.md @@ -311,6 +311,8 @@ $person | get --ignore-case name (Environment variables are an exception: `$env.path` and `$env.PATH` both work.) +A member can also be both case-insensitive and [optional](#the-optional-operator). Add both modifiers, in either order: `$person.age?!` returns `null` instead of failing. + ## Handling Missing Data ### The Optional Operator diff --git a/book/operators.md b/book/operators.md index 0b4ac0d3569..2f6a712c19b 100644 --- a/book/operators.md +++ b/book/operators.md @@ -67,6 +67,27 @@ Presented in descending order of precedence, the article details the operations # => 9 ``` +## Negation + +A `-` written directly in front of a variable or a parenthesized expression negates it. This works for numbers, durations and file sizes: + +```nu +let x = 5 +-$x +# => -5 +-(1 + $x) +# => -6 +let d = 2sec +-$d +# => -2sec +``` + +The `-` has to touch the value. `- $x`, with a space, is a parse error ("expected operator"). Negating any other type, such as a string or a bool, is a parse error with the hint "Only numbers, durations and filesizes can be negated." When the parser can't know the type, as with a variable declared `any`, the error comes when the line runs instead. + +Negation binds more tightly than every binary operator, `**` included, so `-$x ** 2` is `25`. Write `-($x ** 2)` to get `-25`. + +In a command call, Nushell reads a word that starts with `-` as a flag. `echo -$x` fails with "The `echo` command doesn't have flag `-$`", so put the negation in parentheses: `echo (-$x)`. An external command gets `-$x` as the literal text `-$x`, so use `^echo (-$x)` there too. + ## Types Not all operations make sense for all data types. diff --git a/book/stdout_stderr_exit_codes.md b/book/stdout_stderr_exit_codes.md index 350e3bb0c89..74fa1023764 100644 --- a/book/stdout_stderr_exit_codes.md +++ b/book/stdout_stderr_exit_codes.md @@ -55,6 +55,27 @@ try { ^false | lines } catch {|err| $err.exit_code } This pipeline behavior is an opt-out experimental option named `pipefail`. To turn it off, start Nushell with `nu --experimental-options '[pipefail=false]'`. ::: +### Nushell's own exit status + +When a script (`nu script.nu`) or a command string (`nu -c '...'`) stops at an error that nothing catches, Nushell prints the error and exits with a non-zero status. The status tells the calling program what failed: + +- `1` for an error from Nushell itself, such as a parse error, a failing built-in command, or [`error make`](/commands/docs/error_make.md). +- The external command's own exit code when an external failed. A script that stops at an external that exited with `42` exits with `42`. +- `256 - N` when an external was killed by signal `N`. This only happens on Unix-like systems. Inside Nushell, [`complete`](/commands/docs/complete.md) and the `exit_code` field of a `catch` error report the signal as `-N`, and the operating system keeps only the low 8 bits of that, so SIGTERM (15) becomes `241`. Bash reports `128 + N` (`143` for SIGTERM) in the same situation. + +```nu +nu -c 'error make {msg: boom}' | complete | get exit_code +# => 1 +nu -c 'nu -c "exit 42"' | complete | get exit_code +# => 42 +sh -c 'kill -TERM $$' | complete | get exit_code +# => -15 +nu -c 'sh -c "kill -TERM $$"' | complete | get exit_code +# => 241 +``` + +To set the status yourself, end the script with [`exit`](/commands/docs/exit.md). + ## Using the [`complete`](/commands/docs/complete.md) command The [`complete`](/commands/docs/complete.md) command allows you to run an external to completion, and gather the stdout, stderr, and exit code together in one record. @@ -112,6 +133,29 @@ cat unknown.txt o> out.log e> err.log cat unknown.txt o+e> log.log ``` +The `>` forms replace the file's contents. To add to the end of the file instead, use `>>`. It creates the file if it doesn't exist yet: + +```nu +nu -c 'print one' o> out.log +nu -c 'print two' o>> out.log +open out.log +# => one +# => two +``` + +The combined forms can name the streams in either order, so `e+o>` and `err+out>` do the same as `o+e>`. This table lists every redirection operator, including the [pipe redirections](#pipe-redirections) described below: + +| Operators | Effect | +| ------------------------------------------------- | ------------------------------------------------ | +| `o>`, `out>` | Write stdout to a file, replacing its contents | +| `o>>`, `out>>` | Append stdout to a file | +| `e>`, `err>` | Write stderr to a file, replacing its contents | +| `e>>`, `err>>` | Append stderr to a file | +| `o+e>`, `out+err>`, `e+o>`, `err+out>` | Write both streams to one file | +| `o+e>>`, `out+err>>`, `e+o>>`, `err+out>>` | Append both streams to one file | +| `e>\|`, `err>\|` | Pipe stderr to the next command | +| `o+e>\|`, `out+err>\|`, `e+o>\|`, `err+out>\|` | Pipe both streams to the next command | + Also, any expression can be used for the file path, as long as it is a string value: ```nu use std @@ -159,6 +203,23 @@ nu -c 'print output; print -e error' o+e>| str uppercase # => ERROR ``` +There is no pipe redirection for stdout alone, since a plain `|` already does that job. `o>|` and `out>|` are parse errors: + +```nu +nu -c 'print hello' o>| str uppercase +# => Error: nu::parser::parse_mismatch +# => +# => × Parse mismatch: expected `|`. Redirecting stdout to a pipe is the same as +# => │ normal piping.. +# => ╭─[repl_entry #1:1:21] +# => 1 │ nu -c 'print hello' o>| str uppercase +# => · ─┬─ +# => · ╰── expected `|`. Redirecting stdout to a pipe is the same as normal piping. +# => ╰──── +# => help: Check the syntax around this position — a typo, missing delimiter, or +# => wrong separator is common. +``` + ::: note Because a failing external makes the whole pipeline fail (see [Exit Code](#exit-code)), the redirected output of a command that exits with an error can be lost. For example, `cat unknown.txt e>| str uppercase` prints nothing, because `cat` exits with code 1. Use [`complete`](#using-the-complete-command) when you need both the output and the exit code of a failing command. ::: @@ -170,6 +231,47 @@ Unlike file redirections, pipe redirections do not apply to all commands inside # => TWO ``` +## Where redirections are allowed + +A redirection belongs to the command in front of it. One with no command, such as `ls | o> out.txt`, is an error: + +```nu +ls | o> out.txt +# => Error: nu::parser::unexpected_redirection +# => +# => × Unexpected redirection. +# => ╭─[repl_entry #1:1:6] +# => 1 │ ls | o> out.txt +# => · ─┬ +# => · ╰── redirecting nothing +# => ╰──── +``` + +The keywords that define or load code can't be redirected: `def`, `extern`, `module`, `use`, `hide`, the `overlay` subcommands, `plugin use`, `source`, `source-env` and `run`, along with the `export` forms of these. `for` is in the same group. Each one fails with "Redirection can not be used with" followed by the keyword: + +```nu +for i in 1..2 { ^echo $i } o> loop.txt +# => Error: nu::parser::error +# => +# => × Redirection can not be used with for. +# => ╭─[repl_entry #1:1:28] +# => 1 │ for i in 1..2 { ^echo $i } o> loop.txt +# => · ─┬ +# => · ╰── not allowed here +# => ╰──── +``` + +Two other keywords reject a redirection with a different error. `type T = int o> t.txt` is "Extra tokens in code", and `alias l = ls o> x.txt` is "Can't create alias to expression". + +To redirect what a loop prints, run it inside [`do`](/commands/docs/do.md) and redirect the `do` call. A file redirection applies to every external command inside it: + +```nu +do { for i in 1..2 { ^echo $i } } o> loop.txt +open loop.txt +# => 1 +# => 2 +``` + ## Discarding Output The [`ignore`](/commands/docs/ignore.md) command discards the output of the previous command. By default, it consumes stdout and lets the stderr of an external command through to the screen. Use `--stderr` to consume stderr instead, or both flags to silence the command completely: diff --git a/book/types_of_data.md b/book/types_of_data.md index c56ef5489b4..49e3bded1f8 100644 --- a/book/types_of_data.md +++ b/book/types_of_data.md @@ -81,6 +81,7 @@ The `/` operator always returns a float, even when both operands are integers an | **_Description:_** | Numbers with some fractional component | | **_Annotation:_** | `float` | | **_Literal Syntax:_** | A decimal numeric value including a decimal place. E.g., `1.5`, `2.0`, `-15.333` | +| | `inf`, `-inf` and `NaN` (also `nan`) for infinity and "not a number" | | **_See also:_** | [Language Reference - Float](/lang-guide/chapters/types/basic_types/float.md) | Simple Example: @@ -216,6 +217,7 @@ See the [Language Reference](/lang-guide/chapters/types/basic_types/filesize.htm | **_Annotation:_** | `range` | | **_Literal Syntax:_** | `..`. E.g., `1..10`. | | | `....`. E.g., `2..4..20` | +| | `..<` excludes the end value (`0..<5`), and `..=` is an explicit spelling of `..` (`0..=4`) | | **_See also:_** | [Language Guide - Range](/lang-guide/chapters/types/basic_types/range.md) | Simple example: @@ -232,7 +234,7 @@ Simple example: ``` ::: tip -You can also easily create lists of characters with a form similar to ranges with the command [`seq char`](/commands/docs/seq_char.html) as well as with dates using the [`seq date`](/commands/docs/seq_date.html) command. +The values of a range must be numbers, so `("a")..("z")` is an error. To make a list of characters, use the [`seq char`](/commands/docs/seq_char.html) command, and for dates use [`seq date`](/commands/docs/seq_date.html). ::: ### Cell Paths diff --git a/book/working_with_strings.md b/book/working_with_strings.md index df9724e6b0b..9d0e6350cb6 100644 --- a/book/working_with_strings.md +++ b/book/working_with_strings.md @@ -30,7 +30,7 @@ end' Single-quoted strings don't do anything to the text they're given, making them ideal for holding a wide range of text data. -There is no escape for `'` inside a single-quoted string. Inner single quotes work only in pairs, and only when the word ends with `'`. Nushell keeps them as written, so `''` is not read as one quote the way it is in SQL: +There is no escape for `'` inside a single-quoted string. Inner single quotes work only in pairs, and only when the word ends with `'` (see [Quotes inside a quoted word](#quotes-inside-a-quoted-word)). Nushell keeps them as written, so `''` is not read as one quote the way it is in SQL: ```nu 'it''s' @@ -94,6 +94,35 @@ r###'r##'This is an example of a raw string.'##'### # => r##'This is an example of a raw string.'## ``` +## Quotes inside a quoted word + +Nushell splits a line into words at whitespace outside of quotes. When a word starts with `'` or `"`, the string runs from that quote to the last quote of the same kind in the word, and any quotes of that kind in between are part of the string. That's why `'it''s'` keeps both quotes, and why inner double quotes can go unescaped as long as the word has no spaces outside them: + +```nu +"[{a: "b"}]" +# => [{a: "b"}] +``` + +Text after the last quote is an error: + +```nu +'a'b +# => Error: nu::parser::extra_token_after_closing_delimiter +# => +# => × Invalid characters after closing delimiter +# => ╭─[repl_entry #1:1:4] +# => 1 │ 'a'b +# => · ┬ +# => · ╰── invalid characters +# => ╰──── +# => help: Remove these characters, or check that a delimiter closed too early +# => above. +``` + +A space outside the inner quotes ends the word, so `"a "b c" d"` fails the same way at the `b`, and so does JSON with a space in a value, such as `"{"k": "a b"}"`. Escape the inner quotes instead (`"a \"b c\" d"`), or use the other kind of quote or a raw string: `'{"k": "a b"}'` works. + +The rule also catches words that look like operators. `'a'..'z'` is not a range of letters. It is the single string `a'..'z`. + ## Bare Word Strings Like other shell languages (but unlike most other programming languages) strings consisting of a single 'word' can also be written without any quotes: @@ -253,6 +282,32 @@ $"2 + 2 is (2 + 2) \(you guessed it!)" # => 2 + 2 is 4 (you guessed it!) ``` +The code inside `( )` is ordinary Nushell code, not part of the surrounding string. Quotes inside it don't end the interpolated string, and you write them without escapes, the same way you would outside a string. That includes another interpolated string: + +```nu +$"(["x" "y"] | str join ", ")" +# => x, y +$"a ($"b (1 + 1)")" +# => a b 2 +``` + +A `)` inside a quoted string within the parentheses doesn't close them either: `$"a (")") c"` is `a ) c`. Escaping a quote inside the parentheses is an error, because `\"` isn't valid Nushell code outside a string: + +```nu +$"a (\"b\") c" +# => Error: nu::parser::unclosed_delimiter +# => +# => × Unclosed delimiter. +# => ╭─[repl_entry #1:1:14] +# => 1 │ $"a (\"b\") c" +# => · ┬ ┬ +# => · │ ╰── expected `)` here +# => · ╰── unclosed — opens here (need `)`) +# => ╰──── +# => help: Add a matching `)` to close this delimiter, or check that an earlier +# => closer closed the wrong block. +``` + Interpolated strings can be evaluated at parse time, but if they include values whose formatting depends on your configuration and your `config.nu` hasn't been loaded yet, they will use the default configuration. So if you have something like this in your `config.nu`, `x` will be `"2.0 kB"` even if your config says to use @@ -262,6 +317,26 @@ So if you have something like this in your `config.nu`, `x` will be `"2.0 kB"` e const x = $"(2kb)" ``` +### Interpolation in bare words + +A [bare word](#bare-word-strings) that contains `(` is interpolated without the `$"..."`. This is handy for file names and other arguments built from a variable: + +```nu +let n = 3 +echo file($n).txt +# => file3.txt +[v($n) ($n)-beta] | to nuon +# => ["v3", "3-beta"] +``` + +It follows the rules for bare words: + +- It works where Nushell expects a value, such as a command argument, a list item or a record value. At the start of a pipeline or after `let x =`, a word like `v($n)` is a command name, so Nushell tries to run an external command called `v3`. A word that starts with `(`, like `($n)-beta`, works in both places. +- There are no escapes. As in single-quoted interpolation, `v\($n)` is `v\3`. +- It can't be attached to a quoted string. `"v"($n)` is the "Invalid characters after closing delimiter" error from [above](#quotes-inside-a-quoted-word). +- The variable needs parentheses. Nushell reads all of `$n-beta` as one variable name and rejects it with "expected valid variable name". +- In a command argument that takes a glob, such as for `ls` or `rm`, the result is a glob pattern: `ls ($n)*.txt` lists the files whose names start with `3` and end in `.txt`. See [Converting Strings to Globs](moving_around.md#converting-strings-to-globs). + ## Splitting Strings The [`split row`](/commands/docs/split_row.md) command creates a list from a string based on a delimiter. diff --git a/lang-guide/chapters/operators.md b/lang-guide/chapters/operators.md index 29c2a6658f3..1f77c49e7e7 100644 --- a/lang-guide/chapters/operators.md +++ b/lang-guide/chapters/operators.md @@ -12,6 +12,7 @@ For a full list with precedence values, run `help operators`. See also [Operator - `mod` - Modulo (floor semantics: the result has the sign of the divisor) - `**` - Pow - `++` - Concatenates two lists, two strings, or two binary values +- `-` directly before a variable or a parenthesized expression (`-$x`, `-(1 + $x)`) - Negation of a number, duration or file size. There is no space after the `-`, and negation binds more tightly than `**`. See [Negation](/book/operators.md#negation) in the Book. ```nu 10 / 4 diff --git a/lang-guide/chapters/strings_and_text.md b/lang-guide/chapters/strings_and_text.md index a8e11180619..335b3246623 100644 --- a/lang-guide/chapters/strings_and_text.md +++ b/lang-guide/chapters/strings_and_text.md @@ -155,3 +155,15 @@ The key to always remember is that double quotes recognize and interpret escapes It doesn't work because it sees `\P` and `\s` as escapes that are not recognized. Use single quotes or a raw string instead: `'C:\Program Files\somedir'` or `r#'C:\Program Files\somedir'#`. ## Bare word + +A bare word is a string written without quotes, such as `hello` or `./my-file.txt`. See [Bare Word Strings](/book/working_with_strings.md#bare-word-strings) in the Book for where Nushell reads one as a string and where it reads it as a command name. + +A bare word that contains `(` is an interpolated string. Each `( )` part is evaluated and joined with the text around it. Backslashes are kept as written, as in `$'...'`: + +```nu +let n = 3 +echo file($n).txt +# => file3.txt +``` + +In command position the word is still a command name, so `v($n)` on its own runs an external command named `v3`. A word that starts with a quote is not bare, and `"v"($n)` is a parse error. See [Interpolation in bare words](/book/working_with_strings.md#interpolation-in-bare-words) for the details. diff --git a/lang-guide/chapters/types/basic_types/cellpath.md b/lang-guide/chapters/types/basic_types/cellpath.md index 55d6933c546..0672ce35a6d 100644 --- a/lang-guide/chapters/types/basic_types/cellpath.md +++ b/lang-guide/chapters/types/basic_types/cellpath.md @@ -63,6 +63,33 @@ let data = [ # => 1 ``` + One member can have both modifiers, in either order. `?!` and `!?` mean the same thing, and Nushell displays the combination as `!?`. Repeating a modifier is a parse error: `{a: 1}.a??` fails with "expected . or !", and `.a!!` with "expected . or ?". + + ```nu + {Name: 1}.name?! + # => 1 + {Name: 1}.age!? | describe + # => nothing + ``` + +- Negative indexes: + + A row index counts from the start, and there is no negative form for counting from the end. `$list.-1` is a parse error: + + ```nu + [1 2 3].-1 + # => Error: nu::parser::error + # => + # => × Invalid literal + # => ╭─[repl_entry #1:1:9] + # => 1 │ [1 2 3].-1 + # => · ─┬ + # => · ╰── negative index is not supported in cell path + # => ╰──── + ``` + + A negative int passed to `get` fails at runtime with "can't convert negative number to cell path". Use [`last`](/commands/docs/last.md) to get items from the end of a list. + ## Additional Language Notes 1. Ordering diff --git a/lang-guide/chapters/types/basic_types/float.md b/lang-guide/chapters/types/basic_types/float.md index ab5e3f6f906..ffedf9396e4 100644 --- a/lang-guide/chapters/types/basic_types/float.md +++ b/lang-guide/chapters/types/basic_types/float.md @@ -28,4 +28,31 @@ - `into int` truncates the fractional part. Use `math round`, `math floor` or `math ceil` to round instead. - +## Infinity and NaN + +The words `inf` and `NaN` are float literals for infinity and "not a number". Write `-inf` for negative infinity. `nan` is accepted as another spelling of `NaN`, and Nushell prints it as `NaN`. No other spelling is a float. `Nan`, `Inf` and `infinity` are bare-word strings: + +```nu +[inf -inf nan NaN Nan Inf infinity] | to nuon +# => [inf, -inf, NaN, NaN, "Nan", "Inf", "infinity"] +``` + +[`into float`](/commands/docs/into_float.md) is more lenient with text. `'infinity' | into float` returns `inf`. + +These values also come out of float arithmetic. A literal too large for a float becomes `inf` (`1e400` is `inf`), and `inf - inf` is `NaN`. Division by zero is an error, even for floats, so `1.0 / 0` and `0.0 / 0.0` fail with `nu::shell::division_by_zero` instead of returning `inf` or `NaN`. + +Comparisons follow IEEE-754. `inf == inf` is `true`, and `NaN` is not equal to anything, itself included: + +```nu +NaN == NaN +# => false +NaN in [NaN] +# => false +``` + +Other places where they behave differently from ordinary floats: + +- [`sort`](/commands/docs/sort.md) puts `NaN` after every other number: `[3 NaN 1 inf -inf] | sort` is `[-inf, 1, 3, inf, NaN]`. +- [`to nuon`](/commands/docs/to_nuon.md) writes `inf`, `-inf` and `NaN`, which `from nuon` reads back as floats. JSON has no such values, so [`to json`](/commands/docs/to_json.md) writes each of them as `null`. +- Converting to an int doesn't fail. `inf | into int` is the largest int, `9223372036854775807`, and `NaN | into int` is `0`. `math floor` and `math ceil` do the same, while `math round` rejects them with "cannot round non-finite number". +- A range can't start at `inf`, `-inf` or `NaN`. See [Range](range.md#range-errors). diff --git a/lang-guide/chapters/types/basic_types/glob.md b/lang-guide/chapters/types/basic_types/glob.md index eb95a90d145..19ed61b860c 100644 --- a/lang-guide/chapters/types/basic_types/glob.md +++ b/lang-guide/chapters/types/basic_types/glob.md @@ -29,6 +29,17 @@ open '*.txt' # it's quoted, opens a file named `*.txt` ``` + - It will interpret an interpolated string as a glob when the string has at least one `( )` part. This holds for `$"..."`, `$'...'` and [bare-word interpolation](/book/working_with_strings.md#interpolation-in-bare-words). An interpolated string with nothing to interpolate is a plain string: + + ```nu + let prefix = "a" + ls $"($prefix)*.txt" # lists the files that start with `a` and end in `.txt` + ls ($prefix)*.txt # the same + ls $"a*.txt" # no `( )`, so it looks for a file named `a*.txt` + ``` + + The glob comes from writing the interpolation as the argument. If you store it in a variable first, the variable holds a string, so use `into glob` or a `glob` annotation. + 1. There is no literal syntax for a glob. As seen above, it is usually created as a string and then interpreted by the calling command as a glob. Example @@ -74,6 +85,8 @@ ^cat *.txt | lines ``` + For an interpolated argument, only a bare word that doesn't start with `(` is expanded. `^echo *($prefix)*` passes the matching file names, while `^echo $"*($prefix)*"` and `^echo ($prefix)*` pass the text as written. + 1. As with most other types, globs can be saved in a variable, passed to custom commands and returned from custom commands. 1. You can use `into glob` and `into string` to convert values between `glob` and `string`. diff --git a/lang-guide/chapters/types/basic_types/list.md b/lang-guide/chapters/types/basic_types/list.md index d42b30aa969..bf7787c921c 100644 --- a/lang-guide/chapters/types/basic_types/list.md +++ b/lang-guide/chapters/types/basic_types/list.md @@ -51,6 +51,45 @@ List syntax is very similar to that of arrays in JSON. However, commas are _not_ # => ╰───┴─────╯ ``` +Extra commas are ignored, so a trailing comma (`[1, 2,]`) or a doubled one (`[1,,2]`) still gives `[1, 2]`. A semicolon is not a separator: + +```nu +[1; 2] +# => Error: nu::parser::error +# => +# => × Unexpected semicolon in list +# => ╭─[repl_entry #1:1:3] +# => 1 │ [1; 2] +# => · ┬ +# => · ╰── not a valid list separator +# => ╰──── +# => help: Use commas or whitespace to separate list items. +``` + +### Expressions in a list literal + +Because whitespace separates the items, a list literal doesn't evaluate operators or pipelines. Each word is its own item, so `[1 + 1]` is a list of three values: + +```nu +[1 + 1] +# => ╭───┬───╮ +# => │ 0 │ 1 │ +# => │ 1 │ + │ +# => │ 2 │ 1 │ +# => ╰───┴───╯ +``` + +Put an expression in parentheses to make it one item: + +```nu +[(1 + 1)] +# => ╭───┬───╮ +# => │ 0 │ 2 │ +# => ╰───┴───╯ +``` + +Variables and cell paths (`$x`, `$row.name`) work without parentheses. The same rule applies to [record literals](record.md#expressions-in-a-record-literal). + ## Additional Language Notes 1. A list is like a vector or array list in other languages. diff --git a/lang-guide/chapters/types/basic_types/range.md b/lang-guide/chapters/types/basic_types/range.md index 6801ebdfbb5..02da5f89f30 100644 --- a/lang-guide/chapters/types/basic_types/range.md +++ b/lang-guide/chapters/types/basic_types/range.md @@ -27,6 +27,15 @@ # => ╰───┴───╯ ``` + `..=` spells the inclusive form out, as Rust does. `1..=5` is the same range as `1..5`. The `=` goes only on the last `..`, so `1..3..=9` and `..=3` are ranges, but `1..=3..9` is not. Nushell reads that word as the name of an external command. + + ```nu + (1..=5) == (1..5) + # => true + 1..3..=9 | each {} | to nuon + # => [1, 3, 5, 7, 9] + ``` + 1. In many programming languages, the _step_ (or interval) is specified. Nushell's range is inspired by more functional languages, where the second value is literally the second value that should be generated. The step is then automatically calculated as the distance between the first and second values. Example - Values from 1 to 10, striding with 2 (only odds): @@ -73,6 +82,30 @@ Note: Parentheses (subexpressions) are not required in this example; they are simply used for readability. + If any of the values is a float, the whole range is a float range. `1..2.5` starts at `1.0`: + + ```nu + 1..2.5 | each {} | to nuon + # => [1.0, 2.0] + ``` + +1. The start, second and end values must be numbers. A range of strings or dates is a parse error: + + ```nu + ("a")..("z") + # => Error: nu::parser::operator_unsupported_type + # => + # => × The '..' operator does not work on values of type 'string'. + # => ╭─[repl_entry #1:1:1] + # => 1 │ ("a")..("z") + # => · ──┬───┬ + # => · │ ╰── does not support 'string' + # => · ╰── string + # => ╰──── + ``` + + Without the parentheses, `'a'..'z'` isn't a range at all. A quoted word runs to its last quote, so it is the single string `a'..'z` (see [Quotes inside a quoted word](/book/working_with_strings.md#quotes-inside-a-quoted-word)). For a sequence of letters, use [`seq char`](/commands/docs/seq_char.md), and for dates use [`seq date`](/commands/docs/seq_date.md). + 1. When no second value is given, the step is `1` (or `-1` when counting down). The exception is a float range whose start and end are less than `1` apart. Its step is based on the order of magnitude of the difference: ```nu @@ -134,3 +167,26 @@ ``` A range stays a `range` when it is assigned to a variable or passed through `collect`. Most filter commands, such as `each`, `take` and `append`, produce a list from it. + +## Range errors + +Some ranges parse but can't produce any values. Nushell reports them when the range is evaluated, not when it is parsed, so a bad range inside an `if` branch that never runs causes no error. Each one fails with the same error, which underlines either the value at fault or the whole range: + +```nu +1..1..5 +# => Error: nu::shell::range_to_countable +# => +# => × Can't convert range to countable values +# => ╭─[repl_entry #1:1:4] +# => 1 │ 1..1..5 +# => · ┬ +# => · ╰── can't convert to countable values +# => ╰──── +``` + +These ranges fail: + +- The second value equals the start, as in `1..1..5`. The step would be zero. +- The second value is on the other side of the start from the end, as in `1..2..-5` or `5..1..10`. Counting would never reach the end. +- A float range has equal start and end and no second value, as in `1.0..1.0` or `1..1.0`. An int range with equal bounds is fine: `1..1` yields `[1]`. +- A float range starts at `inf`, `-inf` or `NaN` (`inf..5`), has a second value that isn't finite (`1..inf..5`), or ends at `NaN` (`1..2..NaN`). An end of `inf` is allowed and makes an endless range, like `1..`. diff --git a/lang-guide/chapters/types/basic_types/record.md b/lang-guide/chapters/types/basic_types/record.md index fe18d13540a..6e93ba22d7f 100644 --- a/lang-guide/chapters/types/basic_types/record.md +++ b/lang-guide/chapters/types/basic_types/record.md @@ -62,6 +62,47 @@ Record syntax is very similar to objects in JSON. However, commas are _not_ requ # => ╰──────┴─────╯ ``` +As in lists, extra commas are ignored: `{a: 1,, b: 2,}` is `{a: 1, b: 2}`. + +## Expressions in a record literal + +A field's value is a single word, just like a [list item](list.md#expressions-in-a-list-literal). In `{a: 1 + 1}`, the value of `a` is `1`, and Nushell then reads `+` as the next key: + +```nu +{a: 1 + 1} +# => Error: nu::parser::error +# => +# => × Expected `:` after record key +# => ╭─[repl_entry #1:1:9] +# => 1 │ {a: 1 + 1} +# => · ┬ +# => · ╰── expected `:`, found `1` +# => ╰──── +# => help: Record fields look like `key: value`. A missing colon often causes +# => this field to be parsed as a block or closure. +``` + +Wrap the expression in parentheses: + +```nu +{a: (1 + 1)} +# => ╭───┬───╮ +# => │ a │ 2 │ +# => ╰───┴───╯ +``` + +## No field shorthand + +JavaScript lets you write `{a}` for `{a: a}`. Nushell has no such shorthand, and every field needs a key and a colon. Braces holding only a variable, such as `{$a}`, are a closure that returns `$a`: + +```nu +let a = 1 +{$a} | describe +# => closure +``` + +When the braces also hold a real field, the missing colon is an error. `{a: 1, b}` and `{a: 1, $b}` both fail with "Incomplete record field". Write the key out instead: `{a: $a, b: $b}`. + ## Common commands that can be used with `record` Since the record data type is foundational to Nushell's structured nature, many commands use records as inputs or as parameters. See the list of commands for tables as many of those also take records. diff --git a/lang-guide/chapters/types/type_signatures.md b/lang-guide/chapters/types/type_signatures.md index 1162a39e98f..e8008d00c84 100644 --- a/lang-guide/chapters/types/type_signatures.md +++ b/lang-guide/chapters/types/type_signatures.md @@ -65,6 +65,59 @@ There are 3 forms of valid type signatures in Nu: Any of these can be given a name with a [type alias](#type-aliases). +## Which values a type accepts + +An annotation accepts values of its own type and of its subtypes. These are the subtype rules: + +- `any` accepts every value. +- `number` accepts `int` and `float` values. +- `glob` accepts a `string`, but `string` doesn't accept a `glob`. Convert it with `into string` first. +- `cell-path` accepts a `string` or an `int`, which is why `get $key` works with a plain string or int variable. +- `list` accepts any list whose item type `T` accepts, so a `list` can be passed where a `list` is expected. A plain `list` accepts every list. +- `record` accepts any record with a field `a` that `T` accepts. The record may have other fields too. A plain `record` accepts every record. +- `table` follows the same rule for columns. A table is also accepted as a `list>` with the same columns, and the other way around. +- `oneof` accepts whatever `A` or `B` accepts. + +For example, a command that needs a `name` field takes any record that has one: + +```nu +def name-of [r: record] { $r.name } +name-of {name: "nu", stars: 30} +# => nu +``` + +A record without that field is rejected when the call is parsed: + +```nu +def name-of [r: record] { $r.name }; name-of {title: "nu"} +# => Error: nu::parser::type_mismatch +# => +# => × Type mismatch. +# => ╭─[repl_entry #1:1:60] +# => 1 │ def name-of [r: record] { $r.name }; name-of {title: "nu"} +# => · ──────┬────── +# => · ╰── expected record, found record +# => ╰──── +``` + +The parser can only reject a value whose type it knows can't fit. When the known type is wider than the annotation, as with a variable declared `any` or `number`, the parser lets it through and the value itself is checked when the command runs. A `number` that holds `2` can be passed to an `int` parameter, but one that holds `1.5` fails: + +```nu +def double [x: int] { $x * 2 }; let y: number = 1.5; double $y +# => Error: nu::shell::cant_convert +# => +# => × Can't convert to int. +# => ╭─[repl_entry #1:1:61] +# => 1 │ def double [x: int] { $x * 2 }; let y: number = 1.5; double $y +# => · ─┬ +# => · ╰── can't convert float to int +# => ╰──── +``` + +`glob` to `string` is different. A `glob` is never a `string`, so passing a `glob` variable to a `string` parameter is a parse error ("expected string, found glob"). + +Custom values, such as a `semver` from `into semver` or a value from a plugin, also pass the parser when the parameter is a `list`, `record` or `table`, and are checked when the command runs. A `semver` doesn't fit any of these, so `def f [r: record] { $r }; f ('1.2.3' | into semver)` fails at runtime with "can't convert semver to record". + ## Type aliases `type Name = ` gives a type signature a name. The name can then be used wherever a type signature can: parameters, flags, rest parameters, closure parameters, input/output types, `let`/`mut`/`const` annotations, inside other types, and on the right-hand side of another `type`: From d6cf32c08555cf43768f0765a7f76a04592dc735 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 16:31:47 -0600 Subject: [PATCH 03/46] Document environment and startup features that had no docs Covers the rows rated `none` in the coverage checklist for environment variables, the nu executable, and startup: - special_variables: COLUMNS/LINES, proxy variables and NO_PROXY, LC_ALL/LC_TIME/LANG, NU_BACKTRACE, NU_EXPERIMENTAL_OPTIONS, NU_VENDOR_AUTOLOAD_DIR, NUSHELL_SHELLS and friends, PATHEXT, PWD, SSH_CLIENT, TERM_PROGRAM, XDG_CACHE_HOME - environment: the automatic PWD, FILE_PWD, and CURRENT_FILE variables and the error when you try to set or hide them - configuration: $env.config validation errors, flag syntax for nu, starting the REPL without a terminal, errors and broken symlinks in startup files, and experimental options Windows-only PATHEXT behavior and the build-time vendor autoload setting were written from the 0.117.0 source; the rest was run. --- book/configuration.md | 195 ++++++++++++++++++++++++++++++++++++++ book/environment.md | 28 +++++- book/special_variables.md | 132 +++++++++++++++++++++++++- 3 files changed, 351 insertions(+), 4 deletions(-) diff --git a/book/configuration.md b/book/configuration.md index 794caef496b..048b6a268b9 100644 --- a/book/configuration.md +++ b/book/configuration.md @@ -363,6 +363,70 @@ $env.config.history = { The history settings `file_format`, `max_size`, `isolation`, and `path` are read once, when the REPL starts. Set them in `config.nu`; changing them afterwards (for example, at the prompt) raises a `nu::shell::config_option_locked_after_startup` error. ::: +#### Errors in settings + +Nushell checks every value you assign to `$env.config`. When something is wrong, the assignment raises a `nu::shell::invalid_config` error that lists each problem with its own code: + +- `nu::shell::unknown_config_option` for a key Nushell doesn't know, often a typo. +- `nu::shell::invalid_value` for a value outside the accepted set. The label lists the values it accepts. +- `nu::shell::type_mismatch` for a value of the wrong type. +- `nu::shell::missing_required_column` for a record without a key it needs, such as `table.trim` without `methodology`. + +Other errors can appear in the list too. For example, a keybinding without an `event` gives `nu::shell::column_not_found`. The history lock error above is reported the same way. + +A setting with an error keeps its old value, and the other settings in the same assignment still change: + +```nu +$env.config.completions = { case_sensitive: true, algorithm: "fast", partal: false } +# => Error: nu::shell::invalid_config +# => +# => × Encountered 2 error(s) when updating config +# => +# => Error: nu::shell::invalid_value +# => +# => × Invalid value for $env.config.completions.algorithm +# => ╭─[repl_entry #1:1:62] +# => 1 │ $env.config.completions = { case_sensitive: true, algorithm: "fast", partal: false } +# => · ───┬── +# => · ╰── expected 'prefix' or 'fuzzy' or 'substring', but got 'fast' +# => ╰──── +# => +# => Error: nu::shell::unknown_config_option +# => +# => × Unknown config option: $env.config.completions.partal +# => ╭─[repl_entry #1:1:78] +# => 1 │ $env.config.completions = { case_sensitive: true, algorithm: "fast", partal: false } +# => · ──┬── +# => · ╰── remove this +# => ╰──── +$env.config.completions.case_sensitive +# => true +``` + +The error stops the rest of the script, or the rest of `config.nu`, like any other error, unless you catch it with [`try`](/commands/docs/try.md). See [Problems with startup files](#problems-with-startup-files) for how startup continues after an error in `config.nu`. + +A common mistake is leaving out the colons in a record. `{ mode light }` is a closure, not a record, and the error says so: + +```nu +$env.config.table = { mode light } +# => Error: nu::shell::invalid_config +# => +# => × Encountered 1 error(s) when updating config +# => +# => Error: nu::shell::type_mismatch +# => +# => × Type mismatch at $env.config.table +# => ╭─[repl_entry #1:1:21] +# => 1 │ $env.config.table = { mode light } +# => · ───────┬────── +# => · ╰── expected record, but got closure +# => ╰──── +# => help: If you meant a record, use `key: value` fields (colon required). A +# => missing `:` makes `{ … }` parse as a closure/block. +``` + +A few combinations only produce a warning (`nu::shell::incompatible_options`), and the value is still set. For example, setting `history.isolation = true` in `config.nu` while history uses the plain-text format warns that isolation needs SQLite history. + ### Remove Welcome Message :::note @@ -433,6 +497,12 @@ The variables that affect Nushell file locations are: - `$env.XDG_DATA_DIRS` _(Unix Platforms Only)_: If this environment variable is set, it is used to populate the `$nu.vendor-autoload-dirs` directories. Following the XDG convention that earlier entries take precedence, the directories are processed in _reverse_ order: the first directory in `XDG_DATA_DIRS` is read last, giving it the ability to override definitions from the others. +- `$env.XDG_CACHE_HOME`: If this environment variable is set to an absolute path, Nushell sets the `$nu.cache-dir` constant to `($env.XDG_CACHE_HOME)/nushell`. Otherwise `$nu.cache-dir` is the `nushell` directory under the platform's cache directory, such as `~/Library/Caches/nushell` on macOS, `~/.cache/nushell` on Linux, or `%LOCALAPPDATA%\nushell` on Windows. A relative or empty value is ignored. Nushell doesn't store anything in this directory or create it. It is a standard place for your scripts and plugins to keep data they can rebuild. + +- `$env.NU_VENDOR_AUTOLOAD_DIR`: If this environment variable is set to an absolute path, Nushell adds that directory to the end of `$nu.vendor-autoload-dirs`, after the `$nu.data-dir` one, so its files load last among the vendor files and can override the others. Unlike the other entries, the path is used as given, without `nushell/vendor/autoload` appended. A relative path is ignored, and a directory already in the list isn't added twice. + + Packagers can also set `NU_VENDOR_AUTOLOAD_DIR` when they build Nushell. The value is compiled into `nu` and placed just before the `$nu.data-dir` entry. The build-time and runtime values can be used together. + ::: warning The `XDG_*` variables are **not** Nushell-specific and should not be set to a directory with only Nushell files. Instead, set the environment variable to the directory _above_ the one with the `nushell` directory. @@ -755,3 +825,128 @@ The following stages and their steps _may_ occur during startup, based on the fl - ❌ Does not enter the REPL - ❌ Does not source the files in `vendor-autoload-dirs` - ❌ Does not source the files in `user-autoload-dirs` + +### Passing flags to `nu` + +`nu` reads its flags in the usual Unix styles: + +- A long flag takes its value after a space or after `=`, as in `--table-mode light` or `--table-mode=light`. +- A short flag works the same way, as in `-m light` or `-m=light`. Writing the value right after the letter, as in `-mlight`, is an error. +- Short flags can share one `-`, so `-nl` means `-n -l`. Only the last letter of such a group can be a flag that takes a value. `nu -nc 'ls'` works, and `nu -cn 'ls'` is an error: + + ```nu + nu -cn 'ls' + # => Error: nu::shell::error + # => + # => × `-c` expects a value + # => help: Move `-c` to the end, then pass a value like `-c ` or + # => `-c=`. + ``` + +- A value after `=` on a flag that doesn't take one, as in `-n=1`, is an error, and so is an empty value, as in `-c=`. A `-` on its own is an error too. + +When a flag is unknown, `nu` suggests a flag with a similar name if it finds one: + +```nu +nu --no-config +# => Error: nu::shell::error +# => +# => × Unknown flag '--no-config' +# => help: Did you mean '--no-config-file'? +``` + +Flags that accept a fixed set of values, such as `--table-mode`, `--error-style`, `--log-level`, and `--experimental-options`, check the value the same way. A misspelled value gets a suggestion, so `--table-mode rouned` suggests `rounded`, and a value that is not close to any valid one gets the list of valid values. Any of these errors stops `nu` with exit status 1 before it runs anything. + +### Starting the REPL without a terminal + +The REPL needs a terminal to read from. When `nu` would start the REPL, because neither `-c` nor a script file was given, and its standard input isn't a terminal, it prints an error and exits with status 1: + +```nu +"ls" | nu +# => Error: × Nushell launched as a REPL, but STDIN is not a TTY; either launch in a +# => │ valid terminal or provide arguments to invoke a script! +``` + +The same happens when a program starts Nushell as a login shell with no command and no terminal. The check comes right before the line editor starts, after `env.nu`, `config.nu`, the autoload files, and any `--execute` commands have run, so their output appears before the error. `--stdin` doesn't change this. To run Nushell code from another program, pass it with `-c` or in a script file, and add `--stdin` if that code should read the piped input as `$in`. + +### Problems with startup files + +In the REPL, an error in `env.nu`, `config.nu`, `login.nu`, or an autoload file is printed, and startup goes on with the next file. A runtime error stops the rest of that file, but changes made before the error stay in effect. Commands that the file defines with `def` are available even when their definitions come after the error, because Nushell defines them when it parses the file. A parse error means none of the file runs. + +With `-c` or a script file, the configuration files Nushell loads are strict. If one fails, `nu` stops before running the command or script and exits with that file's exit status, which is 1 for a Nushell error or the external command's own status. This covers the files given with `--env-config` and `--config`, and the default `env.nu` and `config.nu` that `-l` loads together with `-c`. `login.nu` is the exception. When it fails under `nu -l -c`, Nushell prints the error and still runs the command. + +A path given with `--config` or `--env-config` that doesn't exist is an error: + +```nu +nu --config missing.nu -c 'ls' +# => Error: File not found: missing.nu (config.nu) +# => help: Check the path passed to --config / --env-config, or create the file under your config directory. +``` + +With `-c` or a script file, `nu` then exits with status 1. The REPL prints the same error, with the full path, and starts without that file. + +If Nushell itself panics while it loads the startup files for the REPL, it prints `A panic occurred while reading configuration files, using default configuration.`, resets `$env.config` to the defaults, and starts the REPL. + +#### Broken symlinks + +If you keep your configuration in another place, such as a dotfiles repository, and link to it, a broken link doesn't stop Nushell from starting. When the configuration directory, `env.nu`, `config.nu`, or `login.nu` is a symbolic link whose target doesn't exist, Nushell skips that file, keeps the built-in defaults, and prints a warning in the form `Warning: config.nu is a broken symlink ( -> ); using built-in defaults.` For a broken configuration directory, the warning reads `config directory is a broken symlink`, and both `env.nu` and `config.nu` are skipped. Nushell never removes or replaces the link, and on first launch it doesn't create a configuration directory or default files in its place. A `--config` or `--env-config` path that is a broken link counts as a missing file and gets the `File not found` error above. + +### Experimental options + +Nushell ships some features as experimental options. An `opt-in` option is off until you turn it on, and an `opt-out` option is on until you turn it off. [`debug experimental-options`](/commands/docs/debug_experimental-options.md) lists them with their current state and a description: + +```nu +debug experimental-options | select identifier enabled status +# => ╭───┬─────────────────────────────┬─────────┬────────────────────╮ +# => │ # │ identifier │ enabled │ status │ +# => ├───┼─────────────────────────────┼─────────┼────────────────────┤ +# => │ 0 │ example │ false │ deprecated-discard │ +# => │ 1 │ dc-glob │ false │ opt-in │ +# => │ 2 │ reorder-cell-paths │ true │ opt-out │ +# => │ 3 │ pipefail │ true │ opt-out │ +# => │ 4 │ enforce-runtime-annotations │ true │ opt-out │ +# => │ 5 │ native-clip │ false │ opt-in │ +# => │ 6 │ cell-path-types │ false │ opt-in │ +# => ╰───┴─────────────────────────────┴─────────┴────────────────────╯ +``` + +You can set them when Nushell starts, with the `--experimental-options` flag or the `NU_EXPERIMENTAL_OPTIONS` environment variable. Each entry is an option name, which turns the option on, or `name=true` or `name=false`. A bare `all` turns on every option that isn't deprecated. The variable also accepts `all=false`, which turns all of them off, but the flag accepts only a bare `all`. The variable holds a comma-separated list: + +```nu +NU_EXPERIMENTAL_OPTIONS='native-clip,pipefail=false' nu +``` + +Nushell reads `NU_EXPERIMENTAL_OPTIONS` once, before any configuration file, so it has to be in the environment that starts `nu`. Setting it in `config.nu` has no effect on that session. When both are given, the flag is applied after the variable, so the flag wins for an option that both name. + +Problems in the variable are warnings, not errors. Nushell reports an unknown name or a value other than `true` or `false`, skips that entry, and starts anyway: + +```nu +NU_EXPERIMENTAL_OPTIONS='native-clp,pipefail=nope' nu +# => Warning: nu::experimental_option::unknown +# => +# => ⚠ Unknown experimental option `native-clp` +# => ╭──── +# => 1 │ NU_EXPERIMENTAL_OPTIONS=native-clp,pipefail=nope +# => · ────────── +# => ╰──── +# => help: Known experimental options are: example, dc-glob, reorder-cell-paths, +# => pipefail, enforce-runtime-annotations, native-clip, cell-path-types +# => +# => Warning: nu::experimental_option::invalid_assignment +# => +# => ⚠ Invalid assignment for `pipefail`, expected `true` or `false`, got `nope` +# => ╭──── +# => 1 │ NU_EXPERIMENTAL_OPTIONS=native-clp,pipefail=nope +# => · ───────────── +# => ╰──── +``` + +Naming a deprecated option also prints a warning. For a `deprecated-discard` option, the warning says it will be removed. For a `deprecated-default` option, it says the behavior is now the default and that you can remove the option. + +The variable follows the same rule as your configuration files. Nushell ignores it, while still applying `--experimental-options`, in these cases: + +- with `-n` or `--no-config-file` +- with `-c`, unless `-l`, `--config`, or `--env-config` is also given +- with a script file, unless `--config` or `--env-config` is also given, since `-l` doesn't load configuration files for a script + +The REPL always reads it, unless `-n` is given. diff --git a/book/environment.md b/book/environment.md index 96aeafb84e7..b1130bb1271 100644 --- a/book/environment.md +++ b/book/environment.md @@ -158,7 +158,33 @@ See also: [Changing the Environment in a Custom Command](./custom_commands.html# ## Changing the Directory -A common task in a shell is to change the directory using the [`cd`](/commands/docs/cd.md) command. In Nushell, calling [`cd`](/commands/docs/cd.md) is equivalent to setting the `PWD` environment variable. Therefore, it follows the same rules as other environment variables (for example, scoping). +A common task in a shell is to change the directory using the [`cd`](/commands/docs/cd.md) command. In Nushell, [`cd`](/commands/docs/cd.md) works by changing the `PWD` environment variable. Therefore, it follows the same rules as other environment variables (for example, scoping). You can't assign `PWD` yourself, though. Use `cd` instead. + +## Automatic variables + +Nushell sets three environment variables itself: + +- `PWD` holds the current directory. [`cd`](/commands/docs/cd.md) changes it. +- `FILE_PWD` holds the directory of the script, module, or sourced file that is running. +- `CURRENT_FILE` holds the full path of that file. + +Nushell rejects every attempt to set or hide one of them, whether through `$env.PWD = ...`, [`load-env`](/commands/docs/load-env.md), [`with-env`](/commands/docs/with-env.md), a `PWD=... cmd` prefix, or [`hide-env`](/commands/docs/hide-env.md). The check ignores case, so `$env.pwd = ...` fails as well: + +```nu +$env.PWD = '/tmp' +# => Error: nu::compile::automatic_env_var_set_manually +# => +# => × 'PWD' cannot be changed manually. +# => ╭─[repl_entry #1:1:1] +# => 1 │ $env.PWD = '/tmp' +# => · ────┬─── +# => · ╰── cannot change 'PWD' manually +# => ╰──── +# => help: The environment variable 'PWD' is set automatically by Nushell and +# => cannot be changed manually. +``` + +An assignment like this one fails before anything runs, with a `nu::compile` error. The commands fail when they run, with `nu::shell::automatic_env_var_set_manually`. To get the file's path or directory as a constant at parse time, use [`path self`](/commands/docs/path_self.md). ## Single-use Environment Variables diff --git a/book/special_variables.md b/book/special_variables.md index 437c3a15639..c01f2c39195 100644 --- a/book/special_variables.md +++ b/book/special_variables.md @@ -64,6 +64,12 @@ There are also several environment variables that Nushell uses for specific purp The amount of time in milliseconds that the previous command took to run. +### `$env.COLUMNS` and `$env.LINES` + +On Unix, Nushell asks the terminal for its size. When there is no terminal at all, as in a cron job or a CI runner with no controlling terminal, it reads the width from `COLUMNS` and the height from `LINES` instead. Both must be set to whole numbers greater than zero, or Nushell falls back to 80 columns by 24 rows. The width decides where [`table`](/commands/docs/table.md), [`grid`](/commands/docs/grid.md), and `help` output wrap. The height decides when `$env.config.footer_mode = "auto"` shows a table footer. [`term size`](/commands/docs/term_size.md) reports both values. + +A terminal that is attached always wins, even when the output is redirected to a file or a pipe. Nushell reads `COLUMNS` and `LINES` from the environment it was started with, so set them before starting `nu`. Assigning `$env.COLUMNS` inside Nushell has no effect. Windows doesn't use these variables. + ### `$env.config` `$env.config` is the main configuration record used in Nushell. Settings are documented in `config nu --doc`. @@ -72,6 +78,7 @@ The amount of time in milliseconds that the previous command took to run. Inside a script, module, or sourced-file, this variable holds the fully-qualified filename. Note that this information is also available as a constant through the [`path self`](/commands/docs/path_self.md) command. +Nushell sets it, so it can't be assigned or hidden. See [Automatic variables](./environment.md#automatic-variables). ### `$env.ENV_CONVERSIONS` @@ -86,6 +93,28 @@ the file resides. Note that this value is also available as a constant, using [` const this_dir = path self | path dirname ``` +Like `CURRENT_FILE`, it can't be assigned or hidden. + +### `$env.HTTP_PROXY` and other proxy variables + +The [`http`](/commands/docs/http.md) commands send their requests through a proxy when `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY` is set. Nushell takes the first of the three that is set, in that order, and uses it for every request, whether the URL starts with `http://` or `https://`. So with both `HTTP_PROXY` and `HTTPS_PROXY` set, HTTPS requests also go through `HTTP_PROXY`. Like every name in `$env`, these ignore case, so `http_proxy` and `HTTP_PROXY` are the same variable. + +The value is the proxy's URL, such as `http://proxy.example.com:8080`. The scheme can be `http`, `https`, `socks4`, `socks4a`, `socks5`, `socks`, or `socks5h`, and a value without one is treated as `http`. A user name and password in the URL (`http://user:password@proxy.example.com:8080`) are sent to the proxy. If Nushell can't use the value as a proxy URL, for example `ftp://proxy.example.com`, it ignores it and connects directly. + +`NO_PROXY` lists hosts that skip the proxy, separated by commas. Each entry is one of: + +- an exact host name or IP address, such as `localhost` or `127.0.0.1` +- a domain suffix starting with `.` or `*`, such as `.example.com` or `*.example.com` +- a prefix ending with `.` or `*`, such as `10.0.` or `192.168.*` +- `*`, which matches every host + +Entries match the host name only. An entry with a port, such as `localhost:8080`, never matches. + +Nushell reads these variables from `$env` each time an `http` command runs, so setting them in `config.nu`, at the prompt, or for a single command with [`with-env`](/commands/docs/with-env.md) works. Two cases behave differently: + +- Hiding an inherited proxy variable with `hide-env` doesn't turn the proxy off. With no proxy variable in `$env`, the HTTP library falls back to the environment Nushell was started with. To skip an inherited proxy, set `$env.NO_PROXY = "*"` and leave the proxy variable alone. +- The shared client that `--pool` uses is created on the first `--pool` request and keeps that proxy for the rest of the session. It ignores `NO_PROXY` until you rebuild it with [`http pool`](/commands/docs/http_pool.md). + ### `$env.LAST_EXIT_CODE` The exit code of the last command, usually used for external commands — Equivalent to `$?` from POSIX. If several external commands in a pipeline fail, it holds the exit code of the rightmost one that failed (see [Pipelines - Failing External Commands in a Pipeline](./pipelines.md#failing-external-commands-in-a-pipeline)). Note that this information is also made available to the `catch` block in a `try` expression for external commands. For instance: @@ -104,6 +133,69 @@ try { # => 2 ``` +### `$env.LC_ALL`, `$env.LC_TIME`, and `$env.LANG` + +These standard locale variables set the language and the local formats for dates. Nushell uses the first one that is set, in the order `LC_ALL`, `LC_TIME`, `LANG`, and drops an encoding suffix such as `.UTF-8`. When none is set, it uses the operating system's locale. A locale Nushell doesn't know falls back to `en_US`. + +[`format date`](/commands/docs/format_date.md) uses the locale for day and month names and for the `%x`, `%X`, `%c`, and `%r` formats. It reads the variables from `$env`, so `with-env` or an assignment changes the result. On a system with an `en_US` locale: + +```nu +let d = 2026-03-01T14:30:00 +$d | format date "%A %d %B %Y, %X" +# => Sunday 01 March 2026, 02:30:00 PM +with-env { LC_TIME: de_DE.UTF-8 } { $d | format date "%A %d %B %Y, %X" } +# => Sonntag 01 März 2026, 14:30:00 +``` + +The `datetime_format` settings in `$env.config`, which control how Nushell displays dates, work differently. They read the locale from the environment Nushell was started with, so changing `$env.LC_TIME` inside Nushell doesn't change how dates are shown. Set the variable before starting `nu`: + +```nu +LC_TIME=de_DE nu -n -c '$env.config.datetime_format.normal = "%A %d %B %Y"; 2026-03-01T14:30:00' +# => Sonntag 01 März 2026 +``` + +### `$env.NU_BACKTRACE` + +When `NU_BACKTRACE` is set, an error report also shows the calls that led to the error. Each custom command or closure call that the error passed through, including a closure run with [`do`](/commands/docs/do.md), adds a `chained_error` entry labeled "error happened when running this", starting with the outermost call. The original error comes last: + +```nu +NU_BACKTRACE=1 nu -n -c 'def inner [] { error make {msg: boom} }; def outer [] { inner }; outer' +# => Error: chained_error +# => +# => × oops +# => ╭─[source:1:66] +# => 1 │ def inner [] { error make {msg: boom} }; def outer [] { inner }; outer +# => · ──┬── +# => · ╰── error happened when running this +# => ╰──── +# => +# => Error: chained_error +# => +# => × oops +# => ╭─[source:1:57] +# => 1 │ def inner [] { error make {msg: boom} }; def outer [] { inner }; outer +# => · ──┬── +# => · ╰── error happened when running this +# => ╰──── +# => +# => Error: +# => × boom +# => ╭─[source:1:27] +# => 1 │ def inner [] { error make {msg: boom} }; def outer [] { inner }; outer +# => · ─────────── +# => ╰──── +``` + +Without `NU_BACKTRACE`, the same command prints only the `boom` error. An error from a stream, such as one raised inside [`each`](/commands/docs/each.md), also gets a label at each call the stream passed through. + +Any value turns it on, including `0` and `false`. Nushell checks its global environment, which takes in your changes after each startup file and after each line you run at the prompt. So you can set `NU_BACKTRACE` before starting `nu`, in `config.nu`, or at the prompt, where it applies from the next line on. Setting it inside a script or a `nu -c` command doesn't affect that same script or command. + +The chain also changes what [`try`](/commands/docs/try.md) catches. With `NU_BACKTRACE` set, `$e.msg` in a `catch` closure is `oops`, the message of the outer entry, instead of the original message. + +### `$env.NU_EXPERIMENTAL_OPTIONS` + +A comma-separated list of experimental options to turn on or off when Nushell starts, such as `native-clip,pipefail=false`. Nushell reads it once, before any configuration file, so it has to be in the environment that starts `nu`. It is ignored with `-n`, and for `nu -c` and scripts unless they also load configuration files. See [Configuration - Experimental options](./configuration.md#experimental-options). + ### `$env.NU_LIB_DIRS` ::: tip @@ -155,22 +247,38 @@ A list of directories which will be searched when registering plugins with `plug - [Plugin Search Path](./plugins.md#plugin-search-path) +### `$env.NU_VENDOR_AUTOLOAD_DIR` + +Adds a directory to `$nu.vendor-autoload-dirs`. Packagers can also set it when building Nushell. See [Configuration - Startup Variables](./configuration.md#startup-variables). + ### `$env.NU_VERSION` The current Nushell version. The same as `(version).version`, but, as an environment variable, it is exported to and can be read by child processes. +### `$env.NUSHELL_SHELLS`, `$env.NUSHELL_CURRENT_SHELL`, and `$env.NUSHELL_LAST_SHELL` + +Leftovers from the built-in `shells` and `enter` commands of older Nushell versions. Nothing in Nushell reads them, but they can show up in `$env`. When you change directories at the prompt by typing just a path (auto-cd), the REPL writes the new directory into the `NUSHELL_SHELLS` list, at the index in `NUSHELL_CURRENT_SHELL` (`0` when it isn't set), and sets `NUSHELL_LAST_SHELL`. [`cd`](/commands/docs/cd.md) doesn't touch them. To keep a list of directories and move between them, use the [`dirs` module](./directory_stack.md). + ### `$env.PATH` The search path for executing other applications. It is initially inherited from the parent process as a string, but converted to a Nushell `list` at startup for easy access. It is converted back to a string before running a child-process. +### `$env.PATHEXT` + +On Windows, `PATHEXT` lists the file extensions that count as programs, separated by `;`, such as `.COM;.EXE;.BAT;.CMD`. Nushell uses it in two places: + +- To run an external command, Nushell looks the name up with the `PATHEXT` it inherited when it started, so `foo` finds `foo.exe` or `foo.bat` on the path. Changing `$env.PATHEXT` inside Nushell doesn't affect this lookup. When the file it finds ends in an extension other than `.COM`, `.EXE`, `.BAT`, `.CMD`, or `.PS1`, Nushell runs it through `cmd.exe /D /C`, so a file association you made with `assoc` and `ftype` applies. For example, after you associate `.nu` files with `nu.exe` and add `.NU` to `PATHEXT` before starting Nushell, typing `myscript` runs `myscript.nu`. A `.PS1` file runs with `powershell.exe -File` instead. +- [`which`](/commands/docs/which.md) reads `$env.PATHEXT`, so it follows changes you make inside Nushell, including with `with-env`. After `hide-env PATHEXT`, `which` doesn't fall back to the inherited value. + +Other platforms ignore `PATHEXT`. + ### `$env.PROCESS_PATH` -When _executing a script_, this variable represents the name and relative path of the script. Unlike the two variables -above, it is not present when sourcing a file or importing a module. +When _executing a script_, this variable represents the name and relative path of the script. Unlike `CURRENT_FILE` and `FILE_PWD`, it is not present when sourcing a file or importing a module. -Note: Also unlike the two variables above, the exact path (including symlinks) that was used to _invoke_ the file is returned. +Note: Also unlike `CURRENT_FILE` and `FILE_PWD`, the exact path (including symlinks) that was used to _invoke_ the file is returned. ### `$env.PROMPT_*` and `$env.TRANSIENT_PROMPT_*` @@ -179,11 +287,29 @@ A number of variables are available for configuring the Nushell prompt that appe - [Configuration - Prompt Configuration](./configuration.md#prompt-configuration) - `config nu --doc` +### `$env.PWD` + +The current directory, as an absolute path. [`cd`](/commands/docs/cd.md) changes it, and the change follows the same scoping rules as other environment variables. Nushell sets `PWD`, `FILE_PWD`, and `CURRENT_FILE` itself, so assigning or hiding them is an error. See [Automatic variables](./environment.md#automatic-variables). + ### `$env.SHLVL` `SHLVL` is incremented by most shells when entering a new subshell. It can be used to determine the number of nested shells. For instance, if `$env.SHLVL == 2` then typing `exit` should return you to a parent shell. +### `$env.SSH_CLIENT` + +SSH servers set `SSH_CLIENT` in the session they start. When it is set, the file names in `ls` output are not clickable links. Normally, with `$env.config.shell_integration.osc8` on, as it is by default, Nushell writes each name as an OSC 8 hyperlink to the local path, which the terminal can open. Over SSH, those paths are on the remote machine, so Nushell leaves the links out. + +Nushell reads `SSH_CLIENT` from the environment it was started with, so assigning or hiding `$env.SSH_CLIENT` inside Nushell changes nothing. It checks only `SSH_CLIENT`, not `SSH_CONNECTION` or `SSH_TTY`. + +### `$env.TERM_PROGRAM` + +Many terminals set `TERM_PROGRAM` to their own name. Nushell looks for one value, `vscode`, which the terminal in Visual Studio Code sets. In that terminal, with `$env.config.shell_integration.osc633` on, as it is by default, the REPL marks the prompt, the command line, and each command's start and end with VS Code's OSC 633 escape sequences instead of the standard OSC 133 ones. It also sends VS Code the current directory and the text of each command it runs. With any other value, or with `osc633` turned off, the REPL sends OSC 133 marks when `$env.config.shell_integration.osc133` is on. + +### `$env.XDG_CACHE_HOME` + +Can be used to optionally override the `$nu.cache-dir` location. See [Configuration - Startup Variables](./configuration.md#startup-variables). + ### `$env.XDG_CONFIG_HOME` Can be used to optionally override the `$nu.default-config-dir` location. See [Configuration - Startup Variables](./configuration.md#startup-variables). From 3414a2ef0f0c7cb3fde7c1ef45f44dfb1e0f9f7b Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 16:32:39 -0600 Subject: [PATCH 04/46] Document tooling and plugin features that had no docs Covers the rows rated `none` in the coverage checklist for the language server, the debug adapter, explore, and plugins: - new page book/language_server.md: starting `nu --lsp`, what it loads, editor setup for VS Code and Neovim, what the client must send, and each capability with its limits (diagnostics, completion, hover, signature help, definition, highlight, references, rename, symbols, inlay hints, semantic tokens) - debugging: DAP pause and the nuDapVisualize request - explore: the :table and :expand commands and the binary (hex) viewer - plugins: the installed_plugins column of `version` and the JavaScript example plugin; contributor book: serve_plugin_io and create_plugin_signature - dataframes: cloud storage URLs and where polars reads credentials LSP and DAP behavior was checked with scripted clients against a 0.117.1-dev build and the 0.117.0 source. Cloud reads need credentials and were not run. --- .vuepress/configs/sidebar/en.ts | 1 + book/dataframes.md | 26 ++++ book/debugging.md | 4 + book/explore.md | 28 ++++ book/language_server.md | 228 ++++++++++++++++++++++++++++++++ book/plugins.md | 25 ++++ contributor-book/plugins.md | 2 + 7 files changed, 314 insertions(+) create mode 100644 book/language_server.md diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts index 820b09f5679..fec7effc5cb 100644 --- a/.vuepress/configs/sidebar/en.ts +++ b/.vuepress/configs/sidebar/en.ts @@ -65,6 +65,7 @@ export const sidebarEn: SidebarConfig = { '/book/sorting.md', '/book/testing.md', '/book/debugging.md', + '/book/language_server.md', '/book/style_guide.md', ], }, diff --git a/book/dataframes.md b/book/dataframes.md index d3fe8a975e3..0473cf0912b 100644 --- a/book/dataframes.md +++ b/book/dataframes.md @@ -258,6 +258,32 @@ If you want to see all the dataframe commands that are available you can use `scope commands | where category =~ dataframe` ::: +### Cloud Storage + +`polars open` and `polars save` also accept a URL in cloud storage in place of a file path: + +```nu +# Read a Parquet file from Amazon S3 as a lazy dataframe +polars open s3://my-bucket/sales.parquet + +# Write a dataframe to Azure Blob Storage +$df | polars save az://my-container/sales.parquet +``` + +The URL's scheme picks the provider, and each provider has its own way of finding credentials: + +| Schemes | Provider | Where the credentials come from | +| ---------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `s3://`, `s3a://` | Amazon S3 | The AWS SDK's default chain: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`, then the shared config and credentials files (with `AWS_PROFILE`), web identity, ECS, and EC2 instance metadata. Other `AWS_` variables, such as `AWS_REGION`, are read too. | +| `az://`, `azure://`, `abfs://`, `abfss://`, `adl://` | Azure | Variables whose names start with `AZURE_`, such as `AZURE_STORAGE_ACCOUNT_NAME`, `AZURE_STORAGE_ACCOUNT_KEY`, `AZURE_STORAGE_SAS_TOKEN`, or `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID`. | +| `gs://`, `gcs://` | Google Cloud Storage | `SERVICE_ACCOUNT`, the path to a service account key file, and variables whose names start with `GOOGLE_`, such as `GOOGLE_SERVICE_ACCOUNT` (which wins over `SERVICE_ACCOUNT`) and `GOOGLE_APPLICATION_CREDENTIALS`. | + +When no AWS credentials turn up, the command fails with `Could not fetch AWS credentials`, followed by each place the SDK looked. Other schemes, such as `https://` and `file://`, fail with `Could not determine a supported cloud type from path`. + +The plugin reads these variables from its own environment, which it gets from `$env` when Nushell starts it. If you set or change them while the plugin is running, run `plugin stop polars`, and the next `polars` command starts the plugin with the new values. Stopping the plugin also drops the dataframes it holds. + +Not every format works with cloud storage. `polars open` reads CSV, TSV, Parquet, Arrow, and NDJSON files from a cloud URL, always as a lazy dataframe, so `--eager` fails with `Cloud URLs are not supported with --eager`. JSON and Avro files can't be read from the cloud. `polars save` writes Parquet, Arrow, NDJSON, and CSV files to the cloud, but not Avro. + ## Basic Aggregations Let's start with basic aggregations on the dataframe. Let's sum all the columns diff --git a/book/debugging.md b/book/debugging.md index 89686df2f21..458dded6883 100644 --- a/book/debugging.md +++ b/book/debugging.md @@ -62,6 +62,8 @@ The **Runtime errors** exception filter, which is on by default, pauses the scri While the script is paused, you can continue, step over a line, step into a command call or a pipeline stage, or step out of the current command. The call stack shows the command and closure calls that led to the current line. +To stop a script that is running, use the editor's **Pause** command. The script stops at the next step it reaches, as if a breakpoint were there. While a long-running command such as [`sleep`](/commands/docs/sleep.md) or an external program is working, the script isn't at a step, so it pauses when that command finishes. + ## Inspecting Values When the script pauses, the editor's variables view shows: @@ -74,6 +76,8 @@ When the script pauses, the editor's variables view shows: Nested records, lists, and tables load one level at a time as you expand them, so a large value doesn't slow anything down until you look inside it. Streams are described, not read, so looking at one doesn't consume it. +To see a whole value at once, a client can send the debugger's own `nuDapVisualize` request, which the VS Code extension's **Visualize** action uses. Its arguments name a value from the variables view, either with the value's `variablesReference` or, for a value that doesn't expand, with the `containerReference` of the scope or value that holds it and its `name`. The response has the value as JSON in `value`, its Nushell type in `type`, and `truncated`. Lists and records stop at 1000 items, nesting stops at 8 levels, and binary data, sent as a hex string in a `$nuBinary` object, stops at 64 KiB. When any of these limits cuts the value, `truncated` is `true`. Filesizes, durations, and dates come back as strings, such as `"2.0 kB"`, `"1500000000ns"`, and `"2026-01-02T03:04:05+00:00"`. Use references from the current pause. One that the current pause doesn't have gets the error `no value for that reference (stale after resume?)`. + Watch expressions, the debug console, and hovering over a variable evaluate Nushell expressions using the paused values. They run against a copy of the script's state, so they can't change the script's variables. Output from [`print`](/commands/docs/print.md) and from external commands goes to the editor's debug console. The script has no terminal, so external commands get no standard input. diff --git a/book/explore.md b/book/explore.md index 64a045e0dfc..1e96d1d53fc 100644 --- a/book/explore.md +++ b/book/explore.md @@ -65,8 +65,36 @@ Press `/` to search forward or `?` to search backward. Results are highlighted a | `:help` | Show the help page | | `:try` | Open an interactive REPL on the current data | | `:nu ` | Run a Nushell command on the current data | +| `:table` | Open the current value in a new table view | +| `:expand`, `:e` | Show the current value with all nested data expanded | | `:q` | Exit `explore` | +`:table` and `:expand` work on the current value, which is the selected cell in cursor mode and the whole table you are looking at in view mode. Both open a new view on top of the current one, and `Esc` goes back to it. + +`:table` shows the value as a table that you can move around in, even when it is a plain value such as a string. `:expand`, which the `e` key also runs, draws the value as text, the way [`table --expand`](/commands/docs/table.md) does. Every nested list and record is drawn in full inside its cell, in the style set by `$env.config.table.mode`. + +## Viewing Binary Data + +When the input is binary data, `explore` shows a hex dump instead of a table. Each line has the offset of its first byte, the next sixteen bytes in hex, and the same bytes as characters: + +```nu +0x[48 65 6c 6c 6f 2c 20 4e 75 21 00 09 0a 7f c3 a9] | explore +# => 00000000 │ 4865 6c6c 6f2c 204e 7521 0009 0a7f c3a9 │ Hello, Nu!0__•×× +``` + +In the character column, a printable ASCII character stands for itself, `0` is a null byte, `_` is whitespace other than a space (such as a tab or a newline), `•` is any other ASCII control character, and `×` is a byte outside ASCII. + +A byte stream also opens in the hex view, even when it holds text. That includes the output of an external command and a text file read with [`open`](/commands/docs/open.md): + +```nu +^echo hi there | explore +# => 00000000 │ 6869 2074 6865 7265 0a │ hi there_ +``` + +To see the text, convert it first, for example with [`lines`](/commands/docs/lines.md) or [`decode`](/commands/docs/decode.md). `explore` reads the whole stream into memory before it shows anything. + +The hex view is simpler than the table view. You can scroll with the arrow keys, but there is no cursor mode, searching finds nothing, and `--peek` returns nothing. `q` and `Esc` don't exit. Type `:q` or press `Ctrl+C` instead. + ## Config `explore`'s colors are configured in `$env.config.explore`. Each value takes the same forms as [`color_config`](coloring_and_theming.md): a color name, a `#RRGGBB` hex code, or a `{fg, bg, attr}` record. For example: diff --git a/book/language_server.md b/book/language_server.md new file mode 100644 index 00000000000..09f4473c1d3 --- /dev/null +++ b/book/language_server.md @@ -0,0 +1,228 @@ +# Language server + +Running `nu --lsp` starts Nushell's built-in [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) server. An editor that speaks LSP uses it to underline errors as you type, complete commands and paths, show a command's help when you hover over it, jump to definitions, and rename a variable or custom command across files. The server runs Nushell's own parser on your code, so the errors it reports are the ones `nu` would report before running the script. + +The language server is part of the default build (the `lsp` [Cargo feature](./installation.md)). To step through a script while it runs, use the debugger instead (see [Debugging Scripts](./debugging.md)). + +## Starting the server + +You don't run the server by hand. The editor starts `nu --lsp` and talks to it over the process's standard input and output. No other arguments are needed. + +Before it answers the editor, the server loads the same startup files as an interactive session: the plugin registry, `env.nu`, `config.nu`, and the autoload directories. Custom commands, aliases, and modules defined there, and the commands of registered plugins, are all known to the server. It completes them, shows their help, and doesn't treat calls to them as external commands. Add `-n` (`--no-config-file`) to the arguments to start from the defaults instead. The other startup flags, such as `--config`, `--env-config`, `--plugin-config`, and `--plugins`, work with `--lsp` too. + +While the startup files run, [`$nu.is-lsp`](./special_variables.md#nu) is `true`. [`print`](/commands/docs/print.md) writes to stderr in this mode, but the output of an external command still goes to stdout, in between the protocol messages that the editor reads from there. Skip such commands when the language server starts: + +```nu +# in config.nu +if not $nu.is-lsp { + ^echo "hello from config.nu" +} +``` + +The server parses each file with the file's own directory as the current directory. Relative paths in `use` and `source`, and file path completions, start from where the file is, not from where the editor was started. + +## Editor setup + +### VS Code + +The [Nushell extension for VS Code](https://marketplace.visualstudio.com/items?itemName=TheNuProjectContributors.vscode-nushell-lang) starts `nu --lsp` for `.nu` files. + +### Neovim + +Neovim 0.11 and later can start the server with the built-in LSP client. Neovim sets the `nu` filetype for `.nu` files: + +```lua +vim.lsp.config('nushell', { + cmd = { 'nu', '--lsp' }, + filetypes = { 'nu' }, + root_markers = { '.git' }, +}) +vim.lsp.enable('nushell') +``` + +`root_markers` decides the workspace folder. Neovim looks upward from the file for one of the listed names and sends that directory to the server as the workspace folder. When nothing matches, no folder is sent, and find references and rename only see the current file. + +### Other editors + +Any editor with an LSP client can use the server. Configure it to run `nu` with the argument `--lsp` for `.nu` files, and check that it sends a workspace folder, as described in the next section. + +## What the editor sends + +The server uses standard LSP over stdin and stdout: JSON-RPC messages, each preceded by a `Content-Length` header. Editors with an LSP client handle the details, but a few of them matter when a feature doesn't work: + +- The server reads the project directories from the `workspaceFolders` field of the `initialize` request. It ignores `rootUri` and `rootPath`, so a client that only sends those gets no workspace-wide search. Later `workspace/didChangeWorkspaceFolders` notifications add and remove folders. A file belongs to a folder when the file's URI starts with the folder's URI. +- The editor sends `textDocument/didOpen`, `didChange`, and `didClose` for the files you edit. The server asks for incremental changes, so each `didChange` carries only the edited range. The server works from the text it was sent, including unsaved edits. +- The server reports the progress of workspace-wide searches with `$/progress` notifications, and sends warnings as `window/logMessage` notifications. +- The server registers no trigger characters for completion or signature help. Most editors ask for completions while you type a word, but whether signature help appears without you asking for it depends on the editor. + +An `initialize` request with one workspace folder looks like this: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "processId": null, + "capabilities": {}, + "workspaceFolders": [ + { "uri": "file:///home/me/project", "name": "project" } + ] + } +} +``` + +The response lists the features below in `capabilities`, and its `serverInfo` gives the name `Nushell` and the version of `nu`. + +## Features + +| Feature | LSP method | +| ------------------ | -------------------------------------------------------- | +| Diagnostics | `textDocument/publishDiagnostics` (sent by the server) | +| Completion | `textDocument/completion` | +| Hover | `textDocument/hover` | +| Signature help | `textDocument/signatureHelp` | +| Go to definition | `textDocument/definition` | +| Document highlight | `textDocument/documentHighlight` | +| Find references | `textDocument/references` | +| Rename | `textDocument/prepareRename`, then `textDocument/rename` | +| Document symbols | `textDocument/documentSymbol` | +| Workspace symbols | `workspace/symbol` | +| Inlay hints | `textDocument/inlayHint` | +| Semantic tokens | `textDocument/semanticTokens/full` | + +The server has no formatting or code actions. + +### Diagnostics + +Each time a file is opened or changed, the server parses it and sends the problems it found in a `textDocument/publishDiagnostics` notification. Parse errors become errors, and parse warnings, such as a call to a deprecated command, become warnings. These are the problems `nu` finds before it runs a script: syntax errors, unknown flags, missing arguments, variables that don't exist, and the type mismatches the parser can detect. Errors that only happen while a script runs aren't reported. In this file: + +```nu +ls --al +$greting +``` + +the server reports two errors, ``The `ls` command doesn't have flag `al`.`` on `--al` and `Variable not found.` on `$greting`. + +A diagnostic has only the short message, without the help text and labels that `nu` prints. A problem inside a file that this one imports with `use` or `source` is reported on this file, at its end. + +### Completion + +Completions come from the same engine as Tab completion in the REPL. They include commands, flags, file and directory paths, module names after `use`, variables, the fields of a record in a cell path, and operators. [Custom completions](./custom_completions.md) and the external completer set in `config.nu` (`$env.config.completions.external.completer`) apply as well. + +Each item has a kind, which most editors show as an icon: + +| Suggestion | Completion item kind | +| -------------------------------------- | -------------------- | +| Built-in command | Function | +| Custom command or plugin command | Method | +| Keyword, such as `let` or `def` | Keyword | +| Alias | Reference | +| External command | Interface | +| Flag | Field | +| File | File | +| Directory | Folder | +| Module | Module | +| Variable | Variable | +| Cell path member | Property | +| Operator | Operator | +| String value, such as a flag's choices | Value | + +Choosing a command inserts a snippet with a placeholder for each positional parameter. An optional parameter's placeholder ends in `?`, a rest parameter's starts with `...`, and a block parameter gets braces. The item's documentation is the command's help. Completing `str jo` returns (some fields left out): + +```json +{ + "label": "str join", + "labelDetails": { "description": "built-in" }, + "kind": 3, + "detail": "Concatenate multiple strings into a single string, with an optional separator between each.", + "insertTextFormat": 2, + "textEdit": { + "range": { + "start": { "line": 1, "character": 0 }, + "end": { "line": 1, "character": 6 } + }, + "newText": "str join ${1:separator?}" + } +} +``` + +### Hover + +What hovering shows depends on what is under the cursor: + +- A command: its help as Markdown, with the description, usage, flags, parameters, input and output types, and examples. This covers built-in, custom, and plugin commands. +- A variable: its type, and its value if it is a constant. For other variables, hover says whether the variable is `mutable` or `immutable`. +- A cell path such as `$person.name`: the type of that field, and its value when the variable is a constant. +- A module name: the module's documentation comments. +- An external command: its manual page, from `man`. On Windows, the server runs PowerShell's `help` instead. +- Any other expression, such as a literal: its type. + +### Signature help + +With the cursor among a command's arguments, signature help shows the command's usage line, such as `str join {flags} (separator)`, and describes each parameter. Positional parameters come first, in order, and the flags follow them. The active parameter is the positional parameter the cursor is on, counted by the positional arguments before it. + +### Go to definition + +Go to definition jumps to: + +- the body of a custom command +- the declaration of a variable, including command parameters and closure parameters +- the definition of a module +- the value of a field, for a cell path into a constant + +For a module that is a whole file, as in `overlay use lib.nu`, the definition is the start of that file. The definition can be in another file that the current one imports with `use` or `source`, whether or not that file is open in the editor. Built-in commands, plugin commands, and external commands have no definition to go to. Neither do commands from the [standard library](./standard_library.md), which is built into `nu`. For a standard library command, the server logs a warning and returns nothing. + +### Document highlight + +Document highlight marks every place in the current file where the variable, command, or module under the cursor appears, including its definition. + +### Find references + +Find references lists every place where the variable, command, or module under the cursor appears, including its definition. The request's `includeDeclaration` setting is ignored. + +When the file is in a workspace folder, the server searches every `.nu` file under that folder, at any depth, along with the files open in the editor. It parses only the files whose text contains the name, and reports its progress as it goes (`Finding references ...`). The search has a five-second budget. When that runs out, the server stops, logs `Workspace-wide search took too long!`, and returns the references it found so far. + +When the file isn't in a workspace folder, only the current file is searched. + +Results from other files are best-effort. A use of a command in a file that imports it with a different path can be missed, and so can the name in that file's `use` statement. + +### Rename + +Renaming takes two requests. `textDocument/prepareRename` checks what is under the cursor and starts a search for every occurrence, and `textDocument/rename` turns what that search found into edits. + +Only variables, custom commands, and modules defined in your code can be renamed. On a built-in command, or anything else without a definition, preparation fails with `Definition not found. Not allowed to rename built-ins.` On a literal or another expression, it fails with `Rename only works for variable/command.` + +The search covers the same files as find references, and reports progress as `Preparing rename ...`. It has no time limit, but any other message from the editor stops it, such as a hover request or the `didChange` that a keystroke sends. The server then logs `Workspace-wide search took too long!` and ends the progress report with `interrupted.` A rename request that arrives before the search finishes is refused with `Please wait for renaming preparation to complete.` and stops the search too. A rename after a stopped search only edits what the search found before it stopped, which can be nothing at all. Start the rename again to search every file. + +Without a workspace folder, only the current file is edited. When the command is defined in another file, its definition keeps the old name. Because cross-file results are best-effort, check the edits before you save them. + +### Symbols + +Document symbols list the custom commands, variables, and modules defined in a file, as a flat list with the commands first. Editors use them for an outline view and for jumping to a symbol. + +Workspace symbols search the symbols of the files open in the editor and of the files they import with `use` or `source`, matching the query fuzzily. The query is case-insensitive unless it has an uppercase letter. Files in the workspace folder that aren't open or imported aren't searched. + +### Inlay hints + +Inlay hints are short labels that the editor draws inside the code without changing it. The server adds: + +- the type after the name in a `let`, `mut`, or `const` declaration and after a `for` loop variable, unless the code already has a type annotation, as in `let count: int = 0`, +- the type after the variable in an assignment, such as `$count += 1`, +- the parameter name before each positional argument of a custom command defined in your code, with the parameter's type and description as a tooltip. + +Lists, records, and tables are shown as `list`, `record`, and `table`, without their element types. Parameter names aren't shown for built-in or plugin commands, for flags, or for a rest parameter. After a spread argument (`...$args`), no more parameter names are shown. For this file: + +```nu +def greet [name: string] { $"hello ($name)" } +let names = [Ada Grace] +$names | each {|n| greet $n } +``` + +an editor shows `: list` after `names`, and `name:` before `$n`. + +The server computes the hints when the file is opened or changed and always returns the hints for the whole file, whatever range the editor asks for. + +### Semantic tokens + +Most editors color Nushell code with a syntax grammar that only sees the text. Such a grammar can't know which multi-word names, such as `str join`, are a single command, so it may color the second word as an argument. Semantic tokens cover that one case. The server marks each call to a command whose name has more than one word, such as `str join`, a custom command named `git sync`, or `assert equal` from the standard library, with the token type `function`. Calls to commands whose names start with `export` or `overlay` aren't marked, and neither is anything else, so the grammar still colors the rest of the file. Only full-document requests are supported. diff --git a/book/plugins.md b/book/plugins.md index 8e92ab89fb8..844fdb091b9 100644 --- a/book/plugins.md +++ b/book/plugins.md @@ -241,6 +241,15 @@ All of the commands from installed plugins are available in the current scope: scope commands | where type == "plugin" ``` +[`version`](/commands/docs/version.md) also names the plugins, in its `installed_plugins` column. It is a single string with each plugin's name and version, separated by commas: + +```nu +version | get installed_plugins +# => polars 0.117.0, query 0.117.0 +``` + +The column lists the plugins loaded into the current session, running or not. A plugin you have only registered with `plugin add` appears after `plugin use` or a restart, and one you remove with `plugin rm` stays until the session ends. A plugin that didn't report a version is listed by its name alone. + ### Plugin Lifecycle Plugins stay running while they are in use, and are automatically stopped by default after a period of time of inactivity. This behavior is managed by the [plugin garbage collector](#plugin-garbage-collector). To manually stop a plugin, call `plugin stop` with its name: @@ -321,6 +330,22 @@ Nu's main repo contains example plugins that are useful for learning how the plu - [Rust](https://github.com/nushell/nushell/tree/main/crates/nu_plugin_example) - [Python](https://github.com/nushell/nushell/blob/main/crates/nu_plugin_python) - [Nu](https://github.com/nushell/nushell/tree/main/crates/nu_plugin_nu_example) +- [JavaScript (Node.js)](https://github.com/nushell/nushell/tree/main/crates/nu_plugin_javascript) + +The JavaScript example is a single file, `nu_plugin_node_example.js`, that speaks the JSON encoding of the protocol. Its one command, `node_example`, ignores its arguments and returns a 10-row table. The file hard-codes the Nushell version it works with in the `NUSHELL_VERSION` constant, `'0.103.1'` as shipped. During the handshake, the plugin exits unless that constant equals the version of `nu` exactly, and `nu` itself refuses a plugin that reports an incompatible version. Before you add the plugin, set the constant to your version, the value of `(version).version`. Then register the file with Node.js as the interpreter, giving `--shell` the full path to `node`: + +```nu +plugin add --shell (which node | get path.0) ./nu_plugin_node_example.js +plugin use node_example +node_example 2 "3" | first 3 +# => ╭───┬─────┬─────┬───────╮ +# => │ # │ one │ two │ three │ +# => ├───┼─────┼─────┼───────┤ +# => │ 0 │ 0 │ 0 │ 0 │ +# => │ 1 │ 1 │ 2 │ 3 │ +# => │ 2 │ 2 │ 4 │ 6 │ +# => ╰───┴─────┴─────┴───────╯ +``` ### Debugging diff --git a/contributor-book/plugins.md b/contributor-book/plugins.md index 5540936b546..bccdb5bc48e 100644 --- a/contributor-book/plugins.md +++ b/contributor-book/plugins.md @@ -141,6 +141,8 @@ fn main() { In `main()`, we just call a single function `serve_plugin`. This will do the work of calling into our plugin, handling the JSON serialization/deserialization, and sending values and errors back to Nu for us. To start it up, we pass it something that implements the `Plugin` trait and something that implements the `PluginEncoder` trait. We're given a choice of serialization formats that Nu supports. Ordinarily plugins written in Rust should use `MsgPackSerializer` as it is considerably faster, but here we select JSON to demonstrate how the communication protocol works further on in this tutorial. +`serve_plugin` reads the arguments that Nushell starts the plugin with (`--stdio`, or `--local-socket` and a socket name), tells Nushell which encoding the plugin uses, and then hands the connection to `serve_plugin_io`, which runs the protocol over any reader and writer. If two of the plugin's commands return the same `name()`, `serve_plugin_io` prints a warning to stderr when the plugin starts, and the command that comes later in `commands()` replaces the earlier one. When Nushell asks for the plugin's signatures during `plugin add`, `create_plugin_signature` builds each command's signature from its `signature()`, `description()`, `extra_description()`, `search_terms()`, and `examples()` methods. `nu-plugin` exports both functions, but they are hidden from its API documentation and aren't a public API. They exist for `nu-plugin-test-support`. In your own plugin, call `serve_plugin`, and test it with [`nu-plugin-test-support`](#testing-plugins). + Above `main()` is the implementation of the `SimplePluginCommand` trait for the `len` command that our plugin will expose, which is represented by the `Len` type. We use `SimplePluginCommand` rather than `PluginCommand` in order to simplify our implementation and avoid [handling streams](#using-streams-in-plugins). Let's take a look at how we implement this trait: ```rust From d1073adb29fb37d38f00d335b42860a21c45d9d1 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 16:35:42 -0600 Subject: [PATCH 05/46] Document definition and control flow features that had no docs Covers the rows rated `none` in the coverage checklist for custom commands, modules, scripts, and control flow: - defining a command twice in one block, duplicate parameter and flag names, and user-defined attributes - what a module body may contain, and how a submodule named `mod` is merged into its parent - `nu script.nu --help` - `else`, `catch`, and `finally` must stay on the line of the closing brace; type annotations on the `for` variable - `catch` and `finally` with a closure in a variable, `try` collecting the block's output, and re-raising a caught error with `raw` Parse errors were captured from a REPL. The code that decides each behavior is unchanged between 0.117.0 and the build used for testing. --- book/control_flow.md | 49 +++++++- book/creating_errors.md | 57 ++++++++++ book/custom_commands.md | 106 ++++++++++++++++++ book/modules/creating_modules.md | 43 +++++++ book/scripts.md | 58 ++++++++++ lang-guide/chapters/custom_commands.md | 11 ++ lang-guide/chapters/flow_control/if-else.md | 2 + lang-guide/chapters/flow_control/try-catch.md | 50 ++++++++- 8 files changed, 374 insertions(+), 2 deletions(-) diff --git a/book/control_flow.md b/book/control_flow.md index 5664791cb8f..1a9ab028959 100644 --- a/book/control_flow.md +++ b/book/control_flow.md @@ -63,6 +63,41 @@ if $x > 0 { 'positive' } else if $x == 0 { 'zero' } else { "negative" } When the first condition is `true` (`$x` is greater than zero) it will return `'positive'`, when the first condition is `false` and the next condition is `true` (`$x` equals zero) it will return `'zero'`, otherwise it will return `'negative'` (when `$x` is less than zero). +::: warning +`else` has to start on the same line as the `}` before it. A newline ends the `if` command, so Nushell runs the `if` by itself and then tries to run `else` as a separate command. The parser doesn't catch this. The script fails when it reaches the `else`, whichever branch the condition picked: + +```nu +# size.nu +def describe-size [n: int] { + if $n > 100 { + "big" + } + else { + "small" + } +} + +describe-size 5 +``` + +```nu +nu size.nu +# => Error: nu::shell::external_command +# => +# => × External command failed +# => ╭─[/home/me/size.nu:5:5] +# => 4 │ } +# => 5 │ else { +# => · ──┬─ +# => · ╰── Command `else` not found +# => 6 │ "small" +# => ╰──── +# => help: Did you mean `if`? +``` + +Write `} else {` on one line. The same rule applies to `else if` and to the `catch` and `finally` parts of [`try`](#try). Inside parentheses a newline doesn't end the command, so wrapping the whole `if` in `( )` also lets `else` start a new line (see [Multi-line pipelines](pipelines.md#multi-line-pipelines)). +::: + ### `match` [`match`](/commands/docs/match.html) executes one of several conditional branches based on the value given to match. You can also do some [pattern matching](/cookbook/pattern_matching.html) to unpack values in composite types like lists and records. @@ -268,6 +303,14 @@ for x in [1 2 3] { $x * $x | print } # => 9 ``` +The loop variable can have a type annotation, as in `for x: int in $numbers`. Nushell checks that the annotation names a real type, but it doesn't check the items against it, and it doesn't convert them. The variable gets the type of the items instead, so this loop runs without an error: + +```nu +for x: string in [1 2] { print ($x | describe) } +# => int +# => int +``` + #### Expression Command Alternatives - [`each`](/commands/docs/each.html) @@ -373,7 +416,7 @@ try { 1 / 0 } catch { 'An error happened!' } | $in ++ ' And now I am resuming.' # => An error happened! And now I am resuming. ``` -It will not execute the `catch` block if an error did not occur. +It will not execute the `catch` block if an error did not occur. As with [`else`](#if), `catch` and `finally` have to start on the same line as the `}` before them. The `catch` closure can take a parameter, which receives a record describing the error: @@ -382,6 +425,8 @@ try { 1 / 0 } catch {|err| $err.msg } # => Division by zero. ``` +Instead of writing the closure after `catch`, you can give it a closure stored in a variable or passed in as a parameter, as in `try { ... } catch $handler`. `finally` only takes a closure written in place. See [the Language Guide](/lang-guide/chapters/flow_control/try-catch.md#language-notes) for both. + `try` also works for external commands: ```nu @@ -453,6 +498,8 @@ try { 1 / 0 } finally { print 'cleaning up' } # => ╰──── ``` +With a `catch` or a `finally`, `try` collects the whole output of its block before it returns. An error in any item of a stream is therefore still caught, but the output doesn't stream on to the next command while the block runs. See [the Language Guide](/lang-guide/chapters/flow_control/try-catch.md#language-notes) for an example. + ## Other ### `return` diff --git a/book/creating_errors.md b/book/creating_errors.md index 478535fe8a6..fd635c0aadf 100644 --- a/book/creating_errors.md +++ b/book/creating_errors.md @@ -149,3 +149,60 @@ try { check-range 10 1 } catch { error make "could not build the range" } ``` After any other statement in the block, such as a `print`, the caught error is no longer the input, and `error make` reports only the new error. To keep the chain, pipe the error in with `$err | error make "..."`, or pass it with `inner`, as in `catch {|err| print 'cleaning up'; error make {msg: 'could not build the range', inner: [$err]} }`. + +## Re-raising a caught error + +Sometimes a `catch` block only needs to log an error and then let it continue. The `raw` field of the error record holds the original error itself, and returning it from `catch` raises that error again, unchanged: + +```nu +try { check-range 10 1 } catch {|err| print "logging the error"; $err.raw } +# => logging the error +# => Error: nu::shell::error +# => +# => × invalid range +# => ╭─[repl_entry #2:1:19] +# => 1 │ try { check-range 10 1 } catch {|err| print "logging the error"; $err.raw } +# => · ─┬ ┬ +# => · │ ╰── is greater than the upper bound +# => · ╰── lower bound +# => ╰──── +# => help: swap the two arguments +``` + +Reading `$err.raw` raises the error right away, so it can't be stored or inspected. That means `error make {msg: "new message", raw: $err.raw}` also re-raises the original error, before `error make` even runs. + +`error make` treats a `raw` field the same way. When the record it receives has one, `error make` raises the error stored there and ignores the other fields. The record in `$err` has a `raw` field, so `error make $err` re-raises the caught error, and so does a copy with a changed message: + +```nu +try { check-range 10 1 } catch {|err| error make ($err | update msg "could not build the range") } +# => Error: nu::shell::error +# => +# => × invalid range +# => ╭─[repl_entry #3:1:19] +# => 1 │ try { check-range 10 1 } catch {|err| error make ($err | update msg "could not build the range") } +# => · ─┬ ┬ +# => · │ ╰── is greater than the upper bound +# => · ╰── lower bound +# => ╰──── +# => help: swap the two arguments +``` + +To raise a new error based on the caught one, start from `$err.details` instead. It has the `msg`, `labels`, `code`, `url`, `help` and `inner` fields, but no `raw`: + +```nu +try { check-range 10 1 } catch {|err| let details = $err.details | update msg "could not build the range"; error make $details } +# => Error: nu::shell::error +# => +# => × could not build the range +# => ╭─[repl_entry #4:1:19] +# => 1 │ try { check-range 10 1 } catch {|err| let details = $err.details | update msg "could not build the range"; error make $details } +# => · ─┬ ┬ +# => · │ ╰── is greater than the upper bound +# => · ╰── lower bound +# => ╰──── +# => help: swap the two arguments +``` + +The new error keeps the original labels and help. Because `error make` isn't the first command in the block, the caught error isn't also attached as an inner error (see [Chaining Errors](#chaining-errors)). + +A `raw` field has to hold an error. Any other value, such as `raw: 5`, fails with `Can't convert to ShellError`, and `raw: null` is ignored. diff --git a/book/custom_commands.md b/book/custom_commands.md index 1724f65e485..7d28c9a190e 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -383,6 +383,41 @@ def greet [] { "hi" } `%` is handy inside a command that shadows a built-in, because the body can call the original without recursing into itself. See [Aliases](aliases.md#replacing-existing-commands-using-aliases) for a complete example that replaces `ls`. ::: +### Defining a command more than once + +A block can define each command name only once. A second `def` (or [`extern`](externs.md)) with the same name in the same block is a parse error, so nothing in the block runs: + +```nu +def greet [] { "hi" }; def greet [] { "hello" } +# => Error: nu::parser::duplicate_command_def +# => +# => × Duplicate command definition within a block. +# => ╭─[repl_entry #1:1:28] +# => 1 │ def greet [] { "hi" }; def greet [] { "hello" } +# => · ──┬── +# => · ╰── defined more than once +# => ╰──── +``` + +A script file and a module are each a single block, so neither can define the same name twice. At the REPL, each entry is a new block, and entering a new `def greet` at the prompt replaces the earlier one: + +```nu +def greet [] { "hi" } +def greet [] { "hello" } +greet +# => hello +``` + +A `def` inside a nested block, such as a `do` closure or another command's body, shadows the outer command only within that block: + +```nu +def greet [] { "hi" } +do { def greet [] { "hello" }; greet } +# => hello +greet +# => hi +``` + ## Parameters ### Multiple parameters @@ -792,6 +827,33 @@ def greet [ } ``` +Because `--all-caps` creates `$all_caps`, it would collide with a parameter named `all_caps`. Parameters and flags share one set of variable names, and each short flag needs its own letter. Nushell rejects a repeated name when it parses the definition: + +```nu +def greet [--all-caps, all_caps] { $all_caps } +# => Error: nu::parser::duplicate_parameter +# => +# => × Duplicate parameter or flag. +# => ╭─[repl_entry #1:1:24] +# => 1 │ def greet [--all-caps, all_caps] { $all_caps } +# => · ─────┬──── ────┬─── +# => · │ ╰── `all_caps` uses a name that is already taken +# => · ╰── first used here +# => ╰──── +# => help: Each parameter and flag needs its own name, and each short flag its own letter. A long flag's +# => variable replaces `-` with `_`, so `--foo-bar` and `foo_bar` clash. +``` + +The same error covers two parameters with one name, a rest parameter that reuses a name, and two flags with the same short letter, such as `--verbose (-v)` and `--version (-v)`. A flag with only a short form, like `-v`, creates the variable `$v`, so it also collides with a parameter named `v`. + +The one name you can repeat is `_`. Use it for positional arguments the command doesn't need: + +```nu +def third [_, _, value] { $value } +third a b c +# => c +``` + #### Flags with a `null` Value When a flag is given `null` as its value, what happens depends on the flag's type: @@ -1340,6 +1402,50 @@ applies only to `extern`. It lets an external command return data instead of tex To see other attributes available for use within nushell, check the [command reference](/commands/docs/attr.html) or run `help attr` from the nushell REPL. +### Defining your own attributes + +An attribute such as `@owner` calls a command named `attr owner` while Nushell parses the definition, and stores the value that command returns. To create your own attribute, define an alias whose name starts with `attr ` and points to a built-in command that can run at parse time. [`echo`](/commands/docs/echo.md) is the usual choice, since it returns its arguments as they are: + +```nu +alias "attr owner" = echo +alias "attr tags" = echo +alias "attr slow" = echo + +@owner "platform-team" +@tags web api +@slow +@category "deploy" +def deploy [] { "deploying" } + +@slow +def rebuild [] { "rebuilding" } + +scope commands | where name == deploy | get 0.attributes +# => ╭───┬───────┬────────────────╮ +# => │ # │ name │ value │ +# => ├───┼───────┼────────────────┤ +# => │ 0 │ owner │ platform-team │ +# => │ 1 │ tags │ [list 2 items] │ +# => │ 2 │ slow │ │ +# => ╰───┴───────┴────────────────╯ +``` + +Nushell doesn't act on custom attributes. It stores them in the `attributes` column of [`scope commands`](/commands/docs/scope_commands.md), one row per attribute, with its name and value. Several arguments, as in `@tags web api`, give a list, and an attribute without arguments, like `@slow`, stores an empty string. Using the same attribute twice adds two rows. The built-in `@example`, `@search-terms`, `@category` and `@complete` attributes are applied to the command and aren't listed. + +A script can read the attributes back to find the commands it cares about: + +```nu +scope commands | where {|cmd| "slow" in $cmd.attributes.name } | get name +# => ╭───┬─────────╮ +# => │ 0 │ deploy │ +# => │ 1 │ rebuild │ +# => ╰───┴─────────╯ +``` + +To share attributes, export the aliases from a module (`export alias "attr owner" = echo`) and import them with `use ownership.nu *`, or by name with `use ownership.nu ["attr owner"]`. A plain `use ownership.nu` puts the module name in front of the alias, so `@owner` can't find it. The standard library's `@test`, `@ignore` and other [testing attributes](./standard_library.md#importing-submodules) are aliases of `echo` exported this way. + +The command behind an attribute has to be one that can run at parse time. An attribute backed by a custom command, such as `def "attr owner" [x] { $x }`, fails with a `Not a const command` error. An attribute also has to come right before a `def` or `extern`. Anywhere else, it is a `nu::parser::attribute_requires_definition` error. + ## Changing the Environment in a Custom Command Normally, environment variable definitions and changes are [_scoped_ within a block](./environment.html#scoping). This means that changes to those variables are lost when they go out of scope at the end of the block, including the block of a custom command. diff --git a/book/modules/creating_modules.md b/book/modules/creating_modules.md index f0136edcc4c..9777c08544e 100644 --- a/book/modules/creating_modules.md +++ b/book/modules/creating_modules.md @@ -381,6 +381,31 @@ Running this command changes the directory _locally_ in the module, but the chan ## Caveats +### A module can only contain definitions + +The top level of a module, whether it is a file or a `module { }` block, can only contain definitions: `def`, `extern`, `alias`, `const`, `type`, `use` and `module`, any of these with `export` in front, `export-env` blocks, and attributes on a `def` or `extern`. Any other statement, such as `let` or `print`, is a parse error: + +```nu +module greetings { + let default_name = "world" + export def hello [] { $"Hello, ($default_name)!" } +} +# => Error: nu::parser::expected_keyword +# => +# => × Expected keyword. +# => ╭─[repl_entry #1:2:5] +# => 1 │ module greetings { +# => 2 │ let default_name = "world" +# => · ─┬─ +# => · ╰── expected def, const, extern, alias, type, use, module, export or export-env keyword +# => 3 │ export def hello [] { $"Hello, ($default_name)!" } +# => ╰──── +``` + +For a module file, the error appears when you import it with `use`. A pipeline such as `ls | length` is rejected too, with `Parse mismatch: expected not a pipeline`. The rule covers only the module's top level, not the bodies of its commands. + +Use `const` for a value that the module's commands share. Changing `let` to `const` in the example above makes it work. Code that should run when the module is imported belongs in an [`export-env`](#environment-variables) block. + ### `export-env` runs only when the `use` call is _evaluated_ ::: note @@ -491,6 +516,24 @@ module spam { export module spam { } } # => help: Module spam can't export module named the same as the module. Either change the module name, or export `mod` module. ``` +The `mod` in the help text is a submodule name with special handling. Whatever a submodule named `mod` exports is merged into its parent. Its commands (including `main`), aliases, known externals, type aliases and submodules become members of the parent module, as if the parent had exported them itself: + +```nu +module spam { + export module mod { + export def main [] { "spam!" } + export def eggs [] { "eggs" } + } +} +use spam +spam +# => spam! +spam eggs +# => eggs +``` + +With any other submodule name, `use spam` would import neither command (see [Submodules](#submodules)). Constants that `mod` exports are dropped instead of merged. A `main` in `mod` also keeps the name `mod`, so `spam mod` runs it too. If the parent exports a `main` of its own as well, the second one is a `nu::parser::module_double_main` error. + ::: note A `.nu` file _may_ have the same name as its module directory (e.g., `spam/spam.nu`), and Nushell will import it. Still, prefer a different name: if the parent module and the same-named submodule both export a `main`, the two definitions resolve to the same command name and the parent's `main` silently wins. ::: diff --git a/book/scripts.md b/book/scripts.md index f4cad852a8f..8fd8365eb60 100644 --- a/book/scripts.md +++ b/book/scripts.md @@ -78,6 +78,64 @@ nu add_ten.nu 100 # => 110 ``` +### Help for a script + +Run a script with `--help` (or `-h`) to see the help for its `main` command, shown under the script's file name. As with any [documented command](custom_commands.md#documenting-your-command), the comment directly above `def main` becomes the description and a comment after each parameter describes it. The help also lists the [subcommands](#subcommands) of `main`: + +```nu +# welcome.nu + +# Welcome someone by name +# +# Prints a short greeting. +def main [ + name: string # Who to welcome + --shout (-s) # Print the greeting in capitals +] { + let text = $"Welcome, ($name)!" + if $shout { $text | str uppercase } else { $text } +} + +# Say goodbye instead +def "main bye" [name: string] { + $"Goodbye, ($name)!" +} +``` + +```nu +nu welcome.nu --help +# => Welcome someone by name +# => +# => Prints a short greeting. +# => +# => Usage: +# => > welcome.nu {flags} +# => +# => Subcommands: +# => welcome.nu bye (custom) - Say goodbye instead +# => +# => Flags: +# => -h, --help: Display the help message for this command +# => -s, --shout: Print the greeting in capitals +# => +# => Command Type: +# => > custom +# => +# => Parameters: +# => name : Who to welcome +# => +# => Input/output types: +# => ╭───┬───────┬────────╮ +# => │ # │ input │ output │ +# => ├───┼───────┼────────┤ +# => │ 0 │ any │ any │ +# => ╰───┴───────┴────────╯ +``` + +`nu welcome.nu bye --help` shows the help for the subcommand. The blank line after `# welcome.nu` keeps that comment out of the description, because only the comment lines directly above `def main` count. + +Nushell runs the rest of the script before it calls `main`, so code outside any command, such as a top-level `print`, still runs before the help appears. A script without a `main` command has no help to show. It ignores `--help` like any other argument and runs as usual. + ## Argument Type Interpretation By default, arguments provided to a script are interpreted with the type `Type::Any`, implying that they are not constrained to a specific data type and can be dynamically interpreted as fitting any of the available data types during script execution. diff --git a/lang-guide/chapters/custom_commands.md b/lang-guide/chapters/custom_commands.md index 9f795f2c355..f50eb109e3b 100644 --- a/lang-guide/chapters/custom_commands.md +++ b/lang-guide/chapters/custom_commands.md @@ -11,6 +11,7 @@ def []: -> { } ``` - The name may contain spaces to make a subcommand, e.g. `def "str shout" [] { ... }`. Parser keywords such as `if`, `let` or `def` cannot be used as names. +- A block can define each name once. A second `def` or `extern` with the same name in the same block (including a whole script or module) is a `nu::parser::duplicate_command_def` error. A `def` in a nested block shadows the outer one inside that block, and each REPL entry is a new block, so redefining a command at the prompt replaces it. See [Defining a command more than once](/book/custom_commands.md#defining-a-command-more-than-once). - The `: -> ` part is optional. Several input/output pairs can be given in brackets: `[int -> int, string -> string]`. - `def --env` keeps changes the body makes to the environment (see [Function Scope](#function-scope)). - `def --wrapped` passes unknown flags through to a `...rest` parameter as strings, which is useful for wrapping external commands. @@ -160,6 +161,16 @@ apply {|v| $v * 10 } 4 Parameters can be separated by spaces, commas or newlines. Without a type, a parameter accepts `any` value. Flag values can be written as `--flag value` or `--flag=value`, and switches as `--flag` or `--flag=false`. +Every parameter binds a variable, and all of them share one namespace: + +- A positional or rest parameter binds its own name. `$name` in the signature is the same as `name`. +- A long flag binds its name with `-` replaced by `_`, so `--foo-bar` binds `$foo_bar`. A flag with only a short form, such as `-v`, binds `$v`. +- No two parameters or flags may bind the same variable, and no two flags may share a short letter. A repeat is a `nu::parser::duplicate_parameter` error that points at both uses. +- `_` is the exception. Positional parameters named `_` may repeat, to ignore arguments. +- Nushell doesn't check `extern` signatures, because an `extern` binds no variables. + +See [Flags](/book/custom_commands.md#flags) in the Book for an example of the error. + ```nu def greet [ name: string # required positional diff --git a/lang-guide/chapters/flow_control/if-else.md b/lang-guide/chapters/flow_control/if-else.md index 3fe7a87cdce..fa416d3272f 100644 --- a/lang-guide/chapters/flow_control/if-else.md +++ b/lang-guide/chapters/flow_control/if-else.md @@ -28,6 +28,8 @@ The `else` part of `if` is optional. If not provided, if a condition is false, t The code that follows the `else` is an expression rather than a block, allowing any number of follow-on `if` expressions as well as other types of expressions. For example, this expression returns 100: `if false { 1 } else 100`. +`else` must start on the same line as the `}` that closes the block before it. A newline ends the `if` command, so an `else` on the next line is a separate command. The `if` runs without it, and then the `else` line fails with a "Command `else` not found" error (`nu::shell::external_command`). The parser does not report this, so it shows up only when the code runs. Inside parentheses a newline does not end a command, so `else` may start a new line there. See the example in [Control Flow](/book/control_flow.md#if). + Chained `else if` expressions are checked in order, and the first block whose condition is true is run: ```nu diff --git a/lang-guide/chapters/flow_control/try-catch.md b/lang-guide/chapters/flow_control/try-catch.md index 193d8e234af..c6f03c9760d 100644 --- a/lang-guide/chapters/flow_control/try-catch.md +++ b/lang-guide/chapters/flow_control/try-catch.md @@ -8,6 +8,8 @@ try { } catch {|err| } finally {|value| } Both `catch` and `finally` are optional, but if both are given, `catch` comes first. +Each must start on the same line as the `}` before it. On the next line, `catch` or `finally` is a separate command that fails with a "Command not found" error after the `try` has already run without it. A bare `try` swallows the original error, and the cleanup in `finally` never runs. See the `else` example in [Control Flow](/book/control_flow.md#if), which fails the same way. + See also: [`try` command help](/commands/docs/try.md), [Control Flow - `try`](/book/control_flow.md#try) and [Creating Your Own Errors](/book/creating_errors.md) in the Book. ```nu @@ -92,7 +94,7 @@ try { error make {msg: "disk full", help: "free some space"} } catch { $in.detai After any other statement, the original error is no longer the input. Pipe it in (`$e | error make {msg: b}`) or pass it as `inner` to keep it attached: `catch {|e| print "logging"; error make {msg: b, inner: [$e]} }`. - To log an error and re-raise it unchanged, return `$e.raw`: `catch {|e| print "logging"; $e.raw }`. + To log an error and re-raise it unchanged, return `$e.raw`: `catch {|e| print "logging"; $e.raw }`. `error make` also re-raises the error held in the `raw` field of a record it is given, including `$e` itself, and then ignores the record's other fields. See [Re-raising a caught error](/book/creating_errors.md#re-raising-a-caught-error). 1. `finally` runs after the block succeeds, after `catch`, when an uncaught error is about to propagate, and when `break`, `continue`, `return` or `exit` leaves the `try` (only `exit --abort` skips it). It receives a value as its parameter and as `$in`: @@ -141,6 +143,52 @@ try { error make {msg: "disk full", help: "free some space"} } catch { $in.detai # => 6 ``` +1. `catch` accepts any expression that gives a closure, such as a variable or a command's parameter, not only a closure written in place. The closure receives the error record as its parameter and as `$in`. A value the parser already knows is not a closure, such as a string variable, is a `nu::parser::type_mismatch` error. A value it can't check in advance, such as an untyped parameter, fails with `Can't convert to Closure` when an error reaches the `catch`. + + ```nu + let fallback = {|err| $"failed: ($err.msg)" } + try { 1 / 0 } catch $fallback + # => failed: Division by zero. + ``` + + `finally` takes only a closure written in place. A variable after `finally` is rejected before anything runs: + + ```nu + let cleanup = {|| print "cleaning up" } + try { "done" } finally $cleanup + # => Error: nu::compile::invalid_keyword_call + # => + # => × Encountered invalid `try` keyword call. + # => ╭─[repl_entry #2:1:1] + # => 1 │ try { "done" } finally $cleanup + # => · ─┬─ + # => · ╰── this call is not properly formed + # => ╰──── + ``` + + Call the stored closure from a literal one instead: `try { "done" } finally { do $cleanup }`. + +1. With a `catch` or a `finally`, `try` collects the whole output of its block before it returns. It doesn't pass stream items on as they arrive, so an error in a later item of a stream is still caught: + + ```nu + try { 1..3 | each {|x| if $x == 3 { error make {msg: boom} } else { $x } } } catch { "caught" } + # => caught + ``` + + The next command in the pipeline gets the items only after the block has finished. Here all three items are produced before the first one is consumed: + + ```nu + try { 1..3 | each {|x| print $"producing ($x)"; $x } } catch { [] } | each {|x| print $"consuming ($x)"; $x } | ignore + # => producing 1 + # => producing 2 + # => producing 3 + # => consuming 1 + # => consuming 2 + # => consuming 3 + ``` + + Without `catch` and `finally`, the stream passes through and the lines alternate. A `try` with a `catch` around an endless stream never returns. External commands get one exception. When the block ends with an external command and the next command takes its stderr, as [`complete`](/commands/docs/complete.md) and `save --stderr` do, `try` still reads all of the output and waits for the external to exit, but it passes stdout and stderr on separately so that the next command receives both. A non-zero exit code is still caught. + 1. Parse errors cannot be caught. The whole entry or script is parsed before anything runs, so a syntax error inside a `try` block stops everything: ```nu From 3af40c079ef262ffe86834e10db19f56755b0898 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 16:38:45 -0600 Subject: [PATCH 06/46] Document line editor and standard library features that had no docs Covers the rows rated `none` in the coverage checklist for the line editor, completions, and the standard library: - line_editor: the legacy pair edits, prefix history search with the arrow keys, and completion of command names with `^` and `%`, after sudo/doas, cell paths, operators, attributes, and module exports - directory_stack: where std/dirs keeps the stack (DIRS_LIST and DIRS_POSITION) - standard_library: null_device, std/log formats, placeholders, and level commands, and std-rfc/kv universal variables - testing: the testing.nu runner, including the --module workaround - custom_completions: checking suggestions with `commandline complete` REPL behavior was driven through expect; history search details for vi and helix modes and the Windows null device come from the source. --- book/custom_completions.md | 2 + book/directory_stack.md | 76 +++++++++++ book/line_editor.md | 254 +++++++++++++++++++++++++++++++++++++ book/standard_library.md | 142 ++++++++++++++++++++- book/testing.md | 147 +++++++++++++++++++++ 5 files changed, 620 insertions(+), 1 deletion(-) diff --git a/book/custom_completions.md b/book/custom_completions.md index f79b74aee0d..fef60c57250 100644 --- a/book/custom_completions.md +++ b/book/custom_completions.md @@ -409,6 +409,8 @@ def build [target: string@"nu-complete dirs-or-default"] { } # => ╰───┴──────────╯ ``` +In a script or with `nu -c`, `commandline complete` doesn't list the executables in `PATH`. Run it at the prompt to check suggestions that include them. The [completion menu](./line_editor.md#completion-menu) section of the line editor chapter uses `commandline complete` to show what Nushell completes without a custom completer, such as cell paths, operators, attributes and module exports. + ## External Completions External completers can also be integrated, instead of relying solely on Nushell ones. diff --git a/book/directory_stack.md b/book/directory_stack.md index 4db7c8ef327..ec2e6387e14 100644 --- a/book/directory_stack.md +++ b/book/directory_stack.md @@ -111,6 +111,82 @@ dirs When we drop `nu_scripts` from the list, the previous directory (`reedline`) becomes active. +## Where the stack is stored + +The stack lives in two environment variables. `$env.DIRS_LIST` holds the directories, and +`$env.DIRS_POSITION` holds the index of the active one. `use std/dirs` creates them when they +don't exist yet, with the current directory as the only entry and `0` as the position: + +```nu +cd /usr +use std/dirs +dirs add /usr/bin /usr/lib +$env.DIRS_LIST +# => ╭───┬──────────╮ +# => │ 0 │ /usr │ +# => │ 1 │ /usr/bin │ +# => │ 2 │ /usr/lib │ +# => ╰───┴──────────╯ +$env.DIRS_POSITION +# => 1 +``` + +The stored path of the active directory can be out of date. `cd` doesn't know about the stack, +so it changes `$env.PWD` and leaves `DIRS_LIST` alone. `dirs` shows `$env.PWD` for the active +entry instead of the stored path, and `dirs add`, `dirs next`, `dirs prev` and `dirs goto` write +`$env.PWD` into the active slot before they move: + +```nu +cd /usr/share +$env.DIRS_LIST +# => ╭───┬──────────╮ +# => │ 0 │ /usr │ +# => │ 1 │ /usr/bin │ +# => │ 2 │ /usr/lib │ +# => ╰───┴──────────╯ +dirs +# => ╭───┬────────┬────────────╮ +# => │ # │ active │ path │ +# => ├───┼────────┼────────────┤ +# => │ 0 │ false │ /usr │ +# => │ 1 │ true │ /usr/share │ +# => │ 2 │ false │ /usr/lib │ +# => ╰───┴────────┴────────────╯ +dirs next +$env.DIRS_LIST +# => ╭───┬────────────╮ +# => │ 0 │ /usr │ +# => │ 1 │ /usr/share │ +# => │ 2 │ /usr/lib │ +# => ╰───┴────────────╯ +``` + +So read the stack with `dirs` rather than straight from `$env.DIRS_LIST`. + +Because the stack lives in environment variables, it carries over to any Nushell started from this +one, such as a nested `nu` or a restart with `exec nu`. Other programs see `DIRS_LIST` as a single +string, with the directories joined by the path separator (`:`, or `;` on Windows), and +`DIRS_POSITION` as the index written out as a string. `use std/dirs` adds an +[`ENV_CONVERSIONS`](./configuration.md#env-conversions) entry for each variable, so in the new +shell it turns them back into a list and an integer, and the stack is where you left it: + +```nu +nu -c '$env.DIRS_LIST' +# => /usr:/usr/share:/usr/lib +nu -c 'use std/dirs; dirs' +# => ╭───┬────────┬────────────╮ +# => │ # │ active │ path │ +# => ├───┼────────┼────────────┤ +# => │ 0 │ false │ /usr │ +# => │ 1 │ false │ /usr/share │ +# => │ 2 │ true │ /usr/lib │ +# => ╰───┴────────┴────────────╯ +``` + +An `export-env` block in `std/dirs` creates both variables, and that block doesn't run when your +own module imports `std/dirs` with a top-level `use`. See +[Using `std/dirs` in Modules](./standard_library.md#using-std-dirs-in-modules). + ## `shells` Aliases Some users may prefer to think of this feature as multiple "shells within shells", where each has its own directory. diff --git a/book/line_editor.md b/book/line_editor.md index 58ca050badd..40b7e438f9c 100644 --- a/book/line_editor.md +++ b/book/line_editor.md @@ -192,6 +192,8 @@ A mode without the editing set rebinds Backspace and DeleteShift+Alt+, and Shift+Alt+. also work for Alt+< and Alt+>. +When the line already has text and the cursor is at its end, ↑ and ↓ only show history entries that start with that text. See [Prefix search with the arrow keys](#prefix-search-with-the-arrow-keys). + #### Editing Keybindings | Key | Action | @@ -435,6 +437,48 @@ must be set in `config.nu`. They can't be changed once the REPL has started. Set `$env.config.history.path` to `null` turns off the history file. ::: +### Prefix search with the arrow keys + +On an empty line, ↑ (or Ctrl+P) steps back through the whole +history, newest entry first. Once you have typed something and the cursor is at the end of the +line, ↑ searches instead. It jumps to the newest entry that starts with the text you +typed, and each further press goes to the next older match. Say your history holds, from oldest +to newest: + +```nu +echo apple +echo banana +echo apricot +echo apricot +ls +``` + +Typing `echo ap` and pressing ↑ gives `echo apricot`. Pressing it again gives +`echo apple`, because the search passes over `echo banana` and `ls`, and it also skips the +second `echo apricot` since that's the entry already on the line. At the oldest match, +↑ does nothing. ↓ walks back toward newer matches, and past the newest +one it gives you back `echo ap`. If nothing in the history starts with your text, the line +stays as you typed it. + +Some details: + +- The search text is the line as it was at the first press of ↑, and it stays fixed + while you step through the matches. Editing the recalled line ends the search. The next + ↑ starts a new one, with the edited line as the search text. +- An entry matches only if it starts with the search text, letter case included. `echo ap` + doesn't find `ECHO apple` or `print (echo ap)`. +- With the cursor anywhere but at the end of the line, ↑ ignores the text and steps + through the whole history, as on an empty line. Press End first to search. +- A multi-line command never searches. ↑ and ↓ move between its lines, + and from the first line ↑ steps through the whole history. +- In Vi and Helix normal mode, k and j search the same way. After + Esc the cursor rests on the last character, which counts as the end of the line. +- With `history.isolation` turned on, the search sees what plain ↑ sees, which is + this session's commands and the ones saved before the session started. + +To find a command by text in the middle of the line, use Ctrl+Q or the +[history menu](#history-menu) instead. + ## Hints As you type, Reedline shows a hint in a dimmed color (`$env.config.color_config.hints`) after the @@ -823,6 +867,26 @@ $env.config.keybindings ++= [{ As you can see, these two types will allow you to construct any type of keybinding that you require +Configurations written for older versions of Nushell may use the pair edits +`CutInsidePair`, `CopyInsidePair`, `CutAroundPair` and `CopyAroundPair`. Each +takes a `left` and a `right` field of one character. Reedline no longer has these +edits and `keybindings list` doesn't show them, but Nushell still accepts them +and turns each one into a text object edit on the pair you give. `CutInsidePair` +and `CutAroundPair` become `CutTextObject`, the two copy edits become +`CopyTextObject`, and `Inside` and `Around` become `scope: inner` and +`scope: around`. These two events do the same thing. Each cuts the text between +the parentheses around the cursor, or inside the next pair of parentheses when +the cursor isn't between any: + +```nu +event: { edit: CutInsidePair, left: "(", right: ")" } +event: { edit: CutTextObject, scope: inner, object_type: { left: "(", right: ")" } } +``` + +A missing `left` or `right`, or a value longer than one character, is treated +like any other mistake in a keybinding. Nushell prints the error before every +prompt and doesn't apply `$env.config.keybindings` until you fix it. + ### Until Type To complete this keybinding tour we need to discuss the `until` type for event. @@ -1065,6 +1129,196 @@ $env.config.menus ++= [{ By modifying these parameters you can customize the layout of your menu to your liking. +The suggestions depend on what is under the cursor. At the start of a command the menu offers +command names, after a `-` the command's flags, after a `$` the variables in scope, and for most +arguments the names of files and directories. A [custom completer](./custom_completions.md) can +replace the suggestions for a command's arguments. The IDE completion menu below shows the same +suggestions in a different layout. The sections that follow cover built-in completions that are +easy to miss. + +To see what Tab would offer for a line, pipe the line to +[`commandline complete`](/commands/docs/commandline_complete.md), as the examples below do. In a +script or with `nu -c`, `commandline complete` doesn't list the executables in `PATH`, so run the +examples that involve them at the prompt. + +#### Command names, `^` and `%` + +Command name completion lists Nushell's own commands together with the executables in your +`PATH`. When an executable has the same name as a Nushell command, the menu lists it with a `^` +in front, and lists the Nushell command a second time with a `%` in front, so you can pick the +one you mean. On a system with a `sort` executable, typing `sort` at the prompt offers: + +```nu +"sort" | commandline complete +# => ╭───┬─────────╮ +# => │ 0 │ sort │ +# => │ 1 │ sort-by │ +# => │ 2 │ %sort │ +# => │ 3 │ ^sort │ +# => ╰───┴─────────╯ +``` + +Type the sigil yourself to narrow the list. After `^`, the menu offers only executables from +`PATH`, even when `$env.config.completions.external.enable` is `false`. After `%`, it offers only +built-in commands. That includes a built-in hidden by a custom command or alias of the same name, +or by [`hide`](/commands/docs/hide.md), and leaves out custom commands, aliases and externs: + +```nu +"%sort" | commandline complete +# => ╭───┬─────────╮ +# => │ 0 │ sort │ +# => │ 1 │ sort-by │ +# => ╰───┴─────────╯ +``` + +Accepting a suggestion keeps the sigil and replaces only the name after it, and with the cursor +in front of the sigil, Tab offers nothing. See +[Running System (External) Commands](./running_externals.md) for what `^` and `%` do when the +command runs. + +The word right after `sudo` or `doas`, written with or without `^`, completes from the same list +of command names, since it names the command to run. Typing `sudo sor` at the prompt offers the +same four suggestions as `sort` above. Pick a plain name that is an executable. `sudo` can't run +Nushell commands, and a sigil in this position isn't removed, so `sudo ^sort` asks `sudo` for a +program called `^sort`. Only that first word is special. With options in between, as in `sudo -u root sor`, and for the +arguments of the command that follows, you get the usual completion for an external command, +which is your [external completer](./custom_completions.md#external-completions) if you have one +and file names otherwise. The same happens when no command name matches, and when `sudo` or `doas` +is a custom command that you defined. An alias that only names the program, such as +`alias sudo = ^sudo`, keeps the command name completion. One that adds options, such as +`alias doas = ^doas -n`, loses it, because the options fill the first-word slot. + +#### Cell paths + +After a variable and a dot, the menu lists the keys of a record or the columns of a table, with +the type of each value as the description: + +```nu +let user = {name: "Ada", "home dir": "/home/ada", langs: [nu rust], v2: true} +"$user." | commandline complete --detailed | select value description +# => ╭───┬────────────┬──────────────╮ +# => │ # │ value │ description │ +# => ├───┼────────────┼──────────────┤ +# => │ 0 │ "home dir" │ string │ +# => │ 1 │ langs │ list │ +# => │ 2 │ name │ string │ +# => │ 3 │ "v2" │ bool │ +# => ╰───┴────────────┴──────────────╯ +``` + +The menu wraps a key in double quotes when it contains anything other than ASCII letters, `_` +and `-`, which is why `"v2"` is quoted along with `"home dir"`. Each further dot goes a level +deeper, so `$env.config.history.` lists the history settings and `$table.0.` lists the columns +of a table's first row. For a list of records, the menu offers every column that appears in any of +them. A version from [`into semver`](/commands/docs/into_semver.md) completes to `major`, +`minor`, `patch`, `pre`, `build` and `prefix`, and a matrix from +[`into matrix`](/commands/docs/into_matrix.md) to `shape`, `ndim` and `size`. + +The menu reads the actual value when it has one: a variable set by an earlier command, a +constant, `$env`, `$nu`, or a literal such as `{a: 1, b: 2}.`. Otherwise it falls back on the +declared type. Inside a command body, a parameter typed `record` +completes to `age` and `name`, and `(sys host).` completes the fields that +[`sys host`](/commands/docs/sys_host.md) declares for its output. Completion never runs the +command, so `(ls).` offers nothing, because `ls` only declares that it returns a table. + +#### Operators + +After a value and a space, the menu offers the operators that work with the value's type, each +with a short description. An integer gets the arithmetic, comparison and bitwise operators, and a +float gets the same without the bitwise ones. A string gets the comparisons, the regex operators +`=~` and `!~`, which also appear as `like` and `not-like`, then `starts-with`, `ends-with`, `has` +and their `not-` forms, and `++`. A date gets only comparisons, among them `older-than` and +`newer-than`: + +```nu +"(date now) " | commandline complete +# => ╭───┬────────────╮ +# => │ 0 │ != │ +# => │ 1 │ < │ +# => │ 2 │ <= │ +# => │ 3 │ == │ +# => │ 4 │ > │ +# => │ 5 │ >= │ +# => │ 6 │ in │ +# => │ 7 │ newer-than │ +# => │ 8 │ not-in │ +# => │ 9 │ older-than │ +# => ╰───┴────────────╯ +``` + +A list gets `==`, `!=`, `in`, `not-in`, `has`, `not-has` and `++`, a record or a range gets the +same without `++`, and a boolean gets `and`, `or` and `xor` plus `==`, `!=`, `in` and `not-in`. +When the type isn't known, as for a column inside [`where`](/commands/docs/where.md) +(`ls | where size `), the menu offers every operator. Typing the start of an operator narrows the +list, so `1 b` offers the five `bit-` operators. + +A mutable variable, or a variable under `$env`, also gets the assignment operators that fit its +type: `=`, `+=`, `-=`, `*=` and `/=` for a number, `=` and `++=` for a string or a list, and +only `=` for a boolean, date, record or range. + +#### Attributes + +Typing `@` at the start of a line and pressing Tab lists the attributes you can put +above a definition: + +```nu +"@" | commandline complete +# => ╭───┬───────────────────╮ +# => │ 0 │ category │ +# => │ 1 │ complete │ +# => │ 2 │ complete external │ +# => │ 3 │ deprecated │ +# => │ 4 │ example │ +# => │ 5 │ interactive │ +# => │ 6 │ search-terms │ +# => │ 7 │ structured │ +# => ╰───┴───────────────────╯ +``` + +These are all the commands in scope whose names start with `attr `, shown without that prefix +and with their descriptions. Attributes you import show up too, such as `@test` and +`@before-each` after `use std/testing *`, and so do ones you define yourself with +`def "attr my-tag" [] { ... }`. After the attributes, the menu offers the definitions an +attribute can be attached to, which are `def`, `export def`, `extern` and `export extern`. + +#### Modules and their exports + +The module argument of [`use`](/commands/docs/use.md), [`export use`](/commands/docs/export_use.md) +and [`overlay use`](/commands/docs/overlay_use.md) completes from three places: + +- the names of modules already loaded in this session, such as one created with `module` on an + earlier line +- `std` and `std-rfc`, and after `std/` or `std-rfc/` the submodules that are built into Nushell +- `.nu` files and directories in the current directory and in the directories listed in + [`$NU_LIB_DIRS`](./configuration.md#nu-lib-dirs-constant) and `$env.NU_LIB_DIRS`. Other files + are left out. + +```nu +"use std/i" | commandline complete +# => ╭───┬───────────╮ +# => │ 0 │ std/input │ +# => │ 1 │ std/iter │ +# => ╰───┴───────────╯ +``` + +After the module, `use` and `export use` complete what it exports: commands, aliases, submodules +and constants, with names that contain spaces wrapped in quotes. This works for a module file +that isn't loaded yet, and inside a bracketed import list: + +```nu +"use std/log [log-" | commandline complete +# => ╭───┬──────────────────╮ +# => │ 0 │ log-ansi │ +# => │ 1 │ log-level │ +# => │ 2 │ log-prefix │ +# => │ 3 │ log-short-prefix │ +# => ╰───┴──────────────────╯ +``` + +`overlay use` doesn't complete a module's members. [`source-env`](/commands/docs/source-env.md) +offers `.nu` files and directories like `use` does, but not the `std/` paths, and +[`source`](/commands/docs/source.md) offers every file, as for any other path argument. + ### Ide Completion Menu The ide_completion_menu works much like the completion_menu but has an ide look and feel about it. diff --git a/book/standard_library.md b/book/standard_library.md index 3272074b5fd..c0830750556 100644 --- a/book/standard_library.md +++ b/book/standard_library.md @@ -94,9 +94,22 @@ Submodules that are normally imported with `use std/ *` (**with** a g - `use std/formats *`: Additional `to` and `from` format conversions - `use std/math *`: The math constants without a prefix, such as `$E`. Note that the prefixed form #1 above is likely more understandable when reading and maintaining code. - `use std/testing *`: The `@test`, `@ignore`, `@before-each`, `@before-all`, `@after-each`, and `@after-all` attributes for marking tests -- `use std/util *`: Miscellaneous commands such as `path add`, `repeat`, `null-device`, and `structure` +- `use std/util *`: Miscellaneous commands such as `path add`, `repeat`, `null-device`, and `structure`, and the `null_device` constant - `use std/xml *`: Additional commands for working with XML data +::: tip +`std/util` exports `null_device`, a constant that holds the same path the `null-device` command returns: `/dev/null`, or `\\.\NUL` on Windows. Use the constant where Nushell needs a value while it parses the code, such as a parameter's default value. Writing `--log: path = (null-device)` there fails with "Default values should be constant expressions", but the constant works: + +```nu +use std/util [null_device] +def build [--log: path = $null_device] { $log } +build +# => /dev/null +``` + +After `use std/util` without the `*`, the constant is `$util.null_device`. +::: + #### 3. `use std ` It is _possible_ to import Standard Library submodules using a space-separated form: @@ -111,6 +124,90 @@ As mentioned in [Using Modules](./modules/using_modules.md#module-definitions), This form also doesn't work for submodules that have a command of the same name. For example, `use std log` imports only the `log` command itself, not `log info` or the other subcommands. Use `use std/log` instead. ::: +## Logging with `std/log` + +`use std/log` provides `log debug`, `log info`, `log warning`, `log error` and `log critical`. Each one prints its message to stderr, but only when its level is at or above [`$env.NU_LOG_LEVEL`](./special_variables.md#env-nu-log-level). See [`echo`, `print`, and `log` commands](./stdout_stderr_exit_codes.md#echo-print-and-log-commands) for an example of each. + +### Log line format + +Two environment variables decide what a log line looks like. `$env.NU_LOG_FORMAT` is the template for the whole line, and `$env.NU_LOG_DATE_FORMAT` is the [`format date`](/commands/docs/format_date.md) pattern for its timestamp. `use std/log` sets each of them to its default unless it already has a value: + +```nu +use std/log +$env.NU_LOG_FORMAT +# => %ANSI_START%%DATE%|%LEVEL%|%MSG%%CONTEXT%%ANSI_STOP% +$env.NU_LOG_DATE_FORMAT +# => %Y-%m-%dT%H:%M:%S%.3f +log info "started" +# => 2026-11-14T16:26:52.511|INF|started +``` + +The template can contain any of these placeholders, in any order, as often as you like: + +| Placeholder | Replaced with | +| -------------- | ------------------------------------------------------------------------------------------- | +| `%MSG%` | The message | +| `%DATE%` | The current time, formatted with `NU_LOG_DATE_FORMAT` | +| `%LEVEL%` | The level's prefix, such as `INF`, or its one-letter form, such as `I`, with `--short` | +| `%CONTEXT%` | The `--context` record as `key="value"` pairs after a space, or nothing without `--context` | +| `%ANSI_START%` | The level's color | +| `%ANSI_STOP%` | The code that resets the color | + +Text around the placeholders is printed as it is. Changing either variable changes every later log line: + +```nu +$env.NU_LOG_FORMAT = "[%DATE%] %LEVEL%: %MSG%%CONTEXT%" +$env.NU_LOG_DATE_FORMAT = "%H:%M:%S" +log info "cache rebuilt" --context {entries: 120, ms: 34} +# => [16:26:52] INF: cache rebuilt entries="120" ms="34" +log warning "disk almost full" --short +# => [16:26:52] W: disk almost full +``` + +A `--format` given to a single call takes the place of `NU_LOG_FORMAT` for that call. An empty `--format ""` counts as no format, so the call falls back on `NU_LOG_FORMAT`. `log custom` takes its template as an argument and doesn't read `NU_LOG_FORMAT`, though its `%DATE%` still follows `NU_LOG_DATE_FORMAT`. + +Because these are environment variables, scripts you start from the shell, such as `nu build.nu`, inherit them and log in the same format. The color codes are part of the line whether or not stderr is a terminal, so a log saved to a file (`nu build.nu 2> build.log` in another shell) contains them as well. Leave `%ANSI_START%` and `%ANSI_STOP%` out of the template to get plain lines. + +### Levels, prefixes and colors + +Four commands return the tables that `std/log` uses for its five levels, as records keyed by the level's name. `log log-level` gives each level's number, `log log-prefix` its prefix, `log log-short-prefix` its one-letter prefix, and `log log-ansi` the escape code for its color: + +```nu +log log-level +# => ╭──────────┬────╮ +# => │ CRITICAL │ 50 │ +# => │ ERROR │ 40 │ +# => │ WARNING │ 30 │ +# => │ INFO │ 20 │ +# => │ DEBUG │ 10 │ +# => ╰──────────┴────╯ +log log-prefix +# => ╭──────────┬─────╮ +# => │ CRITICAL │ CRT │ +# => │ ERROR │ ERR │ +# => │ WARNING │ WRN │ +# => │ INFO │ INF │ +# => │ DEBUG │ DBG │ +# => ╰──────────┴─────╯ +``` + +The short prefixes are `C`, `E`, `W`, `I` and `D`. The colors are the codes of `ansi red_bold` for CRITICAL, `ansi red` for ERROR, `ansi yellow` for WARNING, `ansi default` for INFO and `ansi default_dimmed` for DEBUG, so `(log log-ansi).WARNING == (ansi yellow)` is `true`. + +These lookups let you name a level instead of hard-coding its number or prefix. `log set-level`, for instance, takes a number: + +```nu +log set-level (log log-level).DEBUG +log debug "cache hit" +# => [16:26:52] DBG: cache hit +``` + +They also help with `log custom`. It works out the prefix and color for itself only when the level is one of the five numbers in `log log-level`, and it reports an error listing them for any other number. A level of your own needs `--level-prefix` and `--ansi`, and it can borrow a color from an existing level: + +```nu +log custom "retrying request" "%ANSI_START%%LEVEL% %MSG%%ANSI_STOP%" 25 --level-prefix NOTE --ansi (log log-ansi).WARNING +# => NOTE retrying request +``` + ## The Standard Library Candidate Module `std-rfc`, found in the [nushell Repository](https://github.com/nushell/nushell/tree/main/crates/nu-std/std-rfc), serves as a staging ground for possible Standard Library additions. @@ -141,6 +238,49 @@ Of course, if a candidate command in `std-rfc` no longer works or has too many i ::: +### Universal variables with `std-rfc/kv` + +The key-value store is a `std-rfc` module, so it's `use std-rfc/kv *`, not `std/kv`. It keeps each value as NUON in SQLite and needs a Nushell built with the `sqlite` feature, which the default build includes. By default `kv set`, `kv get`, `kv list` and `kv drop` use the in-memory database that [`stor`](/commands/docs/stor.md) manages, which is gone when Nushell exits. With `--universal` (`-u`), they use a database file instead, and every Nushell session that uses the same file sees the same keys: + +```nu +use std-rfc/kv * +kv set --universal EDITOR hx +kv set --universal retries 3 +kv list --universal +# => ╭───┬─────────┬───────╮ +# => │ # │ key │ value │ +# => ├───┼─────────┼───────┤ +# => │ 0 │ EDITOR │ hx │ +# => │ 1 │ retries │ 3 │ +# => ╰───┴─────────┴───────╯ +``` + +`$env.NU_UNIVERSAL_KV_PATH` is the path of that file. When it isn't set, the file is `std_kv_variables.sqlite3` in [`$nu.data-dir`](./special_variables.md#nu). The `kv` commands create the file on first use, but its directory must exist. Give an absolute path. The commands use the value exactly as it is, so a relative path points somewhere else after a `cd`, and a leading `~` isn't expanded. Expand it yourself: + +```nu +$env.NU_UNIVERSAL_KV_PATH = ('~/nu-kv.sqlite3' | path expand) +``` + +The universal keys can also become environment variables in every running session, the way universal variables work in fish. `kv universal-variable-hook` returns a closure that loads each universal key into `$env` and then sets `$env.NU_KV_UNIVERSALS` to `true`. Add it as a [`pre_execution` hook](./hooks.md#pre-execution-hooks) in `config.nu`: + +```nu +use std-rfc/kv * +$env.config.hooks.pre_execution ++= [(kv universal-variable-hook)] +``` + +The hook runs before each command line you enter. So after `kv set -u EDITOR hx` in one session, `$env.EDITOR` is `hx` from the next command on, in that session and in every other one that has the hook. Values keep their type, so `$env.retries` from the example above is an `int`. + +`$env.NU_KV_UNIVERSALS` tells `kv drop --universal` that universal keys are loaded as environment variables. When it is `true`, `kv drop -u` also removes the environment variable of the same name from the session that runs it. The hook sets it for you. If you load the keys some other way, for example once at startup with `kv list -u | transpose -dr | load-env`, set `$env.NU_KV_UNIVERSALS = true` yourself. + +::: warning +`std-rfc/kv` is a candidate module, and in Nushell 0.117.0 universal variables have some rough edges: + +- Dropping a key doesn't reach other sessions. Their hook only loads the keys that still exist, so the variable stays set there until the session ends or you remove it with `hide-env`. +- While no universal keys are stored, the hook fails before every command, with `load-env` reporting "Unsupported input". Store at least one key with `kv set -u` before you add the hook. +- Programs started from a session with the hook inherit `NU_KV_UNIVERSALS` as the string `"true"`. In a script or `nu -c` command started that way, `kv drop -u` fails with "The 'and' operator does not work on values of type 'string'", after it has already removed the key from the database. Run `hide-env NU_KV_UNIVERSALS`, or set it to the boolean `true`, before `kv drop -u` there. + +::: + ## Disabling the Standard Library To disable the standard library, you can start Nushell using: diff --git a/book/testing.md b/book/testing.md index cf8dc3229dd..183c1b49973 100644 --- a/book/testing.md +++ b/book/testing.md @@ -221,4 +221,151 @@ def "test show-ignored-test" [] { This is a simple example but could be extended to include many of the things you might expect from a testing framework, including setup and tear down functions and test discovery across files. +### The `testing.nu` runner + +The Nushell repository has a runner that does those things, and the standard library's own tests +use it. It isn't part of the standard library and isn't built into `nu`, so download +[`crates/nu-std/testing.nu`](https://github.com/nushell/nushell/blob/main/crates/nu-std/testing.nu) +first, preferably from the release tag that matches your Nushell version, and import it with +`use testing.nu`. The command it gives you is `testing run-tests`. + +Mark the tests with the attributes from `std/testing`. Using the `math.nu` module from the +standalone example above, a test module `tests/test_fib.nu` could look like this, with one test +that is wrong on purpose: + +```nu +use std/assert +use std/testing * +use ../math.nu fib + +@test +def fib-seven [] { + assert equal (fib 7) 13 +} + +@test +def fib-zero [] { + assert equal (fib 0) 1 +} + +@ignore +def fib-thirty [] { + assert equal (fib 30) 832040 +} +``` + +```nu +use testing.nu +testing run-tests --path tests +# => 2026-11-14T16:29:17.609|INF|Running fib-seven in module test_fib +# => 2026-11-14T16:29:17.609|INF|Running fib-zero in module test_fib +# => 2026-11-14T16:29:17.625|ERR|Error while running fib-zero in module test_fib +# => Error: nu::shell::error +# => +# => × These are not equal. +# => ╭─[/home/myuser/fib/tests/3ABzxausZT.nu:12:26] +# => 11 │ def fib-zero [] { +# => 12 │ assert equal (fib 0) 1 +# => · ┬ +# => · ╰── right: 1 +# => 13 │ } +# => ╰──── +# => ╭─[/home/myuser/fib/tests/../math.nu:4:16] +# => 3 │ if $n == 0 { +# => 4 │ return 0 +# => · ┬ +# => · ╰── left: 0 +# => 5 │ } else if $n == 1 { +# => ╰──── +# => +# => +# => Error: nu::shell::error +# => +# => × some tests did not pass (see complete errors below): +# => │ +# => │ test_fib fib-seven +# => │ ⨯ test_fib fib-zero +# => │ s test_fib fib-thirty +# => │ +``` + +The final error lists every test, with `⨯` for a failure, `s` for a test skipped with `@ignore`, +and nothing for a pass. When all tests pass, `testing run-tests` returns nothing and only the +progress lines appear. Those are logged with [`std/log`](./standard_library.md#logging-with-std-log), +so `$env.NU_LOG_LEVEL = "ERROR"` leaves only the failures, and `"DEBUG"` also logs the module's +global context (see below) for each test. + +#### How tests are found and run + +The runner looks at every `.nu` file under `--path`, which defaults to the current directory, in +subdirectories too. It reads each file's commands in a separate `nu` process by +[`source`](/commands/docs/source.md)-ing the file. Any command marked `@test` is a test, exported +or not, and the file name without `.nu` is the module name. + +::: warning +Discovery sources _every_ `.nu` file under the path, so code at the top level of any of them runs, +including scripts that aren't tests at all. Point `--path` at a directory that only holds test +modules. +::: + +Each test runs in its own `nu --no-config-file` process, so your configuration doesn't apply. Use +`--plugins` with a list of plugin paths to load plugins in those processes. Modules and tests run +in parallel, on as many threads as the machine has CPUs. `--threads` lowers that number, with +anything below `1` treated as `1`. To run a test, the runner saves a copy of the module next to +it under a random name, such as `3ABzxausZT.nu` above, with an extra command that calls the test. +It deletes the copy afterwards. So errors point into that copy, the test directory has to be +writable, and an interrupted run can leave a copy behind. A test passes when its process exits +without an error. + +#### Setup and teardown + +A module can mark one command with each of the setup and teardown attributes. If more than one +command has the same attribute, the runner uses the first. + +- `@before-all` runs once, in its own process, before the module's tests. The record it returns + is the module's global context. If it fails, the run stops with `Before-all failed`. +- `@before-each` runs in each test's process, just before the test. The runner merges the + record it returns into the global context. +- The test receives the merged record as its input, `$in`. +- `@after-each` runs after each test, also after a failing one, and receives the same record. +- `@after-all` runs once, in its own process, after the module's tests and receives the global + context. The runner ignores its output and its errors. + +```nu +use std/assert +use std/testing * + +@before-all +def setup-all [] { + {db: "test.db"} +} + +@before-each +def setup [] { + {user: "alice"} +} + +@test +def context-is-merged [] { + assert equal $in {db: "test.db", user: "alice"} +} +``` + +The global context reaches the tests as NUON text, so it can only hold values that +[`to nuon`](/commands/docs/to_nuon.md) can write. A closure in it makes `@before-all` fail. + +#### Choosing tests + +- `--test ` runs only the tests whose names match, and `--exclude ` leaves out the + ones that match. +- `--exclude-module ` leaves out the modules whose names match. +- `--list` returns a table of the modules it found and their tests, setup and teardown commands, + without running anything. +- `--module ` is meant to pick a single module, but in Nushell 0.117.0 it always fails with + `module_not_found`, even for a module that exists. Filter with `--exclude-module`, or point + `--path` at a directory holding only that module. + +If nothing is left to run, the runner fails with `no test to run`, and a `--path` that doesn't +exist gives `directory_not_found`. + [Nupm]: https://github.com/nushell/nupm From 83d4b1517dec0101e352a01afd8ec57199f5f71f Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:07:57 -0600 Subject: [PATCH 07/46] Fill gaps in the custom command, variable, and alias docs Covers the rows rated `some` in the coverage checklist for custom commands, signatures, attributes, variables, constants, and aliases: - custom_commands: streaming and collecting input, naming rules, optional/default/rest/flag rules including the null-default trap, the full list of parameter types, list and const completers, `--wrapped`, the reserved `--help` flag, and attribute syntax (@example, @deprecated, @category) - lang-guide: definition and signature errors, `scope commands` and signature columns, runtime type checks, compound assignment, which commands run at parse time, and `type` alias errors - variables and aliases: `let` after a pipe, cell-path assignment, `unlet` on a const, what an alias may contain, alias scope and descriptions 40 of the 45 rows are now fully documented; the rest wait on pages owned by other parts of the checklist or on post-0.117.0 changes. --- book/aliases.md | 56 +++- book/custom_commands.md | 348 ++++++++++++++++++++++++- book/variables.md | 56 ++++ lang-guide/chapters/custom_commands.md | 57 +++- lang-guide/chapters/declarations.md | 103 +++++++- lang-guide/chapters/variable_scope.md | 15 ++ 6 files changed, 621 insertions(+), 14 deletions(-) diff --git a/book/aliases.md b/book/aliases.md index 9cd639b1625..f02449bfd86 100644 --- a/book/aliases.md +++ b/book/aliases.md @@ -34,9 +34,63 @@ alias m = math This is particularly handy for plugins with many subcommands. For example, after `alias pl = polars`, you can write `pl into-df`, `pl select` and `pl collect`. +## What an alias can contain + +The right side of an alias is a single command call. It can include some of the command's arguments and leave the rest for the call site, even required ones: + +```nu +alias r = str replace +"a-b-c" | r --all "-" "+" +# => a+b+c +``` + +Anything other than one command call is rejected with `nu::parser::cant_alias_expression`. That covers pipelines like `ls | length`, redirections like `echo hi o> out.txt`, math expressions, and variables or cell paths like `$nu.home-dir`: + +```nu +alias total = 1 + 2 +# => Error: nu::parser::cant_alias_expression +# => +# => × Can't create alias to expression. +# => ╭─[repl_entry #1:1:15] +# => 1 │ alias total = 1 + 2 +# => · ┬ +# => · ╰── aliasing a binary operation is not supported +# => ╰──── +# => help: Only command calls can be aliased. +``` + +Most parser keywords can't be aliased either. The exceptions are `if`, `match`, `try`, `overlay`, `overlay use`, `overlay new` and `overlay hide`. Aliasing any other keyword, such as `alias l = let`, is a `nu::parser::cant_alias_keyword` error. + +The `=` needs a space on each side. `alias ll=ls -l` and `alias ll =ls -l` are both parse errors. + +An alias is visible from the line that defines it to the end of the enclosing block. Unlike a `def`, it can't be used above its definition, and an alias defined inside a block, such as `do { alias ll = ls -l }`, is gone after the block ends. + ## List All Loaded Aliases -Your useable aliases can be seen in `scope aliases` and `help aliases`. +Your useable aliases can be seen in [`scope aliases`](/commands/docs/scope_aliases.md) and [`help aliases`](/commands/docs/help_aliases.md). Both return a table with these columns: + +- `name`: the alias name +- `expansion`: the command call the alias stands for +- `description`: the alias's description, explained below +- `decl_id`: a number that identifies the alias +- `aliased_decl_id`: the `decl_id` of the command the alias calls, as listed by `scope commands`, or `null` for an external command + +A comment on the line above `alias` or `export alias` becomes the alias's description. Without one, the description is ``Alias for `` ``: + +```nu +# List files in long form +alias ll = ls -l +alias la = ls -a +scope aliases | where name in [ll la] | select name expansion description +# => ╭───┬──────┬───────────┬─────────────────────────╮ +# => │ # │ name │ expansion │ description │ +# => ├───┼──────┼───────────┼─────────────────────────┤ +# => │ 0 │ la │ ls -a │ Alias for `ls -a` │ +# => │ 1 │ ll │ ls -l │ List files in long form │ +# => ╰───┴──────┴───────────┴─────────────────────────╯ +``` + +`help aliases --find` keeps only the aliases whose name or description contains the given text, so `help aliases --find long` lists `ll` here. `help aliases ll` shows the help for one alias, the same as `help ll`. An unknown name is a `nu::shell::alias_not_found` error. Running `help` on an alias shows what it expands to, followed by the help for the aliased command. For example, with an alias for a small custom command: diff --git a/book/custom_commands.md b/book/custom_commands.md index 7d28c9a190e..1aa2293934d 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -28,6 +28,8 @@ def greet [name] { Here, we define the `greet` command, which takes a single parameter `name`. Following this parameter is the block that represents what will happen when the custom command runs. When called, the custom command will set the value passed for `name` as the `$name` variable, which will be available to the block. +Put a space between the name and the `[`, since `def greet[name]` is a parse error. The body has to be written out as a `{ ... }` block. A variable that holds a closure can't be used in its place. See [Defining Custom Commands](/lang-guide/chapters/custom_commands.md#defining-custom-commands) in the Language Reference Guide for the exact errors. + To run this command, we can call it just as we would call built-in commands: ```nu @@ -263,18 +265,90 @@ ls | nullify name size # => ╰───┴──────┴──────┴──────┴───────────────╯ ``` +### Streaming and collecting input + +Data moves through a pipeline in one of three forms: + +- a single value, such as a number, a string, or a list that is already in memory +- a list stream, whose items arrive one at a time, such as the output of `ls` or `each` +- a byte stream, which is the raw output of an external command or of `open --raw` + +[`describe`](/commands/docs/describe.md) tells you which one a command receives: + +```nu +1..3 | each { $in } | describe +# => list (stream) + +^echo hi | describe +# => byte stream +``` + +A command such as `each` handles one item at a time, so a stream stays a stream. Some code has to wait for the end of the stream and turn it into a single value. This happens when you: + +- use `$in`, as `nullify` does above +- assign the stream to a variable with `let` or `mut` +- pass a pipeline in parentheses as an argument, as in `my-command (ls)` +- run [`collect`](/commands/docs/collect.md) +- call a command that needs all of its input before it can output anything, such as `sort`, `reverse` or `length` + +A collected list stream becomes a list. A collected byte stream becomes a string, or `binary` if the bytes aren't valid UTF-8. + +To see the difference, print a message on both sides of the pipe. `double` uses `each` directly, so each number is doubled as soon as it arrives: + +```nu +def double [] { each {|n| print $"double ($n)"; 2 * $n } } +[1 2 3] | each {|n| print $"send ($n)"; $n } | double | ignore +# => send 1 +# => double 1 +# => send 2 +# => double 2 +# => send 3 +# => double 3 +``` + +`double-all` stores `$in` in a variable first, so nothing is doubled until all three numbers have been sent: + +```nu +def double-all [] { + let nums = $in + $nums | each {|n| print $"double ($n)"; 2 * $n } +} +[1 2 3] | each {|n| print $"send ($n)"; $n } | double-all | ignore +# => send 1 +# => send 2 +# => send 3 +# => double 1 +# => double 2 +# => double 3 +``` + +With an endless input such as `1..`, `double-all` would never finish. When a command doesn't need all of its input at once, write it in the style of `double`. + ## Naming Commands In Nushell, a command name can be a string of characters. Here are some examples of valid command names: `greet`, `get-size`, `mycommand123`, `my command`, `命令` (English translation: "command"), and even `😊`. Strings which might be confused with other parser patterns should be avoided. For instance, the following command names might not be callable: -- `1`, `"1"`, or `"1.5"`: Nushell will not allow numbers to be used as command names -- `4MiB` or `"4MiB"`: Nushell will not allow filesizes to be used as command names +- `1`, `"1.5"`, `4MiB`, `5sec`, `2024-01-01`, `0x[ff]`, or `1..2`: When the first word of a name is a number, filesize, duration, datetime, binary literal or range, a call would read that word as a value and never reach the command, so Nushell rejects the name. Only the first word counts, so `def "retry 5sec"` is fine. - `"number#four"`, `"number^four"`, or `"number%four"`: Carets, hash symbols, and percent signs are not allowed in command names -- `"foo bar"`, `" foo"`, or `"foo "`: The words of a command name must be separated by single spaces, with no leading or trailing whitespace. Such a name could never be called, so `def`, `extern`, and `alias` reject it. +- `"foo bar"`, `" foo"`, or `"foo "`: The words of a command name must be separated by single spaces, with no leading or trailing whitespace. - `-a`, `"{foo}"`, `"(bar)"`: Will not be callable, as Nushell will interpret them as flags, closures, or expressions. +`def`, `extern`, and `alias` reject the names in the first three groups with a `nu::parser::variable_not_valid` error: + +```nu +def 5sec [] { "five seconds" } +# => Error: nu::parser::variable_not_valid +# => +# => × Command name not supported. +# => ╭─[repl_entry #1:1:5] +# => 1 │ def 5sec [] { "five seconds" } +# => · ──┬─ +# => · ╰── command name can't be a number, a filesize, a duration, a datetime, a binary literal or a range, contain #, ^, or %, or have whitespace other than single spaces between words +# => ╰──── +``` + Parser keywords such as `if`, `for`, `let`, `def`, `type`, `use` or `where` can't be used as command names at all, because shadowing them would break the language constructs they implement: ```nu @@ -450,6 +524,18 @@ def greet [ } ``` +The signature can also be written in parentheses instead of brackets, and a parameter name can start with `$`, the way the variable is written in the body: + +```nu +def greet ($name1, $name2) { + $"Hello, ($name1) and ($name2)!" +} +greet Wei Mei +# => Hello, Wei and Mei! +``` + +`$name1` and `name1` declare the same variable, but `help greet` then lists the parameter as `$name1`. Most code uses brackets and leaves out the `$`. + ### Required positional parameters The basic argument definitions used above are _positional_. The first argument passed into the `greet` command above is assigned to the `name1` parameter (and, as mentioned above, the `$name1` variable). The second argument becomes the `name2` parameter and the `$name2` variable. @@ -511,7 +597,24 @@ greet # => Hello! I don't know your name! ``` -If required and optional positional parameters are used together, then the required parameters must appear in the definition first. +If required and optional positional parameters are used together, then the required parameters must appear in the definition first: + +```nu +def greet [greeting?: string, name: string] { + $"($greeting), ($name)!" +} +# => Error: nu::parser::required_after_optional +# => +# => × Required positional parameter after optional parameter +# => ╭─[repl_entry #1:1:12] +# => 1 │ def greet [greeting?: string, name: string] { +# => · ───────────────┬─────────────── +# => · ╰── required parameter name after optional parameter +# => 2 │ $"($greeting), ($name)!" +# => ╰──── +``` + +Because an optional parameter can be `null`, its type inside the body includes `nothing`. A parameter declared as `limit?: int` has the type `oneof`, and that is the type error messages report for `$limit`. To work with a plain `int`, give the parameter a [default value](#parameters-with-a-default-value), or use `$limit | default 3` in the body. #### Parameters with a Default Value @@ -541,6 +644,43 @@ def congratulate [age: int = 18] { } ``` +Without an annotation, the parameter takes its type from the default value. Here `count` defaults to `1`, so it only accepts an `int`: + +```nu +def repeat [text, count = 1] { 1..$count | each { $text } | str join " " } +repeat hi 2.5 +# => Error: nu::parser::parse_mismatch +# => +# => × Parse mismatch: expected int. +# => ╭─[repl_entry #1:2:11] +# => 1 │ def repeat [text, count = 1] { 1..$count | each { $text } | str join " " } +# => 2 │ repeat hi 2.5 +# => · ─┬─ +# => · ╰── expected int +# => ╰──── +# => help: Check the syntax around this position — a typo, missing delimiter, or wrong separator is common. +``` + +This includes a `null` default. `def f [x = null]` gives `x` the type `nothing`, so any other argument is rejected with "expected nothing". For a parameter that is `null` when it's left out, write `x?`, or annotate it as `x: any = null`. + +Nushell works out the default while it parses the definition, so the default has to be a [constant](./variables.md#constant-variables): a literal, an expression of literals such as `(1 + 2)`, or a `const` variable. A `let` variable can't be used: + +```nu +let fallback = "Nushell" +def greet [name = $fallback] { $"Hello, ($name)!" } +# => Error: nu::parser::non_constant_default_value +# => +# => × Default values should be constant expressions. +# => ╭─[repl_entry #1:2:19] +# => 1 │ let fallback = "Nushell" +# => 2 │ def greet [name = $fallback] { $"Hello, ($name)!" } +# => · ────┬──── +# => · ╰── expected a constant value +# => ╰──── +``` + +With `const fallback = "Nushell"` instead, the definition works. + ### Parameter Types For each parameter, you can optionally define its type. For example, you can write the basic `greet` command as: @@ -585,10 +725,10 @@ The highlight style can be changed using a [theme](https://github.com/nushell/nu ::: details List of Type Annotations Most types can be used as type-annotations. In addition, there are a few "shapes" which can be used. For instance: -- `number`: Accepts either an `int` or a `float` +- `number`: Accepts either an `int` or a `float`. The value keeps its own type, so `describe` reports `int` or `float` for a `number` parameter. `describe` only shows `number` for a collection that mixes the two, such as `[1 2.5]`, which is a `list`. - `path`: A string that is treated as a filesystem path. A leading `~` is expanded to the home directory, and "n-dot" shorthands such as `...` are expanded to `../..`. Relative paths stay relative: `.` stays `.`, and `foo/../bar` becomes `bar`. See [Path](/lang-guide/chapters/types/other_types/path.html) in the Language Reference Guide for example usage. -- `directory`: A subset of `path` (above). Only directories will be offered when using tab-completion for the parameter. Expansions take place just as with `path`. -- `external_arg`: Parses the argument the way an [external command](./running_externals.md) would. A bare word is kept exactly as typed, so `0001` or `true` is not turned into an `int` or `bool`, while quoted strings, variables and subexpressions keep their own value. This is mainly useful for the `main` command of a [script](./scripts.md) that receives arguments from another shell. +- `directory`: A subset of `path` (above). Only directories will be offered when using tab-completion for the parameter. This is the shape of [`cd`](/commands/docs/cd.md)'s argument, which is why Tab after `cd` lists only directories. Expansions take place just as with `path`. +- `external_arg`: Parses the argument the way an [external command](./running_externals.md) would. A bare word is kept exactly as typed, so `0001` or `true` is not turned into an `int` or `bool`, while quoted strings, variables and subexpressions keep their own value. This is mainly useful for the `main` command of a [script](./scripts.md) that receives arguments from another shell. It only changes how a command's argument is parsed. On a variable, as in `let e: external_arg = 0001`, it accepts any value like `any` does, and `0001` is stored as the `int` `1`. - `oneof<...>`: Accepts any one of the listed types, for example `oneof`. A literal argument gets the first listed type that it matches, with the text-like types (`string`, `path`, `directory`, `glob`, `cell-path`, `external_arg`, and `any`) tried last whatever their position. So with `oneof>`, `[foo bar]` is a list, and with `oneof`, `5` (and `007`) is an `int`. Quote the argument if you need the text. - `error`: Available, but currently no known valid usage. See [Error](/lang-guide/chapters/types/other_types/error.html) in the Language Reference Guide for more information. @@ -624,8 +764,24 @@ The following [types](./types_of_data.html) can be used for parameter annotation - `string` - `table` +`list`, `record` and `table` can also say what they contain, for example `list`, `record` or `table`. See [Type Signatures](/lang-guide/chapters/types/type_signatures.md) in the Language Reference Guide for the full syntax. + +Custom value types work too. The built-in [`into semver`](/commands/docs/into_semver.md), [`into semver-range`](/commands/docs/into_semver-range.md) and [`into matrix`](/commands/docs/into_matrix.md) commands create values of type `semver`, `semver-range` and `matrix`, and a plugin can add its own, such as `polars_dataframe` from the Polars plugin. A plugin's type name is only known while the plugin is loaded. Custom value types take no type parameters. + +`block` is not a valid annotation. Nushell rejects it with the hint `Use 'closure' instead of 'block'`. + ::: +A parameter's type can be followed by `@` and a completer, which lists the values Tab offers for that argument. The completer can be the name of a command, a list, or a `const` variable that holds a list: + +```nu +const colors = [red green blue] +def paint [color: string@$colors] { $color } +def pick [size: string@[small medium large]] { $size } +``` + +A list item can also be a record with a `value` field, but its other fields, such as `description` and `style`, are ignored. Completers only suggest values. Any `string` is still accepted. See [Custom Completions](./custom_completions.md) for completer commands and the other forms. + ### Type Aliases When several commands take or return the same structured data, writing out a type like `record` each time gets long and easy to get wrong. The [`type`](/commands/docs/type.md) keyword gives a type a name: @@ -662,6 +818,8 @@ You can use a type alias anywhere a type annotation goes: positional parameters, A few rules apply: - Like [`alias`](./aliases.md) and `const`, a type alias is visible from its definition to the end of the enclosing block. It must be defined above its first use, and it can't refer to itself. +- A type alias can't take the name of a built-in type. The reserved names are `any`, `binary`, `block`, `bool`, `cell-path`, `closure`, `datetime`, `directory`, `duration`, `error`, `external_arg`, `filesize`, `float`, `glob`, `int`, `list`, `nothing`, `number`, `oneof`, `path`, `range`, `record`, `string` and `table`. Using one is a `nu::parser::type_alias_shadows_builtin` error. +- A type alias has no type parameters. `type Pair = ...` is not a valid name, and with `type Point = record`, writing `Point` is a `nu::parser::type_alias_with_params` error. - A custom completer belongs to the parameter, not the type. Write it on the parameter, as in `def paint [color: Color@[red green blue]] { ... }`. `type Color = string@[red green blue]` is an error. - In a module, a type alias is private unless it is defined with `export type`. See [Modules](./modules/creating_modules.md#exports) for how to export one and [Using Modules](./modules/using_modules.md#importing-type-aliases) for how to import it. @@ -811,6 +969,25 @@ def greet [ ::: +A flag with a default value is never a switch, even without a type annotation. It takes a value, and the default sets the value's type. So `--caps = false` declares a flag that needs a `bool` value, as in `--caps true`, and `--caps = null` declares one that only accepts `null`. Here `--times = 1` makes `--times` an `int` flag: + +```nu +def greet [name: string, --times = 1] { + 1..$times | each { $"Hello, ($name)!" } | str join " " +} +greet Mia --times 2 +# => Hello, Mia! Hello, Mia! +greet Mia --times +# => Error: nu::parser::missing_flag_param +# => +# => × Missing flag argument. +# => ╭─[repl_entry #3:1:11] +# => 1 │ greet Mia --times +# => · ───┬─── +# => · ╰── flag missing int argument +# => ╰──── +``` + Flags can contain dashes. They can be accessed by replacing the dash with an underscore in the resulting variable name: ```nu @@ -854,6 +1031,8 @@ third a b c # => c ``` +The names of the built-in variables `in`, `nu`, `env` and `ans` are taken too. A parameter or flag with one of these names, such as `def show [--env] {}`, is a `nu::parser::name_is_builtin_var` error, the same as `let env = 1`. See [Reserved Names](/lang-guide/chapters/declarations.md#reserved-names). + #### Flags with a `null` Value When a flag is given `null` as its value, what happens depends on the flag's type: @@ -967,6 +1146,23 @@ vip-greet $vip ...$guests # => And a special welcome to our VIP today, Tanisha! ``` +A command can have only one rest parameter, and it has to be the last positional parameter, since it takes every remaining argument. Flags can still be listed after it. Putting the VIP last is a parse error: + +```nu +def vip-greet [...names: string, vip: string] {} +# => Error: nu::parser::positional_after_rest +# => +# => × Positional parameter after the rest parameter. +# => ╭─[repl_entry #1:1:34] +# => 1 │ def vip-greet [...names: string, vip: string] {} +# => · ─┬─ +# => · ╰── parameter vip after the rest parameter +# => ╰──── +# => help: The rest parameter takes all remaining positional arguments, so it must be the last positional parameter. Flags can still follow it. +``` + +A second rest parameter is a `nu::parser::multiple_rest_params` error. A rest parameter also can't have a default value, so `...names = [Ada]` is a `nu::parser::assignment_mismatch` error. When no arguments are left for it, it is an empty list. + ### Ending Flag Parsing with `--` Arguments that start with `-` are normally parsed as flags, so passing a value like `-x` as a positional argument is an error. As in POSIX shells, a standalone `--` ends flag parsing. Every argument after it is treated as a positional argument, even if it starts with `-`, and the `--` itself isn't passed to the command: @@ -984,6 +1180,15 @@ show-args -- --verbose -x foo This works for built-in commands too, for example `[a b] | str join -- -x` returns `a-xb`. Commands defined with `def --wrapped` (see below) are the exception: they receive the `--` in their rest parameter, so they can pass it on unchanged to the external command they wrap. +External commands also receive the `--`. Nushell passes the arguments of an external command through without treating any of them as its own flags, and that includes an external declared with [`extern`](externs.md). The `--` reaches the program like any other argument, and the program decides what it means. Compare the built-in `echo` with the system's `echo`: + +```nu +echo -- --x +# => --x +^echo -- --x +# => -- --x +``` + ### Rest Parameters with Wrapped External Commands Custom commands defined with `def --wrapped` will collect any unknown flags and arguments into a @@ -1040,6 +1245,19 @@ ezal -G commands # => categories docs README.md ``` +A few rules apply to `def --wrapped`: + +- The command must have a rest parameter. Without one, the definition is a `nu::parser::missing_positional` error. +- The rest parameter must be untyped or typed as `string`. Any other type is a `nu::parser::type_mismatch_help` error. +- An untyped rest parameter uses the [`external_arg`](#parameter-types) shape. Bare words and flags are kept as the strings you typed, so `0001` stays `"0001"`, while a subexpression keeps its value. With `...rest: string`, a subexpression must produce a string. +- Nushell doesn't add a `--help` flag to a wrapped command. `--help` and `-h` go into the rest parameter, so the wrapped program can show its own help. Use `help ezal` to see the help for the wrapper itself. + +```nu +def --wrapped show-rest [...rest] { $rest | to nuon } +show-rest 0001 --help -x (1 + 1) +# => ["0001", --help, -x, 2] +``` + ## Pipeline Input-Output Signature By default, custom commands accept [`` type](./types_of_data.md#any) as pipeline input and likewise can output `` type. But custom commands can also be given explicit signatures to narrow the types allowed. @@ -1160,6 +1378,23 @@ Input/output types: You can see that Nushell automatically created some basic help for the command simply based on our definition so far. Nushell also automatically adds a `--help`/`-h` flag to the command, so users can also access the help using `vip-greet --help`. ::: +Since every command already has `--help`, you can't declare a flag with that name: + +```nu +def greet [--help] { "hi" } +# => Error: nu::parser::error +# => +# => × The `--help` flag is reserved +# => ╭─[repl_entry #1:1:12] +# => 1 │ def greet [--help] { "hi" } +# => · ───┬── +# => · ╰── every command already has `--help` +# => ╰──── +# => help: Rename this flag. `--help` always shows the command's help. +``` + +The short form `-h` isn't reserved. Another flag can take it, as in `--hidden (-h)`, and then `-h` sets that flag while only `--help` shows the help. A command defined with `def --wrapped` gets no `--help` flag at all, as described in [Rest Parameters with Wrapped External Commands](#rest-parameters-with-wrapped-external-commands). + We can extend the help further with some simple comments describing the command and its parameters: ```nu @@ -1225,7 +1460,7 @@ scope commands | wrap help ``` -This will show the Help _record_ that Nushell creates. +This will show the Help _record_ that Nushell creates. Each column is described in [Inspecting commands](/lang-guide/chapters/custom_commands.md#inspecting-commands) in the Language Reference Guide. ::: The comments following the parameters become their description. A comment can continue on the lines below its parameter. Nushell adds each comment-only line, up to the next parameter, to that parameter's description as a new line. @@ -1241,6 +1476,28 @@ with attributes with subcommands of the `attr` builtin, prefixed by the `@` symb before the definition of the command. For those coming from Python, Java, or JavaScript, this will appear similar to decorators or annotations, but serve a slightly different purpose. +Each attribute goes on its own line, directly above `def`, `export def` or `extern`, and you can stack as many as you need. The command's doc comment goes above the attribute lines. A comment between an attribute and the definition is an error, because the attribute is then followed by something other than a definition: + +```nu +@category math +# Double a number +def double [] { $in * 2 } +# => Error: nu::parser::attribute_requires_definition +# => +# => × Attributes must be followed by a definition. +# => ╭─[repl_entry #1:1:2] +# => 1 │ @category math +# => · ──────┬────── +# => · ╰── must be followed by a definition +# => 2 │ # Double a number +# => ╰──── +# => help: try following this line with a `def` or `extern` definition +``` + +To put an attribute on the same line as the definition, end it with `;`, as in `@category math; def double [] { $in * 2 }`. Without the `;`, `def` is read as another argument to the attribute. + +Nushell evaluates an attribute's arguments while it parses the definition, so they must be [constants](./variables.md#constant-variables): literal values or `const` variables. With `let section = "math"`, `@category $section` fails with a `nu::shell::not_a_constant` error, while `const section = "math"` works. + Let's improve the documentation for the `vip-greet` custom command. The `example` attribute adds to the output of `help {command}` or `{command} -h`: @@ -1309,6 +1566,22 @@ Examples: And a special welcome to our VIP today, Bob! ``` +The example can also be a string instead of a block. Nushell checks that a block parses, but keeps a string exactly as written: + +```nu +@example "Greet the guests listed in a file" "vip-greet Bob ...(open guests.txt | lines)" +``` + +The examples are also stored in the `examples` column of [`scope commands`](/commands/docs/scope_commands.md), as a table with `description`, `example` and `result` columns: + +```nu +scope commands | where name == vip-greet | get 0.examples.example +# => ╭───┬───────────────────────────────────╮ +# => │ 0 │ vip-greet "Bob" │ +# => │ 1 │ vip-greet "Bob" "Alice" "Charlie" │ +# => ╰───┴───────────────────────────────────╯ +``` + When maintaining a script, module, plugin, or library written in nu, some custom commands may end up being replaced by newer versions or removed completely, but remain available temporarily to give users time to transition away from the older @@ -1348,8 +1621,58 @@ greet "bob" # => Hello, bob! ``` -By default, the warning is only shown the first time the command is used in a session. Add -`--report every` to warn on every call. +The `--report` flag sets how often the warning appears. With the default, `--report first`, it is +only shown the first time the command is used in a session. `--report every` warns on every call. + +Two more flags take version strings. `--since` gives the version that deprecated the command, and +`--remove` gives the version that will remove it. Each one replaces its part of the warning text: + +```nu +@deprecated --since 0.9.0 --remove 1.0.0 +def greet [] { "hi" } + +greet +# => Warning: nu::parser::deprecated +# => +# => ⚠ Command deprecated. +# => ╭─[repl_entry #2:1:1] +# => 1 │ greet +# => · ──┬── +# => · ╰── greet was deprecated in 0.9.0 and will be removed in 1.0.0. +# => ╰──── +# => +# => hi +``` + +To deprecate a single flag instead of the whole command, name it with `--flag`, without its +dashes. Calls that don't use the flag get no warning: + +```nu +@deprecated "Use --upper instead." --flag caps +def greet [--caps, --upper] { if $caps or $upper { "HI" } else { "hi" } } + +greet --upper +# => HI +greet --caps +# => Warning: nu::parser::deprecated +# => +# => ⚠ Flag deprecated. +# => ╭─[repl_entry #3:1:7] +# => 1 │ greet --caps +# => · ───┬── +# => · ╰── greet --caps is deprecated and will be removed in a future release. +# => ╰──── +# => help: Use --upper instead. +# => +# => HI +``` + +Nushell doesn't check that the command has a flag with the name you give `--flag`, so a misspelled +name never produces a warning. + +The `deprecation_info` column of [`scope commands`](/commands/docs/scope_commands.md) lists each +deprecation as a record with the fields `type`, `label`, `flag`, `since`, `expected_removal` and +`help`. `type` is `Command` or `Flag`, and `label` holds the warning text. If there is a replacement command or additional context that would assist the user when updating their workflows, add text after `@deprecated`. @@ -1395,6 +1718,11 @@ help commands | where category == deprecated | select name category command_type # => ╰───┴───────┴────────────┴──────────────╯ ``` +Any string can be a category. A name that matches a built-in category, such as `math`, `strings` +or `deprecated`, puts the command in that category. Any other name, such as `"deploy"`, starts a +new category. The exception is `core`, which is kept for Nushell's own commands, so +`@category core` gives the category `custom_core`. + Attributes also work on [`extern`](externs.md) declarations. One of them, [`@structured`](/commands/docs/attr_structured.md), applies only to `extern`. It lets an external command return data instead of text. See [Structured Output](externs.md#structured-output) for examples. diff --git a/book/variables.md b/book/variables.md index ca6c82d6e26..275d518e2f1 100644 --- a/book/variables.md +++ b/book/variables.md @@ -64,6 +64,8 @@ $greeting If you don't want to see the value at the end of a pipeline, add `| ignore`, or use the regular `let nums = ...` form. +After a pipe, only the form without `=` works. `[3 1 2] | let nums = $in` is a `nu::parser::assignment_requires_variable` error. Write `[3 1 2] | let nums` or `let nums = [3 1 2]` instead. + ### Mutable Variables A mutable variable is allowed to change its value by assignment. These are declared using the `mut` keyword. @@ -93,6 +95,32 @@ There are a couple of assignment operators used with mutable variables ::: +The right-hand side of an assignment can be a whole pipeline: + +```nu +mut file_count = 0 +$file_count = ls | length +``` + +An assignment doesn't produce a value. If it is the last statement of a block or custom command, the result is `null`, so end with the variable itself when you want the new value back. + +All of the assignment operators also work on part of a value, through a [cell path](/lang-guide/chapters/types/basic_types/cellpath.md). This updates a field of a mutable record, an item of a mutable list, or an environment variable: + +```nu +mut stats = { hits: 0, sizes: [10 20] } +$stats.hits += 1 +$stats.sizes.1 *= 3 +$stats | to nuon +# => {hits: 1, sizes: [10, 60]} + +$env.RETRIES = 1 +$env.RETRIES += 1 +$env.RETRIES +# => 2 +``` + +`=` can create a new field, as in `$stats.misses = 0`. The compound operators read the field first, so they fail with `nu::shell::column_not_found` when it doesn't exist yet. + #### More on Mutability Closures and nested `def`s cannot capture mutable variables from their environment. For example @@ -193,6 +221,22 @@ generate {|weather_station| } ``` +`generate` can also read a list or stream from its input. The closure then gets each input item as its first argument and the state from the previous call as its second. Generation stops when the input runs out, or earlier if the closure returns no `next`. This keeps a running total without a mutable variable: + +```nu +[3 1 4 1 5] | generate {|n, total = 0| + let total = $total + $n + {out: $total, next: $total} +} +# => ╭───┬────╮ +# => │ 0 │ 3 │ +# => │ 1 │ 4 │ +# => │ 2 │ 8 │ +# => │ 3 │ 9 │ +# => │ 4 │ 14 │ +# => ╰───┴────╯ +``` + ### Performance Considerations Using [filter commands](/commands/categories/filters.html) with immutable variables is often far more performant than mutable variables with traditional flow-control statements such as `for` and `while`. For example: @@ -254,6 +298,18 @@ $a # => ╰──── ``` +A constant isn't deleted, only hidden. `unlet` on a `const` makes the parser forget the name from that point on, so a later `$x` is a parse error, but a command or closure defined earlier keeps using the value: + +```nu +const x = 42 +def show [] { $x } +unlet $x +show +# => 42 +``` + +See [`unlet`](/lang-guide/chapters/declarations.md#unlet) in the Language Reference Guide for the details. + ## Variable Names Variable names in Nushell come with a few restrictions as to what characters they can contain. In particular, they cannot contain these characters: diff --git a/lang-guide/chapters/custom_commands.md b/lang-guide/chapters/custom_commands.md index f50eb109e3b..d4ba2a1a3d7 100644 --- a/lang-guide/chapters/custom_commands.md +++ b/lang-guide/chapters/custom_commands.md @@ -11,10 +11,14 @@ def []: -> { } ``` - The name may contain spaces to make a subcommand, e.g. `def "str shout" [] { ... }`. Parser keywords such as `if`, `let` or `def` cannot be used as names. +- A name whose first word is a value literal (a number, filesize, duration, datetime, binary literal or range, such as `5sec` or `1..2`), or that contains `#`, `^` or `%`, or uses whitespace other than single spaces between words, could never be called. `def`, `extern` and `alias` reject it with `nu::parser::variable_not_valid` ("Command name not supported"). See [Naming Commands](/book/custom_commands.md#naming-commands). +- The name and the signature must be separated by whitespace. `def greet[name] {}` fails with "no space between name and parameters". +- The signature may be written in parentheses instead of brackets: `def add (a: int, b: int) { $a + $b }`. +- The body must be written out as a `{ ... }` block. A variable holding a closure is rejected with `Parse mismatch: expected definition body closure { ... }`. - A block can define each name once. A second `def` or `extern` with the same name in the same block (including a whole script or module) is a `nu::parser::duplicate_command_def` error. A `def` in a nested block shadows the outer one inside that block, and each REPL entry is a new block, so redefining a command at the prompt replaces it. See [Defining a command more than once](/book/custom_commands.md#defining-a-command-more-than-once). - The `: -> ` part is optional. Several input/output pairs can be given in brackets: `[int -> int, string -> string]`. - `def --env` keeps changes the body makes to the environment (see [Function Scope](#function-scope)). -- `def --wrapped` passes unknown flags through to a `...rest` parameter as strings, which is useful for wrapping external commands. +- `def --wrapped` passes unknown flags and arguments through to a `...rest` parameter, which is useful for wrapping external commands. The rest parameter is required (`nu::parser::missing_positional` without one) and must be untyped or `string` (`nu::parser::type_mismatch_help` otherwise). An untyped rest parameter has the `external_arg` shape, so bare words and flags arrive as the strings that were typed, while a subexpression keeps its value. A wrapped command gets no `--help` flag, so `--help` and `-h` go to the rest parameter. See [Rest Parameters with Wrapped External Commands](/book/custom_commands.md#rest-parameters-with-wrapped-external-commands). - A comment directly above the `def`, and comments after each parameter, become the command's `help` text. - Inside a [module](/book/modules.md), `export def` makes the command available to `use`. @@ -159,7 +163,17 @@ apply {|v| $v * 10 } 4 | `--flag: type = value` | Flag with a default value | the default | | `...rest`, `...rest: type` | Any number of remaining positional arguments, as a list | `[]` | -Parameters can be separated by spaces, commas or newlines. Without a type, a parameter accepts `any` value. Flag values can be written as `--flag value` or `--flag=value`, and switches as `--flag` or `--flag=false`. +Parameters can be separated by spaces, commas or newlines, and a parameter name may be written with a leading `$` (`def f [$x]`). Without a type, a parameter accepts `any` value, unless it has a default value, in which case it takes the default's type, so `count = 1` only accepts an `int`. A `null` default gives the type `nothing`, so write `x?` or `x: any = null` for a parameter that may be left out. A flag with a default but no type, such as `--count = 1`, is a flag that takes a value of that type, not a switch. Flag values can be written as `--flag value` or `--flag=value`, and switches as `--flag` or `--flag=false`. + +The parser also checks these rules: + +- Required positional parameters come before optional ones. A required parameter after an optional one is a `nu::parser::required_after_optional` error. +- Inside the body, an optional parameter `name?: T` without a default has the type `oneof`, because it is `null` when the argument is left out. +- A default value must be a parse-time constant: a literal, an expression of literals, or a `const` variable. Anything else is a `nu::parser::non_constant_default_value` error. +- There can be only one rest parameter (`nu::parser::multiple_rest_params`). It must be the last positional parameter (`nu::parser::positional_after_rest`), though flags may follow it, and it can't have a default value (`nu::parser::assignment_mismatch`). +- `--help` is reserved, so declaring it is an error ("The `--help` flag is reserved"). Its short form `-h` isn't. Another flag may use it, and then `-h` sets that flag instead of showing help. +- A switch can't have a type annotation, so `--flag: bool` is an error. +- `block` is not a valid type. The error's hint says to use `closure` instead. Every parameter binds a variable, and all of them share one namespace: @@ -167,6 +181,7 @@ Every parameter binds a variable, and all of them share one namespace: - A long flag binds its name with `-` replaced by `_`, so `--foo-bar` binds `$foo_bar`. A flag with only a short form, such as `-v`, binds `$v`. - No two parameters or flags may bind the same variable, and no two flags may share a short letter. A repeat is a `nu::parser::duplicate_parameter` error that points at both uses. - `_` is the exception. Positional parameters named `_` may repeat, to ignore arguments. +- The names of the built-in variables `in`, `nu`, `env` and `ans` can't be used, so `def f [in] {}` and `def f [--env] {}` are `nu::parser::name_is_builtin_var` errors. See [Reserved Names](./declarations.md#reserved-names). - Nushell doesn't check `extern` signatures, because an `extern` binds no variables. See [Flags](/book/custom_commands.md#flags) in the Book for an example of the error. @@ -204,3 +219,41 @@ def f [x: int] { $x }; f "a" ``` See [Parameters](/book/custom_commands.md#parameters) and [Rest Parameters with Wrapped External Commands](/book/custom_commands.md#rest-parameters-with-wrapped-external-commands) in the Book for more examples, and [Type Signatures](./types/type_signatures.md) for the type syntax. + +## Inspecting commands + +[`scope commands`](/commands/docs/scope_commands.md) returns a row for every command in scope, built-in or custom. [`help commands`](/commands/docs/help_commands.md) gives a shorter view of the same commands. The columns of `scope commands` are: + +| Column | Contents | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | The command name. A subcommand's name contains a space. | +| `category` | The category, set with `@category` for a custom command. Empty for a custom command without one. | +| `signatures` | A record with one key per input type. Each value is a table of the command's parameters (see below). | +| `description` | The first paragraph of the doc comment. | +| `examples` | A table with `description`, `example` and `result` columns, from `@example`. | +| `attributes` | A table with `name` and `value` columns for the attributes Nushell stores rather than applies, such as `@deprecated` and [your own attributes](/book/custom_commands.md#defining-your-own-attributes). | +| `type` | `built-in`, `custom`, `keyword`, `plugin`, or `external` for a command declared with `extern`. | +| `is_sub` | `true` when the name contains a space. | +| `is_const` | `true` when the command can run at parse time. See [`const`](./declarations.md#const). | +| `creates_scope` | `false` for every command in Nushell 0.117.0. | +| `extra_description` | The rest of the doc comment. | +| `search_terms` | The `@search-terms` values, joined with `, `. | +| `complete` | The command-wide completer set with `@complete`: the `decl_id` of the completer command, `external` for `@complete external`, or `null`. | +| `deprecation_info` | A table with a row for each `@deprecated` attribute: `type` (`Command` or `Flag`), `label`, `flag`, `since`, `expected_removal` and `help`. | +| `decl_id` | A number that identifies the command in this session. The `complete` column and the `aliased_decl_id` column of `scope aliases` refer to commands by this number. | + +Each table in `signatures` has a row for the input type, one for each parameter and flag, and one for the output type. Its columns are `parameter_name`, `parameter_type`, `syntax_shape`, `is_optional`, `short_flag`, `description`, `completion` and `parameter_default`. `parameter_type` is one of `input`, `positional`, `rest`, `named` (a flag that takes a value), `switch` or `output`. The built-in `--help` flag isn't listed. + +```nu +def greet [name: string, --times (-t): int = 1, --loud]: nothing -> string { "" } +scope commands | where name == greet | get 0.signatures.nothing | select parameter_name parameter_type syntax_shape short_flag parameter_default +# => ╭───┬────────────────┬────────────────┬──────────────┬────────────┬───────────────────╮ +# => │ # │ parameter_name │ parameter_type │ syntax_shape │ short_flag │ parameter_default │ +# => ├───┼────────────────┼────────────────┼──────────────┼────────────┼───────────────────┤ +# => │ 0 │ │ input │ nothing │ │ │ +# => │ 1 │ name │ positional │ string │ │ │ +# => │ 2 │ times │ named │ int │ t │ 1 │ +# => │ 3 │ loud │ switch │ │ │ │ +# => │ 4 │ │ output │ string │ │ │ +# => ╰───┴────────────────┴────────────────┴──────────────┴────────────┴───────────────────╯ +``` diff --git a/lang-guide/chapters/declarations.md b/lang-guide/chapters/declarations.md index e93debbc3bb..9d32ead3f4a 100644 --- a/lang-guide/chapters/declarations.md +++ b/lang-guide/chapters/declarations.md @@ -34,6 +34,23 @@ let x: int = "ten" # => ╰──── ``` +The parser can only check a value whose type it knows. When the right-hand side is a command whose output type is `any`, such as [`from json`](/commands/docs/from_json.md) or a custom command without an output type, Nushell checks the value again when the `let` runs: + +```nu +let x: int = '"five"' | from json +# => Error: nu::shell::type_mismatch +# => +# => × Type mismatch. +# => ╭─[repl_entry #1:1:1] +# => 1 │ let x: int = '"five"' | from json +# => · ─┬─ ────┬──── +# => · │ ╰── the value is a string +# => · ╰── expected int, got string +# => ╰──── +``` + +Assigning to an annotated `mut` variable is checked the same way. This runtime check is the experimental option `enforce-runtime-annotations`, which is on by default. To turn it off, start Nushell with `--experimental-options '[enforce-runtime-annotations=false]'`. The annotation is then only checked by the parser, and `$x` above would hold the string. See [Experimental options](/book/configuration.md#experimental-options) in the Book. + `let` without `=` takes its value from the pipeline. It also passes that value on, so it can sit at the end or in the middle of a pipeline: ```nu @@ -46,6 +63,21 @@ let x: int = "ten" # => 3 ``` +After a pipe, only this form is allowed. `let x = ...` after a `|` is an error, even when the value is `$in`: + +```nu +[a b] | let x = $in +# => Error: nu::parser::assignment_requires_variable +# => +# => × Assignment operations require a variable. +# => ╭─[repl_entry #1:1:9] +# => 1 │ [a b] | let x = $in +# => · ──┬── +# => · ╰── needs to be a variable +# => ╰──── +# => help: try assigning to a variable or a cell path of a variable +``` + An immutable variable cannot be assigned to, but a new `let` with the same name _shadows_ the old one: ```nu @@ -87,6 +119,39 @@ mut rec = {a: {b: 1}}; $rec.a.b = 2; $rec.c = 3; $rec # => ╰───┴───────────╯ ``` +The compound operators work on cell paths too, including fields of `$env`: + +```nu +mut rec = {a: 1, b: {c: [10 20]}, ratio: 1.0}; $rec.a += 5; $rec.b.c.0 -= 1; $rec.b.c.1 *= 3; $rec.ratio /= 4; $rec | to nuon +# => {a: 6, b: {c: [9, 60]}, ratio: 0.25} +``` + +```nu +$env.COUNT = 1; $env.COUNT += 1; $env.COUNT +# => 2 +``` + +A compound operator reads the current value first, so the field has to exist. `$rec.z += 1` on a record without a `z` field is a `nu::shell::column_not_found` error, while `$rec.z = 1` adds the field. + +As with `let`, the right-hand side of an assignment is a whole pipeline: + +```nu +mut count = 0; $count = [a b c] | length; $count +# => 3 +``` + +An assignment is a statement and produces no value. A block or command whose last statement is an assignment returns `null`, so end it with the variable to return the new value: + +```nu +def bump [] { mut n = 1; $n += 1 }; bump | describe +# => nothing +``` + +```nu +def bump [] { mut n = 1; $n += 1; $n }; bump +# => 2 +``` + The variable's type comes from its annotation or, if there is none, from the initial value. Assignments are type-checked while parsing, so a variable that starts as an `int` cannot later hold a `string`, and `/=` (which produces a float) is rejected on an `int`. Annotate the variable (for example `mut x: any = 1`) if it must hold other types: ```nu @@ -135,6 +200,31 @@ const x = (ls | length) # => ╰──── ``` +[`if`](/commands/docs/if.md) can run at parse time, so a constant can be chosen from other constants or from `$nu`, for example `const x = if $nu.is-interactive { ... } else { null }`: + +```nu +const debug = false +const log_level = if $debug { "debug" } else { "info" } +$log_level +# => info +``` + +`match`, `try` and `do` can't run at parse time. Using them in a `const` is a `nu::shell::not_a_const_command` error like the one above. + +::: details Commands that can run at parse time + +In Nushell 0.117.0, without plugins, `scope commands | where is_const` lists these 88 commands: + +- Core: `const`, `describe`, `echo`, `first`, `get`, `if`, `ignore`, `last`, `version` +- Attributes: `attr category`, `attr complete`, `attr complete external`, `attr deprecated`, `attr example`, `attr interactive`, `attr search-terms`, `attr structured` +- Strings: `ansi`, `char`, `detect columns`, `parse`, `split chars`, `split column`, `split list`, `split row`, `split words`, `str capitalize`, `str contains`, `str distance`, `str downcase`, `str ends-with`, `str escape-regex`, `str expand`, `str index-of`, `str join`, `str length`, `str lowercase`, `str replace`, `str reverse`, `str starts-with`, `str stats`, `str substring`, `str trim`, `str upcase`, `str uppercase` +- Bytes and formats: `bytes length`, `decode`, `decode base32`, `decode base32hex`, `decode base64`, `decode hex`, `encode`, `encode base32`, `encode base32hex`, `encode base64`, `encode hex`, `format date`, `format duration`, `format filesize` +- Math: `math abs`, `math avg`, `math cbrt`, `math ceil`, `math floor`, `math log`, `math max`, `math median`, `math min`, `math mode`, `math product`, `math round`, `math sqrt`, `math stddev`, `math sum`, `math variance` +- Paths: `path basename`, `path dirname`, `path exists`, `path expand`, `path join`, `path parse`, `path relative-to`, `path self`, `path split`, `path type` +- System: `config default`, `sys host`, `uname` + +::: + Constants are required wherever the parser needs a value: the path given to `source` or `use`, and a value pattern in `match`. For example, with a file `greet.nu` containing `export def hello [name: string] { $"Hello, ($name)!" }`: ```nu @@ -176,6 +266,15 @@ unlet $nu # => ╰──── ``` +A constant behaves differently, because the parser copies a constant's value into the code that uses it. `unlet` on a constant hides the name from the parser for the rest of the current block, so a later `$x` is a parse error (`nu::parser::variable_not_found`) and nothing in the block runs. Code parsed before the `unlet`, such as a command or closure that uses the constant, keeps its value: + +```nu +const x = 42; def show [] { $x }; unlet $x; show +# => 42 +``` + +With `let x = 42`, the same `show` fails with `nu::shell::variable_not_found` when it runs, because the variable is gone. A constant hidden inside a nested block, as in `do { unlet $x }`, is visible again after that block. At the REPL, a constant hidden at the top level stays hidden in later entries. + ## `type` `type` declares a type alias, a name that stands for a type signature. How aliases expand is described in [Type aliases](./types/type_signatures.md#type-aliases). This section covers where one is visible. @@ -217,9 +316,11 @@ In a module, a type alias is private unless it is declared with `export type`. A `type` and `export type` are parser keywords. A command, alias or extern can't be named `type` (`nu::parser::name_is_keyword`), and `alias ty = type` is an error (`nu::parser::cant_alias_keyword`). +A type alias can't take the name of a built-in type such as `int` or `number` (`nu::parser::type_alias_shadows_builtin`), and it has no type parameters, so `Point` is a `nu::parser::type_alias_with_params` error. See [Type Aliases](/book/custom_commands.md#type-aliases) in the Book for the full list of reserved names. + ## Reserved Names -The names of the built-in variables `nu`, `env`, `in` and `ans` cannot be used for your own variables: +The names of the built-in variables `nu`, `env`, `in` and `ans` cannot be used for your own variables. The rule covers `let`, `mut` and `const`, and also the parameters and flags of a custom command, so `def f [in] {}` and `def f [--env] {}` fail the same way: ```nu let ans = 1 diff --git a/lang-guide/chapters/variable_scope.md b/lang-guide/chapters/variable_scope.md index 90226ea51a6..0f0109dbd3e 100644 --- a/lang-guide/chapters/variable_scope.md +++ b/lang-guide/chapters/variable_scope.md @@ -97,6 +97,21 @@ def outer [] { def helper [] { 'helper' }; helper }; outer # => helper ``` +An alias used above its definition isn't found, so Nushell runs the name as an external command: + +```nu +ll; alias ll = ls -l +# => Error: nu::shell::external_command +# => +# => × External command failed +# => ╭─[repl_entry #1:1:1] +# => 1 │ ll; alias ll = ls -l +# => · ─┬ +# => · ╰── Command `ll` not found +# => ╰──── +# => help: Did you mean `all`? +``` + ## Environment Scope Changes to `$env`, including the current directory changed with `cd`, stay visible after `if`/`else`, `match`, `for`, `while`, `loop` and `try` (including its `catch` and `finally` parts). They are discarded when a closure or custom command returns, unless the closure is run with `do --env` or the command is defined with `def --env`. From 1b590690b35a6a0465f4a5d639341adfa64068a1 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:10:27 -0600 Subject: [PATCH 08/46] Fill gaps in the data type docs Covers the rows rated `some` in the coverage checklist for data types, literals, annotations, and type signatures: - int, float, duration, filesize, binary, datetime, range: literal rules and spellings, operators and their errors, conversions, rounding, and how file sizes and dates are displayed and formatted - custom values: annotations, `into value`, plugin custom values, semver, semver ranges, and matrices - new pages for the `number` and `external_arg` types, and a fix to the not-assignable types page, which said every annotated variable behaves like `string` - bool.md no longer lists the regex and starts-with/ends-with operators as bool operators - the octal example in types_of_data.md was a parse error The new pages are added to the sidebar. --- .vuepress/configs/sidebar/en.ts | 6 +- book/types_of_data.md | 24 +++- lang-guide/chapters/types/basic_types/any.md | 13 ++ .../chapters/types/basic_types/binary.md | 68 ++++++++- lang-guide/chapters/types/basic_types/bool.md | 8 +- .../chapters/types/basic_types/cellpath.md | 41 ++++++ .../chapters/types/basic_types/closure.md | 27 ++++ .../chapters/types/basic_types/datetime.md | 99 +++++++++++++ .../chapters/types/basic_types/duration.md | 48 +++++-- .../chapters/types/basic_types/filesize.md | 86 +++++++++++- .../chapters/types/basic_types/float.md | 54 ++++++- lang-guide/chapters/types/basic_types/glob.md | 66 +++++++++ lang-guide/chapters/types/basic_types/int.md | 131 ++++++++++++++++- .../chapters/types/basic_types/nothing.md | 20 +++ .../chapters/types/basic_types/number.md | 64 +++++++++ .../chapters/types/basic_types/range.md | 61 ++++++++ .../chapters/types/basic_types/string.md | 15 ++ .../chapters/types/basic_types/table.md | 39 ++++++ .../types/other_types/00_not_assignable.md | 7 +- .../types/other_types/custom_value.md | 132 ++++++++++++++++++ .../types/other_types/external_arg.md | 48 +++++++ lang-guide/chapters/types/other_types/path.md | 29 ++++ lang-guide/chapters/types/related_commands.md | 16 +++ lang-guide/chapters/types/type_signatures.md | 41 ++++++ 24 files changed, 1118 insertions(+), 25 deletions(-) create mode 100644 lang-guide/chapters/types/basic_types/number.md create mode 100644 lang-guide/chapters/types/other_types/external_arg.md diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts index fec7effc5cb..21578d95c55 100644 --- a/.vuepress/configs/sidebar/en.ts +++ b/.vuepress/configs/sidebar/en.ts @@ -193,6 +193,7 @@ export const sidebarEn: SidebarConfig = { collapsible: true, children: [ '/lang-guide/chapters/types/basic_types/any.md', + '/lang-guide/chapters/types/basic_types/number.md', '/lang-guide/chapters/types/basic_types/bool.md', '/lang-guide/chapters/types/basic_types/int.md', '/lang-guide/chapters/types/basic_types/float.md', @@ -218,7 +219,10 @@ export const sidebarEn: SidebarConfig = { { text: 'Types used only in command signatures', link: '/lang-guide/chapters/types/other_types/00_not_assignable.md', - children: ['/lang-guide/chapters/types/other_types/path.md'], + children: [ + '/lang-guide/chapters/types/other_types/path.md', + '/lang-guide/chapters/types/other_types/external_arg.md', + ], }, { text: 'Types which are not declarable', diff --git a/book/types_of_data.md b/book/types_of_data.md index 49e3bded1f8..38cd4f66524 100644 --- a/book/types_of_data.md +++ b/book/types_of_data.md @@ -42,6 +42,7 @@ Each type below lists its _annotation_: the name you write after `:` to declare | [Blocks](#blocks) | `if true { print "hello!" }`, `loop { print "press ctrl-c to exit" }` | | [Null (Nothing)](#nothing-null) | `null` | | [Any](#any) | `let p: any = 5` | +| [Number](#number) | `let n: number = 2.5` | | [SemVer](#semantic-versions) | `'1.2.3' \| into semver` | ## Basic Data Types @@ -291,7 +292,7 @@ Closures are a useful way to represent code that can be executed on each row of | **_Description:_** | Represents binary data | | **_Annotation:_** | `binary` | | **_Literal Syntax:_** | `0x[ffffffff]` - hex-based binary representation | -| | `0o[1234567]` - octal-based binary representation | +| | `0o[377 001]` - octal-based binary representation | | | `0b[10101010101]` - binary-based binary representation | | **_See also:_** | [Language Guide - Binary](/lang-guide/chapters/types/basic_types/binary.md) | @@ -395,6 +396,25 @@ Internally, tables are simply **lists of records**. This means that any command | **_Literal syntax:_** | N/A - Any literal value can be assigned to an `any` type | | **_See also:_** | [Language Reference - Any](/lang-guide/chapters/types/basic_types/any.md) | +### Number + +| | | +| --------------------- | ---------------------------------------------------------------------------------- | +| **_Description:_** | When used in a type annotation or signature, matches either an `int` or a `float`. | +| **_Annotation:_** | `number` | +| **_Literal syntax:_** | N/A - Any int or float literal can be assigned to a `number` type | +| **_See also:_** | [Language Reference - Number](/lang-guide/chapters/types/basic_types/number.md) | + +A value keeps its own type, so `describe` reports `int` or `float`. `number` shows up in `describe` output only for a collection that mixes the two: + +```nu +let n: number = 2.5 +$n | describe +# => float +[1 2.5] | describe +# => list +``` + ### Blocks | | | @@ -455,3 +475,5 @@ Simple example - Semantic versions compare by version number, not as text: '1.2.3' | into semver | semver bump minor # => 1.3.0 ``` + +A semver's parts can be read with a cell path (`$v.major`, `$v.minor`, `$v.patch`, `$v.pre`, `$v.build` and `$v.prefix`), and a version range from `into semver-range` tests versions with `in`. The [SemVer section](/lang-guide/chapters/types/other_types/custom_value.md#semver) of the Language Reference covers these, along with `into semver --loose` and record input. diff --git a/lang-guide/chapters/types/basic_types/any.md b/lang-guide/chapters/types/basic_types/any.md index 80bf8436e1c..4c16ac71b7b 100644 --- a/lang-guide/chapters/types/basic_types/any.md +++ b/lang-guide/chapters/types/basic_types/any.md @@ -71,3 +71,16 @@ [] | describe # => list ``` + + Two mixes don't become a `oneof`. Ints mixed with floats widen to `number`. Records widen to a `table` that keeps only the columns every record has, so records with no key in common give a `table` with no columns. A column whose values differ in type becomes a `oneof` inside the table: + + ```nu + [1 2.0] | describe + # => list + [{a: 1} {a: 2, b: 3}] | describe + # => table + [{a: 1} {b: 2}] | describe + # => table + [{a: 1} {a: "x"}] | describe + # => table> + ``` diff --git a/lang-guide/chapters/types/basic_types/binary.md b/lang-guide/chapters/types/basic_types/binary.md index c79f500a44d..ee8cd779cdc 100644 --- a/lang-guide/chapters/types/basic_types/binary.md +++ b/lang-guide/chapters/types/basic_types/binary.md @@ -12,16 +12,78 @@ ## Additional Language Notes -1. Incomplete bytes are left-padded with zeros. Spaces are ignored, so the padding applies to the literal as a whole: +1. Incomplete bytes are left-padded with zeros. Spaces, commas and line breaks are ignored, so the padding applies to the literal as a whole, not to each group. `0x[1,2]` is the single byte `0x12`, not the two bytes `01` and `02`: ```nu 0x[1 23] | to nuon # => 0x[0123] + 0x[1,2] | to nuon + # => 0x[12] ``` -2. Spaces can be used to improve readability. For example, `0x[ffff ffff]`. +2. Spaces, commas and line breaks can be used to improve readability, as in `0x[ffff ffff]`. A `#` comment can end a line inside the brackets: -3. In an octal literal, each byte is written as three octal digits between `000` and `377`. + ```nu + 0x[ + de ad # first half + be ef + ] | to nuon + # => 0x[DEADBEEF] + ``` + +3. In an octal literal, each byte is written as three octal digits between `000` and `377`. As with hex, the digits are read as one run and padded on the left, so `0o[1]` is the byte `0x01` and `0o[12 3]` is the byte `0o123`. + +4. `0x[]` is an empty binary value, with a length of `0`. + +5. The prefixes `0x`, `0o` and `0b` are lowercase only. Hex digits can be either case. `0X[ff]` is not a binary literal. At the start of a pipeline it is taken as a command name, and elsewhere it is a string. + +6. A digit that doesn't belong to the base, or an octal byte above `377`, is a parse error. The help text names the digits the base accepts: + + ```nu + 0o[400] + # => Error: nu::parser::invalid_binary_string + # => + # => × Invalid binary string. + # => ╭─[repl_entry #1:1:1] + # => 1 │ 0o[400] + # => · ───┬─── + # => · ╰── invalid binary string + # => ╰──── + # => help: octal strings must have a length that is a multiple of three and + # => contain values between 0o000 and 0o377. + ``` + +## Showing the bits with `format bits` + +[`format bits`](/commands/docs/format_bits.md) returns a string of `0`s and `1`s, with a space between bytes. It accepts more than binary values: + +- A binary value or a string shows its bytes in order. A string shows its UTF-8 bytes, so `"é" | format bits` is `11000011 10101001`. +- An int, file size, duration or bool is shown as a signed number in the fewest bytes that hold it: 1, 2, 4 or 8. A file size counts bytes and a duration counts nanoseconds, and `true` is `1`. + +```nu +42 | format bits +# => 00101010 +128 | format bits +# => 00000000 10000000 +-1 | format bits +# => 11111111 +1kB | format bits +# => 00000011 11101000 +``` + +Numbers are shown in big-endian order by default. `--endian` (`-e`) takes `big`, `little` or `native`, the byte order of the machine running Nushell. It has no effect on binary values or strings: + +```nu +258 | format bits --endian little +# => 00000010 00000001 +``` + +For a table or record, name the columns to convert as cell paths after the command. A record or table without them, a list, and a float are all rejected: + +```nu +[[a b]; [1 256]] | format bits a b | to nuon +# => [[a, b]; ["00000001", "00000001 00000000"]] +``` ## Common commands that can be used with `binary` diff --git a/lang-guide/chapters/types/basic_types/bool.md b/lang-guide/chapters/types/basic_types/bool.md index 7f1f897d971..f51c123463d 100644 --- a/lang-guide/chapters/types/basic_types/bool.md +++ b/lang-guide/chapters/types/basic_types/bool.md @@ -24,11 +24,11 @@ The following commands take a closure (or a row condition) as their main argumen ## Common operators that can be used with `bool` -- `==`, `!=`, `<`, `<=`, `>`, `>=` +- `==`, `!=`, `<`, `<=`, `>`, `>=`. When ordered, `false` comes before `true`, so `false < true` is `true`. - `and`, `or`, `xor`, `not` -- `in` -- Regex comparison operators: `=~`, `!~` `` -- String comparison operators: `ends-with`, `starts-with` +- `in`, `not-in`, `has` and `not-has`, to test whether a list holds a bool, as in `true in [true false]` + +The regex operators `=~` and `!~` (also spelled `like` and `not-like`), and `starts-with` and `ends-with`, return a bool, but they compare strings. A bool operand is a parse error, as in `true =~ "t"`. See [Comparison Operators](../../operators.md#comparison-operators). ## Short-circuit evaluation diff --git a/lang-guide/chapters/types/basic_types/cellpath.md b/lang-guide/chapters/types/basic_types/cellpath.md index 0672ce35a6d..b23978b09a9 100644 --- a/lang-guide/chapters/types/basic_types/cellpath.md +++ b/lang-guide/chapters/types/basic_types/cellpath.md @@ -90,6 +90,27 @@ let data = [ A negative int passed to `get` fails at runtime with "can't convert negative number to cell path". Use [`last`](/commands/docs/last.md) to get items from the end of a list. +- Directly on a value: + + A cell path can follow a variable, as in `$data.condition`, and it can also follow a list, record or table literal, or a subexpression in parentheses. There is no need to store the value in a variable or pipe it to `get` first: + + ```nu + [1 2].0 + # => 1 + {a: {b: 2}}.a.b + # => 2 + [[a]; [1] [2]].a | to nuon + # => [1, 2] + (1..5).2 + # => 3 + ({a: 1} | insert b 2).b + # => 2 + ``` + + A command's output in parentheses works the same way, so `(ls).name` is the list of file names. + + A quoted string can't take a cell path. `"abc".0` is a parse error ("Invalid characters after closing delimiter"), and `("abc").0` fails with "string doesn't support cell paths". + ## Additional Language Notes 1. Ordering @@ -166,6 +187,26 @@ let data = [ # => 39.21 ``` + `into cell-path` takes three kinds of input: + + - An int gives a one-member path: `5 | into cell-path` is `$.5`. A negative int is an error. + - A list of ints and strings gives one member per item. An int is a row index and a string is a column name, so the string `"1"` names a column called `1`, not row 1. + - A table with a `value` column gives one member per row. The optional `optional` and `insensitive` columns hold bools that add the `?` and `!` modifiers. Other columns are ignored. + + ```nu + [[value optional insensitive]; [a true false] [B false true]] | into cell-path + # => $.a?.B! + ``` + + A string on its own is rejected on purpose. Text such as `"a.b"` could name the column `a.b` or the path `a` then `b`, so split it yourself, and convert the parts that are row numbers to ints: + + ```nu + "x.1" | split row "." | into cell-path + # => $.x."1" + "x.1" | split row "." | each {|m| try { $m | into int } catch { $m } } | into cell-path + # => $.x.1 + ``` + ## Common commands that can be used with `cell-path` - `get` diff --git a/lang-guide/chapters/types/basic_types/closure.md b/lang-guide/chapters/types/basic_types/closure.md index b7c382f5a35..f763052ef57 100644 --- a/lang-guide/chapters/types/basic_types/closure.md +++ b/lang-guide/chapters/types/basic_types/closure.md @@ -19,11 +19,25 @@ Closures are used in Nu extensively as parameters to iteration style commands li # => 42 ``` + `do --capture-errors` (`-c`) changes how an external command that fails inside the closure is handled. Without the flag, the commands after `do` receive the external's output as it streams, and the non-zero exit code is reported afterward. With it, `do` waits for the external to finish, and if it exited with a non-zero code, the pipeline stops with a `nu::shell::non_zero_exit_code` error before anything downstream sees the output: + + ```nu + try { do { ^nu -c "print out; exit 3" } | lines | each { print $"got ($in)" } | ignore } catch {|err| $"failed with ($err.exit_code)" } + # => got out + # => failed with 3 + try { do -c { ^nu -c "print out; exit 3" } | lines | each { print $"got ($in)" } | ignore } catch {|err| $"failed with ($err.exit_code)" } + # => failed with 3 + ``` + + The flag has no effect on errors from Nushell commands, which stop the pipeline either way. Don't combine it with [`complete`](/commands/docs/complete.md): the error comes before `complete` can record the exit code, so use plain `do` there. + 1. The `|args|` list can also contain 0 arguments (`||`) or more than one argument `|arg1,arg2|` 1. When there are 0 arguments, the `||` is optional as long as the closure cannot be mistaken for a record (which also uses the curly-brace style). - An empty (no-op) closure can be represented as `{||}` + - Empty braces, `{}`, are an empty record where a value is expected, as in `let x = {}` or for a `record` or `any` parameter. Where a command expects a closure, `{}` is an empty closure instead. An empty closure returns its input, so `[1 2 3] | each {}` passes the items through unchanged. + - Braces holding only a variable or expression, such as `{$a}`, are a closure, not a record. See [No field shorthand](record.md#no-field-shorthand). 1. As in other languages with closures, an important feature is their ability to "close over" variables from the parent scope and use their values even after the parent's scope has ended. @@ -107,6 +121,8 @@ Closures are used in Nu extensively as parameters to iteration style commands li A custom command that calls itself from inside a closure (for example from `each` or `do`) uses two levels of the limit for each step, so with the default limit it stops at about 25 levels instead of 50. Raise `$env.config.recursion_limit` in your config if you need more. + Every closure call counts, whether `do` runs the closure, a command such as `each` or `where` runs it for you, or a [hook](/book/hooks.md) runs it. The limit must be greater than 1. Setting it to 1 or less is rejected with "expected an int greater than 1", and the old value stays. + 1. You can also use [pipeline input as `$in`](/book/pipelines.md#pipeline-input-and-the-special-in-variable) in most closures instead of providing an explicit parameter. For example: ```nu @@ -142,6 +158,17 @@ Closures are used in Nu extensively as parameters to iteration style commands li # => 42 ``` + Closure parameters can also be optional (`b?`), have a default value (`c = 5`), or collect the remaining arguments (`...rest`), as the positional parameters of a [custom command](/book/custom_commands.md) can: + + ```nu + do {|a, b?, c = 5, ...rest| {a: $a, b: $b, c: $c, rest: $rest} } 1 | to nuon + # => {a: 1, b: null, c: 5, rest: []} + do {|a, b?, c = 5, ...rest| {a: $a, b: $b, c: $c, rest: $rest} } 1 2 3 4 5 | to nuon + # => {a: 1, b: 2, c: 3, rest: [4, 5]} + ``` + + A missing required argument is a `nu::shell::missing_parameter` error. Extra arguments with no `...rest` parameter to take them are ignored. + ## Common commands that can be used with a `closure` - [`all`](/commands/docs/all.md) diff --git a/lang-guide/chapters/types/basic_types/datetime.md b/lang-guide/chapters/types/basic_types/datetime.md index 969f1769867..a9d29e2697a 100644 --- a/lang-guide/chapters/types/basic_types/datetime.md +++ b/lang-guide/chapters/types/basic_types/datetime.md @@ -9,6 +9,7 @@ | | Date-only: `2022-02-02` | | Date and time (GMT): `2022-02-02T14:30:00` | | Date and time including timezone offset: `2022-02-02T14:30:00+05:00` +| | Date and time in UTC with a `Z` suffix: `2022-02-02T14:30:00Z` | **_Casts:_** | [`into datetime`](/commands/docs/into_datetime.md) | **_See also:_** | [Types of Data - Dates](/book/types_of_data.md#dates) @@ -23,6 +24,104 @@ # => 2022-02-02T14:30:00+05:00 ``` +- A date-only literal is midnight UTC: `2022-02-02 | format date "%+"` is `2022-02-02T00:00:00+00:00`. +- The `T` between the date and the time and the `Z` for UTC can both be lowercase. +- Seconds can have a fraction. Nushell keeps nanosecond precision, the first nine digits, and drops any digits after those: + + ```nu + [2022-02-02T14:30:00Z 2022-02-02t14:30:00z 2022-02-02T14:30:00.123456789Z] | to nuon + # => [2022-02-02T14:30:00+00:00, 2022-02-02T14:30:00+00:00, 2022-02-02T14:30:00.123456789+00:00] + ``` + +- The seconds are required, and the `T` can't be a space. `2022-02-02T14:30` is not a datetime, and `2022-02-02 14:30:00` is two words, a date followed by a word Nushell can't place. +- A word written like a date that names a day that doesn't exist, such as `2023-02-29` or `2023-13-01`, is a parse error: + + ```nu + 2023-02-29 + # => Error: nu::parser::error + # => + # => × Invalid literal + # => ╭─[repl_entry #1:1:1] + # => 1 │ 2023-02-29 + # => · ─────┬──── + # => · ╰── not a valid date in datetime + # => ╰──── + ``` + + Any other text after the date makes the word a bare string, so a file name such as `2024-01-15.log` can be passed without quotes: `echo 2024-01-15.log | describe` is `string`. The same goes for a word that isn't a datetime for the reasons above, such as `2022-02-02T14:30`. Like any bare word, it is taken as a command name if it starts a pipeline. + +## Operators that can be used with `datetime` + +- `+` with a duration on either side gives a datetime. +- `-` with a duration on the right gives a datetime. A duration minus a datetime is an error. +- `-` with another datetime gives the duration between them. +- `==`, `!=`, `<`, `<=`, `>` and `>=` compare the instants that two datetimes name, whatever their offsets. `<`, `<=`, `>` and `>=` accept only another datetime: a string or a duration on the other side is a parse error. Convert a string with [`into datetime`](/commands/docs/into_datetime.md) first. `==` against a value of another type is `false`, not an error. +- `older-than` and `newer-than` take a datetime on the left. With a duration on the right, they count back from now: `$date older-than 2wk` is true when `$date` is more than two weeks in the past. With a datetime on the right, they are the same as `<` and `>`. Both are strict, so a date exactly at the cut-off is neither older nor newer. + +```nu +2024-01-01 + 1day | format date "%F" +# => 2024-01-02 +1day + 2024-01-01 | format date "%F" +# => 2024-01-02 +2024-01-02 - 2024-01-01 +# => 1day +2024-01-01T00:00:00+01:00 == 2023-12-31T23:00:00Z +# => true +2024-01-02 older-than 1day +# => true +``` + +Comparing a datetime with a duration using `<` or `>` is an error whose help points to these operators: + +```nu +2024-01-02 > 1day +# => Error: nu::parser::operator_incompatible_types +# => +# => × Types 'datetime' and 'duration' are not compatible for the '>' operator. +# => ╭─[repl_entry #1:1:1] +# => 1 │ 2024-01-02 > 1day +# => · ─────┬──── ┬ ──┬─ +# => · │ │ ╰── duration +# => · │ ╰── does not operate between 'datetime' and 'duration' +# => · ╰── datetime +# => ╰──── +# => help: to check that a datetime is after now minus a duration, use `newer- +# => than`: `$date newer-than 2wk` +``` + +## Formatting dates + +[`format date`](/commands/docs/format_date.md) turns a datetime into a string. Without a format string it writes the RFC 2822 form: + +```nu +2024-01-15T10:30:00Z | format date +# => Mon, 15 Jan 2024 10:30:00 +0000 +2024-01-15T10:30:00Z | format date "%Y/%m/%d %H:%M" +# => 2024/01/15 10:30 +``` + +The format string uses strftime-style specifiers: `%Y`, `%m` and `%d` for the date, `%H:%M:%S` for the time, `%.3f` for milliseconds, `%s` for Unix seconds, `%+` for RFC 3339, and many more. `format date --list` prints a table of every specifier with an example and a description. A format string that isn't valid, such as a lone `%`, fails with "invalid format". + +The input can also be a string, which is parsed the same way [`into datetime`](/commands/docs/into_datetime.md) parses it, or a list of datetimes and strings: + +```nu +["2024-01-15" 2024-02-01] | format date "%F" +# => ╭───┬────────────╮ +# => │ 0 │ 2024-01-15 │ +# => │ 1 │ 2024-02-01 │ +# => ╰───┴────────────╯ +``` + +A string that isn't a date fails with `nu::shell::datetime_parse_error`. A record or table is rejected, so format a column with `update`, as in `$table | update modified { format date "%F" }`. + +Month and day names, and the locale-dependent specifiers `%c`, `%x`, `%X` and `%r`, follow a locale. Nushell takes it from `$env.LC_ALL`, then `$env.LC_TIME`, then `$env.LANG`, and then from the operating system, falling back to US English: + +```nu +$env.LC_TIME = "de_DE" +2024-01-15T10:30:00Z | format date "%A, %d.%m.%Y" +# => Montag, 15.01.2024 +``` + ## Common commands that can be used with `datetime` Many of Nushell's builtin commands are datetime aware and output or use `datetime` values diff --git a/lang-guide/chapters/types/basic_types/duration.md b/lang-guide/chapters/types/basic_types/duration.md index 8bab0d32ce3..df017a92540 100644 --- a/lang-guide/chapters/types/basic_types/duration.md +++ b/lang-guide/chapters/types/basic_types/duration.md @@ -21,16 +21,38 @@ 1. This chart shows all duration units currently supported: - | Duration | Length | - | --------- | ----------- | - | `ns` | nanosecond | - | `us`/`μs` | microsecond | - | `ms` | millisecond | - | `sec` | second | - | `min` | minute | - | `hr` | hour | - | `day` | day | - | `wk` | week | + | Duration | Length | + | ------------------ | ----------- | + | `ns` | nanosecond | + | `us`, `µs` or `μs` | microsecond | + | `ms` | millisecond | + | `sec` | second | + | `min` | minute | + | `hr` | hour | + | `day` | day | + | `wk` | week | + + The microsecond unit has three spellings: `us`, `µs` with U+00B5 MICRO SIGN, and `μs` with U+03BC GREEK SMALL LETTER MU. The two look alike but are different characters. Nushell displays microseconds with the micro sign, `µs`. + +1. Rules for duration literals: + + - Units are case-sensitive. `1Sec` and `1HR` are not durations. At the start of a pipeline Nushell looks for a command with that name, and anywhere else the word is a string. + - The number can have `_` separators, a leading `+`, an exponent, or a leading dot: `1_000ms`, `+5sec`, `1e3sec` and `.5sec` are all durations. A leading dot can't follow a sign, though. `-.5sec` is a string, so write `-0.5sec`. + - A fraction of a nanosecond is dropped, so `1.5ns` is `1ns`. + - A literal has one number and one unit. `1hr30min` is not a duration. Add the parts instead: `1hr + 30min`. + - A duration is a signed 64-bit count of nanoseconds, which covers about 292 years in either direction. A literal outside that range is a parse error, and arithmetic that leaves it is a `nu::shell::operator_overflow` error: + + ```nu + 9223372036854775808ns + # => Error: nu::parser::literal_too_large + # => + # => × Invalid literal + # => ╭─[repl_entry #1:1:1] + # => 1 │ 9223372036854775808ns + # => · ──────────┬────────── + # => · ╰── duration too large + # => ╰──── + ``` 1. Datetime values can be combined with durations in calculations: @@ -71,3 +93,9 @@ 10sec mod 3sec # => 1sec ``` + +- `+` with a datetime, in either order, and `-` from a datetime. See [Datetime](datetime.md#operators-that-can-be-used-with-datetime). + +A number can also go on the left of `*`, so `2 * 1hr` is `2hr` and `1.5 * 1hr` is `1hr 30min`. It can't go on the left of `/`: `2 / 1hr` is an error. + +A duration and a plain number don't mix in `+`, `-`, `<`, `<=`, `>` or `>=`, because a bare number has no unit. `1hr + 1` and `1hr > 60` are parse errors. Write the unit: `1hr + 1sec`. `==` and `!=` don't fail. Values of different types are never equal, so `1hr == 60` is `false`. diff --git a/lang-guide/chapters/types/basic_types/filesize.md b/lang-guide/chapters/types/basic_types/filesize.md index 269c4eaa903..efc6524c61c 100644 --- a/lang-guide/chapters/types/basic_types/filesize.md +++ b/lang-guide/chapters/types/basic_types/filesize.md @@ -30,7 +30,28 @@ File size units in literals are case-insensitive. E.g., `1KiB`, `1kib`, and `1Ki The unit argument of `format filesize`, however, must be written exactly as in the table above (e.g., `kB` or `KiB`). ::: -By default, file sizes are displayed with metric units (see `$env.config.filesize.unit`): +Other rules for `filesize` literals: + +- A file size is stored as a whole number of bytes. A fraction of a byte is dropped, so `1.5B` is `1 B` and `0.1B` is `0 B`. Fractions of larger units work, and only the part below one byte is dropped: `1.5kB` is 1500 bytes. +- File sizes can be negative, as in `-1kB`, which displays as `-1.0 kB`. +- The number can have `_` separators, a leading `+`, or a leading dot: `1_000kB`, `+2kB` and `.5kB` are all file sizes. As with durations, a leading dot can't follow a sign, so `-.5kB` is a string. Write `-0.5kB` instead. +- The size has to fit in a signed 64-bit count of bytes, a little over 9.2 EB. `8EiB` and anything larger is a parse error: + + ```nu + 8EiB + # => Error: nu::parser::literal_too_large + # => + # => × Invalid literal + # => ╭─[repl_entry #1:1:1] + # => 1 │ 8EiB + # => · ──┬─ + # => · ╰── filesize too large + # => ╰──── + ``` + +## Displaying file sizes + +By default, file sizes are displayed with metric units: ```nu 1500B @@ -39,6 +60,60 @@ By default, file sizes are displayed with metric units (see `$env.config.filesiz # => 1000 kB ``` +Three settings in `$env.config.filesize` control the display: + +- `unit` picks the unit. `"metric"`, the default, and `"binary"` choose a unit to fit each value, from the metric (`kB`, `MB`, ...) or binary (`KiB`, `MiB`, ...) column of the table above. A unit name shows every size in that unit: `"B"`, `"kB"`, `"MB"`, `"GB"`, `"TB"`, `"PB"`, `"EB"`, `"KiB"`, `"MiB"`, `"GiB"`, `"TiB"`, `"PiB"` or `"EiB"`. Unlike in literals, the case must match exactly. `"KB"` and `"kb"` are rejected with "Invalid value for $env.config.filesize.unit", even though `config nu --doc` lists `"KB"`. +- `show_unit` (default `true`) can be set to `false` to leave off the unit. With a fixed unit, every value has the same one anyway. +- `precision` (default `1`) is the number of decimal places. `null` shows all of them. + +```nu +$env.config.filesize.unit = 'binary' +1500B +# => 1.4 KiB +$env.config.filesize.unit = 'MB' +1500B +# => 0.0 MB +``` + +### `format filesize` + +[`format filesize`](/commands/docs/format_filesize.md) turns a file size into a string in the unit you name, whatever `$env.config.filesize.unit` says. A whole number in that unit is shown without decimals. Otherwise the number of decimal places comes from `$env.config.float_precision` (default `2`), not from `filesize.precision`: + +```nu +1500B | format filesize kB +# => 1.50 kB +1MiB | format filesize KiB +# => 1024 KiB +``` + +An unknown unit, or one with the wrong case, is an error: + +```nu +1500B | format filesize kb +# => Error: nu::shell::invalid_unit +# => +# => × Invalid unit +# => ╭─[repl_entry #1:1:25] +# => 1 │ 1500B | format filesize kb +# => · ─┬ +# => · ╰── encountered here +# => ╰──── +# => help: Supported units are: B, kB, MB, GB, TB, PB, EB, KiB, MiB, GiB, TiB, +# => PiB, EiB +``` + +For a record or table, name the columns to format as cell paths after the unit. Without them a record or table is rejected, and a plain list isn't accepted at all, so use `each` for a list: + +```nu +[[name size]; [a 1500B] [b 2MB]] | format filesize KiB size +# => ╭───┬──────┬─────────────╮ +# => │ # │ name │ size │ +# => ├───┼──────┼─────────────┤ +# => │ 0 │ a │ 1.46 KiB │ +# => │ 1 │ b │ 1953.12 KiB │ +# => ╰───┴──────┴─────────────╯ +``` + ## Common commands that can work with `filesizes` - `ls` @@ -56,10 +131,19 @@ Note: The `where` command and other filters can use filesize in comparison expre - `<`, `<=`, `>`, `>=` - `*`, `/`, `//` and `mod` with a number, which return a filesize - `/` with another filesize, which returns a `float` (use `//` for an `int`) +- `mod` with another filesize, which returns a filesize ```nu 10MB / 2 # => 5.0 MB 1GiB / 1B # => 1073741824.0 + 10kB // 3kB + # => 3 + 10kB mod 3kB + # => 1.0 kB ``` + +A number can also go on the left of `*`, so `2 * 1kB` is `2.0 kB`. It can't go on the left of `/`: `2 / 1kB` is an error. Two file sizes can't be multiplied. + +A file size and a plain number don't mix in `+`, `-`, `<`, `<=`, `>` or `>=`. `1kB > 1` and `1kB + 1` are parse errors, since a bare number has no unit. Compare with a file size instead (`1kB > 1B`). `==` and `!=` don't fail, but a file size never equals a number, so `1kB == 1000` is `false`. diff --git a/lang-guide/chapters/types/basic_types/float.md b/lang-guide/chapters/types/basic_types/float.md index ffedf9396e4..d9d3e15c690 100644 --- a/lang-guide/chapters/types/basic_types/float.md +++ b/lang-guide/chapters/types/basic_types/float.md @@ -11,7 +11,8 @@ ## Additional language notes - Floats are internally represented as IEEE-754 floats with 64 bit precision. -- Scientific notation is supported in literals, e.g. `1e3` or `1.5e-3`. +- Scientific notation is supported in literals, e.g. `1e3` or `1.5e-3`. The `e` can also be uppercase: `1E-2` is `0.01`. An exponent too large for a float doesn't cause an error. The literal becomes `inf`, so `1e400` is `inf`. +- The digits before or after the decimal point can be left out: `.5` is `0.5`, `5.` is `5.0` and `-.5` is `-0.5`. Underscores separate digits anywhere in a float literal, as in `1_000.000_1`. - A float is always displayed with a decimal point, even when it has no fractional part. The `/` operator always returns a float, even when both operands are integers (use `//` for integer division). - Floats and integers can be compared with each other. @@ -26,7 +27,54 @@ # => true ``` -- `into int` truncates the fractional part. Use `math round`, `math floor` or `math ceil` to round instead. +- An int combined with a float by `+`, `-`, `*`, `/`, `//`, `mod` or `**` gives a float, even when the result is a whole number: + + ```nu + [(1 + 1.5) (2 * 2.0) (7 // 2.0) (7 mod 2.0) (2 ** 2.0)] | to nuon + # => [2.5, 4.0, 3.0, 1.0, 4.0] + ``` + +- `into int` truncates the fractional part. Use `math round`, `math floor` or `math ceil` to round instead (see [Rounding](#rounding)). + +## Rounding + +[`math floor`](/commands/docs/math_floor.md) rounds down, [`math ceil`](/commands/docs/math_ceil.md) rounds up, and [`math round`](/commands/docs/math_round.md) rounds to the nearest whole number. A value exactly halfway rounds away from zero. All three return an `int`: + +```nu +[-1.5 1.5 2.5] | each {|x| {x: $x, floor: ($x | math floor), ceil: ($x | math ceil), round: ($x | math round)} } +# => ╭───┬───────┬───────┬──────┬───────╮ +# => │ # │ x │ floor │ ceil │ round │ +# => ├───┼───────┼───────┼──────┼───────┤ +# => │ 0 │ -1.50 │ -2 │ -1 │ -2 │ +# => │ 1 │ 1.50 │ 1 │ 2 │ 2 │ +# => │ 2 │ 2.50 │ 2 │ 3 │ 3 │ +# => ╰───┴───────┴───────┴──────┴───────╯ +``` + +`math round --precision` (`-p`) keeps that many decimal places and returns a `float`. A negative precision rounds to tens, hundreds and so on: + +```nu +[1.555 2.333] | math round --precision 2 | to nuon +# => [1.56, 2.33] +1234.5 | math round --precision -2 +# => 1200.0 +``` + +The rounding works on the stored binary value, so a decimal that a float can't hold exactly may round the other way: `1.005 | math round -p 2` is `1.0`. + +The three commands accept other input too: + +- An int comes back unchanged. +- A list or range of numbers gives a list, as in `1.5..3.5 | math ceil`, which is `[2, 3, 4]`. +- A file size or duration also comes back unchanged, since it is already a whole number of bytes or nanoseconds. `math round --precision` rejects them. +- A record has every field rounded, and each field must be a number, file size or duration. To round only some fields, name them as cell paths after the command: `{a: 1.26, b: 2.5} | math round -p 1 a` is `{a: 1.3, b: 2.5}`. + +A table is not accepted. Round a column with `update` instead: + +```nu +[[item price]; [a 1.25] [b 2.5]] | update price { math round } | to nuon +# => [[item, price]; [a, 1], [b, 3]] +``` ## Infinity and NaN @@ -39,7 +87,7 @@ The words `inf` and `NaN` are float literals for infinity and "not a number". Wr [`into float`](/commands/docs/into_float.md) is more lenient with text. `'infinity' | into float` returns `inf`. -These values also come out of float arithmetic. A literal too large for a float becomes `inf` (`1e400` is `inf`), and `inf - inf` is `NaN`. Division by zero is an error, even for floats, so `1.0 / 0` and `0.0 / 0.0` fail with `nu::shell::division_by_zero` instead of returning `inf` or `NaN`. +These values also come out of float arithmetic. A literal too large for a float becomes `inf` (`1e400` is `inf`), and so does a result too large for a float (`1e308 * 10` is `inf`). `inf - inf` is `NaN`. Division by zero is an error, even for floats, so `1.0 / 0` and `0.0 / 0.0` fail with `nu::shell::division_by_zero` instead of returning `inf` or `NaN`. Comparisons follow IEEE-754. `inf == inf` is `true`, and `NaN` is not equal to anything, itself included: diff --git a/lang-guide/chapters/types/basic_types/glob.md b/lang-guide/chapters/types/basic_types/glob.md index 19ed61b860c..eb44e47ae30 100644 --- a/lang-guide/chapters/types/basic_types/glob.md +++ b/lang-guide/chapters/types/basic_types/glob.md @@ -87,6 +87,21 @@ For an interpolated argument, only a bare word that doesn't start with `(` is expanded. `^echo *($prefix)*` passes the matching file names, while `^echo $"*($prefix)*"` and `^echo ($prefix)*` pass the text as written. + The quoting rules are the same as for internal commands. Bare words and backtick-quoted words are expanded. Single- and double-quoted strings are not, and neither is a string stored in a variable. A `glob` value is always expanded, so annotate the variable or use `into glob` to expand a pattern you built. A pattern that matches nothing is passed on unchanged, as Bash does by default, while `ls` and the other file commands report an error for it. In a directory holding `a.txt` and `b.txt`: + + ```nu + ^echo *.txt + # => a.txt b.txt + ^echo "*.txt" + # => *.txt + let s = "*.txt"; ^echo $s + # => *.txt + let g: glob = "*.txt"; ^echo $g + # => a.txt b.txt + ^echo *.zip + # => *.zip + ``` + 1. As with most other types, globs can be saved in a variable, passed to custom commands and returned from custom commands. 1. You can use `into glob` and `into string` to convert values between `glob` and `string`. @@ -100,6 +115,22 @@ # => true ``` + Only the string-to-glob direction happens on its own. A string is accepted where a `glob` is expected, as with `$glob1` above, but a glob is rejected where a `string` is expected: + + ```nu + let x: string = ("*" | into glob) + # => Error: nu::parser::type_mismatch + # => + # => × Type mismatch. + # => ╭─[repl_entry #1:1:17] + # => 1 │ let x: string = ("*" | into glob) + # => · ────────┬──────── + # => · ╰── expected string, found glob + # => ╰──── + ``` + + The same error comes from passing a glob to a `string` parameter. Convert it with `into string` first. See [Which values a type accepts](../type_signatures.md#which-values-a-type-accepts). + 1. Globs can also represent directory trees recursively using the `**` pattern. For example, in Unix-like systems you might use a combination of the `find` and `xargs` commands to operate on directory trees: @@ -150,6 +181,41 @@ glob -D b* | path basename | sort # => ╰───┴────────╯ ``` +The other options: + +- `--no-file` (`-F`) and `--no-symlink` (`-S`) leave out files and symbolic links, the way `--no-dir` (`-D`) leaves out directories. A symbolic link counts only as a link, so `--no-file` keeps a link to a file, and `--no-dir` keeps a link to a directory. +- `--depth` (`-d`) limits how far `**` searches. Depth 1 is the entries of the current directory, depth 2 adds one level of subdirectories, and so on. +- `--follow-symlinks` (`-l`) makes `**` descend into directories that are reached through a symbolic link. Without it, a linked directory is listed but not searched. +- `--exclude` (`-e`) takes a list of patterns to leave out. `glob` doesn't walk into a directory that an exclude pattern matches, which saves time in large trees such as `target` or `node_modules`. The pattern has to match the paths inside the directory, so write `target/**`. Plain `target` excludes nothing below it. + +For a project that holds `build.rs`, `src/main.rs`, `src/util/mod.rs` and `target/debug/out.rs`: + +```nu +glob **/*.rs --depth 2 | path relative-to (pwd) | sort +# => ╭───┬─────────────╮ +# => │ 0 │ build.rs │ +# => │ 1 │ src/main.rs │ +# => ╰───┴─────────────╯ +glob **/*.rs --exclude [target/**] | path relative-to (pwd) | sort +# => ╭───┬─────────────────╮ +# => │ 0 │ build.rs │ +# => │ 1 │ src/main.rs │ +# => │ 2 │ src/util/mod.rs │ +# => ╰───┴─────────────────╯ +``` + +### Pattern syntax of the `glob` command + +The `glob` command reads its pattern with the [wax](https://docs.rs/wax/latest/wax/) crate, not with `nu_glob` like `ls`, `rm` and the other file commands. Wax patterns have features that the file commands lack: + +- `{a,b}` matches either alternative: `glob *.{rs,toml}`. +- `` matches the pattern between `n` and `m` times. `glob "file<[0-9]:1,2>"` matches `file1` and `file10` but not `file100`. +- `(?i)` at the start makes the match case-insensitive: `glob "(?i)readme*"`. + +`ls *.{rs,toml}` doesn't work, since `ls` has no `{a,b}` alternatives and looks for that pattern literally. Use `glob` and pass its result on, as in `ls ...(glob *.{rs,toml})`. + +The experimental option `dc-glob` replaces both backends with one, so `glob` uses the same rules as `ls` and the other file commands, and all of them get `{a,b}` alternatives. With it on, wax's `` repetitions, the `(?i)` flag and `\` escapes no longer work in `glob`, and `dir/**` lists only the directories below `dir`. Use `dir/**/*` to list everything. See [Experimental options](/book/configuration.md#experimental-options) for how to turn it on. + ## Common commands that can work with `glob` - `cp` diff --git a/lang-guide/chapters/types/basic_types/int.md b/lang-guide/chapters/types/basic_types/int.md index c7709e3d650..2b9a034e625 100644 --- a/lang-guide/chapters/types/basic_types/int.md +++ b/lang-guide/chapters/types/basic_types/int.md @@ -11,7 +11,7 @@ ## Additional Language Notes - Integers are internally represented as signed 64-bit numbers with two's-complement arithmetic. An operation that overflows this range raises an `operator_overflow` error rather than wrapping around. -- Underscores can be used as digit separators in literals, e.g. `1_000_000`. +- Underscores can be used as digit separators in literals, e.g. `1_000_000`. Nushell drops every `_` wherever it appears, so `_1`, `1_` and `1__0` are the ints `1`, `1` and `10`. The same goes for hex, octal and binary literals: `0x10_00` is `4096`. - The `/` operator always returns a `float`. Use `//` for floor division, which returns an `int`. `mod` uses the same floor semantics, so the result has the sign of the divisor: ```nu @@ -25,6 +25,135 @@ # => 2 ``` +- An int combined with a float gives a float. See [Float](float.md#additional-language-notes). + +## Integer literals + +A decimal literal has to fit in a signed 64-bit int, from `-9223372036854775808` to `9223372036854775807`. A larger one is a parse error. Add `.0` to make it a float instead: + +```nu +9223372036854775808 +# => Error: nu::parser::error +# => +# => × Invalid literal +# => ╭─[repl_entry #1:1:1] +# => 1 │ 9223372036854775808 +# => · ─────────┬───────── +# => · ╰── number too large (add `.0` for a float) in int +# => ╰──── +``` + +Hex (`0x`), octal (`0o`) and binary (`0b`) literals can have a sign before the prefix, so `-0x10` is `-16` and `-0b101` is `-5`. The prefixes are lowercase only. + +Nushell reads a hex, octal or binary literal as the 64 bits of the int, not as a signed number. Every 64-bit pattern can be written this way, and the upper half of the unsigned range comes out negative. A decimal literal with the same value would be rejected: + +```nu +[0x7fffffffffffffff 0x8000000000000000 0xffffffffffffffff] | to nuon +# => [9223372036854775807, -9223372036854775808, -1] +``` + +More than 64 bits, as in `0x10000000000000000`, is a parse error ("number too large for 64 bits"). + +A digit that doesn't belong to the base is reported where Nushell expects a value. `echo 0xZZ` fails with "invalid digits for radix 16", and `echo 0o9` with "invalid digits for radix 8". At the start of a pipeline, though, the same word is read as the name of an external command, so `0xZZ` on its own fails with "Command `0xZZ` not found". An uppercase prefix never makes a number: `echo 0X10` prints the string `0X10`, and `0X10` alone looks for a command with that name. + +## Arithmetic errors + +Integer arithmetic doesn't wrap around. A result outside the 64-bit range is a `nu::shell::operator_overflow` error. That covers `+`, `-`, `*` and `**`, and also `-9223372036854775808 // -1`, the one division that overflows: + +```nu +9223372036854775807 + 1 +# => Error: nu::shell::operator_overflow +# => +# => × Operator overflow. +# => ╭─[repl_entry #1:1:21] +# => 1 │ 9223372036854775807 + 1 +# => · ┬ +# => · ╰── add operation overflowed +# => ╰──── +# => help: Consider using floating point values for increased range by promoting +# => operand with 'into float'. Note: float has reduced precision! +``` + +An int raised to a negative power, such as `2 ** -1`, is a `nu::shell::incorrect_value` error, since the result isn't an int. Use a float base: `2.0 ** -1` is `0.5`. + +Division by zero is an error for `/`, `//` and `mod`. That holds for floats too, and for file sizes and durations divided by zero: + +```nu +1.5 mod 0.0 +# => Error: nu::shell::division_by_zero +# => +# => × Division by zero. +# => ╭─[repl_entry #1:1:5] +# => 1 │ 1.5 mod 0.0 +# => · ─┬─ +# => · ╰── division by zero +# => ╰──── +``` + +Float arithmetic doesn't overflow with an error. A float result too large to represent becomes `inf`, so `1e308 * 10` is `inf`. See [Infinity and NaN](float.md#infinity-and-nan). + +`bit-shl` and `bit-shr` take a shift amount from 0 to 63. Any other amount, negative ones included, is an `operator_overflow` error whose help says "Limit operand to 0 <= rhs < 64". A shift inside that range drops the bits that move out without an error, so `1 bit-shl 63` is `-9223372036854775808`. + +## Converting to int + +[`into int`](/commands/docs/into_int.md) accepts these input types: + +| Input | Result | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `float` | The value truncated toward zero, so `-1.9` gives `-1`. Use `math round`, `math floor` or `math ceil` to round instead. | +| `bool` | `1` for `true`, `0` for `false` | +| `filesize` | The number of bytes | +| `duration` | The number of nanoseconds | +| `datetime` | Nanoseconds since 1970-01-01T00:00:00Z. A date before 1677-09-21 or after 2262-04-11 is an error, because the count won't fit. | +| `string` | The number the text holds (see below) | +| `binary` | The bytes read as one number (see below) | + +A string can hold a decimal number, or a hex, octal or binary number with a `0x`, `0o` or `0b` prefix. Leading and trailing whitespace is ignored, and so is the thousands separator of the system locale, so `"1,000"` is `1000` with an English locale. A decimal fraction or an exponent is truncated as a float would be: `"1.9"` gives `1`, and `"1e3"` gives `1000`. Unlike a literal, the text can't use `_` separators. Text that isn't a number is an error: + +```nu +"1_000" | into int +# => Error: nu::shell::cant_convert +# => +# => × Can't convert to int. +# => ╭─[repl_entry #1:1:1] +# => 1 │ "1_000" | into int +# => · ───┬─── +# => · ╰── can't convert string to int +# => ╰──── +# => help: string "1_000" does not represent a valid integer +``` + +`--radix` (`-r`) reads the string in another base, from 2 to 36. Letters stand for the digits above 9, in either case: + +```nu +"ff" | into int --radix 16 +# => 255 +"zz" | into int --radix 36 +# => 1295 +``` + +A binary value of up to 8 bytes becomes one int. `--endian` (`-e`) sets the byte order to `little`, `big`, or `native`, the default, which is the byte order of the machine running Nushell (little-endian on x86-64 and on most ARM systems). Without `--signed`, the bytes form an unsigned number. With `--signed`, the highest bit is the sign bit: + +```nu +0x[01 02] | into int --endian big +# => 258 +0x[01 02] | into int --endian little +# => 513 +0x[ff] | into int +# => 255 +0x[ff] | into int --signed +# => -1 +``` + +An empty binary value gives `0`. More than 8 bytes is an error ("binary input is too large to convert to int"), and so are 8 unsigned bytes above the largest int, such as `0x[ff ff ff ff ff ff ff ff]` without `--signed`. + +For a table or record, list the columns to convert as cell paths after the command. The other columns keep their values: + +```nu +[[a b]; ["1" "2"]] | into int a | to nuon +# => [[a, b]; [1, "2"]] +``` + ## Common commands that can be used with `int` - `into int`, `into float` diff --git a/lang-guide/chapters/types/basic_types/nothing.md b/lang-guide/chapters/types/basic_types/nothing.md index 3b345a1d55a..830ae5998f3 100644 --- a/lang-guide/chapters/types/basic_types/nothing.md +++ b/lang-guide/chapters/types/basic_types/nothing.md @@ -79,3 +79,23 @@ - [`default`](/commands/docs/default.html): Set a default value for missing (`null`) fields in a record or table - [`compact`](/commands/docs/compact.html): Removes `null` values from a list + +### Removing nulls with `compact` + +Given a list, `compact` drops the `null` items. Given a record, it drops the fields whose value is `null`. `--empty` (`-e`) also drops empty strings, lists and records. `0`, `false` and a string of spaces are not empty, so they stay: + +```nu +[1 null 2 "" [] {}] | compact | to nuon +# => [1, 2, "", [], {}] +[1 null 2 "" [] {}] | compact --empty | to nuon +# => [1, 2] +{a: 1, b: null, c: ""} | compact | to nuon +# => {a: 1, c: ""} +``` + +A table row is a record, not `null`, so `compact` on its own keeps every row. Name columns to drop the rows where any of those columns is `null` (or empty, with `--empty`): + +```nu +[[a b]; [1 null] [null 2] [3 4]] | compact a | to nuon +# => [[a, b]; [1, null], [3, 4]] +``` diff --git a/lang-guide/chapters/types/basic_types/number.md b/lang-guide/chapters/types/basic_types/number.md new file mode 100644 index 00000000000..6d73164ea92 --- /dev/null +++ b/lang-guide/chapters/types/basic_types/number.md @@ -0,0 +1,64 @@ +# Number + +| | | +| --------------------- | ---------------------------------------------------------------------------------- | +| **_Description:_** | When used in a type annotation or signature, matches either an `int` or a `float`. | +| **_Annotation:_** | `number` | +| **_Literal syntax:_** | N/A - Any [int](int.md) or [float](float.md) literal can be assigned to a `number` | +| **_Casts:_** | N/A | + +## Additional Language Notes + +1. `number` is a type for annotations, like [`any`](any.md). No single value has the type `number`. A value annotated as `number` keeps its own type, so `describe` reports `int` or `float`: + + ```nu + def kind [x: number] { $x | describe } + [(kind 1) (kind 1.5)] | to nuon + # => [int, float] + ``` + + `describe` shows `number` only for a collection that mixes ints and floats: + + ```nu + [1 2.5] | describe + # => list + ``` + +2. Other types are rejected, including text that looks like a number and the number-like `filesize` and `duration` types. A literal is checked when the code is parsed: + + ```nu + let n: number = "1" + # => Error: nu::parser::type_mismatch + # => + # => × Type mismatch. + # => ╭─[repl_entry #1:1:17] + # => 1 │ let n: number = "1" + # => · ─┬─ + # => · ╰── expected number, found string + # => ╰──── + ``` + + Convert text with [`into int`](/commands/docs/into_int.md) or [`into float`](/commands/docs/into_float.md) first. + +3. A `mut` variable without an annotation keeps the type of its first value, so an int variable can't later hold a float. Annotate it as `number` to allow both: + + ```nu + mut total: number = 0 + $total = $total + 2.5 + $total + # => 2.5 + ``` + + Without the annotation, `$total = 2.5` after `mut total = 0` fails with `nu::parser::operator_incompatible_types`. + +4. `number` also works as an input or output type, and inside other types such as `list`: + + ```nu + def half []: number -> float { $in / 2 } + [(4 | half) (1.5 | half)] | to nuon + # => [2.0, 0.75] + ``` + + Many built-in commands use it this way. `help math abs`, for example, lists `number` and `list` among its input types. + +5. A `number` can be passed where an `int` or a `float` is expected. The parser lets it through, and the value is checked when the command runs. See [Which values a type accepts](../type_signatures.md#which-values-a-type-accepts). diff --git a/lang-guide/chapters/types/basic_types/range.md b/lang-guide/chapters/types/basic_types/range.md index 02da5f89f30..ad518e69ab9 100644 --- a/lang-guide/chapters/types/basic_types/range.md +++ b/lang-guide/chapters/types/basic_types/range.md @@ -51,6 +51,15 @@ # => ╰───┴───╯ ``` + The second value sets the direction too, so a second value below the start counts down. The step form also works with an exclusive end: + + ```nu + 10..8..0 | each {} | to nuon + # => [10, 8, 6, 4, 2, 0] + 1..3..<9 | each {} | to nuon + # => [1, 3, 5, 7] + ``` + 1. Exclusive range - You can also use `..<` to have values up to, but not including, the range end. Values from 1 to 5 (exclusive): @@ -89,6 +98,40 @@ # => [1.0, 2.0] ``` +1. The start, second and end values can be variables or subexpressions, not just literals: + + ```nu + let start = 2 + let end = 5 + $start..$end | each {} | to nuon + # => [2, 3, 4, 5] + let list = [a b c] + 0..<($list | length) | each {} | to nuon + # => [0, 1, 2] + ``` + + A negative start works where an expression begins (`-2..0`), but not as a command argument, where a word that starts with `-` is read as a flag: + + ```nu + [a b c d e] | slice -2.. + # => Error: nu::parser::unknown_flag + # => + # => × The `slice` command doesn't have flag `-2`. + # => ╭─[repl_entry #1:1:22] + # => 1 │ [a b c d e] | slice -2.. + # => · ┬ + # => · ╰── unknown flag + # => ╰──── + # => help: Use `--help` to see available flags + ``` + + Put the number in parentheses, or pass it in a variable: + + ```nu + [a b c d e] | slice (-2).. | to nuon + # => [d, e] + ``` + 1. The start, second and end values must be numbers. A range of strings or dates is a parse error: ```nu @@ -106,6 +149,24 @@ Without the parentheses, `'a'..'z'` isn't a range at all. A quoted word runs to its last quote, so it is the single string `a'..'z` (see [Quotes inside a quoted word](/book/working_with_strings.md#quotes-inside-a-quoted-word)). For a sequence of letters, use [`seq char`](/commands/docs/seq_char.md), and for dates use [`seq date`](/commands/docs/seq_date.md). + `seq char` includes both ends, and counts down when the start comes after the end. Each bound must be a single ASCII character, and anything else is an error. The characters follow ASCII order, so a run from uppercase to lowercase picks up the punctuation in between: + + ```nu + seq char e a | str join + # => edcba + seq char Y b | str join + # => YZ[\]^_`ab + seq char é z + # => Error: nu::shell::error + # => + # => × seq char only accepts individual ASCII characters as parameters + # => ╭─[repl_entry #1:1:10] + # => 1 │ seq char é z + # => · ┬ + # => · ╰── input should be a single ASCII character + # => ╰──── + ``` + 1. When no second value is given, the step is `1` (or `-1` when counting down). The exception is a float range whose start and end are less than `1` apart. Its step is based on the order of magnitude of the difference: ```nu diff --git a/lang-guide/chapters/types/basic_types/string.md b/lang-guide/chapters/types/basic_types/string.md index 7e186085edb..56b7480831a 100644 --- a/lang-guide/chapters/types/basic_types/string.md +++ b/lang-guide/chapters/types/basic_types/string.md @@ -27,6 +27,21 @@ # => 5 ``` + [`str length`](/commands/docs/str_length.md) counts in one of three units. `--utf-8-bytes` (`-b`) counts bytes, the default. `--chars` (`-c`) counts Unicode scalar values, roughly the code points. `--grapheme-clusters` (`-g`) counts what a reader sees as one character. The last two differ when a character is built from several code points, such as `e` followed by a combining accent: + + ```nu + let s = "e\u{301}" + [($s | str length) ($s | str length --chars) ($s | str length --grapheme-clusters)] | to nuon + # => [3, 2, 1] + ``` + + Only one of `--chars` and `--grapheme-clusters` can be given. A list of strings gives a list of lengths. For a table or record, name the columns as cell paths after the command, and each string there is replaced by its length: + + ```nu + [[name]; [ab] [héllo]] | str length name | to nuon + # => [[name]; [2], [6]] + ``` + ## Common commands that work with `string` Many commands takes strings as inputs or parameters. diff --git a/lang-guide/chapters/types/basic_types/table.md b/lang-guide/chapters/types/basic_types/table.md index b2ed58109f1..d3fc0bf8069 100644 --- a/lang-guide/chapters/types/basic_types/table.md +++ b/lang-guide/chapters/types/basic_types/table.md @@ -28,6 +28,45 @@ Table literals can be created using a syntax similar to that of a list literal. In this syntax, the headers are separated from the data cells using a semicolon(`;`). The semicolon separator is mandatory in a table-literal. It must follow the headers. +A table literal has these rules: + +- At least one row must follow the `;`. `[[a b];]` fails with "expected table row". For an empty table, use `[]`. +- Each row needs exactly one cell per column. A short row is a `nu::parser::missing_columns` error, and a long one is `nu::parser::extra_columns`: + + ```nu + [[a b]; [1]] + # => Error: nu::parser::missing_columns + # => + # => × Missing columns. + # => ╭─[repl_entry #1:1:9] + # => 1 │ [[a b]; [1]] + # => · ─┬─ + # => · ╰── expected 2 columns + # => ╰──── + ``` + +- A column name can't appear twice. With literal names, as in `[[a a]; [1 2]]`, that is a parse error (`nu::parser::column_defined_twice`). When the names come from variables, the same check happens at runtime as `nu::shell::column_defined_twice`. +- A row can't use the spread operator. `[[a b]; [...$row]]` fails with "Cannot spread in a table row". Build such a table from records instead. + +Column names can be bare words, quoted strings, variables or subexpressions: + +```nu +let c = "x" +[[$c ("y" + "z") "a b"]; [1 2 3]] +# => ╭───┬───┬────┬─────╮ +# => │ # │ x │ yz │ a b │ +# => ├───┼───┼────┼─────┤ +# => │ 0 │ 1 │ 2 │ 3 │ +# => ╰───┴───┴────┴─────╯ +``` + +[`to nuon`](/commands/docs/to_nuon.md) writes a table in this form, and `from nuon` reads it back as a table: + +```nu +[{a: 1, b: 2} {a: 3, b: 4}] | to nuon +# => [[a, b]; [1, 2], [3, 4]] +``` + ### List-of-Records syntax You can also create a table as a list of records, JSON-style: diff --git a/lang-guide/chapters/types/other_types/00_not_assignable.md b/lang-guide/chapters/types/other_types/00_not_assignable.md index dca9f91d7b4..ca6a468b0c9 100644 --- a/lang-guide/chapters/types/other_types/00_not_assignable.md +++ b/lang-guide/chapters/types/other_types/00_not_assignable.md @@ -1,4 +1,9 @@ # Types used only in command signatures The following type annotations are meant for custom command signatures, where they change how an argument is parsed. -A variable can also be annotated with one of them, but there it is the same as `string`: `let p: path = "~/x"` stores the string `~/x` unchanged, and `$p | describe` returns `string`. +They are [`path`](path.md), `directory` and [`external_arg`](external_arg.md). + +A variable can also be annotated with one of them, but the annotation doesn't change how the value is parsed there: + +- With `path` or `directory`, it is the same as `string`. `let p: path = "~/x"` stores the string `~/x` unchanged, `$p | describe` returns `string`, and `let p: path = 5` is a type mismatch. +- With `external_arg`, it is the same as `any`. `let e: external_arg = 0001` stores the int `1`. diff --git a/lang-guide/chapters/types/other_types/custom_value.md b/lang-guide/chapters/types/other_types/custom_value.md index bfc7e61a514..b6bab09e28c 100644 --- a/lang-guide/chapters/types/other_types/custom_value.md +++ b/lang-guide/chapters/types/other_types/custom_value.md @@ -55,3 +55,135 @@ [[1 2] [3 4]] | into matrix | into value | describe # => list> ``` + + Any other input passes through `into value` unchanged, so it is safe on input that may or may not be a custom value. It converts only a custom value that is the whole input. A list, record or stream that holds custom values comes back as it was, and passing it through [`collect`](/commands/docs/collect.md) first doesn't change that, despite the hint in `help into value`. Convert each item instead, or use `update` for a record field: + + ```nu + ["1.2.3" "2.0.0"] | into semver | into value | describe + # => list (stream) + ["1.2.3" "2.0.0"] | into semver | each { into value } | describe + # => list (stream) + ``` + +1. A custom value's type name, as `describe` reports it, can be used as a type annotation when a command in scope declares that type. The built-in `semver`, `semver-range`, `matrix` and `SQLiteDatabase` always qualify, and a plugin's types do once the plugin is loaded (see [Types which are not declarable](./01_not_declarable.md)). The name also works inside other types: + + ```nu + def newest [versions: list] { $versions | sort | last } + newest (["1.2.0" "1.10.0"] | into semver) + # => 1.10.0 + ``` + +## Plugin custom values + +A plugin's custom value, such as a Polars dataframe, is a handle to data that the plugin manages. Whenever Nushell needs something from the value, it asks the plugin: to display it, to follow a cell path into it, to apply an operator, to compare it (as `sort` does), or to `save` it. If the plugin isn't running at that moment, Nushell starts it again first, the same way it does for one of the plugin's commands. + +A restart brings back the plugin but not what it kept in memory. The Polars plugin keeps each dataframe in a cache inside its own process. While that cache holds anything, Polars keeps the [plugin garbage collector](/book/plugins.md#plugin-garbage-collector) from stopping it, but `plugin stop polars` still ends the process. After that, an existing dataframe value can't be resolved, and using it fails with an error that the dataframe was not found in the cache. Create the dataframe again. Other plugins that keep their values in memory have the same limit. + +## SemVer + +[`into semver`](/commands/docs/into_semver.md) accepts a string or a record. A string must be a full `major.minor.patch` version, which can have a pre-release after `-` and build metadata after `+`, as in `1.2.3-rc.1+build.5`. `--loose` (`-l`) also accepts a prefix of `v` or `V`, alone or followed by `.`, `:`, `-` or `_`, as in `v1.2.3` or `v.1.2.3`. Even with `--loose`, `1.2` is not a version. + +A record needs the int fields `major`, `minor` and `patch`, and can have the string fields `pre`, `build` and `prefix`: + +```nu +{major: 1, minor: 2, patch: 3, pre: "rc.1", build: "abc", prefix: "v"} | into semver +# => v1.2.3-rc.1+abc +``` + +A list of strings gives a list of versions. For a table or record, name the columns to convert as cell paths after the command, as in `$deps | into semver version`. + +A cell path can read six fields from a `semver`. `major`, `minor` and `patch` are ints, and `pre`, `build` and `prefix` are strings, empty when the version has none: + +```nu +let v = "v1.2.3-rc.1+build.5" | into semver --loose +[$v.major $v.minor $v.patch $v.pre $v.build $v.prefix] | to nuon +# => [1, 2, 3, "rc.1", "build.5", v] +``` + +Versions compare by semantic version precedence, so `1.10.0` comes after `1.2.0` and a pre-release such as `1.0.0-rc.1` comes before `1.0.0`. This holds for `<`, `>` and the other comparison operators, and for `sort`. The prefix is only for display, so `v1.0.0` and `1.0.0` are equal. + +When the `semver` is on the left, the right side can also be a version string, read as if by `into semver --loose`: + +```nu +let v = "1.2.3" | into semver +$v > "1.0.0" +# => true +``` + +With the string on the left, as in `"1.0.0" < $v`, the parser rejects the comparison (`nu::parser::operator_incompatible_types`). A string that isn't a version is an error when the comparison runs, with the help "expected another semver or a valid version string". + +Nushell never turns a string into a `semver` on its own. A `semver` variable or parameter rejects a string literal when the code is parsed: + +```nu +let v: semver = "1.2.3" +# => Error: nu::parser::type_mismatch +# => +# => × Type mismatch. +# => ╭─[repl_entry #1:1:17] +# => 1 │ let v: semver = "1.2.3" +# => · ───┬─── +# => · ╰── expected semver, found string +# => ╰──── +``` + +## SemVer ranges + +[`into semver-range`](/commands/docs/into_semver-range.md) turns a version requirement into a `semver-range` value. Its use is the `in` operator, which tests whether a version meets the requirement: + +```nu +let r = "^1.2" | into semver-range +["1.2.0" "1.9.9" "2.0.0" "1.1.0"] | each {|s| {version: $s, ok: (($s | into semver) in $r)} } +# => ╭───┬─────────┬───────╮ +# => │ # │ version │ ok │ +# => ├───┼─────────┼───────┤ +# => │ 0 │ 1.2.0 │ true │ +# => │ 1 │ 1.9.9 │ true │ +# => │ 2 │ 2.0.0 │ false │ +# => │ 3 │ 1.1.0 │ false │ +# => ╰───┴─────────┴───────╯ +``` + +Requirements use the syntax of Cargo, the Rust package manager, as implemented by the [semver crate](https://docs.rs/semver/latest/semver/struct.VersionReq.html): + +- `^1.2.3` allows any later version that keeps the leftmost non-zero number, so `^1.2.3` stops before `2.0.0` and `^0.2.3` stops before `0.3.0`. A bare version means the same thing: `"1.2.3" | into semver-range` displays as `^1.2.3`. +- `~1.2` allows only patch updates, from `1.2.0` up to but not including `1.3.0`. +- `=`, `>`, `>=`, `<` and `<=` compare with a single version. +- `*` matches any version, and `1.2.*` any `1.2` version. +- Requirements separated by commas must all hold, as in `>=1.0.0, <2.0.0`. + +A pre-release version only matches a requirement that names a pre-release of the same `major.minor.patch`, so `1.5.0-beta` is not in `^1.0`, while `1.0.0-beta.2` is in `^1.0.0-beta`. `--loose` lets the versions inside the requirement have the same prefixes that `into semver --loose` accepts, as in `>=v1.0.0`. + +The left side of `in` must be a `semver`. A string there is rejected when the code is parsed, so write `("1.5.0" | into semver) in $r`. + +## Matrices + +[`into matrix`](/commands/docs/into_matrix.md) turns a list of lists of numbers, or a table of numbers, into a `matrix`: an array of floats that the `matrix` commands work on. They cover arithmetic (`matrix add`, `matrix subtract`, `matrix scale`, and `matrix multiply` for the matrix product), reductions (`matrix sum`, `matrix mean`, `matrix max`, `matrix reduce`), shape changes (`matrix transpose`, `matrix reshape`), access to rows and columns (`matrix get-row`, `matrix set-row`, `matrix get-col`, `matrix set-col`), `matrix map`, and the constructors `matrix identity` and `matrix zeros`. `help matrix` lists them. + +```nu +let m = [[1 2] [3 4]] | into matrix +$m | matrix multiply $m | matrix into-nu | to nuon +# => [[7.0, 10.0], [15.0, 22.0]] +``` + +A table, or any list of records, is read one record at a time, with the values in each record's field order. Every row must have the same length: + +```nu +[[1 2] [3]] | into matrix +# => Error: nu::shell::error +# => +# => × Inconsistent row lengths +# => ╭─[repl_entry #1:1:15] +# => 1 │ [[1 2] [3]] | into matrix +# => · ─────┬───── +# => · ╰── row 1 has 1 elements, expected 2 +# => ╰──── +``` + +A value that isn't a number, as in `[[1 "a"]]`, is an `only_supports_this_input_type` error. + +[`matrix into-nu`](/commands/docs/matrix_into-nu.md) converts a matrix back to a list of lists of floats, as `into value` does. `--as-records` (`-r`) gives a table instead, with the columns `col0`, `col1` and so on: + +```nu +[[1 2] [3 4]] | into matrix | matrix into-nu --as-records | to nuon +# => [["col0", "col1"]; [1.0, 2.0], [3.0, 4.0]] +``` diff --git a/lang-guide/chapters/types/other_types/external_arg.md b/lang-guide/chapters/types/other_types/external_arg.md new file mode 100644 index 00000000000..b0c0cfedc52 --- /dev/null +++ b/lang-guide/chapters/types/other_types/external_arg.md @@ -0,0 +1,48 @@ +# External argument + + +| | | +| --- | --- | +| **_Description:_** | A parameter that reads its argument the way an external command's argument is read +| **_Annotation:_** | `external_arg` +| **_Literal syntax:_** | None +| **_Casts:_** | N/A +| **_See also:_** | [Custom Commands - Parameter types](/book/custom_commands.md#parameter-types) in the Book + +## Additional Language Notes + +1. Like [`path`](path.md), `external_arg` is a "syntax shape" rather than a full type. It is meant for custom command parameters, where it changes how the argument is parsed: + + - A bare word keeps the exact text you typed. `0001`, `5` and `true` aren't turned into an int or a bool. The value is a `glob` holding that text, so when you pass it on to an external command, a pattern such as `*.md` or a leading `~` is expanded there. + - A quoted string stays a `string`, and isn't expanded. + - A variable, subexpression or list literal keeps its own value and type. + + ```nu + def show [x: external_arg] { [$x ($x | describe)] | to nuon } + show 0001 + # => ["0001", glob] + show "a b" + # => ["a b", string] + show (1 + 1) + # => [2, int] + ``` + + An untyped parameter parses the same bare word as a number, so `show-any 0001` with `def show-any [x] { ... }` receives the int `1`. + +2. It is mainly useful for commands that hand their arguments to an external program, such as the `main` command of a [script](/book/scripts.md) called from another shell, or a wrapper with a rest parameter. In a directory that holds `README.md`: + + ```nu + def run-echo [...args: external_arg] { ^echo ...$args } + run-echo 0001 *.md "*.md" + # => 0001 README.md *.md + ``` + + Here the bare `*.md` matched `README.md`, while the quoted `"*.md"` was passed as written. The untyped rest parameter of a `def --wrapped` command uses this shape too (see [Rest Parameters with Wrapped External Commands](/book/custom_commands.md#rest-parameters-with-wrapped-external-commands)). + +3. On a variable, `external_arg` doesn't change how the value is parsed. It accepts any value, as [`any`](../basic_types/any.md) does, so a variable annotated this way behaves like an unannotated one: + + ```nu + let e: external_arg = 0001 + $e | describe + # => int + ``` diff --git a/lang-guide/chapters/types/other_types/path.md b/lang-guide/chapters/types/other_types/path.md index 8ecc0a52d6c..3dd921a27a4 100644 --- a/lang-guide/chapters/types/other_types/path.md +++ b/lang-guide/chapters/types/other_types/path.md @@ -64,6 +64,35 @@ There is no `into path` command, but several commands can be used to convert to - `path join` - `path parse` +### Absolute paths with `path expand` + +[`path expand`](/commands/docs/path_expand.md) turns a string, or a list of strings, into absolute paths. It expands a leading `~` to the home directory and multi-dot shorthands such as `...`, makes a relative path absolute against the current directory, and removes `.` and `..` segments. + +When the path exists, `path expand` also resolves symbolic links, so the result is the real location. When it doesn't exist, the command still returns the expanded text, without an error. Two flags change this: + +- `--no-symlink` (`-n`) skips the symlink resolution. `..` segments are then removed as text, so `link/..` becomes the directory holding `link`, not the parent of the link's target. +- `--strict` (`-s`) makes a path that doesn't exist an error ("Could not expand path"). With `--no-symlink` as well, the path must still exist, but the result keeps its links. + +With `link` a symbolic link to the directory `real`, in `/home/you/proj`: + +```nu +"link/f.txt" | path expand +# => /home/you/proj/real/f.txt +"link/f.txt" | path expand --no-symlink +# => /home/you/proj/link/f.txt +"nope/x" | path expand +# => /home/you/proj/nope/x +"nope/x" | path expand --strict +# => Error: nu::shell::error +# => +# => × Could not expand path +# => ╭─[repl_entry #1:1:1] +# => 1 │ "nope/x" | path expand --strict +# => · ────┬─── +# => · ╰── could not be expanded (path might not exist, non-final component is not a directory, or other cause) +# => ╰──── +``` + ## Common commands that can work with `path` - `path (subcommands)` diff --git a/lang-guide/chapters/types/related_commands.md b/lang-guide/chapters/types/related_commands.md index e867b2733bc..52b46a3c84e 100644 --- a/lang-guide/chapters/types/related_commands.md +++ b/lang-guide/chapters/types/related_commands.md @@ -35,5 +35,21 @@ E.g. # => duration ``` + It tries these types in order and returns the first one that converts: + + | Type | Text that converts | + | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `bool` | `true` or `false`, in any case | + | `float` | A number with a decimal point or an exponent (`3.14`, `5.`, `6.02e23`), or `inf` or `NaN` | + | `int` | Digits with an optional sign, also grouped in threes with `,` or `_` (`1,234`, `1_000`) | + | `datetime` | A date written `M/D/YYYY`, `D/M/YYYY`, `YYYY-MM-DD` or `YYYY/MM/DD` (`-` and `/` are interchangeable), optionally with a time after `T` or a space. A year-first date with a time can end in `Z` or an offset | + | `duration` | One or more numbers with duration units, separated by spaces (`1hr 3min`, `1.5hr`, `-1hr`) | + + Anything else comes back unchanged as a string. That includes text that only looks like a value, such as `12,34`, `1kb`, `0x10`, `null`, `nan`, `01:30:00` and an int too large for 64 bits. A string with leading or trailing whitespace is also returned as is, even `" 42"`. + + A date such as `01/02/2025` could be read either way, and `detect type` reads it month first, as January 2. `--prefer-dmy` reads it day first. When only one reading is a real date, as with `13/02/2025`, that one is used without the flag. A date-only string is midnight in the local time zone, unlike a date-only literal, which is midnight UTC. + + `--prefer-filesize` (`-f`) makes an int a file size of that many bytes: `"1024" | detect type -f` is `1.0 kB`. + - `ast` - In the branches of abstract syntax tree that describe the type of some element diff --git a/lang-guide/chapters/types/type_signatures.md b/lang-guide/chapters/types/type_signatures.md index e8008d00c84..bc5c10f5e06 100644 --- a/lang-guide/chapters/types/type_signatures.md +++ b/lang-guide/chapters/types/type_signatures.md @@ -46,9 +46,30 @@ There are 3 forms of valid type signatures in Nu: - Basic: E.g. `int`, `bool`, `string`, etc. - Compound: + - `list`, `record`, `table` + + `list` takes exactly one type parameter. `list` fails with "expected a single type parameter", so write `list>` for a list that mixes the two. A bare `list` means `list`, and `help` shows it that way. + + In `record<...>` and `table<...>`, a key without a type, such as `name` in `record`, has the type `any`. A key that isn't a bare word can be quoted, as in `record<"a b": int>`. A bare `record` or `table` places no limit on the fields or columns. + + The item type is checked. With `def f [x: list] {}`, the call `f [1.5]` fails to parse with "expected int", and `let x: list = [1.5]` is a `nu::parser::type_mismatch`. A list with mixed items has the type `list>`, which the parser can't rule out, so a mixed list assigned to an annotated variable is checked when the assignment runs: + + ```nu + let x: list = [1 a] + # => Error: nu::shell::type_mismatch + # => + # => × Type mismatch. + # => ╭─[repl_entry #1:1:1] + # => 1 │ let x: list = [1 a] + # => · ─┬─ ──┬── + # => · │ ╰── the value is a list> + # => · ╰── expected list, got list> + # => ╰──── + ``` + - Union: `oneof` matches a value of any of the listed types. When a literal argument is passed to a `oneof` parameter, it is parsed as the first listed type it matches, except that the text-like types (`string`, `path`, `directory`, `glob`, `cell-path`, `external_arg` and `any`) are always tried last. The order in which the types are written doesn't matter: @@ -155,6 +176,26 @@ type Tree = list # => help: type aliases can't be recursive ``` +The name of an alias follows these rules: + +- It starts with a letter or `_` and continues with letters, digits, `_` and `-`, as in `Point`, `_my-type2` or `Polygon3d`. Any other name, such as `1abc` or `my.type`, fails with `nu::parser::type_alias_name_not_valid`. +- It can't be the name of a built-in type, such as `int`, `list`, `record`, `number`, `path` or `oneof`. Names are case-sensitive, so `Int` is allowed. + + ```nu + type int = string + # => Error: nu::parser::type_alias_shadows_builtin + # => + # => × `int` is a built-in type. + # => ╭─[repl_entry #1:1:6] + # => 1 │ type int = string + # => · ─┬─ + # => · ╰── built-in type + # => ╰──── + # => help: choose a name that isn't a built-in type + ``` + +- An alias has no type parameters. `type Point = record` is an invalid name, and using a plain alias with parameters, as in `let p: Point = ...`, fails with `nu::parser::type_alias_with_params` ("Type alias `Point` takes no type parameters"). + A [custom completer](/book/custom_completions.md) is part of a parameter, not of its type, so it goes on the parameter that uses the alias, as in `def paint [color: Color@[red green blue]] { $color }`. Attaching one to the alias is an error: ```nu From 4e2acb8b8d8b72ade0de70b7b11055e33d0530d5 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:10:41 -0600 Subject: [PATCH 09/46] Add a configuration reference and fill gaps in the config docs Covers the rows rated `some` in the coverage checklist for startup files, `$env.config` update semantics, config commands, and the display and behavior settings that only `config nu --doc` described: - new page book/config_reference.md: every `$env.config` key in 0.117.0, grouped as `config nu --doc` groups them, with its type, default, accepted values, behavior, and a verified example - configuration: first-run messages, `config reset` after config.nu is deleted, editor lookup order, autoload directories, PATH lookup and `path add`, the default prompt, `config nu/env --doc/--default`, XDG variable handling, a table of every `nu` flag, and corrected launch-stage rows Where `config nu --doc` disagrees with the binary (the "KB" unit, tabs in ignore_space_prefixed, `~` in history.path, stream_page_size and collect), the new page follows the binary. --- .vuepress/configs/sidebar/en.ts | 1 + book/config_reference.md | 619 ++++++++++++++++++++++++++++++++ book/configuration.md | 162 ++++++++- 3 files changed, 764 insertions(+), 18 deletions(-) create mode 100644 book/config_reference.md diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts index 21578d95c55..973df1651cc 100644 --- a/.vuepress/configs/sidebar/en.ts +++ b/.vuepress/configs/sidebar/en.ts @@ -75,6 +75,7 @@ export const sidebarEn: SidebarConfig = { collapsible: false, children: [ '/book/configuration.md', + '/book/config_reference.md', '/book/environment.md', '/book/stdout_stderr_exit_codes.md', '/book/running_externals.md', diff --git a/book/config_reference.md b/book/config_reference.md new file mode 100644 index 00000000000..2294c7d2fdb --- /dev/null +++ b/book/config_reference.md @@ -0,0 +1,619 @@ +# Configuration reference + +This page lists every setting in the `$env.config` record, grouped the way `config nu --doc` groups them. For each one it gives the type, the default, the values Nushell accepts, and what the setting changes. + +Set a value by assigning to its cell path, usually in `config.nu`: + +```nu +$env.config.table.mode = "light" +``` + +[Changing Settings in the `$env.config` Record](./configuration.md#changing-settings-in-the-env-config-record) explains how assigning a whole record merges into the current settings, and [Errors in settings](./configuration.md#errors-in-settings) explains what Nushell does with a value it can't use. `$env.config` shows the values in effect, and [`config default`](/commands/docs/config_default.md) shows the built-in defaults. + +[[toc]] + +## History + +| Setting | Type | Default | +| ------------------------------- | ---------------- | ------------- | +| `history.file_format` | string | `"plaintext"` | +| `history.max_size` | int | `100_000` | +| `history.sync_on_enter` | bool | `true` | +| `history.isolation` | bool | `false` | +| `history.path` | string or `null` | `""` | +| `history.ignore_space_prefixed` | bool | `true` | + +Nushell reads `file_format`, `max_size`, `isolation`, and `path` once, when the REPL starts, so set them in `config.nu`. Changing one of them later raises a `nu::shell::config_option_locked_after_startup` error. The other two take effect at the next prompt. Commands run with `nu -c` or in a script are never added to the history. + +`max_size` is the number of entries plain-text history keeps. Once it is reached, each new entry pushes out the oldest one. SQLite history doesn't use it. + +### `history.file_format` + +`"plaintext"` stores one command per line, in a file named `history.txt`. `"sqlite"` stores the history in an SQLite database named `history.sqlite3`, and records more about each command: when it started, how long it ran, its exit status, the directory it ran in, the host name, and the session it came from. [`history --long`](/commands/docs/history.md) shows those columns, and `history.isolation` needs them. After you change `file_format`, [`history import`](/commands/docs/history_import.md) with no input copies the entries from the other format's file in the configuration directory into the file now in use. + +A `nu` built without its `sqlite` feature still accepts `"sqlite"`, but it warns and keeps using plain text. + +### `history.sync_on_enter` + +This setting only affects plain-text history. With `true`, after each command Nushell writes the new entries to the file and reads in the entries that other open Nushell sessions have written, so their commands show up when you press Up. With `false`, Nushell writes the file only when it exits. SQLite history saves every command as soon as you run it. + +### `history.isolation` + +With SQLite history, `true` hides the commands that other Nushell sessions run while this one is open, so they don't appear when you walk through the history with Up and Down. Commands from before the session started still do. Plain-text history can't tell sessions apart, so with `file_format: "plaintext"` this setting does nothing, and setting it to `true` gives a `nu::shell::incompatible_options` warning. + +### `history.path` + +| Value | History file | +| ------------------ | ---------------------------------------------------------------------- | +| `""` (the default) | `history.txt` or `history.sqlite3` in the configuration directory | +| a directory | `history.txt` or `history.sqlite3` in that directory | +| any other path | that file | +| `null` | none. The session remembers its own commands in memory until it exits. | + +`$nu.history-path` shows the file in use. + +Give an absolute path. Nushell uses the string as it is and doesn't expand `~`, so `"~/history.txt"` creates a directory literally named `~` inside the current directory. A relative path is resolved against the current directory every time Nushell writes the file, so after a `cd` your history goes to a different file. Build the path from one of the [`$nu` constants](./configuration.md#nu-constant) instead: + +```nu +$env.config.history.path = ($nu.home-dir | path join ".nu_history.txt") +``` + +### `history.ignore_space_prefixed` + +With `true`, a command line that starts with a space isn't saved to the history. A leading tab doesn't count. You can still bring the command back with Up until you run another command; after that it's gone. With `false`, every command is saved. + +## Startup and miscellaneous + +| Setting | Type | Default | +| ---------------------- | -------------- | ------- | +| `show_banner` | bool or string | `true` | +| `rm.always_trash` | bool | `false` | +| `recursion_limit` | int | `50` | +| `max_last_result_size` | filesize | `0b` | +| `auto_cd_implicit` | bool | `false` | + +### `show_banner` + +| Value | What Nushell shows when the REPL starts | +| ------------------- | ------------------------------------------ | +| `true` or `"full"` | The welcome message, then the startup time | +| `"short"` | Only the `Startup Time:` line | +| `false` or `"none"` | Nothing | + +Reading the setting back gives `true`, `"short"`, or `false`. The banner is the standard library's `banner` command, so `nu --no-std-lib` never shows it. Three `color_config` entries color it: `banner_foreground` for the text (default `"attr_normal"`), and `banner_highlight1` (default `"green"`) and `banner_highlight2` (default `"purple"`) for the highlighted words. See also [Remove Welcome Message](./configuration.md#remove-welcome-message). + +### `rm.always_trash` + +With `true`, [`rm`](/commands/docs/rm.md) moves files to the system trash as if you had passed `--trash`. With `false`, it deletes them permanently. The `--trash` and `--permanent` flags always win over this setting. The trash needs support from the operating system. + +### `recursion_limit` + +How deeply calls to custom commands and closures may nest. Each call to a custom command or closure, including those that [`each`](/commands/docs/each.md), `do`, and hooks make, adds one level. Going deeper raises `nu::shell::recursion_limit_reached` instead of crashing Nushell. The value must be greater than 1. + +### `max_last_result_size` + +How much memory `$ans.last` may hold. The default, `0b`, leaves `last` out of `$ans`. See [`$ans`](./special_variables.md#ans). + +### `auto_cd_implicit` + +At the prompt, you can change directories by typing just the path, without `cd`. This is called auto-cd: + +```nu +./src +~ +.. +``` + +Nushell treats a line as auto-cd when all of these are true: + +- The line is a single token. Wrapping it in backticks lets it contain spaces, as in `` `./My Documents` ``. +- The token looks like a path. It starts with `.`, `~`, `/`, or `\`, or it ends with the path separator (`/`, or `\` on Windows). On Windows, a drive such as `D:` or `D:\data` also counts. +- It names a directory that exists. + +`auto_cd_implicit: true` drops the second rule, so typing just `src` changes into the `src` subdirectory. The directory wins over a command of the same name. With a subdirectory named `ls`, typing `ls` changes into it, and you need `^ls` or `%ls` to run the command. + +Auto-cd sets `$env.OLDPWD` the way [`cd`](/commands/docs/cd.md) does, so `cd -` goes back, and it sets `$env.LAST_EXIT_CODE` to `0`. If you don't have permission to enter the directory, Nushell reports the error and stays where it is. A line that doesn't name an existing directory isn't auto-cd at all, so Nushell runs it as a command and reports that the command wasn't found. Auto-cd only works at the prompt, not in scripts. + +## Clipboard + +| Setting | Type | Default | +| -------------------- | ---- | ---------------------------------- | +| `clip.resident_mode` | bool | `true` on Linux, `false` elsewhere | +| `clip.default_raw` | bool | `false` | + +These settings are for the built-in `clip copy` and `clip paste` commands, which only exist when the `native-clip` [experimental option](./configuration.md#experimental-options) is on. The standard library's `clip copy52` and `clip paste52` don't read them. + +### `clip.resident_mode` + +Only Linux uses this setting. On Linux, a program that copies text has to keep running to hand that text to other programs, unless a clipboard manager takes it over. With `true`, `clip copy` passes the text to a background thread inside Nushell, which keeps serving it until Nushell exits. In 0.117.0, Nushell uses that thread on Linux even when this setting is `false`. Only the older plugin-style setting, `$env.config.plugins.clip.NO_RESIDENT = true`, turns it off. + +### `clip.default_raw` + +`clip paste` parses clipboard text that starts with `{`, `[`, or `"` as JSON and returns the value, and returns any other text, or text that isn't valid JSON, as a string. `clip paste --raw` always returns a string. `default_raw: true` swaps the two, so plain `clip paste` returns a string and `clip paste --raw` parses JSON. + +`clip copy` doesn't read this setting. It copies a string as it is and copies any other value as the plain-text table that Nushell would print for it. + +## Line editor + +| Setting | Type | Default | +| --------------------------- | ------------------------------- | ----------- | +| `edit_mode` | string | `"emacs"` | +| `buffer_editor` | string, list of strings, `null` | `null` | +| `cursor_shape.emacs` | string | `"inherit"` | +| `cursor_shape.vi_insert` | string | `"inherit"` | +| `cursor_shape.vi_normal` | string | `"inherit"` | +| `cursor_shape.vi_visual` | string | `"inherit"` | +| `cursor_shape.helix_normal` | string | `"inherit"` | +| `cursor_shape.helix_select` | string | `"inherit"` | +| `cursor_shape.helix_insert` | string | `"inherit"` | +| `show_hints` | bool | `true` | +| `hinter.closure` | closure or `null` | `null` | +| `status_line.enable` | bool | `true` | +| `status_line.errors` | bool | `true` | +| `status_line.signature` | bool | `true` | +| `status_line.type` | bool | `true` | +| `status_line.preview` | bool | `true` | + +- `edit_mode` is `"emacs"`, `"vi"`, or `"helix"`. See [Setting the Editing Mode](./line_editor.md#setting-the-editing-mode). +- Each `cursor_shape` entry is one of `"block"`, `"underscore"`, `"line"`, `"blink_block"`, `"blink_underscore"`, `"blink_line"`, or `"inherit"`, which leaves the terminal's cursor alone. `vi_visual: "inherit"` uses the `vi_normal` shape. +- `show_hints` and `hinter.closure` control the gray suggestion after the cursor. See [Hints](./line_editor.md#hints). +- `status_line` controls the line under the one you are editing. See [Status Line](./line_editor.md#status-line). + +### `buffer_editor` + +The editor that Ctrl+O opens to edit the current command line, and that [`config nu`](/commands/docs/config_nu.md) and [`config env`](/commands/docs/config_env.md) open. When it is `null`, an empty string, or an empty list, Nushell uses `$env.VISUAL`, and when that isn't set either, `$env.EDITOR`. With none of them set, those commands fail with `No editor configured`. + +A string is the name of the program and nothing else. `"code --wait"` makes Nushell look for a program named `code --wait`, and fail. To pass arguments, use a list: + +```nu +$env.config.buffer_editor = ["code", "--wait"] +``` + +An argument can contain the placeholders `{file}`, `{line}`, and `{col}`. Nushell replaces them with the path of the file to edit and a line and column, both counted from 1. For Ctrl+O, the line and column are where the cursor is in the command line; `config nu` and `config env` use line 1, column 1. Nushell adds the file path as the last argument unless an argument contains `{file}` or is the file path itself. + +```nu +$env.config.buffer_editor = ["hx", "{file}:{line}:{col}"] +$env.config.buffer_editor = ["vim", "+{line}"] # the file path is appended +``` + +## Completions + +| Setting | Type | Default | +| ---------------------------------- | ----------------------- | ---------- | +| `completions.algorithm` | string | `"prefix"` | +| `completions.sort` | string | `"smart"` | +| `completions.case_sensitive` | bool | `false` | +| `completions.quick` | bool | `true` | +| `completions.partial` | bool | `true` | +| `completions.persistent_menus` | bool | `false` | +| `completions.use_ls_colors` | bool | `true` | +| `completions.cache_size` | int | `100` | +| `completions.external.enable` | bool | `true` | +| `completions.external.max_results` | int | `100` | +| `completions.external.completer` | closure, record, `null` | `null` | + +- `algorithm` is `"prefix"` (match from the start), `"substring"` (match anywhere), or `"fuzzy"`. +- `sort` is `"smart"` or `"alphabetical"`. `"smart"` sorts alphabetically for `prefix` and `substring`, and by match score for `fuzzy`. +- `quick: true` fills in the only remaining suggestion without opening a menu. +- `partial: true` fills in the part that all suggestions share. With `apple`, `apricot`, and `apron` in a directory, Tab after `ls a` fills in `ap`. +- `persistent_menus: true` keeps a menu open while you delete text or empty the line, refiltering it instead. The menu closes on Esc, Ctrl+C, or when you accept a value. This applies to the history menu too. +- `use_ls_colors` colors file and directory suggestions with `LS_COLORS`. +- `external.enable: false` stops Nushell from searching `PATH` for command names, which helps when `PATH` includes slow file systems. `external.max_results` limits how many it collects. +- `external.completer` is a closure that completes arguments of external commands. See [External Completions](./custom_completions.md#external-completions). + +### `completions.cache_size` + +Nushell remembers the suggestions it computed for the text up to the cursor, such as `ls ap`, and reuses them the next time you complete the same text, instead of reading the directory or the list of commands again. `cache_size` is how many of these it keeps. When the cache is full, the one used least recently is dropped. `0` turns the cache off, so every completion is computed again. + +The cache lasts from one prompt to the next. Nushell empties it when anything that could change the answers changes: + +- the current directory, or the files in it +- `PATH` +- the set of commands, for example after you define or import one +- `$env.config` + +Answers from [custom completers](./custom_completions.md) and from `completions.external.completer` are cached the same way. A completer that lists data that changes on its own, such as Git branches, can therefore show an old list until one of the changes above happens. A completer that runs an `@interactive` command is never cached. See [Interactive Completers](./custom_completions.md#interactive-completers). + +## Terminal integration + +| Setting | Type | Default | +| ------------------------------------------ | ---------------- | -------------------------- | +| `use_kitty_protocol` | bool | `false` | +| `shell_integration.osc2` | bool | `true` | +| `shell_integration.osc7` | bool | `true`, `false` on Windows | +| `shell_integration.osc8` | bool | `true` | +| `shell_integration.osc9_9` | bool | `false`, `true` on Windows | +| `shell_integration.osc133` | bool | `true` | +| `shell_integration.osc633` | bool | `true` | +| `shell_integration.reset_application_mode` | bool | `true` | +| `bracketed_paste` | bool | `true` | +| `use_ansi_coloring` | bool or `"auto"` | `"auto"` | + +Each of these makes Nushell send escape sequences that the terminal has to understand. Turn off the ones your terminal doesn't support. + +- `use_kitty_protocol` turns on the Kitty keyboard protocol, which lets the terminal report keys that otherwise look the same, such as Ctrl+I and Tab. +- `osc2` sets the window or tab title to the current directory and the running command. +- `osc7` tells the terminal the current directory, so a new tab or window can open there. `osc9_9` does the same for ConEmu and Windows Terminal. +- `osc8` makes file names in [`ls`](/commands/docs/ls.md) output clickable. See [`ls.clickable_links`](#ls). +- `osc133` marks where prompts, commands, and their output start and end, and reports exit codes, for terminals that can jump between prompts or select a command's output. `osc633` sends the VS Code variant of the same marks. +- `reset_application_mode` sends `ESC[?1l` after each command, which keeps the arrow keys working after an SSH session to a host that changed the cursor key mode. +- `bracketed_paste` lets you paste several lines without running each one as it arrives. It isn't supported on Windows. + +### `use_ansi_coloring` + +`true` always colors output and `false` never does. `"auto"` checks these in order and uses the first that applies: + +1. `FORCE_COLOR` set to anything other than `0`, `false`, or an empty string turns colors on. +2. `NO_COLOR` set the same way turns them off. +3. `CLICOLOR` turns them off when it is `0`, `false`, or empty, and on when it has any other value. +4. `TERM` set to `dumb` turns them off. +5. Otherwise, Nushell colors output when its standard output is a terminal. + +Without colors, error messages are drawn with plain ASCII characters instead of line-drawing ones. The [`ansi`](/commands/docs/ansi.md) command ignores this setting. + +## Errors + +| Setting | Type | Default | +| ----------------------------------- | ------ | --------- | +| `error_style` | string | `"fancy"` | +| `error_lines` | int | `1` | +| `display_errors.exit_code` | bool | `false` | +| `display_errors.termination_signal` | bool | `true` | + +### `error_style` + +- `"fancy"` draws the source code around the error and points at the problem with line-drawing characters. +- `"nested"` is like `"fancy"`, and shows related errors nested under the main one. +- `"plain"` describes the error and its location in plain sentences, which works better with screen readers. +- `"short"` prints the error on one line. + +`nu --error-style` sets the style for a `nu -c` run only, and accepts only `fancy`, `plain`, and `short`. + +### `error_lines` + +How many lines of source code `"fancy"` and `"nested"` errors show above and below the line with the error. `0` shows only that line. The value must be `0` or more. `"plain"` errors always show one line of context, and `"short"` errors show none. + +### `display_errors` + +`exit_code: true` makes Nushell print an error when an external command exits with a non-zero code. With `false`, you see only what the command itself printed. Either way, the failure stops the rest of the pipeline and script. A core dump is always reported, and `SIGPIPE` is never treated as an error. + +`termination_signal: true` makes Nushell print an error when a signal ends an external command. + +## Tables + +| Setting | Type | Default | +| ----------------------------- | ------------- | ---------------------------------------------------------- | +| `table.mode` | string | `"rounded"` | +| `table.index_mode` | string | `"always"` | +| `table.show_empty` | bool | `true` | +| `table.padding` | record or int | `{left: 1, right: 1}` | +| `table.trim` | record | `{methodology: "wrapping", wrapping_try_keep_words: true}` | +| `table.header_on_separator` | bool | `false` | +| `table.abbreviated_row_count` | int or `null` | `null` | +| `table.footer_inheritance` | bool | `false` | +| `table.missing_value_symbol` | string | a cross mark (U+274E) | +| `table.batch_duration` | duration | `1sec` | +| `table.stream_page_size` | int | `1000` | +| `footer_mode` | string or int | `25` | + +`table.mode` sets the border style. [Table Borders](./coloring_and_theming.md#table-borders) shows the styles, and `table --list` lists their names. `nu --table-mode` (`-m`) overrides it for one run, and `table --theme` for one table. + +### `table.index_mode` + +- `"always"` shows the `#` column. +- `"never"` hides it. +- `"auto"` shows it only for data that has a column named `index`. + +When the data has an `index` column and the `#` column is shown, the `#` column shows that column's values instead of row numbers. With `"never"`, `index` is an ordinary column. + +```nu +$env.config.table.index_mode = "auto" +[[name size]; [a 1] [b 2]] +# => ╭──────┬──────╮ +# => │ name │ size │ +# => ├──────┼──────┤ +# => │ a │ 1 │ +# => │ b │ 2 │ +# => ╰──────┴──────╯ +[[index name]; [x a] [y b]] +# => ╭───┬──────╮ +# => │ # │ name │ +# => ├───┼──────┤ +# => │ x │ a │ +# => │ y │ b │ +# => ╰───┴──────╯ +``` + +[`table --index false`](/commands/docs/table.md) hides the column for one table, and `table --index 1` numbers the rows from 1. Neither brings the column back when `index_mode` hides it. + +### `table.show_empty` + +With `true`, an empty list prints as a small table that reads `empty list`, and an empty record as one that reads `empty record`. With `false`, they print nothing. Empty lists and records inside a table are always shown as `[list 0 items]` and `{record 0 fields}`. + +### `table.padding` + +The number of spaces between a cell's border and its text, on the left and on the right. Each must be `0` or more. An int sets both sides at once: + +```nu +$env.config.table.padding = 0 +[[name size]; [a 1] [b 2]] +# => ╭─┬────┬────╮ +# => │#│name│size│ +# => ├─┼────┼────┤ +# => │0│a │ 1│ +# => │1│b │ 2│ +# => ╰─┴────┴────╯ +``` + +Reading the setting back always gives a record, such as `{left: 0, right: 0}`. + +### `table.trim` + +What Nushell does with a table that is wider than the terminal. The record must have a `methodology` key, which is `"wrapping"` or `"truncating"`: + +- `{methodology: "wrapping", wrapping_try_keep_words: true}` wraps text that doesn't fit onto more lines. With `wrapping_try_keep_words: true`, it breaks lines between words where it can; with `false`, it breaks them anywhere. +- `{methodology: "truncating", truncating_suffix: "..."}` keeps each row on one line and cuts text that doesn't fit, ending it with `truncating_suffix`. Without a suffix, or with `null`, the text is cut with no marker. + +Each method ignores the other's key. If you switch methods without giving the key, `wrapping_try_keep_words` becomes `false`, and `truncating_suffix` becomes empty. + +```nu +let row = [[name description]; [alpha "the quick brown fox jumps over the lazy dog"]] +$row | table --width 40 +# => ╭───┬───────┬──────────────────────────╮ +# => │ # │ name │ description │ +# => ├───┼───────┼──────────────────────────┤ +# => │ 0 │ alpha │ the quick brown fox │ +# => │ │ │ jumps over the lazy dog │ +# => ╰───┴───────┴──────────────────────────╯ +$env.config.table.trim = {methodology: "truncating", truncating_suffix: "..."} +$row | table --width 40 +# => ╭───┬───────┬──────────────────────────╮ +# => │ # │ name │ description │ +# => ├───┼───────┼──────────────────────────┤ +# => │ 0 │ alpha │ the quick brown fox j... │ +# => ╰───┴───────┴──────────────────────────╯ +``` + +When the columns don't fit even after shrinking, Nushell shows as many as it can, each at least 10 characters wide or as wide as its contents if that is less, and replaces the rest with a single column of `...`. That marker is not `truncating_suffix`: + +```nu +[{name: alpha, size: 1234, owner: someone, modified: "2024-01-01", note: "long text here"}] | table --width 40 +# => ╭───┬───────┬──────┬─────────┬─────╮ +# => │ # │ name │ size │ owner │ ... │ +# => ├───┼───────┼──────┼─────────┼─────┤ +# => │ 0 │ alpha │ 1234 │ someone │ ... │ +# => ╰───┴───────┴──────┴─────────┴─────╯ +``` + +### `table.header_on_separator` + +With `true`, the column names are drawn in the top border, and in the bottom border when there is a footer: + +```nu +$env.config.table.header_on_separator = true +[[name size]; [a 1] [b 2]] +# => ╭─#─┬─name─┬─size─╮ +# => │ 0 │ a │ 1 │ +# => │ 1 │ b │ 2 │ +# => ╰───┴──────┴──────╯ +``` + +A column is always at least as wide as its name. If a column name contains a character that isn't one column wide, such as a CJK character, an emoji, or a newline, the names go back to their own row. The `markdown` and `restructured` modes always keep the names in their own row, so the output stays valid markup. + +### `table.abbreviated_row_count` + +With an int `n`, a list or table longer than that shows its first `n` and last `n` rows, with a row of `...` between them. The `#` column numbers the rows that are shown, so it doesn't match their positions in the data. A record with more than `2n + 1` fields is shortened the same way. `null` shows every row. + +```nu +$env.config.table.abbreviated_row_count = 2 +1..10 +# => ╭───┬─────╮ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ ... │ +# => │ 3 │ 9 │ +# => │ 4 │ 10 │ +# => ╰───┴─────╯ +``` + +[`table --abbreviated`](/commands/docs/table.md) (`-a`) sets the count for one table. While abbreviation is on, Nushell reads the whole stream before it prints anything, so `batch_duration` and `stream_page_size` don't apply, and an endless stream prints nothing. + +### `footer_mode` and `table.footer_inheritance` + +A footer repeats the column names below the last row. `footer_mode` decides when a table gets one: + +- `"always"` and `"never"` do what they say. +- An int `n`, such as the default `25`, adds a footer when the table has `n` rows or more. +- `"auto"` adds a footer when the table has at least as many rows as the terminal has lines, so that its header would scroll out of sight. + +`table.footer_inheritance` matters for nested tables, as drawn by [`table --expand`](/commands/docs/table.md) and by the default display at 100 or more terminal columns. With `false`, each table counts only its own rows. With `true`, a table counts the rows of the tables nested in it too, so a short outer table around a long inner one gets a footer as well. + +### `table.missing_value_symbol` + +What a table shows in a cell when the row has no value for that column. The default is the cross-mark emoji U+274E. Its color comes from `color_config.empty`. A `null` value is different, and shows as an empty cell. + +```nu +$env.config.table.missing_value_symbol = "-" +[{name: a, size: 1} {name: b}] +# => ╭───┬──────┬──────╮ +# => │ # │ name │ size │ +# => ├───┼──────┼──────┤ +# => │ 0 │ a │ 1 │ +# => │ 1 │ b │ - │ +# => ╰───┴──────┴──────╯ +``` + +### `table.batch_duration` and `table.stream_page_size` + +Nushell prints a list in batches, as separate tables, so that the rows of a slow stream show up before the stream ends. A batch ends when it has `stream_page_size` rows or when `batch_duration` has passed since it started, whichever comes first. `stream_page_size` must be between 1 and 65535. + +A list that is already complete is split by `stream_page_size` too. With the default, a list of 1500 rows prints as one table of 1000 rows and one of 500, which may have different column widths. [`collect`](/commands/docs/collect.md) doesn't change this. + +```nu +$env.config.table.stream_page_size = 2 +1..5 +# => ╭───┬───╮ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => ╰───┴───╯ +# => ╭───┬───╮ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => ╰───┴───╯ +# => ╭───┬───╮ +# => │ 4 │ 5 │ +# => ╰───┴───╯ +``` + +## Dates, file sizes, and numbers + +| Setting | Type | Default | +| ------------------------ | ---------------- | ---------- | +| `datetime_format.normal` | string or `null` | `null` | +| `datetime_format.table` | string or `null` | `null` | +| `filesize.unit` | string | `"metric"` | +| `filesize.show_unit` | bool | `true` | +| `filesize.precision` | int or `null` | `1` | +| `duration_max_unit` | string | `"wk"` | +| `float_precision` | int | `2` | + +### `datetime_format` + +`normal` formats a date printed on its own and a date in string interpolation. `table` formats dates inside tables, lists, and records. Each one is a format string as used by [`format date`](/commands/docs/format_date.md); `format date --list` lists the specifiers. A format string Nushell can't use prints as `Invalid format string` followed by the string. + +With `null`, a date on its own prints as an RFC 2822 date followed by how long ago it was, such as `Tue, 2 Jan 2024 03:04:05 +0000 (2 years ago)`, and a date in a table prints only the relative part, such as `2 years ago`. + +```nu +$env.config.datetime_format.normal = "%Y-%m-%d %H:%M" +2024-01-02T03:04:05Z +# => 2024-01-02 03:04 +$env.config.datetime_format.table = "%Y-%m-%d" +[2024-01-02T03:04:05Z] +# => ╭───┬────────────╮ +# => │ 0 │ 2024-01-02 │ +# => ╰───┴────────────╯ +``` + +[`into string`](/commands/docs/into_string.md) and [`format date`](/commands/docs/format_date.md) don't use these settings. + +### `filesize` + +`filesize.unit` is `"metric"` (the default), `"binary"`, or a fixed unit. `"metric"` picks a unit for each value in powers of 1000 (kB, MB, GB), and `"binary"` in powers of 1024 (KiB, MiB, GiB). A fixed unit shows every value in that unit, and is one of `"B"`, `"kB"`, `"MB"`, `"GB"`, `"TB"`, `"PB"`, `"EB"`, `"KiB"`, `"MiB"`, `"GiB"`, `"TiB"`, `"PiB"`, or `"EiB"`. The names are case-sensitive. + +`filesize.precision` is the number of decimal places. Extra digits are cut off, not rounded, so 1,999,999 bytes shows as `1.9 MB`. A value in bytes never has decimals. `null` shows every significant digit. The value can't be negative. + +`filesize.show_unit: false` leaves the unit off. Use it with a fixed unit, since with `"metric"` or `"binary"` the numbers no longer say which unit they are in. + +```nu +[1_999_999b 1_000b 500b] +# => ╭───┬────────╮ +# => │ 0 │ 1.9 MB │ +# => │ 1 │ 1.0 kB │ +# => │ 2 │ 500 B │ +# => ╰───┴────────╯ +$env.config.filesize.precision = null +[1_999_999b 1_000b 500b] +# => ╭───┬─────────────╮ +# => │ 0 │ 1.999999 MB │ +# => │ 1 │ 1 kB │ +# => │ 2 │ 500 B │ +# => ╰───┴─────────────╯ +$env.config.filesize = {unit: "kB", show_unit: false, precision: 1} +[1_999_999b 1_000b 500b] +# => ╭───┬─────────╮ +# => │ 0 │ 1,999.9 │ +# => │ 1 │ 1.0 │ +# => │ 2 │ 0.5 │ +# => ╰───┴─────────╯ +``` + +### `duration_max_unit` + +The largest unit used to print a duration. Nushell splits a duration into units from this one down. The values are `"wk"`, `"day"`, `"hr"`, `"min"`, `"sec"`, `"ms"`, `"us"` (also written `"µs"`), and `"ns"`. + +```nu +365day +# => 52wk 1day +$env.config.duration_max_unit = "day" +[365day 90min] +# => ╭───┬───────────╮ +# => │ 0 │ 365day │ +# => │ 1 │ 1hr 30min │ +# => ╰───┴───────────╯ +``` + +[`into string`](/commands/docs/into_string.md) uses this setting too. + +### `float_precision` + +The number of decimal places for floats in tables, lists, and records. Nushell rounds to it and pads with zeros. A float printed on its own shows all its digits. + +```nu +[3.14159 2.0] +# => ╭───┬──────╮ +# => │ 0 │ 3.14 │ +# => │ 1 │ 2.00 │ +# => ╰───┴──────╯ +3.14159 +# => 3.14159 +``` + +## `ls` + +| Setting | Type | Default | +| -------------------- | ---- | ------- | +| `ls.use_ls_colors` | bool | `true` | +| `ls.clickable_links` | bool | `true` | + +`ls.use_ls_colors` colors file names in [`ls`](/commands/docs/ls.md) output with the `LS_COLORS` environment variable. With `false`, Nushell doesn't use `LS_COLORS` for them. See [`LS_COLORS` Colors for the `ls` Command](./coloring_and_theming.md#ls-colors-colors-for-the-ls-command). + +`ls.clickable_links` makes each file name in `ls` output an OSC 8 hyperlink to the file, which terminals that support OSC 8 let you click. Nushell only adds the links when all of these hold: + +- `ls.clickable_links` and `shell_integration.osc8` are both `true`. +- `ls.use_ls_colors` is `true` and the output is colored (see [`use_ansi_coloring`](#use-ansi-coloring)). +- The `SSH_CLIENT` environment variable isn't set. Nushell leaves the links out in SSH sessions, where they wouldn't work. +- The file exists. + +## Prompt and highlighting + +| Setting | Type | Default | +| ---------------------------------- | ------ | ------------------ | +| `render_right_prompt_on_last_line` | bool | `false` | +| `highlight_resolved_externals` | bool | `false` | +| `color_config` | record | the built-in theme | + +`render_right_prompt_on_last_line: true` draws the right prompt on the last line of a multi-line left prompt instead of the first. See [Prompt Configuration and Coloring](./coloring_and_theming.md#prompt-configuration-and-coloring). + +`highlight_resolved_externals: true` colors an external command name at the prompt with `color_config.shape_external_resolved` (default `light_yellow_bold`) when Nushell finds the command on `PATH`, so you can tell a typo before you press Enter. With `false`, every external command name gets `shape_external`. The setting is off by default because looking up names on `PATH` while you type can slow highlighting down. + +`color_config` sets the colors of output values, syntax highlighting, and parts of the interface. It is a free-form record, so assigning a whole record replaces all of it; change single entries instead, as in `$env.config.color_config.string = "red"`. See [Coloring and Theming](./coloring_and_theming.md). + +## Hooks, keybindings, menus, and abbreviations + +| Setting | Type | Default | Documentation | +| ------------------------- | ----------------------- | ------------------------------------------------------------- | ---------------------------------------------------- | +| `hooks.pre_prompt` | list | `[]` | [Hooks](./hooks.md) | +| `hooks.pre_execution` | list | `[]` | [Hooks](./hooks.md) | +| `hooks.env_change` | record | `{}` | [Hooks](./hooks.md#changing-environment) | +| `hooks.display_output` | string, closure, `null` | `"if (term size).columns >= 100 { table -e } else { table }"` | [Hooks](./hooks.md#changing-how-output-is-displayed) | +| `hooks.command_not_found` | closure or `null` | `null` | [Hooks](./hooks.md) | +| `keybindings` | list | Nushell's menu keybindings | [Keybindings](./line_editor.md#keybindings) | +| `menus` | list | the completion, IDE completion, history, and help menus | [Menus](./line_editor.md#menus) | +| `abbreviations` | record | `{}` | [Abbreviations](./line_editor.md#abbreviations) | + +`keybindings`, `menus`, the hook lists, `hooks.env_change`, and `abbreviations` are replaced whole when you assign them. Add to them with `++=` or [`merge`](/commands/docs/merge.md), as those pages show, to keep the entries already there. + +## Plugins + +| Setting | Type | Default | +| ------------------------------ | -------- | ------- | +| `plugins` | record | `{}` | +| `plugin_gc.default.enabled` | bool | `true` | +| `plugin_gc.default.stop_after` | duration | `10sec` | +| `plugin_gc.plugins` | record | `{}` | + +`plugins` holds settings for each plugin, under the plugin's name. Assigning a whole record to it replaces the settings of every plugin. `plugin_gc` decides when Nushell stops plugins that have been idle. See [Plugin Garbage Collector](./plugins.md#plugin-garbage-collector). + +## `explore` and `tui` + +`explore` holds the colors of the [`explore`](/commands/docs/explore.md) viewer, and `tui` holds the colors and the `border_type` of the [`tui`](./tui.md) commands. Both are free-form, so assigning a whole record replaces it. See [`explore` Config](./explore.md#config) and [Theming the `tui` commands](./tui.md#theming). diff --git a/book/configuration.md b/book/configuration.md index 048b6a268b9..d9c5653da0f 100644 --- a/book/configuration.md +++ b/book/configuration.md @@ -88,15 +88,25 @@ $nu.default-config-dir # => C:\Users\me\AppData\Roaming\nushell ``` -The first time Nushell is launched, it will create the configuration directory and an empty (other than comments) `env.nu` and `config.nu`. +The first time Nushell is launched, it will create the configuration directory and an empty (other than comments) `env.nu` and `config.nu`. It prints where it put them: + +``` +Environment config file created at: /home/me/.config/nushell/env.nu +Config file created at: /home/me/.config/nushell/config.nu +``` + +Nushell decides that this is the first launch only when the configuration directory doesn't exist. If you delete `config.nu` later, Nushell starts without it and doesn't write a new one. To get the commented `config.nu` back, run `config reset --nu --without-backup`. Plain [`config reset`](/commands/docs/config_reset.md) writes the same text into both files after renaming the current ones to `oldconfig-.nu` and `oldenv-.nu`, and fails if one of them is missing. Nushell doesn't create the `autoload` directory; see [Autoload directories](#autoload-directories). ::: tip -You can quickly open `config.nu` in your default text editor using the `config nu` command. Likewise, the `config env` command will open `env.nu`. +You can quickly open `config.nu` in your default text editor using the `config nu` command. Likewise, the `config env` command will open `env.nu`. If Nushell was started with `--config` or `--env-config`, these commands open that file instead. + +This requires that you have configured an editor. Nushell uses the first of these that is set: -This requires that you have configured a default editor using either: +1. Nushell's `$env.config.buffer_editor` setting +2. The `$env.VISUAL` environment variable +3. The `$env.EDITOR` environment variable -- Nushell's `$env.config.buffer_editor` setting -- The `$env.VISUAL` or `$env.EDITOR` environment variables +If none of them is set, `config nu` fails with a `No editor configured` error. For example, place this in your `config.nu` to edit your files in Visual Studio Code: @@ -104,8 +114,32 @@ For example, place this in your `config.nu` to edit your files in Visual Studio $env.config.buffer_editor = 'code' ``` +A string names only the program. To pass arguments to the editor, use a list, as in `['code', '--wait']`. See [`buffer_editor`](./config_reference.md#buffer-editor) for the `{file}`, `{line}`, and `{col}` placeholders. ::: +### Autoload directories + +After `config.nu`, and after `login.nu` in a login shell, Nushell loads every file whose name ends in `.nu` from the autoload directories. It goes through the vendor directories first, in the order `$nu.vendor-autoload-dirs` lists them, then the user directory. Directories that don't exist are skipped. + +Within a directory, files load in the byte order of their names, not in dictionary order. Digits come before uppercase letters, uppercase before lowercase, and `10.nu` before `9.nu`. If the order matters, start the names with zero-padded numbers, such as `01-path.nu` and `02-aliases.nu`. Nushell doesn't look inside subdirectories and skips files with other extensions. + +`$nu.user-autoload-dirs` always holds exactly one directory, `autoload` inside the configuration directory, so it moves along with `XDG_CONFIG_HOME` and `--config-home`. Nushell doesn't create it. To start using it: + +```nu +mkdir ($nu.user-autoload-dirs | first) +``` + +`$nu.vendor-autoload-dirs` is for files that package managers and other programs install. It lists, in load order: + +1. On macOS, `/Library/Application Support/nushell/vendor/autoload`. +2. On Linux, macOS, and other Unix systems, `nushell/vendor/autoload` in each directory of `XDG_DATA_DIRS`, starting with the last one, so that the first directory loads last and wins. When `XDG_DATA_DIRS` is unset or empty, Nushell uses `/usr/local/share/:/usr/share/`, which packagers can change when they build Nushell. Relative entries are skipped. +3. On Windows, `nushell\vendor\autoload` in `%ProgramData%`. +4. The directory that packagers can compile in with `NU_VENDOR_AUTOLOAD_DIR`, if there is one. +5. `vendor/autoload` in `$nu.data-dir`. +6. The directory in the `NU_VENDOR_AUTOLOAD_DIR` environment variable, if it is set to an absolute path. + +A directory that would appear twice is listed only once, in its first place. See [Startup Variables](#startup-variables) for the variables that change these directories. + ## Common Configuration Tasks in `config.nu`: ::: tip @@ -131,6 +165,8 @@ The [Environment](./environment.md) Chapter covers additional information on how As with most shells, Nushell searches the environment variable named `PATH` (or variants). +To run an external command, Nushell looks for it in the `PATH` directories, in order. On Windows, it looks in the current directory first, before any `PATH` entry. Windows also tries the file extensions listed in `PATHEXT`. Nushell reads that list from the environment it was started with, so changing `$env.PATHEXT` inside Nushell doesn't change which files it finds. + :::tip Unlike some shells, Nushell attempts to be "case agnostic" with environment variables. `Path`, `path`, `PATH`, and even `pAtH` are all allowed variants of the same environment variable. See [Environment - Case Sensitivity](./environment.md#case-sensitivity) for details. ::: @@ -151,10 +187,33 @@ path add "~/.local/bin" path add ($nu.home-dir | path join ".cargo" "bin") ``` +`path add` takes one or more paths and changes `$env.PATH`, or `$env.Path` when there is no `PATH` variable: + +- It expands each path with [`path expand --no-symlink`](/lang-guide/chapters/types/other_types/path.md#absolute-paths-with-path-expand), so `~` and relative paths become absolute and symbolic links are kept as they are. +- `--append` (`-a`) adds the paths at the end instead of the front. +- Afterwards, it removes repeated entries from the whole list, keeping the first. A directory that is already in the path moves to the front, or stays where it was with `--append`. +- `--ret` (`-r`) also returns the new list. +- A record picks a path by operating system, using the names that `$nu.os-info.name` reports, such as `linux`, `macos`, and `windows`. A record without a key for the current system adds nothing. +- With no paths, it fails with `Empty input`, and with a value that isn't a string or a record, `Invalid input`. + +```nu +path add --append {linux: "/opt/tools/bin", macos: "/opt/homebrew/bin"} +``` + ::: tip Notice the use of `path join` in the example above. This command properly joins two path components regardless of whether or not the path separator is present. See `help path` for more commands in this category. + +[`path join`](/commands/docs/path_join.md) also joins a list of parts, and a part that is an absolute path replaces everything before it: + +```nu +[$nu.home-dir ".cargo" "bin"] | path join +# => /home/me/.cargo/bin +"/home/me" | path join "/opt/tools" "bin" +# => /opt/tools/bin +``` + ::: ### Prompt Configuration @@ -162,9 +221,9 @@ more commands in this category. Nushell provides a number of prompt configuration options. By default, Nushell includes: - A prompt which includes the current directory, abbreviated using `~` if it is (or is under) - the home directory. + the home directory. The directory is green, or red when Nushell runs with administrator (root) rights. - A prompt indicator which appears immediately to the right of the prompt. This defaults to `> ` when in normal editing mode, or a `: ` when in Vi-insert mode. Note extra space after the character to provide separation of the command from the prompt. -- A right-prompt with the date and time +- A right-prompt with the date and time. When the last command failed, its exit code (`$env.LAST_EXIT_CODE`) appears in red in front of the date. - An indicator which is displayed when the current commandline extends over multiple lines - `::: ` by default The environment variables which control these prompt components are: @@ -278,6 +337,8 @@ $env.ENV_CONVERSIONS = $env.ENV_CONVERSIONS | merge { } ``` +`path expand --no-symlink` makes each directory absolute without following symbolic links, so a linked directory keeps the path you gave it. See [Absolute paths with `path expand`](/lang-guide/chapters/types/other_types/path.md#absolute-paths-with-path-expand). + ### `LS_COLORS` As with many `ls`-like utilities, Nushell's directory listings make use of the `LS_COLORS` environment variable for defining styles/colors to apply to certain file types and patterns. @@ -316,12 +377,14 @@ config nu --doc | nu-highlight | bat config nu --doc | nu-highlight | less -R ``` -Some of the more recently added settings are: +`config nu --default` prints the built-in `default_config.nu` instead, and `config env --doc` and `config env --default` do the same for `env.nu`. Each command takes only one of the two flags at a time; giving both is an error. + +The [Configuration reference](./config_reference.md) lists every setting with its type, default, and accepted values. Some of the more recently added settings are: -- `error_style`: `"fancy"` (the default), `"plain"`, `"short"` for concise single-line error messages, or `"nested"` to show related errors nested under the main one. `error_lines` sets how many lines of source code are shown around the location of an error (default `1`). -- `auto_cd_implicit`: when `true`, typing just the name of a subdirectory (such as `src`) changes into it. By default, auto-cd requires a path such as `./src`. -- `history.path`: a custom location for the history file, or `null` to disable history. `history.ignore_space_prefixed` (default `true`) keeps commands that start with a space out of the history. -- `completions.cache_size`: how many Tab-completion prefixes to remember (default `100`; `0` disables the cache). `completions.persistent_menus`: when `true`, completion and history menus stay open while you edit the commandline. +- `error_style`: `"fancy"` (the default), `"plain"`, `"short"` for concise single-line error messages, or `"nested"` to show related errors nested under the main one. `error_lines` sets how many lines of source code the `fancy` and `nested` styles show above and below the line with the error (default `1`, and it can't be negative). See [Errors](./config_reference.md#errors). +- `auto_cd_implicit`: when `true`, typing just the name of a subdirectory (such as `src`) changes into it. By default, auto-cd requires a path such as `./src`. See [`auto_cd_implicit`](./config_reference.md#auto-cd-implicit) for how auto-cd works. +- `history.path`: a custom location for the history file, or `null` to keep no history file. `history.ignore_space_prefixed` (default `true`) keeps commands that start with a space out of the history. See [History](./config_reference.md#history). +- `completions.cache_size`: how many Tab-completion prefixes to remember (default `100`; `0` disables the cache). `completions.persistent_menus`: when `true`, completion and history menus stay open while you edit the commandline. See [`completions.cache_size`](./config_reference.md#completions-cache-size) for when Nushell empties the cache. To avoid overwriting existing settings, it's best to simply assign updated values to the desired configuration keys, rather than the entire `config` record. In other words: @@ -458,6 +521,8 @@ To remove the welcome message that displays each time Nushell starts: 4. Save and exit your editor. 5. Restart Nushell to test the change. +To keep only the line with the startup time, set `$env.config.show_banner = "short"` instead. The setting also accepts `"full"`, which is the same as `true`, and `"none"`, which is the same as `false`. The banner's colors come from `color_config.banner_foreground`, `banner_highlight1`, and `banner_highlight2`. See [`show_banner`](./config_reference.md#show-banner). + ## Additional Startup Configuration ### Changing default directories @@ -486,16 +551,25 @@ The variables that affect Nushell file locations are: Once Nushell starts, this value is stored in the `$nu.default-config-dir` constant. See [Using Constants](#using-constants) below. - The configuration directory can also be chosen with the `--config-home ` flag when launching `nu`, which takes precedence over `XDG_CONFIG_HOME`. Unlike `XDG_CONFIG_HOME`, the path given to `--config-home` is the Nushell configuration directory itself (no `nushell` subdirectory is added), and a relative path is resolved against the current directory. + An empty value is ignored. A relative path is ignored too, but Nushell reports it with a `nu::shell::xdg_config_home_invalid` error that names the directory it uses instead, and then starts normally with the platform's default directory. + + On macOS and Windows, where the platform's configuration directory isn't the XDG one, Nushell also warns when `/nushell` is empty or missing while the platform's `nushell` directory still has files in it. It doesn't copy anything for you: + + ``` + WARNING: XDG_CONFIG_HOME has been set but /Users/me/dotfiles/nushell is empty. + Nushell will not move your configuration files from /Users/me/Library/Application Support/nushell + ``` -- `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to `($env.XDG_DATA_HOME)/nushell`. The `data-dir` is used in several startup tasks: + The configuration directory can also be chosen with the `--config-home ` flag when launching `nu`, which takes precedence over `XDG_CONFIG_HOME`. Unlike `XDG_CONFIG_HOME`, the path given to `--config-home` is the Nushell configuration directory itself (no `nushell` subdirectory is added), a leading `~` is expanded to your home directory, and a relative path is resolved against the current directory. + +- `$env.XDG_DATA_HOME`: If this environment variable is set to an absolute path, Nushell sets the `$nu.data-dir` constant to `($env.XDG_DATA_HOME)/nushell`. Otherwise `$nu.data-dir` is the `nushell` directory under the platform's data directory, such as `~/Library/Application Support/nushell` on macOS, `~/.local/share/nushell` on Linux, or `%APPDATA%\nushell` on Windows. A relative or empty value is ignored without a warning. The `data-dir` is used in several startup tasks: - `($nu.data-dir)/completions` is added to the `const` variable [`$NU_LIB_DIRS`](./special_variables.md#nu-lib-dirs), as well as to `$env.NU_LIB_DIRS`, which starts with the same default list. The constant is the preferred way to configure the search path; see [`NU_LIB_DIRS` Constant](#nu-lib-dirs-constant) below. - `($nu.data-dir)/vendor/autoload` is added to `$nu.vendor-autoload-dirs` after the system vendor directories (such as those from `XDG_DATA_DIRS`). Files in this directory will be read after those in the other vendor autoload directories, thus overriding any of their settings. Note that the directory represented by `$nu.data-dir`, including any of its subdirectories, are NOT created by default. Creation and use of these directories is up to the user. -- `$env.XDG_DATA_DIRS` _(Unix Platforms Only)_: If this environment variable is set, it is used to populate the `$nu.vendor-autoload-dirs` directories. Following the XDG convention that earlier entries take precedence, the directories are processed in _reverse_ order: the first directory in `XDG_DATA_DIRS` is read last, giving it the ability to override definitions from the others. +- `$env.XDG_DATA_DIRS` _(Unix Platforms Only)_: If this environment variable is set, it is used to populate the `$nu.vendor-autoload-dirs` directories. Following the XDG convention that earlier entries take precedence, the directories are processed in _reverse_ order: the first directory in `XDG_DATA_DIRS` is read last, giving it the ability to override definitions from the others. When the variable is unset or empty, Nushell uses `/usr/local/share/:/usr/share/`. Relative entries are skipped. See [Autoload directories](#autoload-directories) for the whole list. - `$env.XDG_CACHE_HOME`: If this environment variable is set to an absolute path, Nushell sets the `$nu.cache-dir` constant to `($env.XDG_CACHE_HOME)/nushell`. Otherwise `$nu.cache-dir` is the `nushell` directory under the platform's cache directory, such as `~/Library/Caches/nushell` on macOS, `~/.cache/nushell` on Linux, or `%LOCALAPPDATA%\nushell` on Windows. A relative or empty value is ignored. Nushell doesn't store anything in this directory or create it. It is a standard place for your scripts and plugins to keep data they can rebuild. @@ -666,7 +740,7 @@ The following stages and their steps _may_ occur during startup, based on the fl | Step | Stage | Nushell Action | | ---- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0. | (misc) | Sets internal defaults via its internal Rust implementation. In practice, this may not take place until "first use" of the setting or variable, but there will typically be a Rust default for most (but not all) settings and variables that control Nushell's behavior. These defaults can then be superseded by the steps below. | -| 1. | (main) | Processes commandline arguments such as `--plugin-config `, `--plugins `, `--experimental-options `, and others. See `nu --help` for a complete list. | +| 1. | (main) | Processes commandline arguments such as `--plugin-config `, `--plugins `, `--experimental-options `, and others. See [`nu` flags](#nu-flags) for a complete list. | | 2. | (main) | Gets the configuration directory. This is OS-dependent (see [dirs::config_dir](https://docs.rs/dirs/latest/dirs/fn.config_dir.html)), but can be overridden using `XDG_CONFIG_HOME` on all platforms as discussed [above](#changing-default-directories), or with the `--config-home ` flag. | | 3. | (main) | Gets the path to `env.nu` and `config.nu`. By default, these are located in the config directory, but either or both can be overridden using the `--env-config ` and `--config ` flags. The data directory, the autoload directories, and the plugin registry file are located at this point as well. | | 4. | (main) | Creates the initial `$env.NU_PLUGIN_DIRS` variable. By default, it is an empty list. | @@ -689,8 +763,8 @@ The following stages and their steps _may_ occur during startup, based on the fl | 21. | (config files) (config.nu) | Loads the internal `default_config.nu`, which is essentially empty, since the defaults for all `$env.config` settings are now built into Nushell (step 7). This file can be viewed with: `config nu --default \| nu-highlight \| less -R`. | | 22. | (config files) (config.nu) | Loads (parses and evaluates) the user's `config.nu` (the path to which was determined above). | | 23. | (config files) (login) | When Nushell is running as a login shell, loads the user's `login.nu`. | -| 24. | (config files) | Loops through the vendor autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.vendor-autoload-dirs`, and files in those directories are processed in alphabetical order. | -| 25. | (config files) | Loops through the user autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.user-autoload-dirs`, and files in those directories are processed in alphabetical order. | +| 24. | (config files) | Loops through the vendor autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.vendor-autoload-dirs`, and files in those directories are processed in the byte order of their names (see [Autoload directories](#autoload-directories)). | +| 25. | (config files) | Loops through the user autoload directory and loads any `.nu` files found. `$nu.user-autoload-dirs` holds one directory, and files in it are processed in the byte order of their names. | | 26. | (repl) | Runs the commands given with the `--execute (-e)` flag, if any. | | 27. | (repl) | Sets up the line editor and the command history. From this point on, the `history.file_format`, `history.max_size`, `history.isolation`, and `history.path` settings can no longer be changed. | | 28. | (repl) and (stdlib) | Shows the welcome banner if configured. | @@ -785,6 +859,10 @@ The following stages and their steps _may_ occur during startup, based on the fl - ❌ Does not source the files in `vendor-autoload-dirs` - ❌ Does not source the files in `user-autoload-dirs` +- `nu -l test.nu` + + - Same as `nu test.nu`. Unlike with `-c`, `-l` doesn't make Nushell load `env.nu`, `config.nu`, or `login.nu` for a script file. + - `nu --config foo_config.nu test.nu` - ✅ Makes the Standard Library available @@ -826,6 +904,54 @@ The following stages and their steps _may_ occur during startup, based on the fl - ❌ Does not source the files in `vendor-autoload-dirs` - ❌ Does not source the files in `user-autoload-dirs` +### `nu` flags + +`nu --help` lists every flag with a one-line description. It prints the list in color only when its output goes to a terminal. The tables below say more about what each flag does. A command line is `nu [flags] [script file] [script arguments]`. + +Running commands: + +| Flag | What it does | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-c`, `--commands ` | Runs the commands and exits. Any arguments after the commands go to their `main` command; see [Arguments with `nu -c`](./scripts.md#arguments-with-nu-c). | +| `-e`, `--execute ` | Runs the commands after the startup files have loaded, then starts the REPL. It is ignored when `-c` or a script file is given. | +| `-l`, `--login` | Starts a login shell, which also loads `login.nu`. Nushell starts as a login shell, too, when the name it was started under (`argv[0]`) begins with `-`, which is how `login` and `sshd` start a user's shell. With `-c`, `-l` also loads `env.nu` and `config.nu`; with a script file, it loads none of the three. | +| `-i`, `--interactive` | Treats a `-c` or script run as an interactive session. On Unix, Nushell then takes control of the terminal and hands it to each external command while it runs, as the REPL does. | +| `--stdin` | Lets the `-c` commands or the script read the input piped to `nu` as `$in`. See [Shebangs](./scripts.md#shebangs). | +| `--no-newline` | Prints the result of the `-c` commands without a newline at the end. | +| `-m`, `--table-mode ` | Draws tables in this mode for the whole run, over the `table.mode` setting from the configuration files. `$env.config.table.mode` still shows the configured value. | +| `--error-style ` | Sets the error style to `fancy`, `plain`, or `short` for a `-c` run. It has no effect on a script file or the REPL, and it doesn't accept `nested`; set `$env.config.error_style` for those. | + +Configuration: + +| Flag | What it does | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `-n`, `--no-config-file` | Skips the plugin registry, `default_env.nu`, `env.nu`, `config.nu`, `login.nu`, and the autoload files. Nushell also ignores the `NU_EXPERIMENTAL_OPTIONS` variable. Plugins given with `--plugins` still load. | +| `--no-std-lib` | Starts without the [Standard Library](./standard_library.md). The `std` modules, the banner, and the `pwd` command from the standard library aren't available; `pwd` then runs the external program of that name, if there is one. | +| `--no-history` | Starts the REPL without reading or writing the history file. `$nu.history-enabled` is `false`. | +| `-I`, `--include-path ` | Adds directories to `$NU_LIB_DIRS` and `$env.NU_LIB_DIRS`, after those from an inherited `NU_LIB_DIRS` variable and before the default ones. Separate several directories with `:`, `;`, or the ASCII record separator character, `(char record_sep)`, on every platform. Because `:` separates too, a Windows path with a drive letter, such as `C:\libs`, is split in two. | +| `--config ` | Loads this file instead of `config.nu`. `$nu.config-path` shows it, and `config nu` opens it. | +| `--env-config ` | Loads this file instead of `env.nu`. `$nu.env-path` shows it, and `config env` opens it. | +| `--config-home ` | Uses this directory as the configuration directory, instead of `/nushell` or the platform default. See [Startup Variables](#startup-variables). | +| `--plugin-config ` | Uses this file as the plugin registry instead of `plugin.msgpackz` in the configuration directory. Nushell loads the plugins registered in it at startup, [`plugin add`](/commands/docs/plugin_add.md), `plugin rm`, and `plugin use` read and write it, and `$nu.plugin-path` shows it. If the file's directory doesn't exist, Nushell reports `File not found` for that directory and starts without a registry. | +| `--plugins ` | Loads these plugin executables for this session only, without adding them to the registry. Give several with repeated flags or a list, as in `--plugins '[/path/a /path/b]'`. | +| `--experimental-options ` | Turns experimental options on or off. See [Experimental options](#experimental-options). | + +In the four path flags, a leading `~` is expanded to your home directory, and a relative path is resolved against the current directory. A `--config` or `--env-config` file that doesn't exist is an error; see [Problems with startup files](#problems-with-startup-files). With `-n`, Nushell loads none of these files. `$nu.plugin-path` still shows the `--plugin-config` path, but `plugin add`, `plugin rm`, and `plugin use` fail with `Plugin registry file not set` unless you pass them their own `--plugin-config`. + +Other flags: + +| Flag | What it does | +| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Prints the list of flags and exits. | +| `-v`, `--version` | Prints the version number and exits. | +| `--log-level ` | Turns on Nushell's internal diagnostic log at `error`, `warn`, `info`, `debug`, `trace`, or `perf` level. This is unrelated to the [`std/log`](./standard_library.md) commands. | +| `--log-target `, `--log-file ` | Sends the log to `stderr` (the default), `stdout`, `mixed`, or a `file` named with `--log-file`. | +| `--log-include `, `--log-exclude ` | Keeps or drops log lines by the Rust module they come from, such as `nu_cli`. | +| `--mcp`, `--mcp-transport`, `--mcp-port`, `--mcp-host`, `--mcp-allowed-hosts`, `--mcp-allowed-origins` | Start Nushell as a Model Context Protocol server. See [MCP Server](./mcp.md). | +| `--lsp` | Starts Nushell as a language server. See [Language server](./language_server.md). | +| `--dap` | Starts Nushell as a debug adapter. See [Debugging Scripts](./debugging.md). | +| `--ide-goto-def`, `--ide-hover`, `--ide-complete`, `--ide-check`, `--ide-ast` | Answer one question about the script file that follows and print the answer as JSON, for editor integrations. | + ### Passing flags to `nu` `nu` reads its flags in the usual Unix styles: From 63234348b348a6e876e91b21f79697cb3a0b8b91 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:11:19 -0600 Subject: [PATCH 10/46] Fill gaps in the operator and shell migration docs Covers the rows rated `some` in the coverage checklist for operators, precedence and type rules, and the "coming from" pages: - operators: older-than/newer-than, associativity, subexpressions, operators in command arguments, comparing datetimes, regex details and errors, and spread errors and null spreads - lang-guide operators: types, edge cases, and errors for each operator group, with the precedence numbers from `help operators` - nushell_operator_map: every operator `help operators` prints; the `=~`/`like` row was wrong in the SQL and PowerShell columns - thinking_in_nu: a lone `>` is an argument, the parse errors for `&&`, `||`, `2>`, and `2>&1`, `echo` return values, and `o>` as an alternative to `save` - coming_from_bash and coming_from_cmd: more command equivalents, `which` output, history expansion, and how `start` picks an opener --- book/coming_from_bash.md | 27 +++- book/coming_from_cmd.md | 8 ++ book/nushell_operator_map.md | 80 +++++++----- book/operators.md | 217 ++++++++++++++++++++++++++++++- book/thinking_in_nu.md | 53 +++++++- lang-guide/chapters/operators.md | 185 ++++++++++++++++++++++++++ 6 files changed, 532 insertions(+), 38 deletions(-) diff --git a/book/coming_from_bash.md b/book/coming_from_bash.md index 78100935413..52a631a3d41 100644 --- a/book/coming_from_bash.md +++ b/book/coming_from_bash.md @@ -54,10 +54,12 @@ $env.Path = ($env.Path | prepend 'C:\Program Files\Git\usr\bin') | `rm -rf ` | `rm -r ` | Recursively removes the given path | | `date -d ` | `"" \| into datetime -f ` | Parse a date ([format documentation](https://docs.rs/chrono/0.4.15/chrono/format/strftime/index.html)) | | `date -d "tomorrow"` | `"tomorrow" \| date from-human` | Parse a human-readable date | +| | `date from-human --list` | Show example phrases that `date from-human` understands | | `sed` | `str replace` | Find and replace a pattern in a string | | `grep ` | `where $it =~ ` or `find ` | Filter strings that contain the substring | | `grep -i ` | `find -i ` | Filter strings that contain the substring, ignoring case | | `grep -o ` | `find -o -r ` | Output only the matched text, one value per match | +| `grep -v ` | `find -v ` | Filter strings that don't contain the substring | | `man ` | `help ` | Get the help for a given command | | | `help commands` | List all available commands | | | `help --find ` | Search for match in all available commands | @@ -80,16 +82,34 @@ $env.Path = ($env.Path | prepend 'C:\Program Files\Git\usr\bin') | `unset FOO` | `hide-env FOO` | Unset environment variable for current session | | `alias s="git status -sb"` | `alias s = git status -sb` | Define an alias temporarily | | `type FOO` | `which FOO` | Display information about a command (builtin, alias, or executable) | +| `type -a FOO` | `which -a FOO` | List every match: the Nushell command of that name and each executable in PATH | +| `type -P FOO` | `which ^FOO` | Look up only the external program, skipping Nushell commands | +| `compgen -c` | `which` | List every command: Nushell's own and each executable in PATH | | `` | `vim $nu.config-path` | Add and edit alias permanently (for new shells) | | `bash -c ` | `nu -c ` | Run a pipeline of commands | | `bash