From 13fe3f16e7ba203516ba21738f0c98d14da9ab9a Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sat, 1 Feb 2025 17:23:46 +0100 Subject: [PATCH 1/5] Fix and extend color documentation * Drop ambiguous hash label - works just fine with only the symbol `#` * Clarify when it is commented out vs may be (hex) value * Drop text table of contents; the website has it's own sidebar table of contents / headline jump list * Fix headline levels - the general color declaration docs were under Table Borders, and hex and full hex were not on the same level * Introduce/Rename main section 'Color Configuration' * Show command to print the current configuration * Add closure declaration format documentation * Drop separators following headlines; other headlines do not have this, they make no logical sense, and they lead to double-separator-lines being rendered on the website Resolves #1503 --- book/coloring_and_theming.md | 58 ++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index a7b25ced8ab..fab840ef804 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -1,12 +1,6 @@ # Coloring and Theming in Nu -Many parts of Nushell's interface can have their color customized. All of these can be set in the `config.nu` configuration file. If you see the hash/hashtag/pound mark `#` in the config file it means the text after it is commented out. - -1. table borders -2. primitive values -3. shapes (this is the command line syntax) -4. prompt -5. LS_COLORS +Many parts of Nushell's interface can have their color customized. All of these can be set in the `config.nu` configuration file. If you see the `#` outside of a text value in the config file it means the text after it is commented out. ## Table Borders @@ -34,9 +28,15 @@ Here are the current options for `$env.config.table.mode`: - `none` - `other` -### Color Symbologies +## Color Configuration + +The color configuration is defined in `$env.config.color_config`. The current configuration can be printed with: + +```nu +$env.config.color_config | sort +``` ---- +The color and style-attributes can be declared in multiple alternative formats. - `r` - normal color red's abbreviation - `rb` - normal color red's abbreviation with bold attribute @@ -44,11 +44,11 @@ Here are the current options for `$env.config.table.mode`: - `red_bold` - normal color red with bold attribute - `"#ff0000"` - "#hex" format foreground color red (quotes are required) - `{ fg: "#ff0000" bg: "#0000ff" attr: b }` - "full #hex" format foreground red in "#hex" format with a background of blue in "#hex" format with an attribute of bold abbreviated. +- `{|x| 'yellow' }` - closure returning a valid string +- `{|x| { fg: "#ff0000" bg: "#0000ff" attr: b } }` - closure returning a valid record ### Attributes ---- - | code | meaning | | ---- | ------------------- | | l | blink | @@ -197,17 +197,13 @@ Here are the current options for `$env.config.table.mode`: ### `"#hex"` Format ---- - The "#hex" format is one way you typically see colors represented. It's simply the `#` character followed by 6 characters. The first two are for `red`, the second two are for `green`, and the third two are for `blue`. It's important that this string be surrounded in quotes, otherwise Nushell thinks it's a commented out string. Example: The primary `red` color is `"#ff0000"` or `"#FF0000"`. Upper and lower case in letters shouldn't make a difference. This `"#hex"` format allows us to specify 24-bit truecolor tones to different parts of Nushell. -## Full `"#hex"` Format - ---- +### Full `"#hex"` Format The `full "#hex"` format is a take on the `"#hex"` format but allows one to specify the foreground, background, and attributes in one line. @@ -217,9 +213,33 @@ Example: `{ fg: "#ff0000" bg: "#0000ff" attr: b }` - background of blue in "#hex" format - attribute of bold abbreviated -## Primitive Values +### Closure + +Note that closures are only executed for table output. They do not work for `shape_` configurations, nor when output as the value type itself, or as a list of such value. ---- +For example: + +```nu +$env.config.color_config.filesize = {|x| if $x == 0b { 'dark_gray' } else if $x < 1mb { 'cyan' } else { 'blue' } } +$env.config.color_config.filesize = {|x| if $x == 0b { 'dark_gray' } else if $x < 1mb { 'cyan' } else { 'blue_bold' } } +{a:true,b:false,c:0mb,d:0.5mb,e:10mib} +``` + +prints + +```nu +╭───┬───────────╮ +│ a │ true │ +│ b │ false │ +│ c │ 0 B │ +│ d │ 488.3 KiB │ +│ e │ 10.0 MiB │ +╰───┴───────────╯ +``` + +with a green `true`, a red `false`, a grey `0 B`, a cyan `488.3 KiB`, and a blue `10.0 MiB`. + +## 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. @@ -256,7 +276,7 @@ This is the current list of primitives. Not all of these are configurable. The c | `vardecl` | | | | `variable` | | | -#### Special "primitives" (not really primitives but they exist solely for coloring) +### Special "primitives" (not really primitives but they exist solely for coloring) | primitive | default color | configurable | | --------------------------- | -------------------------- | ------------ | From e945d203baf458822c71d8ac6f780a2a6a3ec386 Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sat, 1 Feb 2025 17:30:50 +0100 Subject: [PATCH 2/5] Improve limited closure execution note --- book/coloring_and_theming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index fab840ef804..a68ce5aa75d 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -215,7 +215,7 @@ Example: `{ fg: "#ff0000" bg: "#0000ff" attr: b }` ### Closure -Note that closures are only executed for table output. They do not work for `shape_` configurations, nor when output as the value type itself, or as a list of such value. +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. For example: From 2e82e512a7c5531c2867287fb7c850e027f30eea Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sat, 1 Feb 2025 19:31:54 +0100 Subject: [PATCH 3/5] Add missing bool closure example Was intended and result is described below. --- book/coloring_and_theming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index a68ce5aa75d..c54eb09973f 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -221,7 +221,7 @@ For example: ```nu $env.config.color_config.filesize = {|x| if $x == 0b { 'dark_gray' } else if $x < 1mb { 'cyan' } else { 'blue' } } -$env.config.color_config.filesize = {|x| if $x == 0b { 'dark_gray' } else if $x < 1mb { 'cyan' } else { 'blue_bold' } } +$env.config.color_config.bool = {|x| if $x { 'green' } else { 'light_red' } } {a:true,b:false,c:0mb,d:0.5mb,e:10mib} ``` From ec98e119a0a17e33bb70e8bba1176ef6f0f5646d Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sat, 1 Feb 2025 19:33:13 +0100 Subject: [PATCH 4/5] Improve closure string return description --- book/coloring_and_theming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index c54eb09973f..7d0b365ea60 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -44,7 +44,7 @@ The color and style-attributes can be declared in multiple alternative formats. - `red_bold` - normal color red with bold attribute - `"#ff0000"` - "#hex" format foreground color red (quotes are required) - `{ fg: "#ff0000" bg: "#0000ff" attr: b }` - "full #hex" format foreground red in "#hex" format with a background of blue in "#hex" format with an attribute of bold abbreviated. -- `{|x| 'yellow' }` - closure returning a valid string +- `{|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 ### Attributes From 2538181c1e6470800351a0e297cc122912577ab3 Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sun, 2 Feb 2025 15:28:42 +0100 Subject: [PATCH 5/5] Be more specific about color description --- book/coloring_and_theming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index 7d0b365ea60..4727f585b91 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -237,7 +237,7 @@ prints ╰───┴───────────╯ ``` -with a green `true`, a red `false`, a grey `0 B`, a cyan `488.3 KiB`, and a blue `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`. ## Primitive Values