feat!: event API

README.md

@@ -61,8 +61,7 @@ vim.g.guard_config = {
 ```
 
 - Use `Guard fmt` to manually call format, when there is a visual selection only the selection is formatted. **NOTE**: Regional formatting just sends your selection to the formatter, if there's not enough context incoherent formatting might occur (e.g. indent being erased)
-- `Guard disable` disables auto format for the current buffer, you can also `Guard disable 16` (the buffer number)
-- Use `Guard enable` to re-enable auto format, usage is the same as `Guard disable`
+- `enable-fmt`, `disable-fmt` turns auto formatting on and off for the current buffer.
 
 Format c files with clang-format and lint with clang-tidy:
 
@@ -92,6 +91,9 @@ Lint all your files with `codespell`
 ft('*'):lint('codespell')
 ```
 
+- Use `Guard Lint` to lint manually.
+- `enable-lint` and `disable-lint` controls auto linting for the current buffer.
+
 You can also easily create your own configuration that's not in `guard-collection`, see [CUSTOMIZE.md](./CUSTOMIZE.md).
 
 For more niche use cases, [ADVANCED.md](./ADVANCED.md) demonstrates how to:

doc/guard.nvim.txt

@@ -1,4 +1,4 @@
-*guard.nvim.txt*         For NVIM v0.8.0         Last change: 2024 December 09
+*guard.nvim.txt*         For NVIM v0.8.0         Last change: 2024 December 10
 
 ==============================================================================
 Table of Contents                               *guard.nvim-table-of-contents*
@@ -80,8 +80,7 @@ To register formatters and linters:
 <
 
 - Use `Guard fmt` to manually call format, when there is a visual selection only the selection is formatted. **NOTE**: Regional formatting just sends your selection to the formatter, if there’s not enough context incoherent formatting might occur (e.g. indent being erased)
-- `Guard disable` disables auto format for the current buffer, you can also `Guard disable 16` (the buffer number)
-- Use `Guard enable` to re-enable auto format, usage is the same as `Guard disable`
+- `enable-fmt`, `disable-fmt` turns auto formatting on and off for the current buffer.
 
 Format c files with clang-format and lint with clang-tidy:
 
@@ -112,6 +111,9 @@ Lint all your files with `codespell`
     ft('*'):lint('codespell')
 <
 
+- Use `Guard Lint` to lint manually.
+- `enable-lint` and `disable-lint` controls auto linting for the current buffer.
+
 You can also easily create your own configuration that’s not in
 `guard-collection`, see CUSTOMIZE.md <./CUSTOMIZE.md>.
 

lua/guard/api.lua

@@ -0,0 +1,114 @@
+-- These are considered public API and changing their signature would be a breaking change
+local M = {}
+local api = vim.api
+local events = require('guard.events')
+
+---Format bufnr or current buffer
+---@param bufnr number?
+function M.fmt(bufnr)
+  require('guard.format').do_fmt(bufnr)
+end
+
+---Lint bufnr or current buffer
+---@param bufnr number?
+function M.lint(bufnr)
+  require('guard.lint').do_lint(bufnr)
+end
+
+---Enable format for bufnr or current buffer
+---@param bufnr number?
+function M.enable_fmt(bufnr)
+  require('guard.events').try_attach_fmt_to_buf(bufnr or api.nvim_get_current_buf())
+end
+
+---Disable format for bufnr or current buffer
+---@param bufnr number?
+function M.disable_fmt(bufnr)
+  local aus = events.get_format_autocmds(bufnr or api.nvim_get_current_buf())
+  vim.iter(aus):each(function(au)
+    api.nvim_del_autocmd(au.id)
+  end)
+end
+
+---Enable lint for bufnr or current buffer
+---@param bufnr number?
+function M.enable_lint(bufnr)
+  local buf = bufnr or api.nvim_get_current_buf()
+  local ft = require('guard.filetype')[vim.bo[buf].ft] or {}
+  if ft.linter and #ft.linter > 0 then
+    events.try_attach_lint_to_buf(buf, require('guard.util').linter_events(ft.linter[1]))
+  end
+end
+
+---Disable format for bufnr or current buffer
+---@param bufnr number?
+function M.disable_lint(bufnr)
+  local aus = events.get_lint_autocmds(bufnr or api.nvim_get_current_buf())
+  vim.iter(aus):each(function(au)
+    api.nvim_del_autocmd(au.id)
+  end)
+end
+
+---Show guard info for current buffer
+function M.info()
+  local util = require('guard.util')
+  local buf = api.nvim_get_current_buf()
+  local ft = require('guard.filetype')[vim.bo[buf].ft] or {}
+  local formatters = ft.formatter or {}
+  local linters = ft.linter or {}
+  local fmtau = events.get_format_autocmds(buf)
+  local lintau = events.get_lint_autocmds(buf)
+
+  util.open_info_win()
+  local lines = {
+    '# Guard info (press Esc or q to close)',
+    '## Settings:',
+    ('- `fmt_on_save`: %s'):format(util.getopt('fmt_on_save')),
+    ('- `lsp_as_default_formatter`: %s'):format(util.getopt('lsp_as_default_formatter')),
+    ('- `save_on_fmt`: %s'):format(util.getopt('save_on_fmt')),
+    '',
+    ('## Current buffer has filetype %s:'):format(vim.bo[buf].ft),
+    ('- %s formatter autocmds attached'):format(#fmtau),
+    ('- %s linter autocmds attached'):format(#lintau),
+    '- formatters:',
+    '',
+    '```lua',
+  }
+
+  vim.list_extend(
+    lines,
+    vim
+      .iter(formatters)
+      :map(function(formatter)
+        return vim.split(vim.inspect(formatter), '\n', { trimempty = true })
+      end)
+      :flatten()
+      :totable()
+  )
+
+  vim.list_extend(lines, {
+    '```',
+    '',
+    '- linters:',
+    '',
+    '```lua',
+  })
+
+  vim.list_extend(
+    lines,
+    vim
+      .iter(linters)
+      :map(function(linter)
+        return vim.split(vim.inspect(linter), '\n', { trimempty = true })
+      end)
+      :flatten()
+      :totable()
+  )
+
+  vim.list_extend(lines, { '```' })
+
+  api.nvim_buf_set_lines(0, 0, -1, true, lines)
+  api.nvim_set_option_value('modifiable', false, { buf = 0 })
+end
+
+return M

lua/guard/events.lua

@@ -7,8 +7,71 @@ local iter = vim.iter
 local M = {}
 M.group = api.nvim_create_augroup('Guard', { clear = true })
 
-function M.try_attach_to_buf(buf)
-  if not util.check_should_attach(buf) then
+local debounce_timer = nil
+local debounced_lint = function(opt)
+  if debounce_timer then
+    debounce_timer:stop()
+    debounce_timer = nil
+  end
+  ---@diagnostic disable-next-line: undefined-field
+  debounce_timer = assert(uv.new_timer()) --[[uv_timer_t]]
+  debounce_timer:start(500, 0, function()
+    debounce_timer:stop()
+    debounce_timer:close()
+    debounce_timer = nil
+    vim.schedule(function()
+      require('guard.lint').do_lint(opt.buf)
+    end)
+  end)
+end
+
+---@param bufnr number
+---@return vim.api.keyset.get_autocmds.ret[]
+function M.get_format_autocmds(bufnr)
+  if not api.nvim_buf_is_valid(bufnr) then
+    return {}
+  end
+  return api.nvim_get_autocmds({ group = M.group, event = 'BufWritePre', buffer = bufnr })
+end
+
+---@param bufnr number
+---@return vim.api.keyset.get_autocmds.ret[]
+function M.get_lint_autocmds(bufnr)
+  if not api.nvim_buf_is_valid(bufnr) then
+    return {}
+  end
+  local aus = api.nvim_get_autocmds({
+    group = M.group,
+    event = { 'BufWritePost', 'BufEnter', 'TextChanged', 'InsertLeave' },
+    buffer = bufnr,
+  })
+  return vim.list_extend(
+    aus,
+    api.nvim_get_autocmds({
+      group = M.group,
+      event = 'User',
+      pattern = 'GuardFmt',
+      buffer = bufnr,
+    })
+  )
+end
+
+---@param buf number
+---@return boolean
+function M.check_fmt_should_attach(buf)
+  -- check if it's not attached already and has an underlying file
+  return #M.get_format_autocmds(buf) == 0 and vim.bo[buf].buftype ~= 'nofile'
+end
+
+---@param buf number
+---@return boolean
+function M.check_lint_should_attach(buf)
+  return #M.get_lint_autocmds(buf) == 0 and vim.bo[buf].buftype ~= 'nofile'
+end
+
+---@param buf number
+function M.try_attach_fmt_to_buf(buf)
+  if not M.check_fmt_should_attach(buf) then
     return
   end
   au('BufWritePre', {
@@ -22,18 +85,46 @@ function M.try_attach_to_buf(buf)
   })
 end
 
+---@param buf number
+---@param events string[]
+function M.try_attach_lint_to_buf(buf, events)
+  if not M.check_lint_should_attach(buf) then
+    return
+  end
+
+  for _, ev in ipairs(events) do
+    if ev == 'User GuardFmt' then
+      au('User', {
+        group = M.group,
+        pattern = 'GuardFmt',
+        callback = function(opt)
+          if opt.data.status == 'done' then
+            debounced_lint(opt)
+          end
+        end,
+      })
+    else
+      au(ev, {
+        group = M.group,
+        buffer = buf,
+        callback = debounced_lint,
+      })
+    end
+  end
+end
+
 ---@param ft string
 function M.fmt_attach_to_existing(ft)
   local bufs = api.nvim_list_bufs()
   for _, buf in ipairs(bufs) do
     if vim.bo[buf].ft == ft then
-      M.try_attach_to_buf(buf)
+      M.try_attach_fmt_to_buf(buf)
     end
   end
 end
 
 ---@param ft string
-function M.watch_ft(ft)
+function M.fmt_watch_ft(ft)
   -- check if all cmds executable before registering formatter
   iter(require('guard.filetype')[ft].formatter):any(function(config)
     if type(config) == 'table' and config.cmd and vim.fn.executable(config.cmd) ~= 1 then
@@ -47,7 +138,7 @@ function M.watch_ft(ft)
     group = M.group,
     pattern = ft,
     callback = function(args)
-      M.try_attach_to_buf(args.buf)
+      M.try_attach_fmt_to_buf(args.buf)
     end,
     desc = 'guard',
   })
@@ -69,9 +160,9 @@ function M.maybe_default_to_lsp(config, ft, buf)
         pattern = ft,
       }) == 0
     then
