[mini.snippets] Context aware global snippets

[danielt812]

Hi, I would like to share how to create context-aware global snippets using mini.snippets.

Demo

mini_snippets_context_demo.mp4

Example mini.snippets setup:

local snippets = require("mini.snippets")

snippets.setup({
  snippets = {
    snippets.gen_loader.from_file("~/.config/nvim/snippets/global.lua"),
  },
})

snippets.start_lsp_server()

Example snippets/global.lua file:

return {
  function()
    local cs = vim.bo.commentstring:gsub("%%s", ""):gsub("%s*$", "")

    local filename = vim.fn.expand("%:t")

    local function is_git_repo()
      return vim.fn.system("git rev-parse --is-inside-work-tree 2>/dev/null"):match("true") ~= nil
    end

    local function git_author_or_placeholder()
      if not is_git_repo() then
        return "${2:Author}"
      end

      local author = vim.fn.system("git config user.name"):gsub("%s+$", "")
      if author == "" then
        return "${2:Author}"
      end

      return author
    end

    local author = git_author_or_placeholder()

    return {
      {
        -- stylua: ignore start
        { prefix = "fixme", body = cs .. " FIXME  ${1:describe the bug or needed fix}",  desc = "Create a fixme comment" },
        { prefix = "hack",  body = cs .. " HACK  ${1:temporary workaround or solution}", desc = "Create a hack comment" },
        { prefix = "info",  body = cs .. " INFO  ${1:relevant context or metadata}",     desc = "Create a info comment" },
        { prefix = "link",  body = cs .. " LINK  ${1:href to issue or documentation}",   desc = "Create a link comment" },
        { prefix = "note",  body = cs .. " NOTE  ${1:important detail}",                 desc = "Create a note comment" },
        { prefix = "todo",  body = cs .. " TODO  ${1:describe the task or goal}",        desc = "Create a todo comment" },
        { prefix = "warn",  body = cs .. " WARN  ${1:potential risk or edge case}",      desc = "Create a warn comment" },
        {
          prefix = "box",
          body = {
            cs .. " ┌──────────────────────────────────────┐",
            cs .. " │ ${1:TITLE} │",
            cs .. " └──────────────────────────────────────┘",
          },
          desc = "Create a boxed comment",
        },
        {
          prefix = "section",
          body = cs .. " ── ${1:Section name} ─────────────────────────────",
          desc = "Create a section divider",
        },
        {
          prefix = "header",
          body = {
            cs .. " ================================================",
            cs .. " " .. filename,
            cs .. "",
            cs .. " Description: ${1:What this file does}",
            cs .. " Author: " .. author,
            cs .. " ================================================",
          },
          desc = "Create a file header",
        },
        -- stylua: ignore end
      },
    }
  end,
}

Would love to hear if anyone else has fun ideas for context-aware snippets

[echasnovski]

That's some very nice ideas! Thanks for sharing!

This is also related to #1225 and is something I'd recommend doing. One unfortunate drawback of using snippets here is inability to pre-align text in boxes (like for "TITLE" in the box snippet).

I'd also suggest adjusting couple of things:

• 'commentstring' can be not only <left><space>%s, but also <left><space>%s<space><right>. Like for example /* %s */.

• Computing author inside function snippet is very expensive. It will execute two blocking system calls on every snippet matching (i.e. almost every typed word). I'd just compute author once (this should cover >90% of use cases, I'd say) before computing the function snippet. Reading with gen_loader.from_file by default caches its output, so the file contents will be executed once per session.

• All currently present snippets only have a single tabstop. 'mini.snippets' relies on snippets also having final tabstop, so it automatically adds them at the end of the snippet text. Almost all snippets shared here don't really need one (maybe except "boxes", but that is a matter of taste). So I'd use ${0:...} here.

  Now, there is a bit of ambiguity around whether final tabstop can have placeholder text. Luckily, 'mini.snippets' by default allows it and precisely for this sort of situation when it helps clarify the intent of the final placeholder.

So all in all here is something I'd do:

local author = vim.fn.executable('git') == 1 and vim.fn.system('git config user.name'):gsub('%s+$', '')
  or vim.uv.os_get_passwd().username

