feat!: event API

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -40,8 +40,17 @@ body:
         git clone https://github.com/nvimdev/guard-collection /tmp
         echo "vim.opt.rtp:append('/tmp/guard.nvim')" >> /tmp/repro.lua
         echo "vim.opt.rtp:append('/tmp/guard-collection')" >> /tmp/repro.lua
+        nvim --clean -u /tmp/repro.lua
     validations:
       required: true
+  - type: checkboxes
+    attributes:
+      label: Are you sure this is a min repro?
+      options:
+        - label: I understand that if my repro step is too complicated (e.g. here is my 1k+ line config and please help me), developers might not be able to help.
+          required: true
+        - label: I can confirm that my reproduction step only involves `vim.opt.rtp` and configuration themselves
+          required: true
   - type: textarea
     attributes:
       label: "Expected behaviour"
@@ -53,16 +62,3 @@ body:
       label: "Actual behaviour"
     validations:
       required: true
-  - type: textarea
-    attributes:
-      label: "The minimal config used to reproduce this issue."
-      description: |
-        Run with `nvim -u /tmp/repro.lua`
-      placeholder: |
-        vim.opt.rtp:append('/tmp/guard.nvim')
-        vim.opt.rtp:append('/tmp/guard-collection')
-        -- do anything else you need to do to reproduce the issue
-
-      render: "Lua"
-    validations:
-      required: true

CUSTOMIZE.md

@@ -24,6 +24,7 @@ A tool is specified as follows:
 
     -- special
     parse            -- function: linter only, parses linter output to neovim diagnostic
+    events           -- { name: string, opt: autocmd options }: override default events, for formatter autocmds only the first one is used (passed in from `:fmt`)
 }
 ```
 

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 13
+*guard.nvim.txt*         For NVIM v0.8.0         Last change: 2024 December 18
 
 ==============================================================================
 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>.
 
@@ -150,6 +152,7 @@ A tool is specified as follows:
 
         -- special
         parse            -- function: linter only, parses linter output to neovim diagnostic
+        events           -- { name: string, opt: autocmd options }: override default events, for formatter autocmds only the first one is used (passed in from `:fmt`)
     }
 <
 

lua/guard/_meta.lua

@@ -4,6 +4,7 @@
 ---@field fname boolean?
 ---@field stdin boolean?
 ---@field fn function?
+---@field events EventOption[]
 ---@field ignore_patterns string|string[]?
 ---@field ignore_error boolean?
 ---@field find string|string[]?
@@ -18,6 +19,7 @@
 ---@field fname boolean?
 ---@field stdin boolean?
 ---@field fn function?
+---@field events EventOption[]
 ---@field parse function
 ---@field ignore_patterns string|string[]?
 ---@field ignore_error boolean?
@@ -26,3 +28,9 @@
 ---@field timeout integer?
 
 ---@alias LintConfig LintConfigTable|fun(): LintConfigTable
+
+---@alias AuOption vim.api.keyset.create_autocmd
+
+---@class EventOption
+---@field name string
+---@field opt AuOption?

lua/guard/api.lua

@@ -0,0 +1,122 @@
+-- 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)
+  local buf = bufnr or api.nvim_get_current_buf()
+  local ft_handler = require('guard.filetype')
+  local ft = vim.bo[buf].ft
+  local head = vim.tbl_get(ft_handler, ft, 'formatter', 1)
+  if type(head) == 'table' and type(head.events) == 'table' then
+    events.attach_custom(ft, head.events)
+  else
+    events.try_attach_fmt_to_buf(buf)
+  end
+end
+
+---Disable format for bufnr or current buffer
+---@param bufnr number?
+function M.disable_fmt(bufnr)
+  local buf = bufnr or api.nvim_get_current_buf()
+  vim.iter(events.get_format_autocmds(buf)):each(function(x)
+    api.nvim_del_autocmd(x)
+  end)
+  events.user_fmt_autocmds[vim.bo[buf].ft] = {}
+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]), ft)
+  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:',
+    '',
+  }
+
+  if #formatters > 0 then
+    vim.list_extend(lines, { '', '```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, { '```', '' })
+  end
+
+  vim.list_extend(lines, { '- linters:' })
+
+  if #linters > 0 then
+    vim.list_extend(lines, { '', '```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, { '```' })
+  end
+
+  api.nvim_buf_set_lines(0, 0, -1, true, lines)
+  api.nvim_set_option_value('modifiable', false, { buf = 0 })
+end
+
+return M