LuaSnip on Clément Joly – Open-Source, Rust & SQLite

Luasnip and Treesitter for Smarter Snippets

Wed, 30 Aug 2023 13:28:14 +0100

⚡ TL;DR

A context-aware snippet for Go error handling code, returning the right types, with the default values.

Demo
Snippet

✏ Edit

TJ DeVries made a video explaining an improved version of this snippet. You may still find the discussion on Go errors in this post interesting.

Introduction

Golang’s error handling is notoriously verbose. It was also the top pain point in the Go Developer Survey Q2 2022. Numerous proposals to simplify error handling have been written, but at the time of writing, none have been accepted.

So we have to live with the current state of things. It’s ok, Neovim with Treesitter has a good “understanding” of code, so we can use it to generate the error handling code.

Treesitter

One of Neovim 0.5 most exciting features was the introduction of Treesitter. This new parsing system gives the editor a basic understanding of the code at hand: the editor “knows” what the function name is, where a variable is defined… It enables great plugins, showing the context around some code, improved selection, better renaming and navigation and more! In this post, we will look into how Treesitter can be combined with LuaSnip for smarter snippets.

Error Handling in Go

ℹ️ Note

Feel free to skip this section if you already know about Go error handling.

In Golang, errors are handled by returning a value of type error, sometimes along the types returned when everything goes well. For instance, the time.Parse function has the following signature:

func Parse(layout, value string) (Time, error)

time.Parse will try to parse a string with the given format. If it’s successful, it’ll return a value of type Time and the error will be nil. If a date can’t be parsed, then the error won’t be nil. And so it’s common in Go to check for errors like so:

timeStr := "Aug 6, 2022 @ 7:54pm"
t, err := time.Parse("Jan 2, 2006 @ 3:04pm", timeStr)
if err != nil {
    log.Fatal(err)
}
// Now, we can safely use t

In the example above, we just log the error and panic. But if we are in a function, we will likely return an error to the caller, wrapping the error returned by time.Parse. For instance:

1func parseLong(timeStr string) (Time, error) {
2    t, err := time.Parse("Jan 2, 2006 @ 3:04pm", timeStr)
3    if err != nil {
4        return t, fmt.Errorf("couldn’t parse %v: %v", timeStr, err)
5    }
6    return t, nil
7}

The key takeaway here is that the return line in the error case (line 4 above) depends on the return type of the function and so can vary significantly.

This is covered in more details in this post on the Go blog.

Clever Snippets with LuaSnip and Treesitter

As we have seen, error handling code varies depending on the number and type of the values returned by the parent function. So we are very often writing variations of the following in our Go code:

func f(arg1 string, arg2 string) (…, error) {
    val, err := someFunction(arg1, arg2)
    if err != nil {
        return …, err
    }
    …
}

Or with 3 return values:

func f(arg string) (…, …, error) {
    val, err := someFunction(arg)
    if err != nil {
        return …, …, err
    }
    …
}

It would be handy to have a snippet that would adjust the return’s shape depending on the return type of the function that contains it.

Demo

Here is a short asciicast demonstration¹ of the snippet we are going to build. It is called smart_err:

To run this asciicast without javascript, use asciinema play https://cj.rs/blog/luasnip-and-treesitter-for-smarter-snippets/demo.json with Asciinema

The snippet inserted (line 11 in the asciicast) is

myVal, myErr := anotherFunc(arg1, arg2)
if myErr != nil {
	return false, fmt.Errorf("anotherFunc: %v", myErr)
}

when the return type of the function was (bool, error).

And

val, err := f()
if err != nil {
	return false, fmt.Errorf("f: %v", err), 0, ""
}

when the return type was (bool, error, int, string).

And it even works in nested functions:

