refactor!: pass context table to all user functions instead of parameters

## Details

This modifies every user accessible function to take a single context
table as input rather than a growing list of parameters. This makes
adding parameters to existing functions as well as using the functions
easier since you no longer need to pay attention to the order of
arguments but does unfortunately break existing users, hence the major
version version bump.

The fix to any errors is straightforward as the fields of the context
continue to have the same names. So if you have an existing function like:

```lua
function(param1, param2)
    vim.print(param1)
    vim.print(param2)
end
```

The fixed version would be:

```lua
function(ctx)
    vim.print(ctx.param1)
    vim.print(ctx.param2)
end
```

If you use the same parameters many times in the function and don't want
to add the `ctx.` prefix everywhere you can add a line at the top to
define local variables with the same name as before and keep the rest of
the function body unchanged:

```lua
function(ctx)
    local param1, param2 = ctx.param1, ctx.param2
    vim.print(param1)
    vim.print(param2)
end
```

The fields impacted are:

- The `parse` functions in `custom_handlers`:
  - `buf` -> `ctx.buf`
  - `root` -> `ctx.root`
- The callbacks in `on`: `on.attach` & `on.render`:
  - `buf` -> `ctx.buf`
- `bullet.icons` & `bullet.ordered_icons` if a non-default function was set:
  - `level` -> `ctx.level`
  - `index` -> `ctx.index`
  - `value` -> `ctx.value`
- `heading.icons` if a function was set:
  - `sections` -> `ctx.sections`

Author: MeanderingProgrammer

README.md

