From aa0fc3e1e192c7858e7bcff309ae96ed31d26621 Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Mon, 28 Sep 2026 10:56:21 -0500 Subject: [PATCH 1/3] update docs, test and fix examples --- .vuepress/configs/sidebar/en.ts | 3 +- book/3rdpartyprompts.md | 23 +- book/advanced.md | 4 +- book/aliases.md | 93 +- book/background_jobs.md | 68 +- book/cheat_sheet.md | 34 +- book/coloring_and_theming.md | 274 ++--- book/coming_from_bash.md | 6 +- book/coming_from_cmd.md | 14 +- book/configuration.md | 157 +-- book/control_flow.md | 114 +- book/creating_errors.md | 105 +- book/custom_commands.md | 397 +++++-- book/custom_completions.md | 259 ++++- book/dataframes.md | 486 +++++---- book/directory_stack.md | 63 +- book/environment.md | 115 ++- book/explore.md | 107 +- book/hooks.md | 125 ++- book/how_nushell_code_gets_run.md | 118 ++- book/installation.md | 48 +- book/line_editor.md | 825 +++++++++++---- book/loading_data.md | 226 ++-- book/metadata.md | 134 ++- book/modules/creating_modules.md | 182 +++- book/modules/using_modules.md | 167 ++- book/moving_around.md | 61 +- book/navigating_structured_data.md | 104 +- book/nushell_map.md | 6 +- book/nushell_map_functional.md | 10 +- book/nushell_map_imperative.md | 145 +-- book/nushell_operator_map.md | 54 +- book/operators.md | 164 +-- book/overlays.md | 219 ++-- book/parallelism.md | 19 +- book/pipelines.md | 174 ++-- book/plugins.md | 97 +- book/programming_in_nu.md | 4 +- book/quick_tour.md | 103 +- book/regular_expressions.md | 2 +- book/running_externals.md | 29 + book/scripts.md | 143 ++- book/sorting.md | 119 ++- book/special_variables.md | 65 +- book/standard_library.md | 40 +- book/stdout_stderr_exit_codes.md | 71 +- book/style_guide.md | 45 +- book/table_of_contents.md | 99 +- book/testing.md | 105 +- book/thinking_in_nu.md | 56 +- book/tui.md | 974 ++++++++++++++++++ book/types_of_data.md | 56 +- book/variables.md | 111 +- book/working_with_lists.md | 132 ++- book/working_with_strings.md | 55 +- book/working_with_tables.md | 483 ++++----- contributor-book/README.md | 2 +- contributor-book/commands.md | 26 +- contributor-book/philosophy.md | 2 +- contributor-book/plugin_protocol_reference.md | 830 +++++++++------ contributor-book/plugins.md | 305 +++--- cookbook/custom_completers.md | 14 +- cookbook/external_completers.md | 107 +- cookbook/files.md | 151 ++- cookbook/foreign_shell_scripts.md | 29 +- cookbook/git.md | 65 +- cookbook/help.md | 71 +- cookbook/http.md | 274 +++-- cookbook/input_listen_keys.md | 25 +- cookbook/jq_v_nushell.md | 78 +- cookbook/modules.md | 27 +- cookbook/parsing.md | 50 +- cookbook/parsing_git_log.md | 658 ++++-------- cookbook/pattern_matching.md | 44 +- cookbook/polars_v_pandas_v_nushell.md | 129 +-- cookbook/setup.md | 40 +- cookbook/ssh_agent.md | 4 +- cookbook/system.md | 117 ++- cookbook/tables.md | 54 +- lang-guide/chapters/custom_commands.md | 187 +++- lang-guide/chapters/declarations.md | 198 +++- lang-guide/chapters/filters/each-par-each.md | 139 ++- lang-guide/chapters/filters/select-get.md | 112 +- lang-guide/chapters/filters/selecting_data.md | 154 ++- lang-guide/chapters/filters/where-filter.md | 156 ++- lang-guide/chapters/flow_control/break.md | 87 +- lang-guide/chapters/flow_control/continue.md | 84 +- lang-guide/chapters/flow_control/if-else.md | 35 + lang-guide/chapters/flow_control/loop.md | 104 +- lang-guide/chapters/flow_control/match.md | 156 ++- lang-guide/chapters/flow_control/return.md | 99 +- lang-guide/chapters/flow_control/try-catch.md | 158 ++- lang-guide/chapters/flow_control/while.md | 92 +- lang-guide/chapters/helpers_and_debugging.md | 209 +++- lang-guide/chapters/mime_types.md | 27 +- lang-guide/chapters/operators.md | 96 +- lang-guide/chapters/pipelines.md | 71 +- lang-guide/chapters/strings_and_text.md | 42 +- lang-guide/chapters/types/basic_types/any.md | 20 +- .../chapters/types/basic_types/binary.md | 14 +- lang-guide/chapters/types/basic_types/bool.md | 6 +- .../chapters/types/basic_types/cellpath.md | 88 +- .../chapters/types/basic_types/closure.md | 20 +- .../chapters/types/basic_types/datetime.md | 16 +- .../chapters/types/basic_types/duration.md | 37 +- .../chapters/types/basic_types/filesize.md | 25 +- .../chapters/types/basic_types/float.md | 16 + lang-guide/chapters/types/basic_types/glob.md | 24 +- lang-guide/chapters/types/basic_types/int.md | 23 +- lang-guide/chapters/types/basic_types/list.md | 62 +- .../chapters/types/basic_types/nothing.md | 64 +- .../chapters/types/basic_types/range.md | 128 ++- .../chapters/types/basic_types/record.md | 46 +- .../chapters/types/basic_types/string.md | 20 +- .../chapters/types/basic_types/table.md | 4 +- .../types/other_types/00_not_assignable.md | 6 +- .../types/other_types/01_not_declarable.md | 16 + .../chapters/types/other_types/block.md | 59 +- .../types/other_types/custom_value.md | 25 +- .../chapters/types/other_types/error.md | 53 +- lang-guide/chapters/types/other_types/path.md | 41 +- lang-guide/chapters/types/related_commands.md | 11 + lang-guide/chapters/types/type_signatures.md | 24 +- lang-guide/chapters/variable_scope.md | 139 ++- .../install_pkg_config_libssl_dev.sh | 4 +- .../installation/install_rhel_dependencies.sh | 4 +- snippets/installation/macos_deps.sh | 4 +- snippets/loading_data/cargo-toml.sh | 13 +- snippets/loading_data/vscode.sh | 60 +- 129 files changed, 10206 insertions(+), 4066 deletions(-) create mode 100644 book/tui.md diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts index 3a2b3284420..ca2a3b6f498 100644 --- a/.vuepress/configs/sidebar/en.ts +++ b/.vuepress/configs/sidebar/en.ts @@ -118,6 +118,7 @@ export const sidebarEn: SidebarConfig = { '/book/parallelism.md', '/book/plugins.md', '/book/explore.md', + '/book/tui.md', ], }, ], @@ -212,7 +213,7 @@ export const sidebarEn: SidebarConfig = { collapsible: true, children: [ { - text: 'Types that cannot be used to declare variables', + 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'], }, diff --git a/book/3rdpartyprompts.md b/book/3rdpartyprompts.md index 615ce95ed8d..3a7305a3ccb 100644 --- a/book/3rdpartyprompts.md +++ b/book/3rdpartyprompts.md @@ -20,17 +20,15 @@ If you like [oh-my-posh](https://ohmyposh.dev/), you can use oh-my-posh with Nus 1. Install Oh My Posh and download oh-my-posh's themes following [guide](https://ohmyposh.dev/docs/installation/linux). 2. Download and install a [nerd font](https://github.com/ryanoasis/nerd-fonts). -3. Generate the .oh-my-posh.nu file. By default it will be generated to your home directory. You can use `--config` to specify a theme, other wise, oh-my-posh comes with a default theme. -4. Initialize oh-my-posh prompt by adding in ~/.config/nushell/config.nu(or the path output by `$nu.config-path`) to source ~/.oh-my-posh.nu. +3. Add `oh-my-posh init nu` to the end of your config.nu (the path output by `$nu.config-path`). You can use `--config` to specify a theme, otherwise, oh-my-posh comes with a default theme. ```nu -# Generate the .oh-my-posh.nu file +# Initialize oh-my-posh at shell startup by adding this line at the end of your config.nu file oh-my-posh init nu --config ~/.poshthemes/M365Princess.omp.json - -# Initialize oh-my-posh.nu at shell startup by adding this line in your config.nu file -source ~/.oh-my-posh.nu ``` +Each time Nushell starts, this writes oh-my-posh's initialization script (`oh-my-posh.nu`) into a Nushell [vendor autoload directory](configuration.md#configuration-overview), which Nushell loads after `config.nu` (and `login.nu`). + For MacOS users: 1. You can install oh-my-posh using `brew`, just following the [guide here](https://ohmyposh.dev/docs/installation/macos) @@ -40,10 +38,10 @@ For MacOS users: ```nu let posh_dir = (brew --prefix oh-my-posh | str trim) let posh_theme = $'($posh_dir)/share/oh-my-posh/themes/' -# Change the theme names to: zash/space/robbyrussel/powerline/powerlevel10k_lean/ +# Change the theme names to: zash/space/robbyrussell/powerline/powerlevel10k_lean/ # material/half-life/lambda Or double lines theme: amro/pure/spaceship, etc. # For more [Themes demo](https://ohmyposh.dev/docs/themes) -$env.PROMPT_COMMAND = { || oh-my-posh prompt print primary --config $'($posh_theme)/zash.omp.json' } +$env.PROMPT_COMMAND = { || oh-my-posh print primary --config $'($posh_theme)/zash.omp.json' } # Optional $env.PROMPT_INDICATOR = $"(ansi y)$> (ansi reset)" ``` @@ -65,7 +63,12 @@ The link above is the official integration of Starship and Nushell and is the si Starship running without doing anything manual: - Starship will create its own configuration / environment setup script -- you simply have to create it in `env.nu` and `use` it in `config.nu` +- you simply have to save it into a Nushell vendor autoload directory from your `config.nu`, and Nushell loads it automatically: + +```nu +mkdir ($nu.data-dir | path join "vendor/autoload") +starship init nu | save -f ($nu.data-dir | path join "vendor/autoload/starship.nu") +``` ::: @@ -93,7 +96,7 @@ $env.PROMPT_MULTILINE_INDICATOR = "::: " Now restart Nu. ``` -nushell on ๐Ÿ“™ main is ๐Ÿ“ฆ v0.60.0 via ๐Ÿฆ€ v1.59.0 +nushell on ๐Ÿ“™ main is ๐Ÿ“ฆ v0.116.0 via ๐Ÿฆ€ v1.96.1 โฏ ``` diff --git a/book/advanced.md b/book/advanced.md index acba88063bf..36b473999a5 100644 --- a/book/advanced.md +++ b/book/advanced.md @@ -3,7 +3,7 @@ prev: text: How Nushell Code Gets Run link: /book/how_nushell_code_gets_run.md next: - text: Standard Library (Preview) + text: Standard Library link: /book/standard_library.md --- # (Not so) Advanced @@ -22,7 +22,7 @@ This metadata can be used, for example, to [create custom errors](creating_error Thanks to Nushell's strict scoping rules, it is very easy to [iterate over collections in parallel](parallelism.md) which can help you speed up long-running scripts by just typing a few characters. -You can [interactively explore data](explore.md) with the [`explore`](/commands/docs/explore.md) command. +You can [interactively explore data](explore.md) with the [`explore`](/commands/docs/explore.md) command, and you can [build your own terminal user interfaces](tui.md), such as pickers, dialogs, and dashboards, with the `tui` family of commands. Finally, you can extend Nushell's functionality with [plugins](plugins.md). Almost anything can be a plugin as long as it communicates with Nushell in a protocol that Nushell understands. diff --git a/book/aliases.md b/book/aliases.md index fa3987bdfe9..5defa4cb455 100644 --- a/book/aliases.md +++ b/book/aliases.md @@ -22,10 +22,58 @@ ll -a And get the equivalent to having typed `ls -l -a`. +## Aliasing Parent Commands + +An alias can also point to a command that has subcommands, such as `math` or `str`. The subcommands are then available through the alias as well: + +```nu +alias m = math +[1 2 3 4] | m sum +# => 10 +``` + +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`. + ## List All Loaded Aliases Your useable aliases can be seen in `scope aliases` and `help aliases`. +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: + +```nu +# Say hello to someone +def greet [name: string] { $"Hello, ($name)!" } +alias hi = greet +help hi +# => Alias for greet +# => +# => Alias: hi +# => +# => Expansion: +# => greet +# => +# => Say hello to someone +# => +# => Usage: +# => > greet +# => +# => Flags: +# => -h, --help: Display the help message for this command +# => +# => Command Type: +# => > custom +# => +# => Parameters: +# => name +# => +# => Input/output types: +# => โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +# => โ”‚ # โ”‚ input โ”‚ output โ”‚ +# => โ”œโ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +# => โ”‚ 0 โ”‚ any โ”‚ any โ”‚ +# => โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +``` + ## Persisting To make your aliases persistent they must be added to your _config.nu_ file by running `config nu` to open an editor and inserting them, and then restarting nushell. @@ -66,39 +114,39 @@ displaying all listed files and folders in a grid. When replacing commands it is best to "back up" the command first and avoid a recursion error. ::: +::: tip Note +Parser keywords such as `if`, `for` or `let` can't be replaced. Using one as the name of an alias (or a custom command) is a `nu::parser::name_is_keyword` error. +::: + How to back up a command like `ls`: ```nu alias core-ls = ls # This will create a new alias core-ls for ls ``` -Now you can use `core-ls` as `ls` in your nu-programming. You will see further down how to use `core-ls`. +Now you can use `core-ls` as `ls` in your nu-programming, even after `ls` itself has been replaced. The reason you need to use alias is because, unlike `def`, aliases are position-dependent. So, you need to "back up" the old command first with an alias, before re-defining it. If you do not backup the command and you replace the command using `def` you get a recursion error. ```nu def ls [] { ls }; ls # Do *NOT* do this! This will throw a recursion error - -#output: -#Error: nu::shell::recursion_limit_reached -# -# ร— Recursion limit (50) reached -# โ•ญโ”€[C:\Users\zolodev\AppData\Roaming\nushell\config.nu:807:1] -# 807 โ”‚ -# 808 โ”‚ def ls [] { ls }; ls -# ยท โ”€โ”€โ”€โ”ฌโ”€โ”€ -# ยท โ•ฐโ”€โ”€ This called itself too many times -# โ•ฐโ”€โ”€โ”€โ”€ +# => Error: nu::shell::recursion_limit_reached +# => +# => ร— Recursion limit (50) reached +# => โ•ญโ”€[repl_entry #1:1:11] +# => 1 โ”‚ def ls [] { ls }; ls # Do *NOT* do this! This will throw a recursion error +# => ยท โ”€โ”€โ”€โ”ฌโ”€โ”€ +# => ยท โ•ฐโ”€โ”€ This called itself too many times +# => โ•ฐโ”€โ”€โ”€โ”€ ``` -The recommended way to replace an existing command is to shadow the command. +The recommended way to replace an existing command is to shadow the command, and to call the original +built-in inside the new definition with the `%` sigil. `%ls` always runs the built-in `ls`, even when a +custom command or alias shadows it, so there is no recursion. Here is an example shadowing the `ls` command. ```nu -# alias the built-in ls command to ls-builtins -alias ls-builtin = ls - # List the filenames, sizes, and modification times of items in a directory. def ls [ --all (-a), # Show hidden files @@ -112,7 +160,7 @@ def ls [ ...pattern: glob, # The glob pattern to use. ]: [ nothing -> table ] { let pattern = if ($pattern | is-empty) { [ '.' ] } else { $pattern } - (ls-builtin + (%ls --all=$all --long=$long --short-names=$short_names @@ -126,11 +174,8 @@ def ls [ } ``` -To call the underlying built-in command you can use a percent sigil `%`, e.g. -```nu -def ls [] { - "something else" -} +You can also type `%ls` at the prompt to run the built-in `ls` while it is shadowed. -%ls # <- calls the original ls -``` +Before the `%` sigil existed, the body called a backup alias instead, such as `ls-builtin` created with `alias ls-builtin = ls`. That still works, but only if the alias is created while `ls` still refers to the built-in command. + +See [Shadowing Built-in Commands](custom_commands.md#shadowing-built-in-commands) for more about the `%` sigil. diff --git a/book/background_jobs.md b/book/background_jobs.md index 9c80ad6087c..f3dda6e88f6 100644 --- a/book/background_jobs.md +++ b/book/background_jobs.md @@ -37,11 +37,11 @@ Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job let id = job spawn { sleep 1day } job list -# => โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“ -# => โ”ƒ # โ”ƒ id โ”ƒ type โ”ƒ pids โ”ƒ -# => โ”ฃโ”โ”โ”โ•‹โ”โ”โ”โ”โ•‹โ”โ”โ”โ”โ”โ”โ”โ”โ•‹โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ซ -# => โ”ƒ 0 โ”ƒ 1 โ”ƒ thread โ”ƒ [list 0 items] โ”ƒ -# => โ”—โ”โ”โ”โ”ปโ”โ”โ”โ”โ”ปโ”โ”โ”โ”โ”โ”โ”โ”โ”ปโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”› +# => โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +# => โ”‚ # โ”‚ id โ”‚ type โ”‚ pids โ”‚ +# => โ”œโ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +# => โ”‚ 0 โ”‚ 2 โ”‚ thread โ”‚ [list 0 items] โ”‚ +# => โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ job kill $id @@ -51,22 +51,44 @@ job list # => โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ ``` +## Describing jobs + +To make jobs easier to tell apart, you can give a job a description when you spawn it with `job spawn --description`, or change it later with [`job describe`](/commands/docs/job_describe.md). The description is shown in an additional `description` column of `job list`: + +```nu +let id = job spawn --description "long nap" { sleep 1day } +job describe $id "longer nap" + +job list +# => โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +# => โ”‚ # โ”‚ id โ”‚ type โ”‚ pids โ”‚ description โ”‚ +# => โ”œโ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +# => โ”‚ 0 โ”‚ 3 โ”‚ thread โ”‚ [list 0 items] โ”‚ longer nap โ”‚ +# => โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + +job kill $id +``` + ## Job suspension On Unix targets, such as Linux and macOS, Nushell also supports suspending external commands using Ctrl+Z. When a running process is suspended, it is turned into a "frozen" background job: ```nu -long_running_process # this starts running, then Ctrl+Z is pressed -# => Job 1 is frozen +^sleep 100 # this starts running, then Ctrl+Z is pressed +# => Job 4 is frozen job list -# => โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“ -# => โ”ƒ # โ”ƒ id โ”ƒ type โ”ƒ pids โ”ƒ -# => โ”ฃโ”โ”โ”โ•‹โ”โ”โ”โ”โ•‹โ”โ”โ”โ”โ”โ”โ”โ”โ•‹โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ซ -# => โ”ƒ 0 โ”ƒ 1 โ”ƒ frozen โ”ƒ [list 1 items] โ”ƒ -# => โ”—โ”โ”โ”โ”ปโ”โ”โ”โ”โ”ปโ”โ”โ”โ”โ”โ”โ”โ”โ”ปโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”› +# => โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +# => โ”‚ # โ”‚ id โ”‚ type โ”‚ pids โ”‚ description โ”‚ +# => โ”œโ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +# => โ”‚ 0 โ”‚ 4 โ”‚ frozen โ”‚ โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ sleep โ”‚ +# => โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ 0 โ”‚ 6337 โ”‚ โ”‚ โ”‚ +# => โ”‚ โ”‚ โ”‚ โ”‚ โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ โ”‚ +# => โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ ``` +A frozen job is automatically described with the name of the suspended program. + A frozen job can be brought back into foreground with the [`job unfreeze`](/commands/docs/job_unfreeze.md) command: ```nu @@ -87,12 +109,12 @@ By default, `job unfreeze` will unfreeze the most recently frozen job. However, ```nu vim -# => Job 1 is frozen +# => Job 5 is frozen -long_running_process -# => Job 2 is frozen +^sleep 100 +# => Job 6 is frozen -job unfreeze 1 +job unfreeze 5 # we're back in vim ``` @@ -125,6 +147,20 @@ job recv # => Hello from a background job ``` +Messages can carry a numeric tag with `job send --tag`. `job recv --tag` then only receives messages with that tag, leaving others in the mailbox, and `job recv --timeout` stops waiting after the given duration: + +```nu +'low priority' | job send 0 --tag 2 +'urgent' | job send 0 --tag 1 + +job recv --tag 1 +# => urgent +job recv --timeout 0sec +# => low priority +``` + +To discard messages without reading them, use [`job flush`](/commands/docs/job_flush.md), which clears the whole mailbox of the current job, or only the messages with a given tag when used with `--tag`. + ## Exit Behavior Unlike many other shells, Nushell jobs are **not** separate processes, diff --git a/book/cheat_sheet.md b/book/cheat_sheet.md index d30d35eb60f..06d6d86d757 100644 --- a/book/cheat_sheet.md +++ b/book/cheat_sheet.md @@ -201,6 +201,7 @@ $planets | each { |elt| $"($elt) is a planet of the solar system" } iterate over a list with an index and value: ```nu +let planets = [Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune] $planets | enumerate | each { |elt| $"($elt.index + 1) - ($elt.item)" } # => โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ # => โ”‚ 0 โ”‚ 1 - Mercury โ”‚ @@ -332,7 +333,7 @@ glob **/*.{rs,toml} --depth 2 watch a file, run command whenever it changes: ```nu -watch . --glob=**/*.rs {|| cargo test } +for _ in (watch . --glob=**/*.rs) { cargo test } ``` ## Custom Commands @@ -435,20 +436,26 @@ closures and nested defs cannot capture mutable variables from their environment mut x = 0 [1 2 3] | each { $x += 1 } # => Error: nu::parser::expected_keyword -# => +# => # => ร— Capture of mutable variable. -# => โ•ญโ”€[entry #83:1:18] -# => 1 โ”‚ [1 2 3] | each { $x += 1 } +# => โ•ญโ”€[repl_entry #83:2:18] +# => 1 โ”‚ mut x = 0 +# => 2 โ”‚ [1 2 3] | each { $x += 1 } # => ยท โ”€โ”ฌ # => ยท โ•ฐโ”€โ”€ capture of mutable variable # => โ•ฐโ”€โ”€โ”€โ”€ ``` -a constant variable is immutable and is fully evaluated at parse-time: +a constant variable is immutable and is fully evaluated at parse-time, so it can be used where a value is needed while parsing, such as the file name passed to `source`: + +```nu +'print "hello from file.nu"' | save --force file.nu +``` ```nu -const file = 'path/to/file.nu' +const file = 'file.nu' source $file +# => hello from file.nu ``` use question mark operator `?` to return null instead of error if provided path is incorrect: @@ -481,6 +488,7 @@ module greetings { } use greetings hello hello "world" +# => hello world! ``` import module from file and use its environment in current scope: @@ -493,18 +501,20 @@ export-env { export def hello [] { $"hello ($env.MYNAME)" } +``` +```nu use greetings.nu $env.MYNAME # => Arthur, King of the Britons greetings hello -# => hello Arthur, King of the Britons! +# => hello Arthur, King of the Britons ``` use main command in module: ```nu -# greetings.nu +# salutations.nu export def hello [name: string] { $"hello ($name)!" } @@ -516,10 +526,12 @@ export def hi [where: string] { export def main [] { "greetings and salutations!" } +``` -use greetings.nu -greetings +```nu +use salutations.nu +salutations # => greetings and salutations! -greetings hello world +salutations hello world # => hello world! ``` diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index 5a95b851bd8..025d7756e02 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -22,6 +22,7 @@ The options for `$env.config.table.mode` can be listed with `table --list`: - `default` - `dots` - `double` +- `frameless` - `heavy` - `light` - `markdown` @@ -44,7 +45,7 @@ table --list | first 5 # => โ”‚ 1 โ”‚ compact โ”‚ # => โ”‚ 2 โ”‚ compact_double โ”‚ # => โ”‚ 3 โ”‚ default โ”‚ -# => โ”‚ 4 โ”‚ heavy โ”‚ +# => โ”‚ 4 โ”‚ frameless โ”‚ # => โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ $env.config.table.mode = 'psql' @@ -53,7 +54,9 @@ table --list | first 5 # => 1 | compact # => 2 | compact_double # => 3 | default -# => 4 | heavy +# => 4 | frameless + +$env.config.table.mode = 'rounded' # back to the default ``` ## Color Configuration @@ -258,21 +261,16 @@ For example: $env.config.color_config.filesize = {|x| if $x == 0b { 'dark_gray' } else if $x < 1mb { 'cyan' } else { 'blue' } } $env.config.color_config.bool = {|x| if $x { 'green' } else { 'light_red' } } {a:true,b:false,c:0mb,d:0.5mb,e:10mib} +# => โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +# => โ”‚ a โ”‚ true โ”‚ +# => โ”‚ b โ”‚ false โ”‚ +# => โ”‚ c โ”‚ 0 B โ”‚ +# => โ”‚ d โ”‚ 500.0 kB โ”‚ +# => โ”‚ e โ”‚ 10.4 MB โ”‚ +# => โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ ``` -prints - -```nu -โ•ญโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ a โ”‚ true โ”‚ -โ”‚ b โ”‚ false โ”‚ -โ”‚ c โ”‚ 0 B โ”‚ -โ”‚ d โ”‚ 488.3 KiB โ”‚ -โ”‚ e โ”‚ 10.0 MiB โ”‚ -โ•ฐโ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -``` - -with a green `true`, a light red `false`, a dark grey `0 B`, a cyan `488.3 KiB`, and a blue `10.0 MiB`. +The table shows a green `true`, a light red `false`, a dark grey `0 B`, a cyan `500.0 kB`, and a blue `10.4 MB`. ## Primitive Values @@ -280,73 +278,85 @@ Primitive values are things like `int` and `string`. Primitive values and shapes This is the current list of primitives. Not all of these are configurable. The configurable ones are marked with \*. -| primitive | default color | configurable | -| ------------ | --------------------- | ------------ | -| `any` | | | -| `binary` | Color::White.normal() | \* | -| `block` | Color::White.normal() | \* | -| `bool` | Color::White.normal() | \* | -| `cell-path` | Color::White.normal() | \* | -| `condition` | | | -| `custom` | | | -| `datetime` | Color::White.normal() | \* | -| `duration` | Color::White.normal() | \* | -| `expression` | | | -| `filesize` | Color::White.normal() | \* | -| `float` | Color::White.normal() | \* | -| `glob` | | | -| `import` | | | -| `int` | Color::White.normal() | \* | -| `list` | Color::White.normal() | \* | -| `nothing` | Color::White.normal() | \* | -| `number` | | | -| `operator` | | | -| `path` | | | -| `range` | Color::White.normal() | \* | -| `record` | Color::White.normal() | \* | -| `signature` | | | -| `string` | Color::White.normal() | \* | -| `table` | | | -| `var` | | | -| `vardecl` | | | -| `variable` | | | +| primitive | default color | configurable | +| -------------- | ------------- | ------------ | +| `any` | | | +| `binary` | `default` | \* | +| `block` | `default` | \* | +| `bool` | `light_cyan` | \* | +| `cell-path` | `default` | \* | +| `closure` | `green_bold` | \* | +| `condition` | | | +| `custom` | `default` | \* | +| `datetime` | `purple` | \* | +| `duration` | `default` | \* | +| `expression` | | | +| `filesize` | `cyan` | \* | +| `float` | `default` | \* | +| `glob` | `cyan_bold` | \* | +| `import` | | | +| `int` | `default` | \* | +| `list` | `default` | \* | +| `nothing` | `default` | \* | +| `number` | | | +| `operator` | | | +| `path` | | | +| `range` | `default` | \* | +| `record` | `default` | \* | +| `semver` | `cyan_bold` | \* | +| `semver-range` | `cyan_bold` | \* | +| `signature` | | | +| `string` | `default` | \* | +| `table` | | | +| `var` | | | +| `vardecl` | | | +| `variable` | | | ### Special "primitives" (not really primitives but they exist solely for coloring) | primitive | default color | configurable | | --------------------------- | -------------------------- | ------------ | -| `leading_trailing_space_bg` | Color::Rgb(128, 128, 128)) | \* | -| `header` | Color::Green.bold() | \* | -| `empty` | Color::Blue.normal() | \* | -| `row_index` | Color::Green.bold() | \* | -| `hints` | Color::DarkGray.normal() | \* | - -Here's a small example of changing some of these values. +| `leading_trailing_space_bg` | `{ attr: n }` | \* | +| `header` | `green_bold` | \* | +| `empty` | `blue` | \* | +| `row_index` | `green_bold` | \* | +| `separator` | `default` | \* | +| `hints` | `dark_gray` | \* | +| `search_result` | `{ bg: red, fg: default }` | \* | +| `selection` | `{ attr: r }` | \* | +| `selection_cursor` | `{ attr: n }` | \* | +| `binary_null_char` | `grey42` | \* | +| `binary_printable` | `cyan_bold` | \* | +| `binary_whitespace` | `green_bold` | \* | +| `binary_ascii_other` | `purple_bold` | \* | +| `binary_non_ascii` | `yellow_bold` | \* | + +Here's a small example of changing some of these values. Note that the color names are quoted: Nushell treats a bare word on the right side of `=` as a command name, so `= purple` is a parse error. ```nu -$env.config.color_config.separator = purple +$env.config.color_config.separator = 'purple' $env.config.color_config.leading_trailing_space_bg = "#ffffff" -$env.config.color_config.header = gb -$env.config.color_config.datetime = wd -$env.config.color_config.filesize = c -$env.config.color_config.row_index = cb -$env.config.color_config.bool = red -$env.config.color_config.int = green -$env.config.color_config.duration = blue_bold -$env.config.color_config.range = purple -$env.config.color_config.float = red -$env.config.color_config.string = white -$env.config.color_config.nothing = red -$env.config.color_config.binary = red -$env.config.color_config.cell-path = cyan -$env.config.color_config.hints = dark_gray +$env.config.color_config.header = 'gb' +$env.config.color_config.datetime = 'wd' +$env.config.color_config.filesize = 'c' +$env.config.color_config.row_index = 'cb' +$env.config.color_config.bool = 'red' +$env.config.color_config.int = 'green' +$env.config.color_config.duration = 'blue_bold' +$env.config.color_config.range = 'purple' +$env.config.color_config.float = 'red' +$env.config.color_config.string = 'white' +$env.config.color_config.nothing = 'red' +$env.config.color_config.binary = 'red' +$env.config.color_config.cell-path = 'cyan' +$env.config.color_config.hints = 'dark_gray' ``` Here's another small example using multiple color syntaxes with some comments. ```nu $env.config.color_config.separator = "#88b719" # this sets only the foreground color like PR #486 -$env.config.color_config.leading_trailing_space_bg = white # this sets only the foreground color in the original style +$env.config.color_config.leading_trailing_space_bg = 'white' # this sets only the foreground color in the original style $env.config.color_config.header = { # this is like PR #489 fg: "#B01455", # note, quotes are required on the values with hex colors bg: "#ffb900", # note, commas are not required, it could also be all on one line @@ -366,39 +376,51 @@ As mentioned above, `shape` is a term used to indicate the syntax coloring. Here's the current list of flat shapes. -| shape | default style | configurable | -| ---------------------------- | -------------------------------------- | ------------ | -| `shape_block` | fg(Color::Blue).bold() | \* | -| `shape_bool` | fg(Color::LightCyan) | \* | -| `shape_custom` | bold() | \* | -| `shape_external` | fg(Color::Cyan) | \* | -| `shape_externalarg` | fg(Color::Green).bold() | \* | -| `shape_filepath` | fg(Color::Cyan) | \* | -| `shape_flag` | fg(Color::Blue).bold() | \* | -| `shape_float` | fg(Color::Purple).bold() | \* | -| `shape_garbage` | fg(Color::White).on(Color::Red).bold() | \* | -| `shape_globpattern` | fg(Color::Cyan).bold() | \* | -| `shape_int` | fg(Color::Purple).bold() | \* | -| `shape_internalcall` | fg(Color::Cyan).bold() | \* | -| `shape_list` | fg(Color::Cyan).bold() | \* | -| `shape_literal` | fg(Color::Blue) | \* | -| `shape_nothing` | fg(Color::LightCyan) | \* | -| `shape_operator` | fg(Color::Yellow) | \* | -| `shape_pipe` | fg(Color::Purple).bold() | \* | -| `shape_range` | fg(Color::Yellow).bold() | \* | -| `shape_record` | fg(Color::Cyan).bold() | \* | -| `shape_signature` | fg(Color::Green).bold() | \* | -| `shape_string` | fg(Color::Green) | \* | -| `shape_string_interpolation` | fg(Color::Cyan).bold() | \* | -| `shape_table` | fg(Color::Blue).bold() | \* | -| `shape_variable` | fg(Color::Purple) | \* | +| shape | default style | configurable | +| ---------------------------- | ----------------------------------- | ------------ | +| `shape_binary` | `purple_bold` | \* | +| `shape_block` | `blue_bold` | \* | +| `shape_bool` | `light_cyan` | \* | +| `shape_closure` | `green_bold` | \* | +| `shape_custom` | `green` | \* | +| `shape_datetime` | `cyan_bold` | \* | +| `shape_directory` | `cyan` | \* | +| `shape_external` | `cyan` | \* | +| `shape_external_resolved` | `light_yellow_bold` | \* | +| `shape_externalarg` | `green_bold` | \* | +| `shape_filepath` | `cyan` | \* | +| `shape_flag` | `blue_bold` | \* | +| `shape_float` | `purple_bold` | \* | +| `shape_garbage` | `{ fg: default, bg: red, attr: b }` | \* | +| `shape_glob_interpolation` | `cyan_bold` | \* | +| `shape_globpattern` | `cyan_bold` | \* | +| `shape_int` | `purple_bold` | \* | +| `shape_internalcall` | `cyan_bold` | \* | +| `shape_keyword` | `cyan_bold` | \* | +| `shape_list` | `cyan_bold` | \* | +| `shape_literal` | `blue` | \* | +| `shape_match_pattern` | `green` | \* | +| `shape_matching_brackets` | `default_underline` | \* | +| `shape_nothing` | `light_cyan` | \* | +| `shape_operator` | `yellow` | \* | +| `shape_pipe` | `purple_bold` | \* | +| `shape_range` | `yellow_bold` | \* | +| `shape_raw_string` | `light_purple` | \* | +| `shape_record` | `cyan_bold` | \* | +| `shape_redirection` | `purple_bold` | \* | +| `shape_signature` | `green_bold` | \* | +| `shape_string` | `green` | \* | +| `shape_string_interpolation` | `cyan_bold` | \* | +| `shape_table` | `blue_bold` | \* | +| `shape_variable` | `purple` | \* | +| `shape_vardecl` | `purple` | \* | Here's a small example of how to apply color to these items. Anything not overridden will receive its default color. ```nu -$env.config.color_config.shape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b} -$env.config.color_config.shape_bool: green -$env.config.color_config.shape_int: { fg: "#0000ff" attr: b} +$env.config.color_config.shape_garbage = { fg: "#FFFFFF" bg: "#FF0000" attr: b} +$env.config.color_config.shape_bool = 'green' +$env.config.color_config.shape_int = { fg: "#0000ff" attr: b} ``` ## Prompt Configuration and Coloring @@ -407,9 +429,9 @@ The Nushell prompt is configurable through these environment variables and confi - `PROMPT_COMMAND`: Code to execute for setting up the prompt (block) - `PROMPT_COMMAND_RIGHT`: Code to execute for setting up the _RIGHT_ prompt (block) (see oh-my.nu in nu_scripts) -- `PROMPT_INDICATOR` = "ใ€‰": The indicator printed after the prompt (by default ">"-like Unicode symbol) -- `PROMPT_INDICATOR_VI_INSERT` = ": " -- `PROMPT_INDICATOR_VI_NORMAL` = "v " +- `PROMPT_INDICATOR` = "> ": The indicator printed after the prompt in Emacs mode +- `PROMPT_INDICATOR_VI_INSERT` = ": ": The indicator in Vi insert mode (and Helix insert mode) +- `PROMPT_INDICATOR_VI_NORMAL` = "> ": The indicator in Vi normal and visual mode (and Helix normal and select mode) - `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 @@ -422,7 +444,7 @@ $env.PROMPT_COMMAND = { $"(date now | format date '%m/%d/%Y %I:%M:%S%.3f'): (pwd If you don't like the default `PROMPT_INDICATOR` you could change it like this. ```nu -$env.PROMPT_INDICATOR = "> " +$env.PROMPT_INDICATOR = "โฏ " ``` If you're using `starship`, you'll most likely want to show the right prompt on the last line of the prompt, just like zsh or fish. You could modify the `config.nu` file, just set `render_right_prompt_on_last_line` to true: @@ -499,7 +521,7 @@ You can put this command into your [Nushell configuration](/book/configuration.m Theming combines all the coloring above. Here's a quick example of one we put together quickly to demonstrate the ability to theme. This is a spin on the `base16` themes that we see so widespread on the web. -The key to making theming work is to make sure you specify all themes and colors you're going to use in the `config.nu` file _before_ you declare the `let config = ` line. +The key to making theming work is to make sure you define all themes and colors you're going to use in the `config.nu` file _before_ you assign them to `$env.config.color_config`. ```nu # let's define some colors @@ -564,15 +586,14 @@ let base16_theme = { # now let's apply our regular config settings but also apply the "color_config:" theme that we specified above. -$env.config.color_config: $base16_theme # <-- this is the theme -$env.config.edit_mode: emacs # vi -$env.config.filesize.unit: metric -$env.config.float_precision: 2 -$env.config.footer_mode: always #always, never, number_of_rows, auto -$env.config.history.max_size: 10000 -$env.config.ls.use_ls_colors: true -$env.config.table.mode: rounded # ascii_rounded, basic, basic_compact, compact, compact_double, default, dots, double, heavy, light, markdown, none, psql, reinforced, restructured, rounded, single, thin, with_love -$env.config.use_ansi_coloring: true +$env.config.color_config = $base16_theme # <-- this is the theme +$env.config.edit_mode = 'emacs' # emacs, vi, helix +$env.config.filesize.unit = 'metric' +$env.config.float_precision = 2 +$env.config.footer_mode = 'always' # always, never, auto, or a number of rows +$env.config.ls.use_ls_colors = true +$env.config.table.mode = 'rounded' # ascii_rounded, basic, basic_compact, compact, compact_double, default, dots, double, frameless, heavy, light, markdown, none, psql, reinforced, restructured, rounded, single, thin, with_love +$env.config.use_ansi_coloring = 'auto' # auto, true, false ``` If you want to go full-tilt on theming, you'll want to theme all the items I mentioned at the very beginning, including LS_COLORS, and the prompt. Good luck! @@ -586,11 +607,7 @@ If you are working on a light background terminal, you can apply the light theme # in $nu.config-path use std/config light-theme # add this line to load the theme into scope -$env.config = { - # ... - color_config: (light-theme) # after using dark-theme or light-theme from std, you can change this with `(dark-theme)` in place of `(light-theme)`. - # ... -} +$env.config.color_config = (light-theme) ``` You can also load the dark theme. @@ -599,11 +616,7 @@ You can also load the dark theme. # in $nu.config-path use std/config dark-theme -$env.config = { - # ... - color_config: (dark-theme) - # ... -} +$env.config.color_config = (dark-theme) ``` ## Accessibility @@ -612,20 +625,17 @@ It's often desired to have the minimum amount of decorations when using a screen ```nu # in $nu.config-path -$env.config = { - ... - table: { - ... - mode: "none" - ... - } - error_style: "plain" - ... -} +$env.config.table.mode = "none" +$env.config.error_style = "plain" ``` ## Line Editor Menus (completion, history, helpโ€ฆ) -Reedline (Nuโ€™s line editor) style is not using the `color_config` key. +Reedline (Nuโ€™s line editor) menus don't use the `color_config` key. Instead, each menu has its own style to be configured separately. See the [section dedicated to Reedlineโ€™s menus configuration](line_editor.md#menus) to learn more on this. + +The line editor does use a few `color_config` keys: `hints` styles the inline hints, +`selection` styles text selected in Vi visual mode or Helix mode, and `selection_cursor` +styles the character under the cursor inside a selection. The `shape_*` keys above +style the syntax highlighting of the command line. diff --git a/book/coming_from_bash.md b/book/coming_from_bash.md index e4439674935..5382444d836 100644 --- a/book/coming_from_bash.md +++ b/book/coming_from_bash.md @@ -53,23 +53,27 @@ $env.Path = ($env.Path | prepend 'C:\Program Files\Git\usr\bin') | | `rm -t ` | Move the given file to the system trash | | `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 | | `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 | | `man ` | `help ` | Get the help for a given command | | | `help commands` | List all available commands | | | `help --find ` | Search for match in all available commands | | `command1 && command2` | `command1; command2` | Run a command, and if it's successful run a second | +| `command1 \|\| command2` | `try { command1 } catch { command2 }` | Run a command, and if it fails run a second | | `stat $(which git)` | `stat ...(which git).path` | Use command output as argument for other command | | `echo /tmp/$RANDOM` | `$"/tmp/(random int)"` | Use command output in a string | | `cargo b --jobs=$(nproc)` | `cargo b $"--jobs=(sys cpu \| length)"` | Use command output in an option | | `echo $PATH` | `$env.PATH` (Non-Windows) or `$env.Path` (Windows) | See the current path | | `echo $?` | `$env.LAST_EXIT_CODE` | See the exit status of the last executed command | +| `set -o pipefail` | (default behavior) | Fail a pipeline if any external command in it fails | | `` | `vim $nu.config-path` | Update PATH permanently | | `export PATH = $PATH:/usr/other/bin` | `$env.PATH = ($env.PATH \| append /usr/other/bin)` | Update PATH temporarily | | `export` | `$env` | List the current environment variables | | `` | `vim $nu.config-path` | Update environment variables permanently | | `FOO=BAR ./bin` | `FOO=BAR ./bin` | Update environment temporarily | -| `export FOO=BAR` | `$env.FOO = BAR` | Set environment variable for current session | +| `export FOO=BAR` | `$env.FOO = "BAR"` | Set environment variable for current session | | `echo $FOO` | `$env.FOO` | Use environment variables | | `echo ${FOO:-fallback}` | `$env.FOO? \| default "ABC"` | Use a fallback in place of an unset variable | | `unset FOO` | `hide-env FOO` | Unset environment variable for current session | diff --git a/book/coming_from_cmd.md b/book/coming_from_cmd.md index 42416828745..d0a4a28ebcd 100644 --- a/book/coming_from_cmd.md +++ b/book/coming_from_cmd.md @@ -1,6 +1,6 @@ # Coming from CMD.EXE -This table was last updated for Nu 0.67.0. +This table was last updated for Nu 0.116.0. | CMD.EXE | Nu | Task | | ------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- | @@ -30,22 +30,24 @@ This table was last updated for Nu 0.67.0. | `FTYPE` | | Displays or modifies file types used in file extension associations | | `GOTO` | | Jump to a label | | `IF ERRORLEVEL ` | `if $env.LAST_EXIT_CODE >= { }` | Run a command if the last command returned an error code >= specified | +| | `try { } catch {\|e\| if $e.exit_code >= { } }` | Run a command if `` fails with an error code >= specified | | `IF EQU ` | `if == { }` | Run a command if strings match | | `IF EXIST ` | `if ( \| path exists) { }` | Run a command if the file exists | -| `IF DEFINED ` | `if '$' in (scope variables).name { }` | Run a command if the variable is defined | +| `IF DEFINED ` | `if '' in $env { }` | Run a command if the environment variable is defined | +| | `if '$' in (scope variables).name { }` | Run a command if the Nu variable is defined | | `MD` or `MKDIR` | `mkdir` | Create directories | | `MKLINK` | | Create symbolic links | | `MOVE` | `mv` | Move files | | `PATH` | `$env.Path` | Display the current path variable | -| `PATH ;%PATH%` | `$env.Path = ($env.Path \| append `) | Edit the path variable | -| `PATH %PATH%;` | `$env.Path = ($env.Path \| prepend `) | Edit the path variable | +| `PATH ;%PATH%` | `$env.Path = ($env.Path \| prepend )` | Edit the path variable | +| `PATH %PATH%;` | `$env.Path = ($env.Path \| append )` | Edit the path variable | | `PAUSE` | `input "Press any key to continue . . ."` | Pause script execution | | `PROMPT