fix(hipatterns): mention explicitly how overlapping matching is handled

Resolve #2105

Author: echasnovski

doc/mini-hipatterns.txt

@@ -267,6 +267,13 @@ Each entry defines single highlighter as a table with the following fields:
   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:

lua/mini/hipatterns.lua

@@ -273,6 +273,13 @@ end
 ---   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:
@@ -938,7 +945,7 @@ H.apply_highlighter_pattern = vim.schedule_wrap(function(pattern, hi, buf_id, ns
       -- `init` is more than 1
       if pattern_has_line_start then break end
 
-      from, to, sub_from, sub_to = line:find(pattern, to + 1)
+      from, to, sub_from, sub_to = line:find(pattern, sub_to + 1)
     end
   end
 end)

tests/test_hipatterns.lua

@@ -472,7 +472,7 @@ T['Highlighters']['allows submatch in `pattern`'] = function()
   set_lines({ 'abcd', 'xabcd', 'xxabcd', 'xxabcdxx' })
 
   local validate = function(pattern)
-    child.lua([[require('mini.hipatterns').disable()]])
+    child.lua('require("mini.hipatterns").disable()')
     local config = {
       highlighters = { abcd = { pattern = pattern, group = 'Error' } },
       delay = test_config.delay,
@@ -495,6 +495,29 @@ T['Highlighters']['allows submatch in `pattern`'] = function()
   validate('xx()ab()c()d()')
 end
 
+T['Highlighters']['works with overlapping matches'] = function()
+  local validate = function(pattern, ref_ranges)
+    child.lua('require("mini.hipatterns").disable()')
+    local config = {
+      highlighters = { x = { pattern = pattern, group = 'Error' } },
+      delay = test_config.delay,
+    }
+    enable(0, config)
+
+    sleep(test_config.delay.text_change + small_time)
+    local ranges = vim.tbl_map(function(e) return { e.from_col, e.to_col } end, get_hipatterns_extmarks(0, { 'x' }))
+    eq(ranges, ref_ranges)
+  end
+
+  set_lines({ string.rep('x', 7) })
+
+  -- Should behave similarly to how `/` with `\zs` and `\ze` works
+  validate('xxx', { { 1, 3 }, { 4, 6 } })
+  validate('()xx()x', { { 1, 2 }, { 3, 4 }, { 5, 6 } })
+  validate('x()xx()', { { 2, 3 }, { 5, 6 } })
+  validate('x()x()x', { { 2, 2 }, { 4, 4 }, { 6, 6 } })
+end
+
 T['Highlighters']['allows frontier pattern in `pattern`'] = function()
   local config = {
     highlighters = { abcd = { pattern = '%f[%w]abcd%f[%W]', group = 'Error' } },