@@ -265,7 +265,7 @@ require('render-markdown').setup({
         -- Replaces '#+' of 'atx_h._marker'
         -- The number of '#' in the heading determines the 'level'
         -- The 'level' is used to index into the list using a cycle
-        -- If the value is a function the input is the nesting level of the heading within sections
+        -- If the value is a function the input context contains the nesting level of the heading within sections
         icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Determines how icons fill the available space:
         --  right:   '#'s are concealed and icon is appended to right side
@@ -427,20 +427,20 @@ require('render-markdown').setup({
         render_modes = false,
         -- Replaces '-'|'+'|'*' of 'list_item'
         -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-        -- If a function is provided both of these values are passed in using 1 based indexing
+        -- If a function is provided both of these values are provided in the context using 1 based indexing
         -- If a list is provided we index into it using a cycle based on the level
         -- If the value at that level is also a list we further index into it using a clamp based on the index
         -- If the item is a 'checkbox' a conceal is used to hide the bullet instead
         icons = { '●', '○', '◆', '◇' },
         -- Replaces 'n.'|'n)' of 'list_item'
         -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-        -- If a function is provided both of these values are passed in using 1 based indexing
+        -- If a function is provided both of these values are provided in the context using 1 based indexing
         -- If a list is provided we index into it using a cycle based on the level
         -- If the value at that level is also a list we further index into it using a clamp based on the index
-        ordered_icons = function(level, index, value)
-            value = vim.trim(value)
-            local value_index = tonumber(value:sub(1, #value - 1))
-            return string.format('%d.', value_index > 1 and value_index or index)
+        ordered_icons = function(ctx)
+            local value = vim.trim(ctx.value)
+            local index = tonumber(value:sub(1, #value - 1))
+            return string.format('%d.', index > 1 and index or ctx.index)
         end,
         -- Padding to add to the left of bullet point
         left_pad = 0,
@@ -746,7 +746,7 @@ require('render-markdown').setup({
         -- Replaces '#+' of 'atx_h._marker'
         -- The number of '#' in the heading determines the 'level'
         -- The 'level' is used to index into the list using a cycle
-        -- If the value is a function the input is the nesting level of the heading within sections
+        -- If the value is a function the input context contains the nesting level of the heading within sections
         icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
         -- Determines how icons fill the available space:
         --  right:   '#'s are concealed and icon is appended to right side
@@ -968,20 +968,20 @@ require('render-markdown').setup({
         render_modes = false,
         -- Replaces '-'|'+'|'*' of 'list_item'
         -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-        -- If a function is provided both of these values are passed in using 1 based indexing
+        -- If a function is provided both of these values are provided in the context using 1 based indexing
         -- If a list is provided we index into it using a cycle based on the level
         -- If the value at that level is also a list we further index into it using a clamp based on the index
         -- If the item is a 'checkbox' a conceal is used to hide the bullet instead
         icons = { '●', '○', '◆', '◇' },
         -- Replaces 'n.'|'n)' of 'list_item'
         -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-        -- If a function is provided both of these values are passed in using 1 based indexing
+        -- If a function is provided both of these values are provided in the context using 1 based indexing
         -- If a list is provided we index into it using a cycle based on the level
         -- If the value at that level is also a list we further index into it using a clamp based on the index
-        ordered_icons = function(level, index, value)
-            value = vim.trim(value)
-            local value_index = tonumber(value:sub(1, #value - 1))
-            return string.format('%d.', value_index > 1 and value_index or index)
+        ordered_icons = function(ctx)
+            local value = vim.trim(ctx.value)
+            local index = tonumber(value:sub(1, #value - 1))
+            return string.format('%d.', index > 1 and index or ctx.index)
         end,
         -- Padding to add to the left of bullet point
         left_pad = 0,

doc/custom-handlers.md

@@ -18,15 +18,19 @@ Each handler must conform to the following interface:
 ---@field public start_col integer
 ---@field public opts vim.api.keyset.set_extmark
 
+---@class (exact) render.md.HandlerContext
+---@field public buf integer
+---@field public root TSNode
+
 ---@class (exact) render.md.Handler
 ---@field public extends? boolean
----@field public parse fun(root: TSNode, buf: integer): render.md.Mark[]
+---@field public parse fun(ctx: render.md.HandlerContext): render.md.Mark[]
 ```
 
-The `parse` function parameters are:
+The `parse` function takes a `ctx` parameter whose fields are:
 
-- `root`: The root treesitter node for the specified language
 - `buf`: The buffer containing the root node
+- `root`: The root treesitter node for the specified language
 
 The `extends` parameter defines whether the builtin handler should still be run in
 conjunction with this one. Defaults to `false`.
@@ -71,9 +75,9 @@ This will require a treesitter query and using the range values of nodes.
 ```lua
 -- Parse query outside of the function to avoid doing it for each call
 local query = vim.treesitter.query.parse('python', '(function_definition) @def')
-local function parse_python(root, buf)
+local function parse_python(ctx)
     local marks = {}
-    for id, node in query:iter_captures(root, buf) do
+    for id, node in query:iter_captures(ctx.root, ctx.buf) do
         local capture = query.captures[id]
         local start_row, _, _, _ = node:range()
         if capture == 'def' then

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*         For 0.10.0         Last change: 2025 February 02
+*render-markdown.txt*         For 0.10.0         Last change: 2025 February 06
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -326,7 +326,7 @@ Default Configuration ~
             -- Replaces '#+' of 'atx_h._marker'
             -- The number of '#' in the heading determines the 'level'
             -- The 'level' is used to index into the list using a cycle
-            -- If the value is a function the input is the nesting level of the heading within sections
+            -- If the value is a function the input context contains the nesting level of the heading within sections
             icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
             -- Determines how icons fill the available space:
             --  right:   '#'s are concealed and icon is appended to right side
@@ -488,20 +488,20 @@ Default Configuration ~
             render_modes = false,
             -- Replaces '-'|'+'|'*' of 'list_item'
             -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-            -- If a function is provided both of these values are passed in using 1 based indexing
+            -- If a function is provided both of these values are provided in the context using 1 based indexing
             -- If a list is provided we index into it using a cycle based on the level
             -- If the value at that level is also a list we further index into it using a clamp based on the index
             -- If the item is a 'checkbox' a conceal is used to hide the bullet instead
             icons = { '●', '○', '◆', '◇' },
             -- Replaces 'n.'|'n)' of 'list_item'
             -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-            -- If a function is provided both of these values are passed in using 1 based indexing
+            -- If a function is provided both of these values are provided in the context using 1 based indexing
             -- If a list is provided we index into it using a cycle based on the level
             -- If the value at that level is also a list we further index into it using a clamp based on the index
-            ordered_icons = function(level, index, value)
-                value = vim.trim(value)
-                local value_index = tonumber(value:sub(1, #value - 1))
-                return string.format('%d.', value_index > 1 and value_index or index)
+            ordered_icons = function(ctx)
+                local value = vim.trim(ctx.value)
+                local index = tonumber(value:sub(1, #value - 1))
+                return string.format('%d.', index > 1 and index or ctx.index)
             end,
             -- Padding to add to the left of bullet point
             left_pad = 0,
@@ -805,7 +805,7 @@ Heading Configuration ~
             -- Replaces '#+' of 'atx_h._marker'
             -- The number of '#' in the heading determines the 'level'
             -- The 'level' is used to index into the list using a cycle
-            -- If the value is a function the input is the nesting level of the heading within sections
+            -- If the value is a function the input context contains the nesting level of the heading within sections
             icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
             -- Determines how icons fill the available space:
             --  right:   '#'s are concealed and icon is appended to right side
@@ -1019,20 +1019,20 @@ Bullet Point Configuration ~
             render_modes = false,
             -- Replaces '-'|'+'|'*' of 'list_item'
             -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-            -- If a function is provided both of these values are passed in using 1 based indexing
+            -- If a function is provided both of these values are provided in the context using 1 based indexing
             -- If a list is provided we index into it using a cycle based on the level
             -- If the value at that level is also a list we further index into it using a clamp based on the index
             -- If the item is a 'checkbox' a conceal is used to hide the bullet instead
             icons = { '●', '○', '◆', '◇' },
             -- Replaces 'n.'|'n)' of 'list_item'
             -- How deeply nested the list is determines the 'level', how far down at that level determines the 'index'
-            -- If a function is provided both of these values are passed in using 1 based indexing
+            -- If a function is provided both of these values are provided in the context using 1 based indexing
             -- If a list is provided we index into it using a cycle based on the level
             -- If the value at that level is also a list we further index into it using a clamp based on the index
-            ordered_icons = function(level, index, value)
-                value = vim.trim(value)
-                local value_index = tonumber(value:sub(1, #value - 1))
-                return string.format('%d.', value_index > 1 and value_index or index)
+            ordered_icons = function(ctx)
+                local value = vim.trim(ctx.value)
+                local index = tonumber(value:sub(1, #value - 1))
+                return string.format('%d.', index > 1 and index or ctx.index)
             end,
             -- Padding to add to the left of bullet point
             left_pad = 0,

lua/render-markdown/core/ui.lua

@@ -139,7 +139,7 @@ function M.run_update(buf, win, parse)
                 extmark:show(M.namespace, buf)
             end
         end
-        state.on.render(buf)
+        state.on.render({ buf = buf })
     else
         M.clear(buf, buffer_state)
     end
@@ -190,41 +190,40 @@ function M.parse_buffer(props)
         if language == 'markdown' then
             table.insert(markdown_roots, tree:root())
         else
-            vim.list_extend(marks, M.parse_tree(buf, language, tree:root()))
+            vim.list_extend(marks, M.parse_tree({ buf = buf, root = tree:root() }, language))
         end
     end)
     for _, root in ipairs(markdown_roots) do
-        vim.list_extend(marks, M.parse_tree(buf, 'markdown', root))
+        vim.list_extend(marks, M.parse_tree({ buf = buf, root = root }, 'markdown'))
     end
     return Iter.list.map(marks, Extmark.new)
 end
 
 ---Run user & builtin handlers when available. User handler is always executed,
 ---builtin handler is skipped if user handler does not specify extends.
 ---@private
----@param buf integer
+---@param ctx render.md.HandlerContext
 ---@param language string
----@param root TSNode
 ---@return render.md.Mark[]
-function M.parse_tree(buf, language, root)
-    log.buf('debug', 'language', buf, language)
-    if not Context.get(buf):overlaps_node(root) then
+function M.parse_tree(ctx, language)
+    log.buf('debug', 'language', ctx.buf, language)
+    if not Context.get(ctx.buf):overlaps_node(ctx.root) then
         return {}
     end
 
     local marks = {}
     local user = state.custom_handlers[language]
     if user ~= nil then
-        log.buf('debug', 'running handler', buf, 'user')
-        vim.list_extend(marks, user.parse(root, buf))
+        log.buf('debug', 'running handler', ctx.buf, 'user')
+        vim.list_extend(marks, user.parse(ctx))
         if not user.extends then
             return marks
         end
     end
     local builtin = builtin_handlers[language]
     if builtin ~= nil then
-        log.buf('debug', 'running handler', buf, 'builtin')
-        vim.list_extend(marks, builtin.parse(root, buf))
+        log.buf('debug', 'running handler', ctx.buf, 'builtin')
+        vim.list_extend(marks, builtin.parse(ctx))
     end
     return marks
 end

lua/render-markdown/handler/html.lua

@@ -46,11 +46,10 @@ end
 ---@class render.md.handler.Html: render.md.Handler
 local M = {}
 
----@param root TSNode
----@param buf integer
+---@param ctx render.md.HandlerContext
 ---@return render.md.Mark[]
-function M.parse(root, buf)
-    return Handler.new(buf):parse(root)
+function M.parse(ctx)
+    return Handler.new(ctx.buf):parse(ctx.root)
 end
 
 return M

lua/render-markdown/handler/latex.lua

@@ -12,20 +12,19 @@ local cache = {}
 ---@class render.md.handler.Latex: render.md.Handler
 local M = {}
 
----@param root TSNode
----@param buf integer
+---@param ctx render.md.HandlerContext
 ---@return render.md.Mark[]
-function M.parse(root, buf)
-    local latex = state.get(buf).latex
-    if Context.get(buf):skip(latex) then
+function M.parse(ctx)
+    local latex = state.get(ctx.buf).latex
+    if Context.get(ctx.buf):skip(latex) then
         return {}
     end
     if vim.fn.executable(latex.converter) ~= 1 then
         log.add('debug', 'executable not found', latex.converter)
         return {}
     end
 
-    local node = Node.new(buf, root)
+    local node = Node.new(ctx.buf, ctx.root)
     log.node('latex', node)
 
     local raw_expression = cache[node.text]
@@ -53,7 +52,7 @@ function M.parse(root, buf)
         return { { expression, latex.highlight } }
     end)
 
-    local marks = List.new_marks(buf, true)
+    local marks = List.new_marks(ctx.buf, true)
     marks:add_over(false, node, {
         virt_lines = latex_lines,
         virt_lines_above = true,

lua/render-markdown/handler/markdown.lua

@@ -82,11 +82,10 @@ end
 ---@class render.md.handler.Markdown: render.md.Handler
 local M = {}
 
----@param root TSNode
----@param buf integer
+---@param ctx render.md.HandlerContext
 ---@return render.md.Mark[]
-function M.parse(root, buf)
-    return Handler.new(buf):parse(root)
+function M.parse(ctx)
+    return Handler.new(ctx.buf):parse(ctx.root)
 end
 
 return M

lua/render-markdown/handler/markdown_inline.lua

@@ -64,11 +64,10 @@ end
 ---@class render.md.handler.MarkdownInline: render.md.Handler
 local M = {}
 
----@param root TSNode
----@param buf integer
+---@param ctx render.md.HandlerContext
 ---@return render.md.Mark[]
-function M.parse(root, buf)
-    return Handler.new(buf):parse(root)
+function M.parse(ctx)
+    return Handler.new(ctx.buf):parse(ctx.root)
 end
 
 return M

lua/render-markdown/health.lua

@@ -5,7 +5,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '7.9.0'
+M.version = '8.0.0'
 
 function M.check()
     M.start('version')