func myFunc() (*MyStruct, error) {
    // ...
	a := func() (bool, error, int, string) {
		// The snippet detected that we need 4 values here,
		// and not 2 as in the outer function
		return v, nil, 0, ""
	}

Also note that we can choose to wrap the containing error, or not, with a keystroke (bound to require("luasnip").change_choice(1)). The snippet switches between the following 3 forms (line 18 in the asciicast):

```
return false, err
```
```
return false, fmt.Errorf("f: %v", err)
```
```
return false, errors.Wrap(err, "f")
```

That’s pretty cool! Let’s see how to add it to your Neovim configuration.

Code

The code to define this snippet was initially written by TJ DeVries². I’ve only slightly adapted it so that it fits in one file. I believe the author welcomes this³:

This is TJ’s configuration repo. Feel free to use whatever you would like from it! It’d be great if you mentioned where it came from if you think it’s cool.

https://github.com/tjdevries/config_manager#readme

Copy this alongside your other LuaSnip snippets, for instance in ~/.config/nvim/snippets/go.lua:

  1local ls = require "luasnip"
  2local f = ls.function_node
  3local s = ls.s
  4local i = ls.insert_node
  5local t = ls.text_node
  6local d = ls.dynamic_node
  7local c = ls.choice_node
  8local snippet_from_nodes = ls.sn
  9
 10local ts_locals = require "nvim-treesitter.locals"
 11local ts_utils = require "nvim-treesitter.ts_utils"
 12local get_node_text = vim.treesitter.get_node_text
 13
 14-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 15local function same(index)
 16  return f(function(args)
 17    return args[1]
 18  end, { index })
 19end
 20
 21-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 22vim.treesitter.query.set(
 23  "go",
 24  "LuaSnip_Result",
 25  [[ [
 26    (method_declaration result: (_) @id)
 27    (function_declaration result: (_) @id)
 28    (func_literal result: (_) @id)
 29  ] ]]
 30)
 31
 32-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 33local transform = function(text, info)
 34  if text == "int" then
 35    return t "0"
 36  elseif text == "error" then
 37    if info then
 38      info.index = info.index + 1
 39
 40      return c(info.index, {
 41        t(string.format('fmt.Errorf("%s: %%v", %s)', info.func_name, info.err_name)),
 42        t(info.err_name),
 43        -- Be cautious with wrapping, it makes the error part of the API of the
 44        -- function, see https://go.dev/blog/go1.13-errors#whether-to-wrap
 45        t(string.format('fmt.Errorf("%s: %%w", %s)', info.func_name, info.err_name)),
 46        -- Old style (pre 1.13, see https://go.dev/blog/go1.13-errors), using
 47        -- https://github.com/pkg/errors
 48        t(string.format('errors.Wrap(%s, "%s")', info.err_name, info.func_name)),
 49      })
 50    else
 51      return t "err"
 52    end
 53  elseif text == "bool" then
 54    return t "false"
 55  elseif text == "string" then
 56    return t '""'
 57  elseif string.find(text, "*", 1, true) then
 58    return t "nil"
 59  end
 60
 61  return t(text)
 62end
 63
 64local handlers = {
 65  ["parameter_list"] = function(node, info)
 66    local result = {}
 67
 68    local count = node:named_child_count()
 69    for idx = 0, count - 1 do
 70      table.insert(result, transform(get_node_text(node:named_child(idx), 0), info))
 71      if idx ~= count - 1 then
 72        table.insert(result, t { ", " })
 73      end
 74    end
 75
 76    return result
 77  end,
 78
 79  ["type_identifier"] = function(node, info)
 80    local text = get_node_text(node, 0)
 81    return { transform(text, info) }
 82  end,
 83}
 84
 85-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 86local function go_result_type(info)
 87  local cursor_node = ts_utils.get_node_at_cursor()
 88  local scope = ts_locals.get_scope_tree(cursor_node, 0)
 89
 90  local function_node
 91  for _, v in ipairs(scope) do
 92    if
 93      v:type() == "function_declaration"
 94      or v:type() == "method_declaration"
 95      or v:type() == "func_literal"
 96    then
 97      function_node = v
 98      break
 99    end
100  end
101
102  local query = vim.treesitter.query.get("go", "LuaSnip_Result")
103  for _, node in query:iter_captures(function_node, 0) do
104    if handlers[node:type()] then
105      return handlers[node:type()](node, info)
106    end
107  end
108
109  return { t "nil" }
110end
111
112-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
113local go_ret_vals = function(args)
114  return snippet_from_nodes(
115    nil,
116    go_result_type {
117      index = 0,
118      err_name = args[1][1],
119      func_name = args[2][1],
120    }
121  )
122end
123
124return {
125  -- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
126  s("smart_err", {
127    i(1, { "val" }),
128    t ", ",
129    i(2, { "err" }),
130    t " := ",
131    i(3, { "f" }),
132    t "(",
133    i(4),
134    t ")",
135    t { "", "if " },
136    same(2),
137    t { " != nil {", "\treturn " },
138    d(5, go_ret_vals, { 2, 3 }),
139    t { "", "}" },
140    i(0),
141  }),
142}

We start by importing and aliasing some LuaSnip functions. The snippet itself is defined at the end (line 126). Most of those functions were covered in the previous post, see there for calls to s, i and t. The clever part of this snippet is the dynamic node d on line 138. There, we call a function that queries (line 22 and 102) Treesitter to find the return types of the current function in Go code. Depending on the types found, default values for the type are used (line 33).

Treesitter Query

The Treesitter query is where the magic happens, so let’s take a deeper look.

Treesitter parses code and builds a tree with node for various parts of the code. Each node can have children, like a function definition has a name, a body… This tree can be queried in a Lisp-like language (s-expressions). For instance, in our snippet definition, we use this query:

1[
2    (method_declaration result: (_) @id)
3    (function_declaration result: (_) @id)
4    (func_literal result: (_) @id)
5]

The bracket syntax returns the nodes that match any of the patterns inside the brackets. So it’s effectively the union of all the nodes matched by any of the 3 patterns (on lines 2 to 4). Let’s take a concrete example and put the Go code in the Treesitter playground, with a trimmed down version of the query:

The tree built by Treesitter is at the bottom, with the corresponding code at the top and the query in the middle. The function_declaration node is highlighted in gray in the tree, like the corresponding part of the code (from line 13 to line 22). This node has a number of children, with the function name, the parameters of the function, a result node for the return type and body for the body of the function between curly braces.

Taking the first pattern on the playground, slightly modified:

    (function_declaration result: (_) @id2)

The part it captures is highlighted in blue in the Go code: (*MyStruct, error). It makes sense, since the function_declaration (the part on the gray background) has a result child, that’s captured by @id.

Now, on to the second pattern:

    (func_literal result: (_) @id3)

Similarly, further down in the body of that function, the return type (bool, error, int, string) of the anonymous function is matched.

Conclusion

I started writing this post over a year ago. The snippet has been very stable and kept working as without changes, which is a testament to the stability of the LuaSnip (and Treesitter) APIs. I’m still using it when I write Go code, even if some corner cases (like custom structs) aren’t handled. The snippet is quite complicated and niche, so I’m not sure that I would have invested the time to write it myself. I probably don’t write enough Go code to justify the investment, but finding it shared by someone buried in their config file made it worth it. I hope you have found this port useful, either to copy this particular snippet or as an example of advanced snippets.

This is the last post in a series on LuaSnip.

Resources

If you want to dig deeper:

Working with Errors in Go 1.13
LuaSnip documentation
Explore the Treesitter tree for any Neovim buffer where it is active with :lua vim.treesitter.inspect_tree()
Treesitter’s Pattern Matching with Queries

The test code is available as gist. ↩︎
By the way, he has a very interesting Twitch channel ↩︎
At the time of writing at least. See perma.cc and the wayback machine for a snapshot. ↩︎

Generating Snippets with LuaSnip in Neovim

Sun, 31 Jul 2022 22:10:49 +0100

⚡ TL;DR

When you have many variations of the same snippet, one option is to generate those with Lua code. The complete example is at the end.

I’ve recently moved to LuaSnip as my snippets plugin for Neovim. When I first started, I sticked to the simplest features of LuaSnip, in particular the SnipMate-like syntax for snippets. But I have now started to explore the more distinctive features of LuaSnip, like Lua-defined snippets. It turns out that generating snippets with code can save tedious repetition.

Markdown Journaling

I tend to take notes in Markdown documents. I usually set up one text file for each recurring themes or project. Then, there is a “h1” title per day, a bit like the Bullet Journal daily log. The resulting file looks like this:

# 2022-07-31 Sun

* Point 1
* Point 2
* Point 3

I have a snippet to generate the # 2022-07-31 Sun line, based on the current date and day of the week, as I explained last time. For reference, here is the snippet from back then:

# “Bullet Journal”-styled date for today
snippet bjtoday
  # ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} $CURRENT_DAY_NAME_SHORT

Lua-Generated Snippets

But then, I also sometimes want to put notes for the next session. I usually know when that will be, because the meeting happens, say, every Thursday or every month. So it would be great to have snippets for those dates as well. Let’s build them step by step.

1. Computing the Date of “Next Friday”

The first step is to calculate the date and weekday from human concepts like “next Friday” or “next week”. Thankfully GNU date supports this, and it’s preinstalled on most GNU/Linux systems:

$ date -d 'next Friday' +'%F %a'
2022-08-05 Fri

2. Putting Those Dates in LuaSnip

The second step is to use the output of the date command in LuaSnip.

We could define our own variables like ${NEXT_MONDAY_DATE}. That would be similar to the ${CURRENT_DATE} we used before. But we would need many such variables, for the date and weekday of the next Monday, Tuesday, …, next week or next month. Plus I use those dates only in Markdown snippets, so it feels a bit wasteful to define those variables everywhere.

In the end, I chose to use function nodes to call the date command on the fly, when the snippet gets expanded. This node is inserted in a particular snippet definition and is thus contained to that particular snippet. This way, we avoid creating values everywhere, and we keep the global namespace clean. It looks like this:

f(function(args, snip, user_arg_1)
    return vim.fn.trim(vim.fn.system([[date -d ']] .. target_date .. [[' +'%F %a']]))
end, {}),

3. Generating Snippets Variants

The last step is to generate the variants of the base snippet: bj_today, bj_next_monday, …, bj_next_week and bj_next_month.

In LuaSnip, snippets defined using Lua are just a table calling some agreed-upon functions. Here is an example from the documentation:

ls.add_snippets("all", {
	s("ternary", {
		-- equivalent to "${1:cond} ? ${2:then} : ${3:else}"
		i(1, "cond"), t(" ? "), i(2, "then"), t(" : "), i(3, "else")
	})
})

This creates a snippet (the s function) for all file types. This snippet will expand ternary into cond ? then : else, prompting the user to change the cond, then and else bits (function i) while ? and : are “static text” (function t).

We want to write a function that builds a table of date snippet definitions. That will be returned when the Lua module is loaded.

The Final Code

The final snippet looks like this:

 1-- Bullet Journal styled dates in the future
 2local function gen_date_snippets()
 3  local snippets = {}
 4  local target_dates = {
 5    "today",
 6    "tomorrow",
 7    "next monday",
 8    "next tuesday",
 9    "next wednesday",
10    "next thursday",
11    "next friday",
12    "next week",
13    "next month",
14  }
15  for _, target_date in pairs(target_dates) do
16    table.insert(
17      snippets,
18      s("bj_" .. target_date:gsub(" ", "_"), {
19        t "# ",
20        f(function(args, snip, user_arg_1)
21          return vim.fn.trim(vim.fn.system([[date -d ']] .. target_date .. [[' +'%F %a']]))
22        end, {}),
23      })
24    )
25  end
26
27  return snippets
28end
29
30return gen_date_snippets()

This generates the snippets name (line 18), for instance bj_today or bj_next_tuesday from the arguments passed to the date command. The body of the snippet is made of text (t "# ") and our function node from earlier (line 20-22). All those snippets get collected in a table that is returned at the end of the Lua module (line 30). It’s then usable by LuaSnip.

Conclusion

Generating a bunch of similar snippets like this turned out to be an unanticipated benefit of using Lua to define snippets. Before using LuaSnip, I only had bj_today, bj_tomorrow and bj_next_monday. If I had wanted to expand this set further, I would have to do some more copying and pasting, which quickly becomes unmaintainable.

Of course for simpler or less repetitive snippets, it’s probably best to use the less verbose SnipMate-like syntax presented in the previous post.

From UltiSnips to LuaSnip

Sun, 15 May 2022 07:06:49 +0100

⚡ TL;DR

LuaSnip is fast and doesn’t have to be complicated. Give it a try!

ℹ️ About UltiSnips