local special_comments = function(context)
  local cs_left, cs_right = vim.bo[context.buf_id].commentstring:match('^(.*)%%s(.*)$')
  if cs_left == nil then return {} end

  -- Optional: adjust comment parts to always have inner padding
  cs_left = cs_left:find('%s$') and cs_left or (cs_left .. ' ')
  cs_right = cs_left:find('^%s') and cs_right or (' ' .. cs_right)

  local wrap = function(s)
    -- Optional: make it work nicer with blank lines
    if s:match('^%s*$') then return (cs_left:gsub('%s*$', '') .. cs_right:gsub('^%s*', '')) end
    return (string.format('%s%s%s', cs_left, s, cs_right):gsub('%s$', ''))
  end

  --stylua: ignore
  return {
    {
      { prefix = "fixme", body = wrap("FIXME  ${0:describe the bug or needed fix}"),  desc = "Create a fixme comment" },
      { prefix = "hack",  body = wrap("HACK  ${0:temporary workaround or solution}"), desc = "Create a hack comment" },
      { prefix = "info",  body = wrap("INFO  ${0:relevant context or metadata}"),     desc = "Create a info comment" },
      { prefix = "link",  body = wrap("LINK  ${0:href to issue or documentation}"),   desc = "Create a link comment" },
      { prefix = "note",  body = wrap("NOTE  ${0:important detail}"),                 desc = "Create a note comment" },
      { prefix = "todo",  body = wrap("TODO  ${0:describe the task or goal}"),        desc = "Create a todo comment" },
      { prefix = "warn",  body = wrap("WARN  ${0:potential risk or edge case}"),      desc = "Create a warn comment" },
      {
        prefix = "box",
        body = {
          wrap("┌──────────────────────────────────────┐"),
          wrap("│ ${0:TITLE} │"),
          wrap("└──────────────────────────────────────┘"),
        },
        desc = "Create a boxed comment",
      },
      {
        prefix = "section",
        body = wrap("── ${0:Section name} ─────────────────────────────"),
        desc = "Create a section divider",
      },
      {
        prefix = "header",
        body = {
          wrap("================================================"),
          wrap(" " .. vim.fn.expand('%:t')),
          wrap(""),
          wrap("Description: ${0:What this file does}"),
          wrap("Author: " .. author),
          wrap("================================================"),
        },
        desc = "Create a file header",
      },
    },
  }
end

return { special_comments }

[danielt812]

This is also related to #1225 and is something I'd recommend doing. One unfortunate drawback of using snippets here is inability to pre-align text in boxes (like for "TITLE" in the box snippet).

That makes sense — this approach is definitely cleaner. I’ll switch to this instead of generating boxes via snippets, especially given the alignment limitations you mentioned.

'commentstring' can be not only %s, but also %s. Like for example /* %s */.

Good catch - that was an oversight on my part. I wasn’t accounting for commentstrings with both left and right delimiters (HTML, XML, CSS, etc.).

Computing author inside function snippet is very expensive. It will execute two blocking system calls on every snippet matching (i.e. almost every typed word). I'd just compute author once (this should cover >90% of use cases, I'd say) before computing the function snippet. Reading with gen_loader.from_file by default caches its output, so the file contents will be executed once per session.

That makes sense. How do you determine how expensive a system call would be? I tried to find some resources on this, but didn’t have much luck. Is it mostly something you learn through trial and error or by writing your own benchmarks?

All currently present snippets only have a single tabstop. 'mini.snippets' relies on snippets also having final tabstop, so it automatically adds them at the end of the snippet text. Almost all snippets shared here don't really need one (maybe except "boxes", but that is a matter of taste). So I'd use ${0:...} here.

Good point. I'll keep the final tabstop in mind next time I write snippet

[echasnovski]

That makes sense. How do you determine how expensive a system call would be? I tried to find some resources on this, but didn’t have much luck. Is it mostly something you learn through trial and error or by writing your own benchmarks?

To answer the question as is - yes, only by benchmarking.

To answer the original issue - it is the fact that vim.fn.system will be called "... * every snippet matching (i.e. almost every typed word) ...". So however fast the vim.fn.system call is, the "growth rates" (O(1) one time, or O(n) for number of matching snippets) are very different here. If it can be avoided with reasonably similar and workable result, it is better to do so.