feat(config): add highlight overrides (#12)

* feat(config): add highlight overrides * only apply overrides for current background * add documentation * chore(ci): auto generate docs * adjust documentation * chore(ci): auto generate docs * adjust documentation again * chore(ci): auto generate docs --------- Co-authored-by: ramojus <[email protected]>
ramojus · Jan 21, 2024 · a5c7b7e · a5c7b7e
1 parent d4a5215
commit a5c7b7e
Show file tree

Hide file tree

Showing 4 changed files with 222 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -121,7 +121,7 @@ require 'mellifluous'.setup({
 ```
 
 #### Overriding colors of a color set
-The following snipet shows where and which colors can be overridden:
+The following snippet shows where and which colors can be overridden:
 
 ```lua
 require 'mellifluous'.setup({
@@ -152,7 +152,7 @@ require 'mellifluous'.setup({
                 cyan = nil,
             },
             light = { -- light variant of the color set
-                -- same fields as in dark variant
+                -- same keys as in dark variant
             },
         }
     }
@@ -173,6 +173,99 @@ require 'mellifluous'.setup({
 })
 ```
 
+#### Overriding highlights of a color set
+The following snippet shows how highlight overrides can be defined for a specific color set:
+
+```lua
+require 'mellifluous'.setup({
+    <color_set_name> = { -- name any of the defined color sets
+        -- config structure from here is the same as for global highlight overrides
+    }
+})
+```
+
+For further instructions, refer to [overriding highlights](#overriding-highlights) section
+
+##### Extra colors
+In addition to the colors listed in [available colors](#available-colors) section, some color sets may have more colors available (`cyan` and/or `yellow`). To check your color set, refer to [the source code for color sets](lua/mellifluous/colors/sets/) and see if `get_colors_*` functions return any extra (optional) colors.
+
+### Overriding highlights
+The following snippet shows how global (for any color set) highlight overrides can be defined:
+```lua
+require 'mellifluous'.setup({
+    highlight_overrides = {
+        dark = function(highlighter, colors) -- dark variant of the color set
+            -- set highlights here (using highlighter)
+        end,
+        light = function(highlighter, colors) -- light variant of the color set
+            -- set highlights here (using highlighter)
+        end,
+    }
+})
+```
+
+For an example on how to set the highlights, check [the source code for general highlights](lua/mellifluous/highlights/general.lua), where `M.set` function has the same signature as `dark` or `light` functions seen above. A detailed documentation is provided below.
+
+#### Highlighter usage
+This is the signature to set a highlight:
+
+```lua
+highlighter.set(name, definition_map)
+```
+
+Parameters:
+- `name`: highlight group name in string format
+- `definition_map`: highlight definition map in table format, the supported keys can be found in `:h nvim_set_hl`. Keys `fg`, `bg` and `sp` can also be set to any of the available colors (see [available colors](#available-colors)).
+
+To get an existing highlight, use this function:
+
+```lua
+highlighter.get(name)
+```
+
+This function returns highlight definition map for highlight group with the requested name. 
+
+#### Available colors
+To use one of the available colors from a color set, in highlight definition map, set the value of `fg`, `bg` or `sp` key to `colors.available_color`
+
+Available colors:
+- Syntax element colors.
+    - `main_keywords`: used to indicate keywords related to control flow.
+    - `other_keywords`
+    - `types`
+    - `operators`
+    - `strings`
+    - `functions`
+    - `constants`
+    - `comments`
+    - `fg`: in code -- identifiers.
+    - `bg`
+- Named colors. Used for terminal colors, but most of these colors will match some syntax element color.
+    - `red`
+    - `orange`
+    - `green`
+    - `blue`
+    - `purple`
+- UI colors. Same as named colors, but all are of the same brightness (lightness).
+    - `ui_red`: used to indicate errors, deletes, bad spellings.
+    - `ui_orange`: used to indicate warnings, changes, other (strange) spellings.
+    - `ui_green`: used to indicate staged, additions.
+    - `ui_blue`: used to indicate information, new files.
+    - `ui_purple`: used to indicate hints, merge.
+
+NOTE: some color sets may have more colors available. See [extra colors](#extra-colors) section.
+
+#### Color functions
+Every color from [available colors](#available-colors) has the following meta functions (accessed with `:` operator):
+- `lightened(val)`: returns color with `val` added current to lightness.
+- `darkened(val)`: returns color with `val` subtracted from current lightness.
+- `with_lightness(val)`: returns color with specified lightness, where `val` can be from 0 to 100.
+- `saturated(val)`: returns color with `val` added to current saturation.
+- `desaturated(val)`: returns color with `val` subtracted from current saturation.
+- `with_saturation(val)`: returns color with specified saturation, where `val` can be from 0 to 100.
+
+To create your own color that has the same functions available, use `require('mellifluous.color').new(hex_value)` function.
+
 ## CLI options
 Type `:Mellifluous <TAB>` and see the available options.
 

diff --git a/doc/mellifluous.txt b/doc/mellifluous.txt
@@ -8,6 +8,7 @@ Table of Contents                              *mellifluous-table-of-contents*
 3. Configuration                                   |mellifluous-configuration|
   - Setting light theme        |mellifluous-configuration-setting-light-theme|
   - Color sets                          |mellifluous-configuration-color-sets|
+  - Overriding highlights    |mellifluous-configuration-overriding-highlights|
 4. CLI options                                       |mellifluous-cli-options|
 5. TODO                                                     |mellifluous-todo|
 6. Ports                                                   |mellifluous-ports|
@@ -140,7 +141,7 @@ Default config:
 
 OVERRIDING COLORS OF A COLOR SET ~
 
-The following snipet shows where and which colors can be overridden:
+The following snippet shows where and which colors can be overridden:
 
 >lua
     require 'mellifluous'.setup({
@@ -171,7 +172,7 @@ The following snipet shows where and which colors can be overridden:
                     cyan = nil,
                 },
                 light = { -- light variant of the color set
-                    -- same fields as in dark variant
+                    -- same keys as in dark variant
                 },
             }
         }
@@ -194,6 +195,115 @@ version of the mellifluous color set, one could do the following:
 <
 
 
+OVERRIDING HIGHLIGHTS OF A COLOR SET ~
+
+The following snippet shows how highlight overrides can be defined for a
+specific color set:
+
+>lua
+    require 'mellifluous'.setup({
+        <color_set_name> = { -- name any of the defined color sets
+            -- config structure from here is the same as for global highlight overrides
+        }
+    })
+<
+
+For further instructions, refer to |mellifluous-overriding-highlights| section
+
+
+EXTRA COLORS
+
+In addition to the colors listed in |mellifluous-available-colors| section,
+some color sets may have more colors available (`cyan` and/or `yellow`). To
+check your color set, refer to the source code for color sets
+<lua/mellifluous/colors/sets/> and see if `get_colors_*` functions return any
+extra (optional) colors.
+
+
+OVERRIDING HIGHLIGHTS        *mellifluous-configuration-overriding-highlights*
+
+The following snippet shows how global (for any color set) highlight overrides
+can be defined:
+
+>lua
+    require 'mellifluous'.setup({
+        highlight_overrides = {
+            dark = function(highlighter, colors) -- dark variant of the color set
+                -- set highlights here (using highlighter)
+            end,
+            light = function(highlighter, colors) -- light variant of the color set
+                -- set highlights here (using highlighter)
+            end,
+        }
+    })
+<
+
+For an example on how to set the highlights, check the source code for general
+highlights <lua/mellifluous/highlights/general.lua>, where `M.set` function has
+the same signature as `dark` or `light` functions seen above. A detailed
+documentation is provided below.
+
+
+HIGHLIGHTER USAGE ~
+
+This is the signature to set a highlight:
+
+>lua
+    highlighter.set(name, definition_map)
+<
+
+Parameters: - `name`: highlight group name in string format - `definition_map`:
+highlight definition map in table format, the supported keys can be found in
+|nvim_set_hl|. Keys `fg`, `bg` and `sp` can also be set to any of the available
+colors (see |mellifluous-available-colors|).
+
+To get an existing highlight, use this function:
+
+>lua
+    highlighter.get(name)
+<
+
+This function returns highlight definition map for highlight group with the
+requested name.
+
+
+AVAILABLE COLORS ~
+
+To use one of the available colors from a color set, in highlight definition
+map, set the value of `fg`, `bg` or `sp` key to `colors.available_color`
+
+Available colors: - Syntax element colors. - `main_keywords`: used to indicate
+keywords related to control flow. - `other_keywords` - `types` - `operators` -
+`strings` - `functions` - `constants` - `comments` - `fg`: in code –
+identifiers. - `bg` - Named colors. Used for terminal colors, but most of these
+colors will match some syntax element color. - `red` - `orange` - `green` -
+`blue` - `purple` - UI colors. Same as named colors, but all are of the same
+brightness (lightness). - `ui_red`: used to indicate errors, deletes, bad
+spellings. - `ui_orange`: used to indicate warnings, changes, other (strange)
+spellings. - `ui_green`: used to indicate staged, additions. - `ui_blue`: used
+to indicate information, new files. - `ui_purple`: used to indicate hints,
+merge.
+
+NOTE: some color sets may have more colors available. See
+|mellifluous-extra-colors| section.
+
+
+COLOR FUNCTIONS ~
+
+Every color from |mellifluous-available-colors| has the following meta
+functions (accessed with `:` operator): - `lightened(val)`: returns color with
+`val` added current to lightness. - `darkened(val)`: returns color with `val`
+subtracted from current lightness. - `with_lightness(val)`: returns color with
+specified lightness, where `val` can be from 0 to 100. - `saturated(val)`:
+returns color with `val` added to current saturation. - `desaturated(val)`:
+returns color with `val` subtracted from current saturation. -
+`with_saturation(val)`: returns color with specified saturation, where `val`
+can be from 0 to 100.
+
+To create your own color that has the same functions available, use
+`require('mellifluous.color').new(hex_value)` function.
+
+
 ==============================================================================
 4. CLI options                                       *mellifluous-cli-options*
 

diff --git a/lua/mellifluous/config.lua b/lua/mellifluous/config.lua
@@ -115,4 +115,18 @@ function M.prepare()
     M.config = read_only(config)
 end
 
+function M.set_highlight_overrides(highlighter, colors)
+    local background = config.is_bg_dark and 'dark' or 'light'
+
+    local global_highlight_overrides = vim.tbl_get(M.config, 'highlight_overrides', background) or nil
+    if global_highlight_overrides then
+        global_highlight_overrides(highlighter, colors)
+    end
+
+    local color_set_highlight_overrides = vim.tbl_get(M.config, M.config.color_set, 'highlight_overrides', background) or nil
+    if color_set_highlight_overrides then
+        color_set_highlight_overrides(highlighter, colors)
+    end
+end
+
 return M
diff --git a/lua/mellifluous/init.lua b/lua/mellifluous/init.lua
@@ -20,6 +20,7 @@ function M.load()
     local highlighter = require('mellifluous.utils.highlighter')
 
     require('mellifluous.highlights').set(highlighter, colors)
+    require('mellifluous.config').set_highlight_overrides(highlighter, colors)
 
     return highlighter, colors
 end