From 91d807b1d219ba4847be2635b0ae31f6caeafd42 Mon Sep 17 00:00:00 2001
From: Darren Schroeder <343840+fdncred@users.noreply.github.com>
Date: Mon, 3 Jan 2022 13:06:49 -0600
Subject: [PATCH] add docs about coloring and theming (#654)

---
 docs/How_To_Coloring_and_Theming.md | 458 ++++++++++++++++++++++++++++
 1 file changed, 458 insertions(+)
 create mode 100644 docs/How_To_Coloring_and_Theming.md

diff --git a/docs/How_To_Coloring_and_Theming.md b/docs/How_To_Coloring_and_Theming.md
new file mode 100644
index 0000000000..0b86423ce4
--- /dev/null
+++ b/docs/How_To_Coloring_and_Theming.md
@@ -0,0 +1,458 @@
+# Coloring and Theming in Nushell
+
+There are a few main parts that nushell allows you to change the color. 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. flatshapes (this is the command line syntax)
+4. prompt
+5. LS_COLORS
+
+## `Table borders`
+___
+
+Table borders are controlled by the `table_mode` setting in the `config.nu`. Here is an example:
+```
+let $config = {
+    table_mode: rounded
+}
+```
+
+Here are the current options for `table_mode`:
+1. `rounded` # of course, this is the best one :)
+2. `basic`
+3. `compact`
+4. `compact_double`
+5. `light`
+6. `thin`
+7. `with_love`
+8. `rounded`
+9. `reinforced`
+10. `heavy`
+11. `none`
+12. `other`
+
+### `Color symbologies`
+---
+
+* `r` - normal color red's abbreviation
+* `rb` - normal color red's abbreviation with bold attribute
+* `red` - normal color red
+* `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.
+
+### `attributes`
+---
+
+|code|meaning|
+|-|-|
+|l|blink|
+|b|bold|
+|d|dimmed|
+|h|hidden|
+|i|italic|
+|r|reverse|
+|s|strikethrough|
+|u|underline|
+|n|nothing|
+||defaults to nothing|
+
+### `normal colors` and `abbreviations`
+
+|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|
+|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|
+
+### `"#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
+---
+The `full "#hex"` format is a take on the `"#hex"` format but allows one to specify the foreground, background, and attributes in one line.
+
+Example: ``{ fg: "#ff0000" bg: "#0000ff" attr: b }`
+
+* foreground of red in "#hex" format 
+* background of blue in "#hex" format 
+* attribute of bold abbreviated
+
+## `Primitive values`
+___
+
+Primitive values are things like `int` and `string`. Primitive values and flatshapes 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 *.
+
+* `any`
+* `binary` *
+* `block` *
+* `bool` *
+* `cellpath` *
+* `condition`
+* `custom` 
+* `date` *
+* `duration` *
+* `expression`
+* `filesize` *
+* `float` *
+* `glob`
+* `import`
+* `int` *
+* `list` *
+* `nothing` *
+* `number`
+* `operator`
+* `path`
+* `range` *
+* `record` *
+* `signature`
+* `string` *
+* `table`
+* `var`
+* `vardecl`
+* `variable`
+
+#### special "primitives" (not really primitives but they exist solely for coloring)
+
+* `leading_trailing_space_bg` *
+* `header` *
+* `empty` *
+* `row_index` *
+* `hints` *
+
+Here's a small example of changing some of these values.
+```
+let config = {
+    color_config: {
+        separator: purple
+        leading_trailing_space_bg: "#ffffff"
+        header: gb
+        date: wd
+        filesize: c
+        row_index: cb
+        bool: red
+        int: green
+        duration: blue_bold
+        range: purple
+        float: red
+        string: white
+        nothing: red
+        binary: red
+        cellpath: cyan
+        hints: dark_gray
+    }
+}
+```
+Here's another small example using multiple color syntaxes with some comments.
+```
+let config = {
+    color_config: {
+        separator: "#88b719" # this sets only the foreground color like PR #486
+        leading_trailing_space_bg: white # this sets only the foreground color in the original style
+        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
+        attr: bli # note, there are no quotes around this value. it works with or without quotes
+        }
+        date: "#75507B"
+        filesize: "#729fcf"
+        row_index: { # note, that this is another way to set only the foreground, no need to specify bg and attr
+        fg: "#e50914"
+    }
+}
+```
+
+## `FlatShape` values
+
+As mentioned above, `flatshape` is a term used to indicate the sytax coloring. (get better words from jt)
+
+Here's the current list of flat shapes.
+
+* `flatshape_block`
+* `flatshape_bool`
+* `flatshape_custom`
+* `flatshape_external`
+* `flatshape_externalarg`
+* `flatshape_filepath`
+* `flatshape_flag`
+* `flatshape_float`
+* `flatshape_garbage`
+* `flatshape_globpattern`
+* `flatshape_int`
+* `flatshape_internalcall`
+* `flatshape_list`
+* `flatshape_literal`
+* `flatshape_nothing`
+* `flatshape_operator`
+* `flatshape_range`
+* `flatshape_record`
+* `flatshape_signature`
+* `flatshape_string`
+* `flatshape_string_interpolation`
+* `flatshape_table`
+* `flatshape_variable`
+
+Here's a small example of how to apply color to these items. Anything not specified will receive the default color.
+
+```
+let $config = {
+    color_config: {
+        flatshape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b}
+        flatshape_bool: green
+        flatshape_int: { fg: "#0000ff" attr: b}
+    }
+}
+```
+
+## `Prompt` configuration and coloring
+
+The nushell prompt is configurable through these environment variables settings.
+
+* `PROMPT_COMMAND`: Code to execute for setting up the prompt (block)
+* `PROMPT_INDICATOR` = "〉": The indicator printed after the prompt (by default ">"-like Unicode symbol)
+* `PROMPT_INDICATOR_VI_INSERT` = ": "
+* `PROMPT_INDICATOR_VI_VISUAL` = "v "
+* `PROMPT_MULTILINE_INDICATOR` = "::: "
+
+Example: For a simple prompt one could do this. Note that `PROMPT_COMMAND` requires a `block` whereas the others require a `string`.
+
+`> let-env PROMPT_COMMAND = { build-string (date now | date format '%m/%d/%Y %I:%M:%S%.3f') ': ' (pwd | decode utf-8 | path basename) }`
+
+If you don't like the default `PROMPT_INDICATOR` you could change it like this.
+
+`> let-env PROMPT_INDICATOR = "> "`
+
+Coloring of the prompt is controlled by the `block` in `PROMPT_COMMAND` where you can write your own custom prompt. We've written a slightly fancy one that has git statuses located in the [nu_scripts repo](https://github.com/nushell/nu_scripts/blob/main/prompt/oh-my.nu).
+
+## `LS_COLORS` colors for the `ls` command
+
+Nushell will respect and use the `LS_COLORS` environment variable setting on Mac, Linux, and Windows. This setting allows you to define the color of file types when you do a `ls`. For instance, you can make directories one color, *.md markdown files another color, *.toml files yet another color, etc. There are a variety of ways to color your file types.
+
+There's an exhaustive list [here](https://github.com/trapd00r/LS_COLORS), which is overkill, but gives you an rudimentary understanding of how to create a ls_colors file that `dircolors` can turn into a `LS_COLORS` environment variable.
+
+[This](https://www.linuxhowto.net/how-to-set-colors-for-ls-command/) is a pretty good introduction to `LS_COLORS`. I'm sure you can fine many more tutorials on the web.
+
+I like the `vivid` application and currently have it configured in my `config.nu` like this. You can find `vivid` [here](https://github.com/sharkdp/vivid).
+
+`let-env LS_COLORS = (vivid generate molokai | decode utf-8 | str trim)`
+
+## Theming
+
+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.
+
+```
+# lets define some colors
+
+let base00 = "#181818" # Default Background
+let base01 = "#282828" # Lighter Background (Used for status bars, line number and folding marks)
+let base02 = "#383838" # Selection Background
+let base03 = "#585858" # Comments, Invisibles, Line Highlighting
+let base04 = "#b8b8b8" # Dark Foreground (Used for status bars)
+let base05 = "#d8d8d8" # Default Foreground, Caret, Delimiters, Operators
+let base06 = "#e8e8e8" # Light Foreground (Not often used)
+let base07 = "#f8f8f8" # Light Background (Not often used)
+let base08 = "#ab4642" # Variables, XML Tags, Markup Link Text, Markup Lists, Diff Deleted
+let base09 = "#dc9656" # Integers, Boolean, Constants, XML Attributes, Markup Link Url
+let base0a = "#f7ca88" # Classes, Markup Bold, Search Text Background
+let base0b = "#a1b56c" # Strings, Inherited Class, Markup Code, Diff Inserted
+let base0c = "#86c1b9" # Support, Regular Expressions, Escape Characters, Markup Quotes
+let base0d = "#7cafc2" # Functions, Methods, Attribute IDs, Headings
+let base0e = "#ba8baf" # Keywords, Storage, Selector, Markup Italic, Diff Changed
+let base0f = "#a16946" # Deprecated, Opening/Closing Embedded Language Tags, e.g. <?php ?>
+
+# we're creating a theme here that uses the colors we defined above.
+
+let base16_theme = {
+    separator: $base03
+    leading_trailing_space_bg: $base04
+    header: $base0b
+    date: $base0e
+    filesize: $base0d
+    row_index: $base0c
+    bool: $base08
+    int: $base0b
+    duration: $base08
+    range: $base08
+    float: $base08
+    string: $base04
+    nothing: $base08
+    binary: $base08
+    cellpath: $base08
+    hints: dark_gray
+
+    # flatshape_garbage: { fg: $base07 bg: $base08 attr: b} # base16 white on red
+    # but i like the regular white on red for parse errors
+    flatshape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b}
+    flatshape_bool: $base0d
+    flatshape_int: { fg: $base0e attr: b}
+    flatshape_float: { fg: $base0e attr: b}
+    flatshape_range: { fg: $base0a attr: b}
+    flatshape_internalcall: { fg: $base0c attr: b}
+    flatshape_external: $base0c
+    flatshape_externalarg: { fg: $base0b attr: b}
+    flatshape_literal: $base0d
+    flatshape_operator: $base0a
+    flatshape_signature: { fg: $base0b attr: b}
+    flatshape_string: $base0b
+    flatshape_filepath: $base0d
+    flatshape_globpattern: { fg: $base0d attr: b}
+    flatshape_variable: $base0e
+    flatshape_flag: { fg: $base0d attr: b}
+    flatshape_custom: {attr: b}
+}
+
+# now let's apply our regular config settings but also apply the "color_config:" theme that we specified above.
+
+let config = {
+  filesize_metric: $true
+  table_mode: rounded # basic, compact, compact_double, light, thin, with_love, rounded, reinforced, heavy, none, other
+  use_ls_colors: $true
+  color_config: $base16_theme # <-- this is the theme
+  use_grid_icons: $true
+  footer_mode: always #always, never, number_of_rows, auto
+  animate_prompt: $false
+  float_precision: 2
+  without_color: $false
+  filesize_format: "b" # b, kb, kib, mb, mib, gb, gib, tb, tib, pb, pib, eb, eib, zb, zib, auto
+  edit_mode: emacs # vi
+  max_history_size: 10000
+  log_level: error
+}
+```
+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!
\ No newline at end of file