Feat/add hooks: disable_line_highlight (#138)

* feat: adds user_default_option hook table with `disable_line_highlight` function

Author: catgoose

README.md

@@ -12,6 +12,8 @@
     - [Lua API](#lua-api)
   - [Why another highlighter?](#why-another-highlighter)
   - [Customization](#customization)
+    - [Hooks](#hooks)
+    - [Setup Examples](#setup-examples)
     - [Updating color even when buffer is not focused](#updating-color-even-when-buffer-is-not-focused)
     - [Lazyload Colorizer with Lazy.nvim](#lazyload-colorizer-with-lazynvim)
     - [Tailwind](#tailwind)
@@ -164,11 +166,33 @@ library to do custom highlighting themselves.
       -- update color values even if buffer is not focused
       -- example use: cmp_menu, cmp_docs
       always_update = false,
+      -- hooks to invert control of colorizer
+      hooks = {
+        -- called before line parsing.  Set to function that returns a boolean and accepts the following parameters.  See hooks section.
+        do_lines_parse = false,
+      },
     },
   })
 ```
 
-Setup examples:
+### Hooks
+
+Hooks into colorizer can be defined to customize colorization behavior.
+
+`do_lines_parse`: Expects a function that returns a boolean. The function is called before line parsing with the following function signature:
+
+```lua
+---@param line string: Line's contents
+---@param bufnr number: Buffer number
+---@line_num number: Line number (0-indexed).  Ad 1 to get the line number in buffer
+---@return boolean: Return true if current line should be parsed for highlighting.
+function(line, bufnr, line_num)
+  -- Treesitter could also be used, but be warned it will be quite laggy unless you are caching results somehow
+  return string.sub(line, 1, 2) ~= "--"
+end
+```
+
+### Setup Examples
 
 ```lua
 -- Attaches to every FileType with default options

doc/colorizer.txt

@@ -548,6 +548,9 @@ user_default_options                     *colorizer.config.user_default_options*
 	display.
 	{always_update} -  boolean: Always update color values, even if buffer
 	is not focused.
+	hooks -  table: Table of hook functions
+	{disable_line_highlight} -  function: Returns boolean which controls if
+	line should be parsed for highlights
 
 
 
@@ -615,6 +618,13 @@ ud_opts                                               *colorizer.config.ud_opts*
     for virtual text.
   - `always_update` (boolean): If true, updates color values even if the buffer
     is not focused.<
+ - `hooks` (table): Table of hook functions
+    - `disable_line_highlight` (function): Returns a boolean that controls if
+      the line should be parsed for highlights. Called  with 3 parameters:
+      - `line` (string): The line's contents.
+      - `bufnr` (number): The buffer number.
+      - `line_num` (number): The line number (0-indexed).  Add 1 to get the line
+	number in the buffer.
 	{buftypes} -  (table|nil): Optional. A list of buffer types where
 	colorizer should be enabled. Defaults to all buffer types if not
 	provided.

doc/modules/colorizer.config.html

@@ -329,6 +329,12 @@ <h3>Fields:</h3>
         <li><span class="parameter">always_update</span>
          boolean: Always update color values, even if buffer is not focused.
         </li>
+        <li><span class="parameter">hooks</span> table: Table of hook functions
+        <ul>
+        <li><span class="parameter">disable_line_highlight</span>
+         function: Returns boolean which controls if line should be parsed for highlights
+        </li>
+        </li></ul>
     </ul>
 
 
@@ -417,6 +423,11 @@ <h3>Fields:</h3>
   - `virtualtext_inline` (boolean|'before'|'after'): Shows the virtual text inline with the color.  True defaults to 'before'.
   - `virtualtext_mode` ('background'|'foreground'): Determines the display mode for virtual text.
   - `always_update` (boolean): If true, updates color values even if the buffer is not focused.</pre>
+ - `hooks` (table): Table of hook functions
+    - `disable_line_highlight` (function): Returns a boolean that controls if the line should be parsed for highlights. Called  with 3 parameters:
+      - `line` (string): The line's contents.
+      - `bufnr` (number): The buffer number.
+      - `line_num` (number): The line number (0-indexed).  Add 1 to get the line number in the buffer.
         </li>
         <li><span class="parameter">buftypes</span>
          (table|nil): Optional. A list of buffer types where colorizer should be enabled. Defaults to all buffer types if not provided.

lua/colorizer/buffer.lua

@@ -292,7 +292,7 @@ function M.parse_lines(bufnr, lines, line_start, ud_opts)
     line_nr = line_nr - 1 + line_start
     local i = 1
     while i < #line do
-      local length, rgb_hex = loop_parse_fn(line, i, bufnr)
+      local length, rgb_hex = loop_parse_fn(line, i, bufnr, line_nr)
       if length and not rgb_hex then
         utils.log_message(
           string.format(

lua/colorizer/config.lua

@@ -33,6 +33,9 @@ local plugin_user_default_options = {
   virtualtext_inline = false,
   virtualtext_mode = "foreground",
   always_update = false,
+  hooks = {
+    disable_line_highlight = false,
+  },
 }
 
 --[[-- Default user options for colorizer.
@@ -71,6 +74,8 @@ If both `css` and `css_fn` are true, `css_fn` has more priority over `css`.
 -- @field virtualtext_inline boolean|'before'|'after': Shows virtual text inline with color.
 -- @field virtualtext_mode 'background'|'foreground': Mode for virtual text display.
 -- @field always_update boolean: Always update color values, even if buffer is not focused.
+-- @field hooks table: Table of hook functions
+-- @field hooks.disable_line_highlight function: Returns boolean which controls if line should be parsed for highlights
 
 --- Options for colorizer that were passed in to setup function
 --@field filetypes
@@ -165,6 +170,11 @@ local function validate_options(ud_opts)
     }
     ud_opts.names_custom = false
   end
+  if ud_opts.hooks then
+    if type(ud_opts.hooks.disable_line_highlight) ~= "function" then
+      ud_opts.hooks.disable_line_highlight = false
+    end
+  end
 end
 
 --- Set options for a specific buffer or file type.
@@ -242,6 +252,11 @@ end
 --  - `virtualtext_inline` (boolean|'before'|'after'): Shows the virtual text inline with the color.  True defaults to 'before'.
 --  - `virtualtext_mode` ('background'|'foreground'): Determines the display mode for virtual text.
 --  - `always_update` (boolean): If true, updates color values even if the buffer is not focused.</pre>
+-- - `hooks` (table): Table of hook functions
+--    - `disable_line_highlight` (function): Returns a boolean that controls if the line should be parsed for highlights. Called  with 3 parameters:
+--      - `line` (string): The line's contents.
+--      - `bufnr` (number): The buffer number.
+--      - `line_num` (number): The line number (0-indexed).  Add 1 to get the line number in the buffer.
 -- @field buftypes (table|nil): Optional. A list of buffer types where colorizer should be enabled. Defaults to all buffer types if not provided.
 -- @field user_commands (boolean|table): If true, enables all user commands for colorizer. If `false`, disables user commands. Alternatively, provide a table of specific commands to enable:
 --   - `"ColorizerAttachToBuffer"`

lua/colorizer/matcher.lua

@@ -7,7 +7,6 @@ It uses a trie-based structure to optimize prefix-based parsing.
 local M = {}
 
 local Trie = require("colorizer.trie")
-local utils = require("colorizer.utils")
 local min, max = math.min, math.max
 
 local parsers = {
@@ -31,11 +30,21 @@ parsers.prefix = {
 ---Form a trie stuct with the given prefixes
 ---@param matchers table: List of prefixes, {"rgb", "hsl"}
 ---@param matchers_trie table: Table containing information regarding non-trie based parsers
+---@param hooks? table: Table of hook functions
+-- hooks.disable_line_highlight: function to be called after parsing the line
 ---@return function: function which will just parse the line for enabled parsers
-local function compile(matchers, matchers_trie)
+local function compile(matchers, matchers_trie, hooks)
   local trie = Trie(matchers_trie)
 
-  local function parse_fn(line, i, bufnr)
+  local function parse_fn(line, i, bufnr, line_nr)
+    if
+      hooks
+      and hooks.disable_line_highlight
+      and hooks.disable_line_highlight(line, line_nr, bufnr)
+    then
+      return
+    end
+
     -- prefix #
     if matchers.rgba_hex_parser then
       if line:byte(i) == ("#"):byte() then
@@ -199,7 +208,7 @@ function M.make(ud_opts)
     matchers[value] = { prefix = value }
   end
 
-  loop_parse_fn = compile(matchers, matchers_prefix)
+  loop_parse_fn = compile(matchers, matchers_prefix, ud_opts.hooks)
   matcher_cache[matcher_mask] = loop_parse_fn
 
   return loop_parse_fn