wiki/notebook/editor.neovim.plugins.luasnip.org

Neovim plugin: LuaSnip

• Example snippets in Lua
  • Simple word trigger
  • Patterned trigger
  • Choosing between Asciidoctor admonition blocks
  • Dynamic Asciidoctor header with optional automatic TOC

• manual from Neovim help system: luasnip.txt
• snippets are made of nodes

• there are different type of nodes; these can be found on the luasnip-snippets on the manual

  • text nodes are just static text
  • insert nodes are points to be edited; can be given default text for the snippet
  • function nodes generate text based from other nodes; this is used mostly to generate dynamic output from the snippet
  • choice nodes contains multiple nodes to be chosen for a given jump position
  • snippet nodes contains other node to be inserted in the snippet
  • dynamic nodes are similar to function nodes except they return snippet nodes

• LuaSnip can support several types of snippets other than its own

  • SnipMate snippets
  • Visual Studio Code snippets
  • Lua snippets, obviously
• snippets are not automatically loaded unless you have invoked the appropriate function for a certain type; you will not load Visual Studio Code-style snippets unless you have run lazy_load function from luasnip.loaders.from_vscode; for more details, each supported format has a specific section for loading them from the manual (e.g., luasnip-vscode-snippets-loader)
• adding snippets is as simple as adding them in require("luasnip").snippets.FILETYPE; though, you have to know how to add a snippet through LuaSnip module

Example snippets in Lua

We'll explore different examples from the simplest to the more complex snippets made with Lua. The following code blocks will assume the environment with the default value from luasnip.config.snip_env.

The plugin source code also has a comprehensive set of examples in the Examples/ folder. It also has a wiki containing multiple example snippets showcasing the various nodes.

Simple word trigger

The simplest snippet possible. This will simply replace hello with world.

s("hello", t "world")

Exploring other nodes, we could replace the text node with a function node.

s("hello", f(function ()
    return "world"
end))

Patterned trigger

A simple snippet that will answer you back when triggered.

This snippet makes use of:

• Pattern triggers (see roam:Lua patterns).
• Snippet captures similar to UltiSnips' capture.
• Usage of a function node.

s(
  { trig = "hello (%a+)", regTrig = true },
  f(function (_, snip)
      return string.format("hey there, %s", snip.captures[1])
  end)
)

Choosing between Asciidoctor admonition blocks

We can easily create a snippet for multiple choices. In Asciidoctor, we have admonition blocks that are formatted similarly.

Here's one way to define such snippet…

s(
  "admo",
  fmt([[
    {}: {}
  ]], {
    c(1, {
        t "NOTE",
        t "TIP",
        t "IMPORTANT",
        t "CAUTION",
        t "WARNING",
    }),
    i(0),
  })
)

Dynamic Asciidoctor header with optional automatic TOC

Here is a snippet for Asciidoc documents for creating headers. As an example, h6 should print the appropriate header level.

It should follow some restrictions for this snippet.

• It can only have a maximum level of 6.
• As a bonus, we could set the table of contents on if the header level is 1.

This snippet makes use of dynamic node to change the node between a choice node for the first heading level and a blank text node for the rest.

function min_asciidoc_header_level(level)
  math.min(level, 6)
end

s(
  { trig = "h(%d)", regTrig = true },
  fmt([[
      {} {}
      {}
      {}
    ]], {
      f(function(_, snip)
          local level = min_asciidoc_header(snip.captures[1])
          return string.rep("=", level)
      end),
      i(1, "CHAPTER"),
      d(2, function(_, snip)
          local nodes = {}
          table.insert(nodes, t "")

          local level = min_asciidoc_header(snip.captures[1])

          if level == 1 then
            table.insert(nodes, t ":toc:")
          end

          local parent = c(1, nodes)
          if level > 1 then
            parent = t ""
          end

          return sn(nil, parent)
      end, {}),
      i(0),
  })
)