retrovim 0.0.3

package/nvim/plugins/mini.nvim/doc/mini-hipatterns.txt

@@ -0,0 +1,489 @@
+*mini.hipatterns* Highlight patterns in text
+
+MIT License Copyright (c) 2023 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                *MiniHipatterns*
+Features:
+- Highlight text with configurable patterns and highlight groups (can be
+  string or callable).
+
+- Highlighting is updated asynchronously with configurable debounce delay.
+
+- Function to get matches in a buffer (see |MiniHipatterns.get_matches()|).
+
+See |MiniHipatterns-examples| for common configuration examples.
+
+Notes:
+- It does not define any highlighters by default. Add to `config.highlighters`
+  to have a visible effect.
+
+- Sometimes (especially during frequent buffer updates on same line numbers)
+  highlighting can be outdated or not applied when it should be. This is due
+  to asynchronous nature of updates reacting to text changes (via
+  `on_lines` of |nvim_buf_attach()|).
+  To make them up to date, use one of the following:
+    - Scroll window (for example, with |CTRL-E| / |CTRL-Y|). This will ensure
+      up to date highlighting inside window view.
+    - Hide and show buffer.
+    - Execute `:edit` (if you enabled highlighting with |MiniHipatterns.setup()|).
+    - Manually call |MiniHipatterns.update()|.
+
+- If you experience flicker when typing near highlighted pattern in Insert
+  mode, it might be due to `delay` configuration of |mini.completion| or
+  using built-in completion.
+  For better experience with |mini.completion|, make sure that its
+  `delay.completion` is less than this module's `delay.text_change` (which
+  it is by default).
+  The reason for this is (currently unresolvable) limitations of Neovim's
+  built-in completion implementation.
+
+# Setup ~
+
+Setting up highlights can be done in two ways:
+- Manually for every buffer with `require('mini.hipatterns').enable()`.
+  This will enable highlighting only in one particular buffer until it is
+  unloaded (which also includes calling `:edit` on current file).
+
+- Globally with `require('mini.hipatterns').setup({})` (replace `{}` with
+  your `config` table). This will auto-enable highlighting in "normal"
+  buffers (see |'buftype'|). Use |MiniHipatterns.enable()| to manually enable
+  in other buffers.
+  It will also create global Lua table `MiniHipatterns` which you can use
+  for scripting or manually (with `:lua MiniHipatterns.*`).
+
+See |MiniHipatterns.config| for `config` structure and default values.
+
+You can override runtime config settings (like highlighters and delays)
+locally to buffer inside `vim.b.minihipatterns_config` which should have
+same structure as `MiniHipatterns.config`.
+See |mini.nvim-buffer-local-config| for more details.
+
+# Comparisons ~
+
+- [folke/todo-comments](https://github.com/folke/todo-comments):
+    - Oriented for "TODO", "NOTE", "FIXME" like patterns, while this module
+      can work with any Lua patterns and computable highlight groups.
+    - Has functionality beyond text highlighting (sign placing,
+      "telescope.nvim" extension, etc.), while this module only focuses on
+      highlighting text.
+- [folke/paint.nvim](https://github.com/folke/paint.nvim):
+    - Mostly similar to this module, but with slightly less functionality,
+      such as computed pattern and highlight group, asynchronous delay, etc.
+- [NvChad/nvim-colorizer.lua](https://github.com/NvChad/nvim-colorizer.lua):
+    - Oriented for color highlighting, while this module can work with any
+      Lua patterns and computable highlight groups.
+    - Has more built-in color spaces to highlight, while this module out of
+      the box provides only hex color highlighting
+      (see |MiniHipatterns.gen_highlighter.hex_color()|). Other types are
+      also possible to implement.
+- [uga-rosa/ccc.nvim](https://github.com/uga-rosa/ccc.nvim):
+    - Has more than color highlighting functionality, which is compared to
+      this module in the same way as `NvChad/nvim-colorizer.lua`.
+
+# Highlight groups ~
+*MiniHipatterns-hl-groups*
+
+- `MiniHipatternsFixme` - suggested group to use for `FIXME`-like patterns.
+- `MiniHipatternsHack` - suggested group to use for `HACK`-like patterns.
+- `MiniHipatternsTodo` - suggested group to use for `TODO`-like patterns.
+- `MiniHipatternsNote` - suggested group to use for `NOTE`-like patterns.
+
+To change any highlight group, set it directly with |nvim_set_hl()|.
+
+# Disabling ~
+
+This module can be disabled in three ways:
+- Globally: set `vim.g.minihipatterns_disable` to `true`.
+- Locally for buffer permanently: set `vim.b.minihipatterns_disable` to `true`.
+- Locally for buffer temporarily (until next auto-enabling event if set up
+  with |MiniHipatterns.setup()|): call |MiniHipatterns.disable()|.
+
+Considering high number of different scenarios and customization
+intentions, writing exact rules for disabling module's functionality is
+left to user. See |mini.nvim-disabling-recipes| for common recipes.
+
+------------------------------------------------------------------------------
+                                                       *MiniHipatterns-examples*
+# Common configuration examples ~
+
+- Special words used to convey different level of attention: >lua
+
+  require('mini.hipatterns').setup({
+    highlighters = {
+      fixme = { pattern = 'FIXME', group = 'MiniHipatternsFixme' },
+      hack  = { pattern = 'HACK',  group = 'MiniHipatternsHack'  },
+      todo  = { pattern = 'TODO',  group = 'MiniHipatternsTodo'  },
+      note  = { pattern = 'NOTE',  group = 'MiniHipatternsNote'  },
+    }
+  })
+<
+- To match only when pattern appears as a standalone word, use frontier
+  patterns `%f`. For example, instead of `'TODO'` pattern use
+  `'%f[%w]()TODO()%f[%W]'`. In this case, for example, `TODOING` or `MYTODO`
+  won't match, but `TODO` and `TODO:` will.
+
+- Color hex (like `#rrggbb`) highlighting: >lua
+
+  local hipatterns = require('mini.hipatterns')
+  hipatterns.setup({
+    highlighters = {
+      hex_color = hipatterns.gen_highlighter.hex_color(),
+    }
+  })
+<
+  You can customize which part of hex color is highlighted by using `style`
+  field of input options. See |MiniHipatterns.gen_highlighter.hex_color()|.
+
+- Colored words: >lua
+
+  local words = { red = '#ff0000', green = '#00ff00', blue = '#0000ff' }
+  local word_color_group = function(_, match)
+    local hex = words[match]
+    if hex == nil then return nil end
+    return MiniHipatterns.compute_hex_color_group(hex, 'bg')
+  end
+
+  local hipatterns = require('mini.hipatterns')
+  hipatterns.setup({
+    highlighters = {
+      word_color = { pattern = '%S+', group = word_color_group },
+    },
+  })
+<
+- Trailing whitespace (if don't want to use more specific |mini.trailspace|): >lua
+
+  { pattern = '%f[%s]%s*$', group = 'Error' }
+<
+- Censor certain sensitive information: >lua
+
+  local censor_extmark_opts = function(_, match, _)
+    local mask = string.rep('x', vim.fn.strchars(match))
+    return {
+      virt_text = { { mask, 'Comment' } }, virt_text_pos = 'overlay',
+      priority = 200, right_gravity = false,
+    }
+  end
+
+  require('mini.hipatterns').setup({
+    highlighters = {
+      censor = {
+        pattern = 'password: ()%S+()',
+        group = '',
+        extmark_opts = censor_extmark_opts,
+      },
+    },
+  })
+<
+- Enable only in certain filetypes. There are at least these ways to do it:
+    - (Suggested) With `vim.b.minihipatterns_config` in |filetype-plugin|.
+      Basically, create "after/ftplugin/<filetype>.lua" file in your config
+      directory (see |$XDG_CONFIG_HOME|) and define `vim.b.minihipatterns_config`
+      there with filetype specific highlighters.
+
+      This assumes `require('mini.hipatterns').setup()` call.
+
+      For example, to highlight keywords in EmmyLua comments in Lua files,
+      create "after/ftplugin/lua.lua" with the following content: >lua
+
+        vim.b.minihipatterns_config = {
+          highlighters = {
+            emmylua = { pattern = '^%s*%-%-%-()@%w+()', group = 'Special' }
+          }
+        }
+<
+    - Use callable `pattern` with condition. For example: >lua
+
+      require('mini.hipatterns').setup({
+        highlighters = {
+          emmylua = {
+            pattern = function(buf_id)
+              if vim.bo[buf_id].filetype ~= 'lua' then return nil end
+              return '^%s*%-%-%-()@%w+()'
+            end,
+            group = 'Special',
+          },
+        },
+      })
+<
+- Disable only in certain filetypes. Enable with |MiniHipatterns.setup()|
+  and set `vim.b.minihipatterns_disable` buffer-local variable to `true` for
+  buffer you want disabled. See |mini.nvim-disabling-recipes| for more examples.
+
+------------------------------------------------------------------------------
+                                                        *MiniHipatterns.setup()*
+                        `MiniHipatterns.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniHipatterns.config|.
+
+Usage ~
+>lua
+  require('mini.hipatterns').setup({}) -- replace {} with your config table
+                                       -- needs `highlighters` field present
+<
+------------------------------------------------------------------------------
+                                                         *MiniHipatterns.config*
+                            `MiniHipatterns.config`
+Defaults ~
+>lua
+  MiniHipatterns.config = {
+    -- Table with highlighters (see |MiniHipatterns.config| for more details).
+    -- Nothing is defined by default. Add manually for visible effect.
+    highlighters = {},
+
+    -- Delays (in ms) defining asynchronous highlighting process
+    delay = {
+      -- How much to wait for update after every text change
+      text_change = 200,
+
+      -- How much to wait for update after window scroll
+      scroll = 50,
+    },
+  }
+<
+# Highlighters ~
+
+`highlighters` table defines which patterns will be highlighted by placing
+|extmark| at the match start. It might or might not have explicitly named
+fields, but having them is recommended and is required for proper use of
+`vim.b.minihipatterns_config` as buffer-local config. By default it is
+empty expecting user definition.
+
+Each entry defines single highlighter as a table with the following fields:
+- <pattern> `(string|function|table)` - Lua pattern to highlight. Can be
+  either string, callable returning the string, or an array of those.
+  If string:
+    - It can have submatch delimited by placing `()` on start and end, NOT
+      by surrounding it with parenthesis (results in an error containing
+      `number expected, got string`). Example: `xx()abcd()xx` will match
+      `abcd` only if `xx` is placed before and after it.
+
+  If callable:
+    - It will be called for every enabled buffer with its identifier as input.
+      Should return single string pattern or `nil` (meaning this particular
+      highlighter will not work in this particular buffer).
+
+  If array:
+    - Each element is matched and highlighted with the same highlight group.
+
+    Note: matching does not result in overlapping (sub)matches (similarly
+    to how |cpo-c| works). For example, with line `xxxxxxx`:
+    - Pattern `xxx` matches columns 1-3, 4-6.
+    - Pattern `()xx()x` matches columns 1-2, 3-4, 5-6.
+    - Pattern `x()xx()` matches columns 2-3, 5-6.
+    - Pattern `x()x()x` matches columns 2-2, 4-4, 6-6.
+
+- <group> `(string|function)` - name of highlight group to use. Can be either
+  string or callable returning the string.
+  If callable:
+    - It will be called for every pattern match with the following arguments:
+        - `buf_id` - buffer identifier.
+        - `match` - string pattern match to be highlighted.
+        - `data` - extra table with information about the match.
+          It has at least these fields:
+            - <full_match> - string with full pattern match.
+            - <line> - match line number (1-indexed).
+            - <from_col> - match starting byte column (1-indexed).
+            - <to_col> - match ending byte column (1-indexed, inclusive).
+
+    - It can return `nil` meaning this particular match will not be highlighted.
+
+- <extmark_opts> `(table|function|nil)` - optional extra options
+  for |nvim_buf_set_extmark()|. If callable, will be called in the same way
+  as callable <group> (`data` will also contain `hl_group` key with <group>
+  value) and should return a table with all options for extmark (including
+  `end_row`, `end_col`, `hl_group`, and `priority`).
+
+See "Common use cases" section for the examples.
+
+# Delay ~
+
+`delay` is a table defining delays in milliseconds used for asynchronous
+highlighting process.
+
+`delay.text_change` is used to delay highlighting updates by accumulating
+them (in debounce fashion). Smaller values will lead to faster response but
+more frequent updates. Bigger - slower response but less frequent updates.
+
+`delay.scroll` is used to delay updating highlights in current window view
+during scrolling (see |WinScrolled| event). These updates are present to
+ensure up to date highlighting after scroll.
+
+------------------------------------------------------------------------------
+                                                       *MiniHipatterns.enable()*
+                  `MiniHipatterns.enable`({buf_id}, {config})
+Enable highlighting in buffer
+
+Notes:
+- With default config it will highlight nothing, as there are no default
+  highlighters.
+
+- Buffer highlighting is enabled until buffer is unloaded from memory
+  or |MiniHipatterns.disable()| on this buffer is called.
+
+- `:edit` disables this, as it is mostly equivalent to closing and opening
+  buffer. In order for highlighting to persist after `:edit`, call
+  |MiniHipatterns.setup()|.
+
+Parameters ~
+{buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
+  Default: 0 for current buffer.
+{config} `(table|nil)` Optional buffer-local config. Should have the same
+  structure as |MiniHipatterns.config|. Values will be taken in this order:
+  - From this `config` argument (if supplied).
+  - From buffer-local config in `vim.b.minihipatterns_config` (if present).
+  - From global config (if |MiniHipatterns.setup()| was called).
+  - From default values.
+
+------------------------------------------------------------------------------
+                                                      *MiniHipatterns.disable()*
+                       `MiniHipatterns.disable`({buf_id})
+Disable highlighting in buffer
+
+Note that if |MiniHipatterns.setup()| was called, the effect is present
+until the next auto-enabling event. To permanently disable highlighting in
+buffer, set `vim.b.minihipatterns_disable` to `true`
+
+Parameters ~
+{buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
+  Default: 0 for current buffer.
+
+------------------------------------------------------------------------------
+                                                       *MiniHipatterns.toggle()*
+                  `MiniHipatterns.toggle`({buf_id}, {config})
+Toggle highlighting in buffer
+
+Call |MiniHipatterns.disable()| if enabled; |MiniHipatterns.enable()| otherwise.
+
+Parameters ~
+{buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
+  Default: 0 for current buffer.
+{config} `(table|nil)` Forwarded to |MiniHipatterns.enable()|.
+
+------------------------------------------------------------------------------
+                                                       *MiniHipatterns.update()*
+           `MiniHipatterns.update`({buf_id}, {from_line}, {to_line})
+Update highlighting in range
+
+Works only in buffer with enabled highlighting. Effect takes immediately
+without delay.
+
+Parameters ~
+{buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
+  Default: 0 for current buffer.
+{from_line} `(number|nil)` Start line from which to update (1-indexed).
+{to_line} `(number|nil)` End line from which to update (1-indexed, inclusive).
+
+------------------------------------------------------------------------------
+                                          *MiniHipatterns.get_enabled_buffers()*
+                     `MiniHipatterns.get_enabled_buffers`()
+Get an array of enabled buffers
+
+Return ~
+`(table)` Array of buffer identifiers with enabled highlighting.
+
+------------------------------------------------------------------------------
+                                                  *MiniHipatterns.get_matches()*
+             `MiniHipatterns.get_matches`({buf_id}, {highlighters})
+Get buffer matches
+
+Parameters ~
+{buf_id} `(number|nil)` Buffer identifier for which to return matches.
+  Default: `nil` for current buffer.
+{highlighters} `(table|nil)` Array of highlighter identifiers (as in
+  `highlighters` field of |MiniHipatterns.config|) for which to return matches.
+  Default: all available highlighters (ordered by string representation).
+
+Return ~
+`(table)` Array of buffer matches which are tables with following fields:
+  - <bufnr> `(number)` - buffer identifier of a match.
+  - <highlighter> `(any)` - highlighter identifier which produced the match.
+  - <lnum> `(number)` - line number of the match start (starts with 1).
+  - <col> `(number)` - column number of the match start (starts with 1).
+  - <end_lnum> `(number|nil)` - line number of the match end (starts with 1).
+  - <end_col> `(number|nil)` - column number next to the match end
+    (implements end-exclusive region; starts with 1).
+  - <hl_group> `(string|nil)` - name of match's highlight group.
+
+  Matches are ordered first by supplied `highlighters`, then by line and
+  column of match start.
+
+------------------------------------------------------------------------------
+                                                *MiniHipatterns.gen_highlighter*
+                        `MiniHipatterns.gen_highlighter`
+Generate builtin highlighters
+
+This is a table with function elements. Call to actually get highlighter.
+
+------------------------------------------------------------------------------
+                                    *MiniHipatterns.gen_highlighter.hex_color()*
+               `MiniHipatterns.gen_highlighter.hex_color`({opts})
+Highlight hex color string
+
+This will match color hex string in format `#rrggbb` and highlight it
+according to `opts.style` displaying matched color.
+
+Highlight group is computed using |MiniHipatterns.compute_hex_color_group()|,
+so all its usage notes apply here.
+
+Parameters ~
+{opts} `(table|nil)` Options. Possible fields:
+  - <style> `(string)` - one of:
+      - `'full'` -  highlight background of whole hex string with it. Default.
+      - `'#'` - highlight background of only `#`.
+      - `'line'` - highlight underline with that color.
+      - `'inline'` - highlight text of <inline_text>.
+        Note: requires Neovim>=0.10.
+  - <priority> `(number)` - priority of highlighting. Default: 200.
+  - <filter> `(function)` - callable object used to filter buffers in which
+    highlighting will take place. It should take buffer identifier as input
+    and return `false` or `nil` to not highlight inside this buffer.
+  - <inline_text> `(string)` - string to be placed and highlighted with color
+    to the right of match in case <style> is "inline". Default: "█".
+  - <max_number> `(number)` - as in |MiniHipatterns.compute_hex_color_group()|.
+
+Return ~
+`(table)` Highlighter table ready to be used as part of `config.highlighters`.
+  Both `pattern` and `group` are callable.
+
+Usage ~
+>lua
+  local hipatterns = require('mini.hipatterns')
+  hipatterns.setup({
+    highlighters = {
+      hex_color = hipatterns.gen_highlighter.hex_color(),
+    }
+  })
+<
+------------------------------------------------------------------------------
+                                      *MiniHipatterns.compute_hex_color_group()*
+     `MiniHipatterns.compute_hex_color_group`({hex_color}, {style}, {opts})
+Compute and create group to highlight hex color string
+
+Notes:
+- This works properly only with enabled |'termguicolors'|.
+
+- To increase performance, it caches highlight groups per `hex_color` and
+  `style` combination. Needs a call to |MiniHipatterns.setup()| to have
+  these groups be persistent across color scheme changes.
+
+Parameters ~
+{hex_color} `(string)` Hex color string in format `#rrggbb`.
+{style|nil} `(string)` One of:
+  - `'bg'` - highlight background with `hex_color` and foreground with black or
+    white (whichever is more visible). Default.
+  - `'fg'` - highlight foreground with `hex_color`.
+  - `'line'` - highlight underline with `hex_color`.
+{opts} `(table|nil)` Options. Possible fields:
+  - <max_number> `(number)` - maximum number of different highlight groups
+    this function is allowed to create. Useful to avoid |E849|.
+    Default: 10000.
+
+Return ~
+`(string|nil)` Name of created highlight group appropriate to show `hex_color`
+  or `nil` if highlighted groups was not created.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: