Generating snippets with functions

[kunzaatko]

Hi! I wanted to share the way that I create TODO comment snippets. It allows me to change only one table to add another different signature and it quite nice to be able to check only one function and affect many snippets. Here it is:

Mark signatures

I have these options when selecting the mark component of the snippet:

--- Options for marks to be used in a TODO comment
local marks = {
  signature = function()
    return fmt('<{}>', i(1, _G.luasnip.vars.username))
  end,
  signature_with_email = function()
    return fmt('<{}{}>', { i(1, _G.luasnip.vars.username), i(2, ' ' .. _G.luasnip.vars.email) })
  end,
  date_signature_with_email = function()
    return fmt(
      '<{}{}{}>',
      { i(1, os.date '%d-%m-%y'), i(2, ', ' .. _G.luasnip.vars.username), i(3, ' ' .. _G.luasnip.vars.email) }
    )
  end,
  date_signature = function()
    return fmt('<{}{}>', { i(1, os.date '%d-%m-%y'), i(2, ', ' .. _G.luasnip.vars.username) })
  end,
  date = function()
    return fmt('<{}>', i(1, os.date '%d-%m-%y'))
  end,
  empty = function()
    return t ''
  end,
}

Generation function

I use this function to generate the snippet:

--- Generate a TODO comment snippet with an automatic description and docstring
---@param context table merged with the generated context table `trig` must be specified
---@param aliases string[]|string of aliases for the todo comment (ex.: {FIX, ISSUE, FIXIT, BUG})
---@param opts table merged with the snippet opts table
local todo_snippet = function(context, aliases, opts)
  opts = opts or {}
  aliases = type(aliases) == 'string' and { aliases } or aliases
  context = context or {} -- TODO: Is this needed? <15-03-22, kunzaatko> --
  if not context.trig then
    return error("context doesn't include a `trig` key which is mandatory", 2)
  end
  opts.ctype = opts.ctype or 1
  --- Get the comment string {beg,end} table
  ---@param ctype integer 1 for `line`-comment and 2 for `block`-comment
  ---@return table {begcstring, endcstring}
  local function get_cstring(ctype)
    local comment_string_table =
      calculate_comment_string({ ctype = ctype, range = region() })
        :gsub('%%s', '~')
        :split '~'
    return #comment_string_table == 1 and { comment_string_table[1], comment_string_table[1] }
      or { comment_string_table[1], comment_string_table[2] }
  end
  local alias_string = table.concat(aliases, '|')
  context.name = alias_string .. ' comment'
  context.dscr = context.dscr or (alias_string .. ' comment with a signature-mark')
  context.docstring = context.docstring
    or (get_cstring(opts.ctype)[1] .. ' {' .. alias_string .. '}: {comment} <{mark}> ' .. get_cstring(opts.ctype)[2])
  local aliases_nodes = vim.tbl_map(function(alias)
    return i(nil, alias)
  end, aliases)
  -- TODO: logic for allowed signature-marks for a given comment... should be in the paramlist
  -- somewhere <15-03-22, kunzaatko> --
  local sigmark_nodes = {}
  for _, mark in pairs(marks) do
    table.insert(sigmark_nodes, mark())
  end
  local comment_node = fmt('{} {}: {} {} {}{}', {
    f(function()
      return get_cstring(opts.ctype)[1]
    end),
    c(1, aliases_nodes),
    i(3),
    c(2, sigmark_nodes),
    f(function()
      return get_cstring(opts.ctype)[2]
    end),
    i(0),
  })
  return s(context, comment_node, opts)
end

Generating snippets

And finally I generate the snippets like so:

local M = {
  todo_snippet({ trig = 'todo' }, 'TODO'),
  todo_snippet({ trig = 'fix' }, { 'FIX', 'BUG', 'ISSUE', 'FIXIT' }),
  todo_snippet({ trig = 'hack' }, 'HACK'),
  todo_snippet({ trig = 'warn' }, { 'WARN', 'WARNING', 'XXX' }),
  todo_snippet({ trig = 'perf' }, { 'PERF', 'PERFORMANCE', 'OPTIM', 'OPTIMIZE' }),
  todo_snippet({ trig = 'note' }, { 'NOTE', 'INFO' }),
}

And here it is in action:

edit: Added automatic commentstring detection using the Comment.nvim plugin

[L3MON4D3]

Nice! That's pretty elegant 👍

[amirhhashemi]

That's so cool. I was going to do something similar. you saved me probably a couple of hours:)

[kunzaatko]

I had some time on me, so I have written quite some description of how this works. Please let me know if it is OK and whether something should change. Also I want to add some better GIF with injected languages and block comment snippets but I will do that in the evening I guess. :)
https://github.com/L3MON4D3/LuaSnip/wiki/Cool-Snippets#all---todo-commentsnvim-snippets

[L3MON4D3]

Just skimmed over it, that's a great addition👍👍

[amirhhashemi]

That's great.
Just two small suggestions:
When I hit TAB after I choose the mark format, instead of going to the part where I write the actual message, it goes to the next section of the mark:

I think it's a little annoying, To fix it, concatenate different parts of the marks instead of adding them as insert nodes:

local marks = {
   signature = function()
      return fmt("<{}>", { i(1, _G.luasnip.vars.username) })
   end,
   signature_with_email = function()
      return fmt("<{}>", { i(1, _G.luasnip.vars.username .. " " .. _G.luasnip.vars.email) })
   end,
   date_signature_with_email = function()
      return fmt(
         "<{}>",
         { i(1, os.date "%d-%m-%y" .. ", " .. _G.luasnip.vars.username .. " " .. _G.luasnip.vars.email) }
      )
   end,
   date_signature = function()
      return fmt("<{}>", { i(1, os.date "%d-%m-%y" .. ", " .. _G.luasnip.vars.username) })
   end,
   date = function()
      return fmt("<{}>", { i(1, os.date "%d-%m-%y") })
   end,
   empty = function()
      return t ""
   end,
}

Also, it would be nice if you add date_format to _G.luasnip.vars so it would be easier to change it:

_G.luasnip = {}
_G.luasnip.vars = {
  username = 'kunzaatko',
  email = 'martinkunz@email.cz',
  github = 'https://github.com/kunzaatko',
  real_name = 'Martin Kunz',
  date_format = '%d-%m-%y'
}

local marks = {
   signature = function()
      return fmt("<{}>", { i(1, _G.luasnip.vars.username) })
   end,
   signature_with_email = function()
      return fmt("<{}>", { i(1, _G.luasnip.vars.username .. " " .. _G.luasnip.vars.email) })
   end,
   date_signature_with_email = function()
      return fmt("<{}>", {
         i(1, os.date(_G.luasnip.vars.date_format) .. ", " .. _G.luasnip.vars.username .. " " .. _G.luasnip.vars.email),
      })
   end,
   date_signature = function()
      return fmt("<{}>", { i(1, os.date(_G.luasnip.vars.date_format) .. ", " .. _G.luasnip.vars.username) })
   end,
   date = function()
      return fmt("<{}>", { i(1, os.date(_G.luasnip.vars.date_format)) })
   end,
   empty = function()
      return t ""
   end,
}

[kunzaatko]

1. The insert nodes where by design and not by accident, but retrospectively, I agree, that having the snippet lengths different for marks is counter intuitive. I will change that.
2. That is a good tip. I will also change it.

[kunzaatko]

After the first change the marks no longer need to be tables probably, since they are all only one node long. I will experiment with this, because it will make the code more clear and then add it maybe later today.