diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts index 820b09f5679..5947307c225 100644 --- a/.vuepress/configs/sidebar/en.ts +++ b/.vuepress/configs/sidebar/en.ts @@ -32,11 +32,17 @@ export const sidebarEn: SidebarConfig = { children: [ '/book/types_of_data.md', '/book/loading_data.md', + '/book/data_formats.md', + '/book/working_with_sqlite.md', '/book/pipelines.md', '/book/working_with_strings.md', + '/book/regular_expressions.md', + '/book/working_with_binary.md', '/book/working_with_lists.md', '/book/working_with_records.md', + '/book/working_with_numbers.md', '/book/working_with_tables.md', + '/book/working_with_paths.md', '/book/navigating_structured_data.md', '/book/special_variables.md', ], @@ -65,6 +71,7 @@ export const sidebarEn: SidebarConfig = { '/book/sorting.md', '/book/testing.md', '/book/debugging.md', + '/book/language_server.md', '/book/style_guide.md', ], }, @@ -74,8 +81,10 @@ export const sidebarEn: SidebarConfig = { collapsible: false, children: [ '/book/configuration.md', + '/book/config_reference.md', '/book/environment.md', '/book/stdout_stderr_exit_codes.md', + '/book/terminal.md', '/book/running_externals.md', '/book/3rdpartyprompts.md', '/book/directory_stack.md', @@ -112,8 +121,42 @@ export const sidebarEn: SidebarConfig = { link: '/book/advanced.md', collapsible: false, children: [ - '/book/standard_library.md', - '/book/dataframes.md', + { + text: 'Standard Library', + link: '/book/standard_library.md', + collapsible: false, + children: [ + '/book/standard_library/assert.md', + '/book/standard_library/bench.md', + '/book/standard_library/clip.md', + '/book/standard_library/config.md', + '/book/standard_library/dt.md', + '/book/standard_library/formats.md', + '/book/standard_library/help.md', + '/book/standard_library/input.md', + '/book/standard_library/iter.md', + '/book/standard_library/log.md', + '/book/standard_library/math.md', + '/book/standard_library/random.md', + '/book/standard_library/util.md', + '/book/standard_library/xml.md', + '/book/standard_library/std_rfc.md', + ], + }, + { + text: 'Dataframes', + link: '/book/dataframes.md', + collapsible: false, + children: [ + '/book/dataframes/frames.md', + '/book/dataframes/selectors.md', + '/book/dataframes/math.md', + '/book/dataframes/strings.md', + '/book/dataframes/dates.md', + '/book/dataframes/conditionals.md', + '/book/dataframes/aggregation.md', + ], + }, '/book/metadata.md', '/book/creating_errors.md', '/book/parallelism.md', @@ -192,6 +235,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', @@ -217,7 +261,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', @@ -242,6 +289,7 @@ export const sidebarEn: SidebarConfig = { children: [ '/lang-guide/chapters/flow_control/if-else.md', '/lang-guide/chapters/flow_control/loop.md', + '/lang-guide/chapters/flow_control/for.md', '/lang-guide/chapters/flow_control/while.md', '/lang-guide/chapters/flow_control/match.md', '/lang-guide/chapters/flow_control/try-catch.md', @@ -259,8 +307,12 @@ export const sidebarEn: SidebarConfig = { '/lang-guide/chapters/filters/selecting_data.md', '/lang-guide/chapters/filters/where-filter.md', '/lang-guide/chapters/filters/select-get.md', + '/lang-guide/chapters/filters/changing_data.md', + '/lang-guide/chapters/filters/summarizing_lists.md', + '/lang-guide/chapters/filters/record_commands.md', ], }, + '/lang-guide/chapters/matrices.md', '/lang-guide/chapters/custom_commands.md', '/lang-guide/chapters/declarations.md', '/lang-guide/chapters/variable_scope.md', 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/background_jobs.md b/book/background_jobs.md index 6ea2217a3ad..74d8c37c7d4 100644 --- a/book/background_jobs.md +++ b/book/background_jobs.md @@ -6,7 +6,7 @@ next: # Background Jobs -Nushell currently has experimental support for thread-based background jobs. +Nushell currently has experimental support for thread-based background jobs. The subcommands of [`job`](/commands/docs/job.md) start, list, and control them. `job` on its own only prints its help, which lists those subcommands. ## Spawning Jobs @@ -29,6 +29,10 @@ open status.txt # => i am inevitable ``` +The closure runs on a copy of the caller's variables and environment, so a change it makes, such as setting `$env.FOO`, doesn't come back. Whatever the closure returns is thrown away, and so is the output of the external commands it runs. Only [`print`](/commands/docs/print.md) reaches the terminal. If the closure fails, Nushell prints the error, unless the job was killed or the [`display_errors`](./config_reference.md#display-errors) settings hide it. A job can spawn jobs of its own. + +Spawn a job with `--auto-kill` (`-k`) when it is fine to stop it without notice, such as a file watcher. [Exit Behavior](#exit-behavior) explains how `exit` treats such a job. + ## Listing and Killing jobs Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing. @@ -38,11 +42,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 │ 2 │ thread │ [list 0 items] │ -# => ╰───┴────┴────────┴────────────────╯ +# => ╭───┬────┬────────┬────────────────┬───────────╮ +# => │ # │ id │ type │ pids │ auto_kill │ +# => ├───┼────┼────────┼────────────────┼───────────┤ +# => │ 0 │ 2 │ thread │ [list 0 items] │ false │ +# => ╰───┴────┴────────┴────────────────┴───────────╯ job kill $id @@ -52,6 +56,8 @@ job list # => ╰────────────╯ ``` +The `auto_kill` column says whether the job was spawned with `--auto-kill`. + ## 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`: @@ -61,15 +67,17 @@ 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 │ -# => ╰───┴────┴────────┴────────────────┴─────────────╯ +# => ╭───┬────┬────────┬────────────────┬───────────┬─────────────╮ +# => │ # │ id │ type │ pids │ auto_kill │ description │ +# => ├───┼────┼────────┼────────────────┼───────────┼─────────────┤ +# => │ 0 │ 3 │ thread │ [list 0 items] │ false │ longer nap │ +# => ╰───┴────┴────────┴────────────────┴───────────┴─────────────╯ job kill $id ``` +To remove a description, pass `null`, as in `job describe $id null`. + ## 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: @@ -79,13 +87,13 @@ On Unix targets, such as Linux and macOS, Nushell also supports suspending exter # => Job 4 is frozen job list -# => ╭───┬────┬────────┬──────────────┬─────────────╮ -# => │ # │ id │ type │ pids │ description │ -# => ├───┼────┼────────┼──────────────┼─────────────┤ -# => │ 0 │ 4 │ frozen │ ╭───┬──────╮ │ sleep │ -# => │ │ │ │ │ 0 │ 6337 │ │ │ -# => │ │ │ │ ╰───┴──────╯ │ │ -# => ╰───┴────┴────────┴──────────────┴─────────────╯ +# => ╭───┬────┬────────┬──────────────┬───────────┬─────────────╮ +# => │ # │ id │ type │ pids │ auto_kill │ description │ +# => ├───┼────┼────────┼──────────────┼───────────┼─────────────┤ +# => │ 0 │ 4 │ frozen │ ╭───┬──────╮ │ false │ sleep │ +# => │ │ │ │ │ 0 │ 6337 │ │ │ │ +# => │ │ │ │ ╰───┴──────╯ │ │ │ +# => ╰───┴────┴────────┴──────────────┴───────────┴─────────────╯ ``` A frozen job is automatically described with the name of the suspended program. @@ -148,6 +156,24 @@ job recv # => Hello from a background job ``` +Inside a job, [`job id`](/commands/docs/job_id.md) returns that job's own ID. Outside any job, it returns `0`, the ID of the main thread. A job spawned from another job gets an ID of its own. When several jobs report back to the same receiver, `job id` lets each message say which job sent it: + +```nu +for n in 1..3 { + job spawn { {job: (job id), result: ($n * 10)} | job send 0 } +} +1..3 | each { job recv } | sort-by job +# => ╭───┬─────┬────────╮ +# => │ # │ job │ result │ +# => ├───┼─────┼────────┤ +# => │ 0 │ 1 │ 10 │ +# => │ 1 │ 2 │ 20 │ +# => │ 2 │ 3 │ 30 │ +# => ╰───┴─────┴────────╯ +``` + +The IDs depend on how many jobs the session has started before. + 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 @@ -160,7 +186,11 @@ 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`. +[`job send`](/commands/docs/job_send.md) never waits for the receiver. The message goes straight into the mailbox. Sending to a job that doesn't exist is an error, such as `Job 99 not found`. + +Without `--timeout`, [`job recv`](/commands/docs/job_recv.md) waits until a matching message arrives, and Ctrl+C interrupts the wait. When the timeout runs out first, it fails with `nu::shell::job::recv_timeout`. A timeout of `0sec` succeeds only when a matching message is already in the mailbox. Inside [`par-each`](/commands/docs/par-each.md), only one thread at a time can wait in `job recv`. The other threads wait for their turn in no particular order, whatever their timeouts. + +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`. A message that arrives while `job flush` runs may be discarded too. ## Exit Behavior @@ -175,7 +205,12 @@ 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, and it doesn't ask for confirmation either. It prints a +`nu::shell::background_jobs_running` warning with the number of running jobs, frozen jobs included, +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. A frozen job counts even when its external command was suspended +inside an auto-kill job. Pressing Ctrl+C at the REPL interrupts only the command running in the foreground. Background jobs and frozen jobs keep running. @@ -184,4 +219,7 @@ When Nushell runs a script or a command given with `nu -c`, it stops any jobs th along with their child processes, before it exits. This also happens when the script was interrupted with Ctrl+C and the interruption was caught. +A [`try`](./control_flow.md#try) block catches an interrupt like any other error, as +[Interrupting with Ctrl+C](./stdout_stderr_exit_codes.md#interrupting-with-ctrl-c) describes. + Calling `exit` inside a job's closure ends that job, not the shell. diff --git a/book/cheat_sheet.md b/book/cheat_sheet.md index 06d6d86d757..ea99a9cfbee 100644 --- a/book/cheat_sheet.md +++ b/book/cheat_sheet.md @@ -13,12 +13,6 @@ convert string to integer: "12" | into int ``` -convert present date to provided time zone: - -```nu -date now | date to-timezone "Europe/London" -``` - update a record's language and if none is specified insert provided value: ```nu @@ -298,6 +292,159 @@ $teams_scores | drop column # => ╰───┴───────────────────────┴───────╯ ``` +remove the last two columns of a table: + +```nu +$teams_scores | drop column 2 +# => ╭───┬───────────────────────╮ +# => │ # │ team │ +# => ├───┼───────────────────────┤ +# => │ 0 │ Boston Celtics │ +# => │ 1 │ Golden State Warriors │ +# => ╰───┴───────────────────────╯ +``` + +remove the first column of a table instead of the last: + +```nu +$teams_scores | drop column --left +# => ╭───┬───────┬───────╮ +# => │ # │ score │ plays │ +# => ├───┼───────┼───────┤ +# => │ 0 │ 311 │ 3 │ +# => │ 1 │ 245 │ 2 │ +# => ╰───┴───────┴───────╯ +``` + +remove the last field of a record (use `reject` to remove columns or fields by name): + +```nu +{name: nu, stars: 5, language: Rust} | drop column +# => ╭───────┬────╮ +# => │ name │ nu │ +# => │ stars │ 5 │ +# => ╰───────┴────╯ +``` + +## Numbers + +convert a string to a float (`into float` reads a comma as a decimal point, so remove thousands separators first): + +```nu +"1.5" | into float +# => 1.5 +``` + +find the largest value in each column of a table: + +```nu +[[a b]; [1 5] [3 2]] | math max +# => ╭───┬───╮ +# => │ a │ 3 │ +# => │ b │ 5 │ +# => ╰───┴───╯ +``` + +get the median and the standard deviation of a list (`--sample` divides by N - 1): + +```nu +[2 4 4 4 5 5 7 9] | math median +# => 4.5 +[2 4 4 4 5 5 7 9] | math stddev +# => 2.0 +``` + +apply a function to each number in a list: + +```nu +[1 10 100] | math log 10 +# => ╭───┬──────╮ +# => │ 0 │ 0.00 │ +# => │ 1 │ 1.00 │ +# => │ 2 │ 2.00 │ +# => ╰───┴──────╯ +``` + +roll a six-sided die ten times (`..` includes the end of the range, `..<` leaves it out): + +```nu +1..10 | each { random int 1..6 } +``` + +generate a UUID (`-v 7` makes one that sorts by creation time): + +```nu +random uuid +``` + +read a clock time as a duration and show it in minutes: + +```nu +"1:30:00" | into duration | format duration min +# => 90 min +``` + +read a size written as text (units are case-insensitive, and `KiB`, `MiB` and so on count in 1024s): + +```nu +"1.5 GiB" | into filesize +# => 1.6 GB +``` + +## Dates + +get the current date and time: + +```nu +date now +``` + +convert present date to provided time zone: + +```nu +date now | date to-timezone "Europe/London" +``` + +list the time zone names that `date to-timezone` accepts (case doesn't matter, and any other name is an `invalid time zone` error): + +```nu +date list-timezone | where timezone =~ "Kolkata" +# => ╭───┬──────────────┬────────╮ +# => │ # │ timezone │ offset │ +# => ├───┼──────────────┼────────┤ +# => │ 0 │ Asia/Kolkata │ +05:30 │ +# => ╰───┴──────────────┴────────╯ +``` + +convert a date to a fixed UTC offset (`+0530` and `+05` work too, and `local` converts to your own time zone): + +```nu +2024-06-01T12:00:00Z | date to-timezone "+05:30" | format date "%F %T %z" +# => 2024-06-01 17:30:00 +0530 +``` + +convert date strings, or a list of them, to a time zone: + +```nu +["2024-06-01 12:00:00 +00:00" "2024-12-01 12:00:00 +00:00"] | date to-timezone "America/New_York" | format date "%F %T %z" +# => ╭───┬───────────────────────────╮ +# => │ 0 │ 2024-06-01 08:00:00 -0400 │ +# => │ 1 │ 2024-12-01 07:00:00 -0500 │ +# => ╰───┴───────────────────────────╯ +``` + +describe a date relative to now, such as "2 years ago": + +```nu +2024-06-01T12:00:00Z | date humanize +``` + +parse a date written in words: + +```nu +"next friday" | date from-human +``` + ## Files and Filesystem open a text file with the default text editor: @@ -330,7 +477,7 @@ recursively search for files by file name: glob **/*.{rs,toml} --depth 2 ``` -watch a file, run command whenever it changes: +watch a file, run command whenever it changes (see [Running a command when files change](/cookbook/files.md#running-a-command-when-files-change)): ```nu for _ in (watch . --glob=**/*.rs) { cargo test } diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index 920fb9d559b..6a6cc5a31c4 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -35,6 +35,17 @@ The options for `$env.config.table.mode` can be listed with `table --list`: - `thin` - `with_love` +The names ignore case, so `'PSQL'` works too. `default` is another name for `rounded`, so after you assign `'default'`, the setting reads back as `rounded`. + +To draw one table in a different mode, pass it to [`table --theme`](/commands/docs/table.md) (`-t`) and leave the setting alone. To try a mode without changing your configuration, start Nushell with `nu --table-mode ` (`-m`). The flag overrides the mode from `config.nu`, but `$env.config.table.mode` keeps the configured value. + +```nu +[[a b]; [1 2]] | table --theme markdown +# => | # | a | b | +# => |---|---|---| +# => | 0 | 1 | 2 | +``` + Examples: ```nu @@ -59,6 +70,39 @@ table --list | first 5 $env.config.table.mode = 'rounded' # back to the default ``` +## Other table display settings + +`$env.config.footer_mode` decides when a table repeats its column names below the last row. Only tables with a header row get a footer, such as a list of records. A plain list never does. The setting takes `"always"`, `"never"`, `"auto"`, or a number of rows (default `25`), as described under [`footer_mode`](./config_reference.md#footer-mode-and-table-footer-inheritance). With a number, a table with at least that many rows gets a footer: + +```nu +$env.config.footer_mode = 3 +[[name]; [a] [b] [c]] +# => ╭───┬──────╮ +# => │ # │ name │ +# => ├───┼──────┤ +# => │ 0 │ a │ +# => │ 1 │ b │ +# => │ 2 │ c │ +# => ├───┼──────┤ +# => │ # │ name │ +# => ╰───┴──────╯ +``` + +`$env.config.float_precision` sets how many decimal places a float gets when Nushell draws it inside a table, list, or record. The default is `2`. The float itself keeps its full precision, and a float printed on its own or converted to a string isn't rounded. + +```nu +$env.config.float_precision = 4 +[3.14159 2.0] +# => ╭───┬────────╮ +# => │ 0 │ 3.1416 │ +# => │ 1 │ 2.0000 │ +# => ╰───┴────────╯ +3.14159 +# => 3.14159 +3.14159 | into string +# => 3.14159 +``` + ## Color Configuration The color configuration is defined in `$env.config.color_config`. The current configuration can be printed with: @@ -78,160 +122,187 @@ The color and style-attributes can be declared in multiple alternative formats. - `{|x| 'yellow' }` - closure returning a string with one of the color representations listed above - `{|x| { fg: "#ff0000" bg: "#0000ff" attr: b } }` - closure returning a valid record +Color names are case-sensitive. `red` works, but `Red` and `RED` don't. Nushell doesn't report a name it doesn't know, and draws the text in the terminal's default color instead. + +A string that starts with `{` is read as a JSON style record, so `'{"fg": "red", "attr": "u"}'` works like the record `{ fg: red attr: u }`. It has to be valid JSON, with every key and value in double quotes. + ### Attributes -| code | meaning | -| ---- | ------------------- | -| l | blink | -| b | bold | -| d | dimmed | -| h | hidden | -| i | italic | -| r | reverse | -| s | strikethrough | -| u | underline | -| n | nothing | -| | defaults to nothing | +| code | name | +| ---- | ------------------------- | +| l | `blink` | +| b | `bold` | +| d | `dimmed` | +| h | `hidden` | +| i | `italic` | +| r | `reverse` | +| s | `strike`, `strikethrough` | +| u | `underline` | +| n | `normal` (no attribute) | +| | defaults to nothing | + +`attr` takes codes or names, in any case. Codes can run together, so `attr: bi` is bold italic, and names go in one string separated by spaces, as in `attr: 'bold italic'`. If any part of `attr` isn't a code or a name, or the string contains a comma, Nushell ignores the whole style, `fg` and `bg` included, and draws the value unstyled. ### 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`. Every color except `default` also has a `_blink` and a `_strike` form. + +| code | name | +| -------- | ------------------------- | +| `g` | `green` | +| `gb` | `green_bold` | +| `gu` | `green_underline` | +| `gi` | `green_italic` | +| `gd` | `green_dimmed` | +| `gr` | `green_reverse` | +| `gbl` | `green_blink` | +| `gst` | `green_strike` | +| `lg` | `light_green` | +| `lgb` | `light_green_bold` | +| `lgu` | `light_green_underline` | +| `lgi` | `light_green_italic` | +| `lgd` | `light_green_dimmed` | +| `lgr` | `light_green_reverse` | +| `lgbl` | `light_green_blink` | +| `lgst` | `light_green_strike` | +| `r` | `red` | +| `rb` | `red_bold` | +| `ru` | `red_underline` | +| `ri` | `red_italic` | +| `rd` | `red_dimmed` | +| `rr` | `red_reverse` | +| `rbl` | `red_blink` | +| `rst` | `red_strike` | +| `lr` | `light_red` | +| `lrb` | `light_red_bold` | +| `lru` | `light_red_underline` | +| `lri` | `light_red_italic` | +| `lrd` | `light_red_dimmed` | +| `lrr` | `light_red_reverse` | +| `lrbl` | `light_red_blink` | +| `lrst` | `light_red_strike` | +| `u` | `blue` | +| `ub` | `blue_bold` | +| `uu` | `blue_underline` | +| `ui` | `blue_italic` | +| `ud` | `blue_dimmed` | +| `ur` | `blue_reverse` | +| `ubl` | `blue_blink` | +| `ust` | `blue_strike` | +| `lu` | `light_blue` | +| `lub` | `light_blue_bold` | +| `luu` | `light_blue_underline` | +| `lui` | `light_blue_italic` | +| `lud` | `light_blue_dimmed` | +| `lur` | `light_blue_reverse` | +| `lubl` | `light_blue_blink` | +| `lust` | `light_blue_strike` | +| `b` | `black` | +| `bb` | `black_bold` | +| `bu` | `black_underline` | +| `bi` | `black_italic` | +| `bd` | `black_dimmed` | +| `br` | `black_reverse` | +| `bbl` | `black_blink` | +| `bst` | `black_strike` | +| `ligr` | `light_gray` | +| `ligrb` | `light_gray_bold` | +| `ligru` | `light_gray_underline` | +| `ligri` | `light_gray_italic` | +| `ligrd` | `light_gray_dimmed` | +| `ligrr` | `light_gray_reverse` | +| `ligrbl` | `light_gray_blink` | +| `ligrst` | `light_gray_strike` | +| `y` | `yellow` | +| `yb` | `yellow_bold` | +| `yu` | `yellow_underline` | +| `yi` | `yellow_italic` | +| `yd` | `yellow_dimmed` | +| `yr` | `yellow_reverse` | +| `ybl` | `yellow_blink` | +| `yst` | `yellow_strike` | +| `ly` | `light_yellow` | +| `lyb` | `light_yellow_bold` | +| `lyu` | `light_yellow_underline` | +| `lyi` | `light_yellow_italic` | +| `lyd` | `light_yellow_dimmed` | +| `lyr` | `light_yellow_reverse` | +| `lybl` | `light_yellow_blink` | +| `lyst` | `light_yellow_strike` | +| `p` | `purple` | +| `pb` | `purple_bold` | +| `pu` | `purple_underline` | +| `pi` | `purple_italic` | +| `pd` | `purple_dimmed` | +| `pr` | `purple_reverse` | +| `pbl` | `purple_blink` | +| `pst` | `purple_strike` | +| `lp` | `light_purple` | +| `lpb` | `light_purple_bold` | +| `lpu` | `light_purple_underline` | +| `lpi` | `light_purple_italic` | +| `lpd` | `light_purple_dimmed` | +| `lpr` | `light_purple_reverse` | +| `lpbl` | `light_purple_blink` | +| `lpst` | `light_purple_strike` | +| `m` | `magenta` | +| `mb` | `magenta_bold` | +| `mu` | `magenta_underline` | +| `mi` | `magenta_italic` | +| `md` | `magenta_dimmed` | +| `mr` | `magenta_reverse` | +| `mbl` | `magenta_blink` | +| `mst` | `magenta_strike` | +| `lm` | `light_magenta` | +| `lmb` | `light_magenta_bold` | +| `lmu` | `light_magenta_underline` | +| `lmi` | `light_magenta_italic` | +| `lmd` | `light_magenta_dimmed` | +| `lmr` | `light_magenta_reverse` | +| `lmbl` | `light_magenta_blink` | +| `lmst` | `light_magenta_strike` | +| `c` | `cyan` | +| `cb` | `cyan_bold` | +| `cu` | `cyan_underline` | +| `ci` | `cyan_italic` | +| `cd` | `cyan_dimmed` | +| `cr` | `cyan_reverse` | +| `cbl` | `cyan_blink` | +| `cst` | `cyan_strike` | +| `lc` | `light_cyan` | +| `lcb` | `light_cyan_bold` | +| `lcu` | `light_cyan_underline` | +| `lci` | `light_cyan_italic` | +| `lcd` | `light_cyan_dimmed` | +| `lcr` | `light_cyan_reverse` | +| `lcbl` | `light_cyan_blink` | +| `lcst` | `light_cyan_strike` | +| `w` | `white` | +| `wb` | `white_bold` | +| `wu` | `white_underline` | +| `wi` | `white_italic` | +| `wd` | `white_dimmed` | +| `wr` | `white_reverse` | +| `wbl` | `white_blink` | +| `wst` | `white_strike` | +| `dgr` | `dark_gray` | +| `dgrb` | `dark_gray_bold` | +| `dgru` | `dark_gray_underline` | +| `dgri` | `dark_gray_italic` | +| `dgrd` | `dark_gray_dimmed` | +| `dgrr` | `dark_gray_reverse` | +| `dgrbl` | `dark_gray_blink` | +| `dgrst` | `dark_gray_strike` | +| `def` | `default` | +| `defb` | `default_bold` | +| `defu` | `default_underline` | +| `defi` | `default_italic` | +| `defd` | `default_dimmed` | +| `defr` | `default_reverse` | + + + +`color_config` also accepts the 256 xterm colors that [`ansi --list`](/commands/docs/ansi.md) shows with an `xterm_` prefix, such as `xterm_navy` or `xterm_grey42`. Use the full `xterm_` name. These colors have no `_bold` or other forms, so add attributes with a record, such as `{ fg: xterm_navy attr: b }`. ### `"#hex"` Format @@ -239,6 +310,8 @@ The "#hex" format is one way you typically see colors represented. It's simply t Example: The primary `red` color is `"#ff0000"` or `"#FF0000"`. Upper and lower case in letters shouldn't make a difference. +Only the six-digit form works, as a plain string or as `fg` or `bg` in a record. The three-digit shorthand that CSS allows, such as `"#f00"`, gives no color. + This `"#hex"` format allows us to specify 24-bit truecolor tones to different parts of Nushell. ### Full `"#hex"` Format @@ -253,7 +326,7 @@ Example: `{ fg: "#ff0000" bg: "#0000ff" attr: b }` ### Closure -Note: Closures are only executed for table output. They do not work in other contexts like for `shape_` configurations, when printing a value directly, or as a value in a list. +Nushell runs these closures only when it draws a table, list, or record. A value printed on its own, such as a bare `3`, isn't styled at all, and the `shape_*` keys don't accept closures. For example: @@ -272,72 +345,74 @@ $env.config.color_config.bool = {|x| if $x { 'green' } else { 'light_red' } } 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`. +The closure gets the value both as its parameter and as `$in`, so `{|| if $in { 'green' } else { 'light_red' } }` works the same as the `bool` closure above. It has to return a color string or a style record. Any other result, such as a number, leaves the value unstyled. If the closure raises an error, Nushell prints the error once for each value it was styling and draws those values unstyled. + ## Primitive Values Primitive values are things like `int` and `string`. Primitive values and shapes can be set with a variety of color symbologies seen above. -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` | `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` | | | +These keys style values of each type when Nushell draws them in a table, list, or record. + +| key | default style | +| -------------- | ------------- | +| `binary` | `default` | +| `block` | `default` | +| `bool` | `light_cyan` | +| `cell-path` | `default` | +| `custom` | not set | +| `datetime` | `purple` | +| `duration` | `default` | +| `filesize` | `cyan` | +| `float` | `default` | +| `glob` | `cyan_bold` | +| `int` | `default` | +| `list` | `default` | +| `nothing` | `default` | +| `range` | `default` | +| `record` | `default` | +| `semver` | `cyan_bold` | +| `semver-range` | `cyan_bold` | +| `string` | `default` | + +A few of these keys behave differently from the rest: + +- `list` and `record` style the `[list 2 items]` and `{record 1 field}` summaries that a table shows in place of a nested value. `list` also styles the `[table 1 row]` summary of a nested table. +- `block` is reserved and changes nothing. + +Other type names, such as `any`, `number`, or `table`, aren't `color_config` keys, and setting them has no effect. ### Special "primitives" (not really primitives but they exist solely for coloring) -| primitive | default color | configurable | -| --------------------------- | -------------------------- | ------------ | -| `leading_trailing_space_bg` | `{ attr: n }` | \* | -| `header` | `green_bold` | \* | -| `empty` | `blue` | \* | -| `row_index` | `green_bold` | \* | -| `separator` | `default` | \* | -| `hints` | `dark_gray` | \* | -| `status_line` | the `hints` style | \* | -| `status_line_error` | `red` | \* | -| `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. +| key | default style | styles | +| --------------------------- | -------------------------- | -------------------------------------------------------------- | +| `leading_trailing_space_bg` | `{ attr: n }` | spaces at the start and end of strings in tables | +| `header` | `green_bold` | column headers, the `#` heading, and the keys of a record | +| `empty` | `blue` | the placeholder for a missing cell | +| `row_index` | `green_bold` | the index numbers in the `#` column | +| `separator` | `default` | the borders of tables, lists, and records | +| `hints` | `dark_gray` | inline hints in the line editor | +| `status_line` | the `hints` style | the [status line](line_editor.md#status-line) under the prompt | +| `status_line_error` | `red` | an error shown in the status line | +| `search_result` | `{ bg: red, fg: default }` | the matches that [`find`](/commands/docs/find.md) highlights | +| `selection` | `{ attr: r }` | text selected in Vi visual mode or Helix mode | +| `selection_cursor` | `{ attr: n }` | the character under the cursor inside a selection | +| `binary_null_char` | `grey42` | `00` bytes in the binary hex view | +| `binary_printable` | `cyan_bold` | printable ASCII bytes in the hex view | +| `binary_whitespace` | `green_bold` | ASCII whitespace bytes in the hex view | +| `binary_ascii_other` | `purple_bold` | other ASCII bytes, such as control characters | +| `binary_non_ascii` | `yellow_bold` | bytes above `0x7f` | + +`leading_trailing_space_bg` needs a background color, such as `{ bg: dark_gray }`, because a foreground color has nothing to draw on a space. The default `{ attr: n }` turns the highlight off. + +`empty` styles the symbol that `$env.config.table.missing_value_symbol` sets for a cell a row doesn't have. The default symbol is an emoji, and many terminals draw emoji in their own colors, so `empty` may not change anything until you pick a plain-text symbol. + +The `binary_*` keys color the hex view that Nushell shows for a binary value printed on its own, such as `0x[41 00 20 ff]`. + +Here's a small example of changing some of these values. The color names are quoted because 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.leading_trailing_space_bg = "#ffffff" +$env.config.color_config.leading_trailing_space_bg = { bg: "#ffffff" } $env.config.color_config.header = 'gb' $env.config.color_config.datetime = 'wd' $env.config.color_config.filesize = 'c' @@ -358,7 +433,7 @@ 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 = { bg: 'white' } # spaces have no foreground, so set a background $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 @@ -372,50 +447,56 @@ $env.config.color_config.row_index = { } ``` +### Keys for the banner and for theme scripts + +Three more keys color the welcome banner: `banner_foreground` for its text (default `attr_normal`), and `banner_highlight1` (default `green`) and `banner_highlight2` (default `purple`) for the highlighted words. They aren't in the default `color_config`, and the banner uses those defaults when they're missing. The [`banner`](/commands/docs/banner.md) command passes them to [`ansi`](/commands/docs/ansi.md), so they take what `ansi` takes: its names, such as `attr_normal` or `green`, `"#hex"` strings, and records. Short forms that only `color_config` knows, such as `gbl`, make `banner` fail with an "Unknown ansi code" error. + +`foreground`, `background`, and `cursor` are also accepted, but Nushell never reads them. They're there for scripts that set the terminal's own colors, such as the `theme` commands in [nu_scripts](https://github.com/nushell/nu_scripts/tree/main/themes). None of the three is set by default. + ## Shape Values 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_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` | \* | +| shape | default style | colors | +| ---------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- | +| `shape_binary` | `purple_bold` | binary literals such as `0x[ff]` | +| `shape_block` | `blue_bold` | the braces of a block, as in `if true { }`, and the parentheses of a subexpression | +| `shape_bool` | `light_cyan` | `true` and `false` | +| `shape_closure` | `green_bold` | the braces and parameters of a closure | +| `shape_datetime` | `cyan_bold` | datetime literals such as `2020-01-01` | +| `shape_directory` | `cyan` | arguments that must be a directory, such as `foo` in `cd foo` | +| `shape_external` | `cyan` | a command that Nushell will run as an external command | +| `shape_external_resolved` | `light_yellow_bold` | an external command found in `PATH`, when `$env.config.highlight_resolved_externals` is `true` | +| `shape_externalarg` | `green_bold` | the arguments of an external command | +| `shape_filepath` | `cyan` | file path arguments, such as `out.txt` in `save out.txt` | +| `shape_flag` | `blue_bold` | flags such as `--all` and `-a` | +| `shape_float` | `purple_bold` | float literals | +| `shape_garbage` | `{ fg: default, bg: red, attr: b }` | a token that doesn't parse where it stands, such as `abc` in `sleep abc` or `+` in `1 +` | +| `shape_glob_interpolation` | `cyan_bold` | deprecated | +| `shape_globpattern` | `cyan_bold` | glob arguments, such as `*.txt` in `ls *.txt` | +| `shape_int` | `purple_bold` | integer literals | +| `shape_internalcall` | `cyan_bold` | the names of Nushell commands | +| `shape_keyword` | `cyan_bold` | keywords inside a command's syntax, such as `else`, `catch`, and the `in` of `for x in` | +| `shape_list` | `cyan_bold` | the brackets of a list literal | +| `shape_literal` | `blue` | not used | +| `shape_match_pattern` | `green` | the patterns of a `match` arm | +| `shape_matching_brackets` | `default_underline` | the bracket that pairs with the one under the cursor, on top of its usual style | +| `shape_nothing` | `light_cyan` | `null` | +| `shape_operator` | `yellow` | operators such as `+` and `==`, and the `..` of a range | +| `shape_pipe` | `purple_bold` | the pipe symbol | +| `shape_raw_string` | `light_purple` | raw strings such as `r#'text'#` | +| `shape_record` | `cyan_bold` | the braces and colons of a record literal | +| `shape_redirection` | `purple_bold` | redirections such as `o>` and `e>` | +| `shape_signature` | `green_bold` | the parameter list of a `def` | +| `shape_string` | `green` | strings, including bare words that Nushell reads as strings | +| `shape_string_interpolation` | `cyan_bold` | the `$"` and `"` around an interpolated string | +| `shape_table` | `blue_bold` | the brackets and `;` of a table literal | +| `shape_variable` | `purple` | variables such as `$env` | +| `shape_vardecl` | `purple` | the name a variable gets when it's declared, such as `x` in `let x = 1` | + +A shape key that's missing, or set to something other than a string or a record, falls back to its default style. Here's a small example of how to apply color to these items. Anything not overridden will receive its default color. @@ -437,7 +518,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)" } @@ -481,6 +562,35 @@ Nushell will respect and use the `LS_COLORS` environment variable setting on Mac If `LS_COLORS` is not set, nushell will default to a built-in `LS_COLORS` setting, based on [8-bit (extended) ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit). +::: details What the built-in LS_COLORS contains + +The built-in setting has close to 700 entries. Most of them match file extensions or file names, and they fall into these groups. The numbers after `38;5;` and `48;5;` are 256-color palette indexes for the foreground and background. + +| entries | style | looks like | +| --------------------------------------------------------------------- | --------------------- | ----------------------- | +| `di` (directories) | `0;38;5;81` | light blue | +| `ex` (executables), and files such as `*.exe`, `*.dll`, `*.so` | `1;38;5;203` | bold red | +| `ln` (symbolic links) | `0;38;5;203` | red | +| `or` and `mi` (broken links), `do` (doors), `so` (sockets) | `0;38;5;16;48;5;203` | black on red | +| `pi` (named pipes) | `0;38;5;16;48;5;81` | black on light blue | +| `bd` (block devices) | `0;38;5;81;48;5;236` | light blue on dark grey | +| `cd` (character devices) | `0;38;5;203;48;5;236` | red on dark grey | +| source code, such as `*.rs`, `*.py`, `*.nu`, `*.sh` | `0;38;5;48` | green | +| configuration and build files, such as `*.toml`, `*.json`, `Makefile` | `0;38;5;149` | yellow-green | +| text and markup, such as `*.md`, `*.txt`, `*.html` | `0;38;5;185` | yellow | +| documents, such as `*.pdf`, `*.csv`, `*.docx` | `0;38;5;186` | pale yellow | +| images, audio, and video, such as `*.png`, `*.mp3` | `0;38;5;208` | orange | +| archives, such as `*.zip`, `*.gz` | `4;38;5;203` | underlined red | +| build output and temporary files, such as `*.o`, `*.log`, `*~` | `0;38;5;243` | grey | +| `README`, `CHANGELOG`, and similar files | `0;38;5;16;48;5;186` | black on pale yellow | +| `LICENSE`, `COPYING`, and similar files | `0;38;5;249` | light grey | +| `TODO` | `1` | bold | +| `fi` (regular files) and anything not listed | `0` | no color | + +::: + +To stop [`ls`](/commands/docs/ls.md) output from using `LS_COLORS`, built-in or not, set `$env.config.ls.use_ls_colors = false`. File names then get the `color_config.string` style like any other string, and they lose the clickable links that `ls` adds when `shell_integration.osc8` is on. The setting defaults to `true`. + ### Understanding `LS_COLORS` `LS_COLORS` contains a colon (`:`) separated list of records that map file types and file names to styling attributes (`selector=attributes`). @@ -549,7 +659,7 @@ let base0f = "#a16946" # Deprecated, Opening/Closing Embedded Language Tags, e.g let base16_theme = { separator: $base03 - leading_trailing_space_bg: $base04 + leading_trailing_space_bg: { bg: $base04 } header: $base0b datetime: $base0e filesize: $base0d @@ -598,6 +708,18 @@ $env.config.table.mode = 'rounded' # ascii_rounded, basic, basic_compact, compac $env.config.use_ansi_coloring = 'auto' # auto, true, false ``` +Assigning a record to `$env.config.color_config` replaces the whole map. Keys the theme leaves out disappear from `$env.config.color_config`, along with any value you gave them earlier, and Nushell draws those items in their built-in default style: + +```nu +$env.config.color_config = { header: red } +$env.config.color_config | columns +# => ╭───┬────────╮ +# => │ 0 │ header │ +# => ╰───┴────────╯ +``` + +After this, a `bool` in a table is still light cyan, its built-in default. Code that reads a key directly, such as `ansi $env.config.color_config.shape_external`, fails with "Cannot find column" once the key is gone, so read keys a theme might leave out with `?`, as in `$env.config.color_config.shape_external?`. To change only a few colors, set those keys one at a time (`$env.config.color_config.header = 'red'`) instead of assigning a record. + 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! ### Working on Light Background Terminal @@ -621,6 +743,60 @@ use std/config dark-theme $env.config.color_config = (dark-theme) ``` +Both commands return a record you can inspect or change before assigning it. `dark-theme` looks like the built-in default theme except for `search_result` and `shape_garbage`, which use white text where the defaults use the terminal's default color. `light-theme` draws most values (`int`, `string`, `float`, `duration`, and others) and the table borders in `dark_gray`, so they stay readable on a light background. + +Neither theme sets `glob`, `semver`, `semver-range`, `selection`, `selection_cursor`, or `status_line_error`, so after you assign one, those items get their built-in default style. + +## Turning colors on and off + +`$env.config.use_ansi_coloring` decides whether Nushell's own output, such as tables, help text, and error messages, uses color. It takes three values: + +- `"auto"`, the default, decides from the environment, as described below. +- `true` always uses color, and `false` never does. The strings `"true"` and `"false"` work too. With either value, Nushell ignores the environment variables below. + +In `"auto"` mode, Nushell goes through these checks in order and stops at the first one that applies: + +1. If `FORCE_COLOR` is true, use color. +1. If `NO_COLOR` is true, don't use color. +1. If `CLICOLOR` is set, use color when it's true and don't when it's false. +1. If `TERM` is `dumb`, don't use color. +1. Otherwise, use color only when standard output is a terminal. + +Nushell reads each of these variables as a boolean. An empty value, `0`, and `false` count as false, and anything else, including `no`, counts as true. So `NO_COLOR=0` doesn't turn colors off, although some other programs treat any non-empty `NO_COLOR` as a request for no color. The variable names match in any case, so `force_color` works as well, but the value of `TERM` has to be lowercase `dumb`. + +[`config use-colors`](/commands/docs/config_use-colors.md) returns the result of this check, which is handy in scripts that build their own colored output: + +```nu +$env.config.use_ansi_coloring = false +config use-colors +# => false +``` + +The setting doesn't affect the [`ansi`](/commands/docs/ansi.md) command. `ansi red` returns the escape code for red even when `use_ansi_coloring` is `false`. + +## Gradient text + +[`ansi gradient`](/commands/docs/ansi_gradient.md) colors a string one character at a time, shading from one color to another. `--fgstart` and `--fgend` set the foreground color at the two ends of the string, and `--bgstart` and `--bgend` do the same for the background. You need at least one of these flags, or one of the named gradients described below, otherwise the command fails with a "Missing parameter" error. If you give a start color without an end color, or the other way around, the missing one is black. + +Write each color as `0x` followed by six hex digits, such as `0x40c9ff`. Any other form, including `#40c9ff`, quietly turns into black. In this example, `str replace` makes the escape codes visible: + +```nu +'abcd' | ansi gradient --fgstart '0xff0000' --fgend '0x0000ff' | str replace --all (ansi escape) '\e' +# => \e[38;2;255;0;0ma\e[38;2;191;0;63mb\e[38;2;127;0;127mc\e[38;2;63;0;191md\e[0m +``` + +`--fgnamed` and `--bgnamed` take the name of a built-in gradient instead of two colors, such as `rainbow` or `forest`, in any case. `ansi gradient --list` returns a table with each `name` and a sample `text`. A named gradient can't be mixed with a start or end color for the same layer, but a named foreground works with a two-color background, and the other way around. + +The input can be a string or a list of strings. For a record or a table, pass cell paths to choose which strings get the gradient, as in `ansi gradient --fgstart '0xff0000' name`. Without cell paths, a record or table input is an error, because every value has to be a string. + +`ansi gradient` treats its input as plain characters. Escape codes already in the string get colored too, one character at a time, which breaks them and prints parts of them, such as `[31m`, as text. Remove them first with [`ansi strip`](/commands/docs/ansi_strip.md): + +```nu +$"(ansi red)ab(ansi reset)" | ansi strip | ansi gradient --fgstart '0xffffff' +``` + +The gradient also counts Unicode characters (code points), not screen columns. A double-width character such as `日` takes one step like any other. A character built from several code points, such as an `e` followed by a combining accent, gets a color code between its parts. + ## Accessibility It's often desired to have the minimum amount of decorations when using a screen reader. In those cases, it's possible to disable borders and other decorations for both table and errors with the following options: diff --git a/book/coming_from_bash.md b/book/coming_from_bash.md index 78100935413..28b394463cb 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,36 @@ $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 the Nushell command and each executable in PATH with that name | +| `type -P FOO` | `which ^FOO` | Look up only the external program, skipping Nushell commands | +| `compgen -c` | `which` | List every Nushell command and every 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