Feat: support lazyloading (#129)

* feat: add config option to support lazyloading

* doc: updates ldoc documentation

Author: catgoose

README.md

@@ -13,6 +13,7 @@
   - [Why another highlighter?](#why-another-highlighter)
   - [Customization](#customization)
     - [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)
   - [Testing](#testing)
   - [Extras](#extras)
@@ -113,11 +114,13 @@ library to do custom highlighting themselves.
 
 ```lua
   require("colorizer").setup({
+    -- Filetype options.  Accepts table like `user_default_options`
     filetypes = { "*" },
-    -- all the sub-options of filetypes apply to buftypes
+    -- Buftype options.  Accepts table like `user_default_options`
     buftypes = {},
     -- Boolean | List of usercommands to enable.  See User commands section.
     user_commands = true, -- Enable all or some usercommands
+    lazy_load = false, -- Lazily schedule buffer highlighting setup function
     user_default_options = {
       names = true, -- "Name" codes like Blue or red.  Added from `vim.api.nvim_get_color_map()`
       names_opts = { -- options for mutating/filtering names.
@@ -146,9 +149,10 @@ library to do custom highlighting themselves.
       -- Tailwind colors.  boolean|'normal'|'lsp'|'both'.  True is same as normal
       tailwind = false, -- Enable tailwind colors
       tailwind_opts = { -- Options for highlighting tailwind names
-        update_names = false, -- When using tailwind = 'both', update tailwind names from LSP results.  See tailwind section
+        update_names = false, -- When using tailwind = 'both', update tailwind
+        -- names from LSP results.  See tailwind section
       },
-      -- parsers can contain values used in |user_default_options|
+      -- parsers can contain values used in `user_default_options`
       sass = { enable = false, parsers = { "css" } }, -- Enable sass colors
       -- Virtualtext character to use
       virtualtext = "■",
@@ -329,6 +333,19 @@ For lower level interface, see
 [LuaDocs for API details](https://catgoose.github.io/nvim-colorizer.lua/modules/colorizer.html)
 or use `:h colorizer` once installed.
 
+### Lazyload Colorizer with Lazy.nvim
+
+```lua
+return {
+  "catgoose/nvim-colorizer.lua",
+  event = "VeryLazy",
+  opts = {
+    lazy_load = true,
+    -- other setup options
+  },
+}
+```
+
 ### Tailwind
 
 Tailwind colors can either be parsed from the Tailwind colors file (found in
@@ -357,7 +374,6 @@ This can be useful if you are highlighting `cmp_menu` filetype.
 ```
 
 ![tailwind.update_names](https://github.com/catgoose/screenshots/blob/51466fa599efe6d9821715616106c1712aad00c3/nvim-colorizer.lua/tailwind_update_names.png)
-
 To improve highlighting performance with the slow Tailwind LSP, results from LSP
 are cached and returned on `WinScrolled` event.
 

doc/colorizer.txt

@@ -575,6 +575,7 @@ options                                               *colorizer.config.options*
 	{filetypes} -
 	{buftypes} -
 	{user_commands} -
+	{lazy_load} -
 	{user_default_options} -
 	{exclusions} -
 	{all} -
@@ -630,15 +631,18 @@ opts                                                     *colorizer.config.opts*
    for virtual text.
    - `always_update` (boolean): If true, updates color values even if the buffer
      is not focused.
-	{buftypes} -  table|nil Optional. A list of buffer types where colorizer
-	should be enabled. Defaults to all buffer types if not provided.
-	{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:
+	{buftypes} -  (table|nil): Optional. A list of buffer types where
+	colorizer should be enabled. Defaults to all buffer types if not
+	provided.
+	{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"`
    - `"ColorizerDetachFromBuffer"`
    - `"ColorizerReloadAllBuffers"`
    - `"ColorizerToggle"`
+	{lazy_load} -  (boolean): If true, lazily schedule buffer highlighting
+	setup function
 
 
 

doc/modules/colorizer.config.html

@@ -374,6 +374,9 @@ <h3>Fields:</h3>
         </li>
         <li><span class="parameter">user_commands</span>
 
+        </li>
+        <li><span class="parameter">lazy_load</span>
+
         </li>
         <li><span class="parameter">user_default_options</span>
 
@@ -435,15 +438,18 @@ <h3>Fields:</h3>
    - `always_update` (boolean): If true, updates color values even if the buffer is not focused.
         </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.
+         (table|nil): Optional. A list of buffer types where colorizer should be enabled. Defaults to all buffer types if not provided.
         </li>
         <li><span class="parameter">user_commands</span>
-         boolean|table If true, enables all user commands for colorizer. If `false`, disables user commands. Alternatively, provide a table of specific commands to enable:
+         (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"`
    - `"ColorizerDetachFromBuffer"`
    - `"ColorizerReloadAllBuffers"`
    - `"ColorizerToggle"`
         </li>
+        <li><span class="parameter">lazy_load</span>
+         (boolean): If true, lazily schedule buffer highlighting setup function
+        </li>
     </ul>
 
 

lua/colorizer.lua

@@ -538,7 +538,13 @@ function M.setup(opts)
       group = colorizer_state.augroup,
       pattern = bo_type == "filetype" and (s.all[bo_type] and "*" or list) or nil,
       callback = function()
-        setup(bo_type)
+        if s.lazy_load then
+          vim.schedule(function()
+            setup(bo_type)
+          end)
+        else
+          setup(bo_type)
+        end
       end,
     })
   end

lua/colorizer/config.lua

@@ -73,6 +73,7 @@ local plugin_user_default_options = {
 --@field filetypes
 --@field buftypes
 --@field user_commands
+--@field lazy_load
 --@field user_default_options
 --@field exclusions
 --@field all
@@ -83,6 +84,7 @@ local function init_options()
     filetypes = { "*" },
     buftypes = {},
     user_commands = true,
+    lazy_load = false,
     user_default_options = plugin_user_default_options,
     -- shortcuts for filetype, buftype inclusion, exclusion settings
     exclusions = { buftype = {}, filetype = {} },
@@ -202,12 +204,13 @@ end
 --   - `virtualtext_inline` (boolean|'before'|'after'): Shows the virtual text inline with the color.  True defaults to 'before'.  False or nil disables.
 -- - `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.
--- @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:
+-- @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"`
 --   - `"ColorizerDetachFromBuffer"`
 --   - `"ColorizerReloadAllBuffers"`
 --   - `"ColorizerToggle"`
+-- @field lazy_load (boolean): If true, lazily schedule buffer highlighting setup function
 
 --- Initializes colorizer with user-provided options.
 -- Merges default settings with any user-specified options, setting up `filetypes`,