Add basic logging to file to improve debugging during development

Author: MeanderingProgrammer

README.md

@@ -85,6 +85,9 @@ require('render-markdown').setup({
     inline_query = [[
         (code_span) @code
     ]],
+    -- The level of logs to write to file: vim.fn.stdpath('state') .. '/render-markdown.log'
+    -- Only intended to be used for plugin development / debugging
+    log_level = 'error',
     -- Filetypes this plugin will run on
     file_types = { 'markdown' },
     -- Vim modes that will show a rendered view of the markdown file

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*           For 0.9.5           Last change: 2024 April 13
+*render-markdown.txt*            For 0.9.5            Last change: 2024 May 01
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -112,6 +112,9 @@ modified by the user.
         inline_query = [[
             (code_span) @code
         ]],
+        -- The level of logs to write to file: vim.fn.stdpath('state') .. '/render-markdown.log'
+        -- Only intended to be used for plugin development / debugging
+        log_level = 'error',
         -- Filetypes this plugin will run on
         file_types = { 'markdown' },
         -- Vim modes that will show a rendered view of the markdown file

lua/render-markdown/handler/latex.lua

@@ -1,3 +1,4 @@
+local logger = require('render-markdown.logger')
 local state = require('render-markdown.state')
 
 ---@class Cache
@@ -17,19 +18,21 @@ M.render = function(namespace, root)
         return
     end
 
-    local latex = vim.treesitter.get_node_text(root, 0)
-    local cached_expressions = cache.expressions[latex]
-    if cached_expressions == nil then
-        local raw_expression = vim.fn.system('latex2text', latex)
-        local expressions = vim.split(vim.trim(raw_expression), '\n', { plain = true })
-        cached_expressions = vim.tbl_map(vim.trim, expressions)
-        cache.expressions[latex] = cached_expressions
+    local value = vim.treesitter.get_node_text(root, 0)
+    local start_row, start_col, end_row, end_col = root:range()
+    logger.debug_node('latex', root)
+
+    local expressions = cache.expressions[value]
+    if expressions == nil then
+        local raw_expression = vim.fn.system('latex2text', value)
+        local parsed_expressions = vim.split(vim.trim(raw_expression), '\n', { plain = true })
+        expressions = vim.tbl_map(vim.trim, parsed_expressions)
+        cache.expressions[value] = expressions
     end
 
-    local start_row, start_col, end_row, end_col = root:range()
     local virt_lines = vim.tbl_map(function(expression)
         return { { expression, state.config.highlights.latex } }
-    end, cached_expressions)
+    end, expressions)
     vim.api.nvim_buf_set_extmark(0, namespace, start_row, start_col, {
         end_row = end_row,
         end_col = end_col,

lua/render-markdown/handler/markdown.lua

@@ -1,4 +1,5 @@
 local list = require('render-markdown.list')
+local logger = require('render-markdown.logger')
 local state = require('render-markdown.state')
 
 local M = {}
@@ -12,6 +13,7 @@ M.render = function(namespace, root)
         local capture = state.markdown_query.captures[id]
         local value = vim.treesitter.get_node_text(node, 0)
         local start_row, start_col, end_row, end_col = node:range()
+        logger.debug_node(capture, node)
 
         if capture == 'heading' then
             local level = #value
@@ -137,7 +139,7 @@ M.render = function(namespace, root)
             })
         else
             -- Should only get here if user provides custom capture, currently unhandled
-            vim.print('Unhandled markdown capture: ' .. capture)
+            logger.error('Unhandled markdown capture: ' .. capture)
         end
     end
 end

lua/render-markdown/handler/markdown_inline.lua

@@ -1,3 +1,4 @@
+local logger = require('render-markdown.logger')
 local state = require('render-markdown.state')
 
 local M = {}
@@ -10,6 +11,7 @@ M.render = function(namespace, root)
     for id, node in state.inline_query:iter_captures(root, 0) do
         local capture = state.inline_query.captures[id]
         local start_row, start_col, end_row, end_col = node:range()
+        logger.debug_node(capture, node)
 
         if capture == 'code' then
             vim.api.nvim_buf_set_extmark(0, namespace, start_row, start_col, {
@@ -19,7 +21,7 @@ M.render = function(namespace, root)
             })
         else
             -- Should only get here if user provides custom capture, currently unhandled
-            vim.print('Unhandled inline capture: ' .. capture)
+            logger.error('Unhandled inline capture: ' .. capture)
         end
     end
 end

lua/render-markdown/init.lua

@@ -36,6 +36,7 @@ local M = {}
 ---@class UserConfig
 ---@field public markdown_query? string
 ---@field public inline_query? string
+---@field public log_level? 'debug'|'error'
 ---@field public file_types? string[]
 ---@field public render_modes? string[]
 ---@field public headings? string[]
@@ -47,7 +48,7 @@ local M = {}
 ---@field public fat_tables? boolean
 ---@field public highlights? UserHighlights
 
----@param opts UserConfig|nil
+---@param opts? UserConfig
 function M.setup(opts)
     ---@type Config
     local default_config = {
@@ -85,6 +86,7 @@ function M.setup(opts)
         inline_query = [[
             (code_span) @code
         ]],
+        log_level = 'error',
         file_types = { 'markdown' },
         render_modes = { 'n', 'c' },
         headings = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },

lua/render-markdown/logger.lua

@@ -0,0 +1,86 @@
+local state = require('render-markdown.state')
+
+-- Typically resolves to ~/.local/state/nvim/render-markdown.log
+local log_file = vim.fn.stdpath('state') .. '/render-markdown.log'
+
+---@class LogEntry
+---@field date string
+---@field level string
+---@field message string
+
+---@class Log
+---@field entries LogEntry[]
+local log = {
+    entries = {},
+}
+
+log.reset = function()
+    log.entries = {}
+end
+
+---@param level string
+---@param message any
+log.add = function(level, message)
+    ---@type LogEntry
+    local entry = {
+        ---@diagnostic disable-next-line: assign-type-mismatch
+        date = os.date('%Y-%m-%d %H:%M:%S'),
+        level = string.upper(level),
+        message = vim.inspect(message),
+    }
+    table.insert(log.entries, entry)
+end
+
+log.flush = function()
+    if #log.entries == 0 then
+        return
+    end
+    local file = assert(io.open(log_file, 'w'))
+    for _, entry in ipairs(log.entries) do
+        local line = string.format('%s - %s - %s', entry.date, entry.level, entry.message)
+        file:write(line .. '\n')
+    end
+    file:close()
+    log.reset()
+end
+
+local M = {}
+
+M.start = function()
+    log.reset()
+end
+
+---@param message any
+M.debug = function(message)
+    if vim.tbl_contains({ 'debug' }, state.config.log_level) then
+        log.add('debug', message)
+    end
+end
+
+---@param capture string
+---@param node TSNode
+M.debug_node = function(capture, node)
+    if vim.tbl_contains({ 'debug' }, state.config.log_level) then
+        local value = vim.treesitter.get_node_text(node, 0)
+        local start_row, start_col, end_row, end_col = node:range()
+        log.add('debug', {
+            capture = capture,
+            value = value,
+            rows = { start_row, end_row },
+            cols = { start_col, end_col },
+        })
+    end
+end
+
+---@param message any
+M.error = function(message)
+    if vim.tbl_contains({ 'debug', 'error' }, state.config.log_level) then
+        log.add('error', message)
+    end
+end
+
+M.flush = function()
+    log.flush()
+end
+
+return M

lua/render-markdown/state.lua

@@ -31,6 +31,7 @@
 ---@class Config
 ---@field public markdown_query string
 ---@field public inline_query string
+---@field public log_level 'debug'|'error'
 ---@field public file_types string[]
 ---@field public render_modes string[]
 ---@field public headings string[]

lua/render-markdown/ui.lua

@@ -1,4 +1,5 @@
 local latex = require('render-markdown.handler.latex')
+local logger = require('render-markdown.logger')
 local markdown = require('render-markdown.handler.markdown')
 local markdown_inline = require('render-markdown.handler.markdown_inline')
 local state = require('render-markdown.state')
@@ -26,17 +27,22 @@ M.refresh = function()
         return
     end
 
+    logger.start()
     vim.opt_local.conceallevel = state.config.conceal.rendered
     vim.treesitter.get_parser():for_each_tree(function(tree, language_tree)
         local language = language_tree:lang()
+        logger.debug({ language = language })
         if language == 'markdown' then
             markdown.render(M.namespace, tree:root())
         elseif language == 'markdown_inline' then
             markdown_inline.render(M.namespace, tree:root())
         elseif language == 'latex' then
             latex.render(M.namespace, tree:root())
+        else
+            logger.debug('No handler found')
         end
     end)
+    logger.flush()
 end
 
 return M