-      M.watch_ft(ft)
+      M.fmt_watch_ft(ft)
     end
-    M.try_attach_to_buf(buf)
+    M.try_attach_fmt_to_buf(buf)
   end
 end
 
@@ -96,8 +187,7 @@ function M.create_lspattach_autocmd()
   })
 end
 
-local debounce_timer = nil
-function M.register_lint(ft, events)
+function M.lint_watch_ft(ft, events)
   iter(require('guard.filetype')[ft].linter):any(function(config)
     if config.cmd and vim.fn.executable(config.cmd) ~= 1 then
       report_error(config.cmd .. ' not executable')
@@ -109,41 +199,7 @@ function M.register_lint(ft, events)
     pattern = ft,
     group = M.group,
     callback = function(args)
-      local cb = function(opt)
-        if debounce_timer then
-          debounce_timer:stop()
-          debounce_timer = nil
-        end
-        ---@diagnostic disable-next-line: undefined-field
-        debounce_timer = assert(uv.new_timer()) --[[uv_timer_t]]
-        debounce_timer:start(500, 0, function()
-          debounce_timer:stop()
-          debounce_timer:close()
-          debounce_timer = nil
-          vim.schedule(function()
-            require('guard.lint').do_lint(opt.buf)
-          end)
-        end)
-      end
-      for _, ev in ipairs(events) do
-        if ev == 'User GuardFmt' then
-          au('User', {
-            group = M.group,
-            pattern = 'GuardFmt',
-            callback = function(opt)
-              if opt.data.status == 'done' then
-                cb(opt)
-              end
-            end,
-          })
-        else
-          au(ev, {
-            group = M.group,
-            buffer = args.buf,
-            callback = cb,
-          })
-        end
-      end
+      M.try_attach_lint_to_buf(args.buf, events)
     end,
   })
 end

lua/guard/filetype.lua

@@ -73,7 +73,7 @@ local function box(ft)
         M[it] = box(it)
         M[it].formatter = self.formatter
       end
-      events.watch_ft(it)
+      events.fmt_watch_ft(it)
       events.fmt_attach_to_existing(it)
     end
     return self
@@ -88,17 +88,14 @@ local function box(ft)
       util.toolcopy(try_as('linter', config)),
     }
     local events = require('guard.events')
-    local evs = { 'User GuardFmt', 'BufWritePost', 'BufEnter' }
-    if config.stdin then
-      table.insert(events, 'TextChanged')
-      table.insert(events, 'InsertLeave')
-    end
+    -- TODO: the events might not be correct if we add more linters later
+    local evs = util.linter_events(config)
     for _, it in ipairs(self:ft()) do
       if it ~= ft then
         M[it] = box(it)
         M[it].linter = self.linter
       end
-      events.register_lint(it, evs)
+      events.lint_watch_ft(it, evs)
     end
     return self
   end