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

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

You “Own” 16 Milion+ IPv4 Addresses!

Sat, 05 Mar 2022 21:13:22 +0000

⚡ TL;DR

For the foreseeable future, you can likely use 127.0.0.0/8 freely (or at least 127.0.0.0/16).

Introducing `127.0.0.0/8`, the Loopback Range

Visualization of the 127.0.0.0/8 range

From cidr.xyz by Yuval Adam

If you have ever done web development or otherwise set up a local server, you have most likely used the IP address 127.0.0.1 to communicate with a local server. Often, localhost is even internally translated to that address. But what if you want to run another server on the same computer? Easy, make the first one use, say, port 8080 and the second one, port 8181!

Something more difficult now: say you can convince¹ your browser that your local service is serving a valid HTTPS connection only if you use port number 443. How can you run many of those services? In turns out in IPv4, you have many such local addresses: 127.0.0.1, 127.0.0.2, 127.0.0.3, 127.0.0.4… So you just need to spawn the various servers on the same 443 port number with different addresses and packets will go straight to your localhost.

But how many such addresses do we have? According to RFC990 from 1986:

   The class A network number 127 is assigned the "loopback"
   function, that is, a datagram sent by a higher level protocol
   to a network 127 address should loop back inside the host.  No
   datagram "sent" to a network 127 address should ever appear on
   any network anywhere.

https://www.rfc-editor.org/rfc/rfc990.txt

The “class A network” translate to a /8 in CIDR notation, so that’s all addresses between 127.0.0.0 and 127.255.255.255. A quite sizeable 2²⁴ or 16,777,216 addresses²!

Note the wording of the RFC: IPs are not “owned”, there are just “allocated”. For addresses routable on the wider Internet, it’s usually done by Regional Internet Registeries. And allocations could change, as we will see at the end of this article.

Other Use Cases

What can you do with so many IPs? A couple of things.

Multiple Servers on the Same Port Number

As we have seen earlier with the port number 443 example, the 127.0.0.0/8 range is handy to run multiple local services on the same port. Thus, it’s not surprising to see systemd-resolved – a local DNS resolver that needs to listen on port 53 – use a couple addresses from that range. The man page reads:

Additionally, systemd-resolved provides a local DNS stub listener on the IP addresses 127.0.0.53 and 127.0.0.54 on the local loopback interface.

https://man.archlinux.org/man/core/systemd/systemd-resolved.8.en

In this case, systemd-resolved has to bind on the default port, because one of the main ways (on Unix-like systems) that DNS resolution is configured is through the file /etc/resolv.conf. This file does not widely support setting a port number, forcing the configured server to be reachable on the default port. Thanks to the use of a loopback addresse though, systemd-resolved can become the default resolver just by adding this line to resolv.conf:

nameserver 127.0.0.53

Naming Things

On Unix-like systems, the /etc/hosts file associates IP addresses with names, like so:

127.0.0.1	localhost
::1		localhost

That’s how localhost is associated with 127.0.0.1 (and IPv6 ::1).

You can edit this file and add useful aliases to other IPs (not necessarily in the local range by the way). Then, you just bind your multiple services to their default ports and access to them by name. No more complicated ports to remember! This benefit comes as a byproduct of using default ports but with different IPs for different services.

For instance, you could name one of the aforementioned systemd-resolved IPs by adding this line to /etc/hosts:

127.0.0.1	localhost
::1		localhost

127.0.0.53	sd

And then query it like so:

dig @sd s.cj.rs

instead of

dig @127.0.0.53 s.cj.rs

if you did not have the setting.

I’m using this trick to make the Syncthing web interface accessible on a memorable port on an address with a memorable name in my web browser.

Future of `127.0.0.0/8`

Even if the ability to give various services different IPs is handy, 16 milion addresses is huge. Given how IPv4 is sometimes called “internet real-estate”, there have been discussions to drastically limit the size of this loopback range, and use some of it as “normal” IPs. For instance, this IETF draft proposes to cut the loopback range to 127.0.0.0/16 (so only addresses between 127.0.0.0 and 127.0.255.255) and make the rest (addresses between 127.1.0.0 and 127.255.255.255) routable on the public internet. The 65536 addresses in 127.0.0.0/16 should to be enough for almost everyone on a local machine and nearly 16 million IPs could be used as a fresh supply of IPv4 addresses³.

And IPv6?

Even though IPv6 has a huge namespace, your IPv6 loopback only has one address ::1. And that’s quite a shame because, as we have just seen, multiple loopback addresses are quite handy.

For instance using mkcert. ↩︎
Admittedly, some addresses like 127.0.0.0 or 127.255.255.255 are reserved, but there is still plenty of space. ↩︎
Whether more useable IPv4 addresses is a good thing is debated. It might divert efforts from the IPv6 transition and even with a few millions more IPv4 addresses, these are still scarce. ↩︎

Configuration Management

Fri, 03 Sep 2021 19:59:01 +0100

⚡ TL;DR

Chezmoi follows a declarative approach to configuration management. Even if you already use a configuration-management system, you should check out how it compares!

A Custom Configuration Makes You Feel at Home

Your git aliases, shell setup, keyboard shortcuts and even your favorite fonts are tweaked for your own needs and tastes. It’s part of what makes your computer, your computer. All this configuration evolves over years and is slowly refined over time. It may actually be your longuest-living project.

Do you want to start from scratch when you switch computer? Of course not! And you wouldn’t want to break it with adventurous changes either! Versioning it in git backs up the history and eases the management of this important work. Configuration updates are also more convenient to share between machines this way.

Enter Chezmoi

In the git-based configuration management described above, how to account for the small variations (like between your work environment and personal computer)? Git supports conditional inclusion of configuration files, but how about the other tools? What if you want to encrypt your secrets in your config files, to publish your configuration on GitHub?

Chezmoi follows a declarative approach: it has a separate source repository¹ to describe a target state, that then gets applied to your home directory. This is possible through templates, that are activated selectively for some files. The rest of this post shows how powerful templating can be.

Account for Variations Between Machines

Let’s start with a simple example. In the git configuration, you put your email, that’s then included in all your commits. Thus, you often want to have a different email in .gitconfig for your work and personal profiles. To tackle this issue, I put the following in my .gitconfig chezmoi template:

[user]
    email = {{ .email }}

and it gets rendered to this:

[user]
    email = me@my.home

on my personal computer and this:

[user]
    email = me@my.work

on my work computer. It serves a purpose similar to conditionally setting your gitconfig, but it is applicable to any program.

Even More Variations with Templates

Now, let’s cover a more powerful use of templates.

You can have multiple files generated from one using “global” templates. For instance, if you use i3 and sway as your windows manager, you likely have slightly different configurations, given that sway’s configuration is mostly compatible with that of i3. To keep everything in one file, while taking advantages of sway-specific features, you can (in your chezmoi repository):

Put your configuration in .chezmoitemplates/sway_i3. You can keep any sway specific section in a templated if statement, like so:
```
{{- if eq .f "sway" }}
# Sway specific stuff here, like output configuration
{{- end }}
```
In dot_config/i3/config.tmpl (and dot_config/sway/config.tmpl), use something like:
```
{{/* Environment */}}
{{- $env := . -}}

{{/* Flavor */}}
{{- $f := "i3" -}} # <--- Change this to "sway" in dot_config/sway/config.tmpl

{{- template "sway_i3" dict "f" $f "env" $env -}}
```
As you may have noticed, chezmoi renames some files in the source state, to encode parameters and for readability. So dot_config/sway/config.tmpl becomes .config/sway/config (.tmpl means the file is executed as a template).
Also, $env is used to keep the general template context, for instance to check the OS version in our template config file.

.chezmoiignore

Finally, chezmoi supports an ignore file named .chezmoiignore. The concept is similar to the well known .gitignore: patterns listed in this file are ignored by chezmoi. In other words, some files are stored in your chezmoi repository, but do not reflect in your home. This can be used if you put a README.md in your configuration repository, as you don’t want this file in your home directory. Just write:

README.md

in .chezmoiignore and the README.md won’t be copied in your home.

You can do more advanced things with .chezmoiignore as it is a template by default. From the documentation:

{{- if ne .email "firstname.lastname@company.com" }}
# Ignore .company-directory unless configured with a company email
.company-directory # note that the pattern is not dot_company-directory
{{- end }}

Conclusion

Chezmoi has lot more features, like encryption or installation in GitHub Codespaces. It is quite well documented, in particular with a quick start guide.

I’ve switched to it almost two years ago, I don’t regret it at all!

Bonus: Vim Snippet

To update the target state automatically when editing the source file in the chezmoi repo, I use this vim snippet (with the fish shell):

autocmd BufWritePost ~/.local/share/chezmoi/* ! chezmoi apply --source-path %; or for f in (rg -l 'template "%:t"'); chezmoi apply --source-path $f; end

You should store this source repository in a git repository to easily revert changes and share configuration update between various machines. ↩︎

How I Got Started with NeoVim’s Lua Configuration

Sun, 18 Jul 2021 22:57:01 +0100

Four months ago I was still using SpaceVim when I stumbled upon a blog post on how to configure NeoVim with Lua. I then started to create my own configuration. In this post I’ll share the learnings acquired in the process. I hope you will find this useful to create your own configuration!

Why create your own Vim config from scratch?

Vim has been my daily driver for about ten years. Almost from the beginning, I used Vim distributions for ease of configuration. Spf13 vim first and then SpaceVim. With a distribution, one gets a lot of bells and whistle without spending too much time configuring things. So why spend hours setting up NeoVim from scratch?

SpaceVim does provide a lot of options and plugins so that everyone can find the functionalities they need and discover some new useful tricks. This ends up creating long key mappings like ff and leads to long startup time. For instance on my machine with an SSD drive, it needs between 1 and 2 seconds to start. This is a common problem with distributions.

The long startup time issue can be mitigated by starting Vim less often or by choosing a lighter Vim distribution. One could even reuse only the core and some parts of a distribution, leaving out the rest. Regarding the long key mappings issue, shorter ones could be redefined. However, this has two major drawbacks:

your customized configuration lies on the moving foundations of the underlying distributions,
debugging is made more difficult because of the incorporation of so much code you haven’t written and don’t know well.

To solve all these problems, I found it easier and less time-consuming to have my own configuration. Additional benefits include a better recall of what exists and what functionalities are implemented¹. The good news with NeoVim 0.5 is that you can now use Lua and not an arcane language like VimScript². The result is also quite fast: with my configuration NeoVim starts in 100 to 110 milliseconds.

Starting your own configuration does not mean you can’t draw inspiration from other configurations! The next sections of this post reference guides, snippets and plugins I’ve found useful, so that you can evaluate them for inclusion into your own file.

Enjoy the Ride!

To tailor my experience to my liking, I tried my changes in a new instance of NeoVim after every addition of a plugin or of a set of mappings. Mappings in particular sometime looks good on the screen, but fingers don’t like it that much 😀.

In addition, NeoVim configuration can be notoriously complicated to debug. To quote the documentation:

To find the cause of a problem in your config, you must “bisect” it.

https://neovim.io/doc/user/starting.html#bisect

For this the previous point about regular testing helps, but I would advise for versioning your configuration, for instance with git and chezmoi. With regular commits, you will be able to rely on the git bisect feature when things go wrong.

Guides

Detailed guidance exists online to get started with your configuration. I got started with a mostly one file Lua configuration. This guide contains general explainations on where to put your Lua files, the reasoning behind the changes… If you are not familiar with NeoVim Lua configuration tricks, I strongly recommend reading the above link. See you in a bit 👋.

In addition, these links may prove useful:

Snippets from my Configuration

This section assumes basic knowledge of Lua configuration.

Mapping Hints

Pop up window showing the keys that can follow

Which-Key is a brilliant plugin to display a popup with the possible mappings as you press the keys of the shortcut. For instance, I have mapped j to :tabnew, to open a new tab. On the figure above, I’ve just typed (abbreviated SPC) and the keys that could be pressed then are displayed in a popup at the bottom of the screen. What sets which-key.nvim apart is that you don’t have to configuration your mappings using a special function for it to work. It discovers most of your mappings right away and use them to populate the popup.

I’ve tweaked timeoutlen to get the popup more quickly. I’ve also changed labels for some keys to have shorter or more explicit names, like SPC for .

local wk = require("which-key")
wk.setup {
  key_labels = {
    [""] = "SPC",
    [""] = "RET",
    [""] = "TAB",
  },
}
vim.opt.timeoutlen = 900

Mapping Choices

My custom mappings are mainly around the key, often with only one key following, like s to write the current file. The key is mostly left for plugins, while the is sometimes used for some buffer local mappings.

In general, my mappings are heavily adapted to the BÉPO layout, a Dvorak-like keyboard for French.

Clever-F

rhysd/clever-f.vim extends f, t… so that:

When you press fc, all characters c in the current line get highlighted
Another press on f jumps to the next occurence of c
A press on F jumps backward

This makes , and ; redondant and these can be remapped.

Leaders

The universal leader is by default mapped on \. However, it is frequently remapped to ,, which is easier to reach. Since clever-f freed two mappings, I reuse them like so:

g.mapleader = ","
g.maplocalleader = ";"

Buffer Jump

With the awesome hop.nvim, one can get hints to jump to various parts of a buffer (see the figure below if that does not make sense just yet). It is similiar to EasyMotions and supports jumps by line, word, characters sequences and pattern. However, in my opinion this plugin is not replacement for w and the like, because for short movements I find w or f shorter to type and because the need to read the screen for caracters may be quite slow compared to 3w. It is also not a replacement for / because hop.nvim highlights whats visible on the current buffer. Thus it fills the void left for medium range move.

Word jump example with hop.nvim

I invoqued HopWord from line 105 and if I press dr, I’ll jump to the last word of line 116

Here is my configuration for this plugin:

map('n', 'T', 'HopLineStart')
map('v', 'T', 'HopLineStart')
map('n', 'S', 'HopWord')
map('v', 'S', 'HopWord')
map('n', 'è', 'HopChar2')
map('v', 'è', 'HopChar2')
map('n', 'È', 'HopPattern')
map('v', 'È', 'HopPattern')
require('hop').setup {
  keys = 'auietsrncbpovdljyxqghf', -- Hint keys
}

It is heavily optimized for the the BÉPO layout, whose home row contains the auie keys on the left hand and the tsrn keys on the right hand. Hence the choice to put most mappings on T and S, easily reachable with the right hand and to start the hint keys with auie on the left hand.

Plugins

These plugin are often mostly written in Lua, although vim script plugins can be more mature. The Lua-plugin ecosystem is moving really quickly, you may find that other plugins are more suitable in a couple months.

Plugins I use

Telescope

I use telescope.nvim as a fuzzy finder. It can be slow at times compared to skim or fzf. However, it is relatively easy to script in Lua, making it easy to tightly integrate with other functions.

Completion-nvim

I use nvim-lua/completion-nvim in particular for its chains of completion (several completion sources are chained and sources lower in the chain are used when upper sources don’t have any results). However, nvim-compe may be a better choice if you start fresh.

Complete List

This is a list of plugins I use, roughly ordered by frequency of use.

Click to show the list of plugins

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

Generating Snippets with LuaSnip in Neovim

Markdown Journaling

Lua-Generated Snippets

1. Computing the Date of “Next Friday”

2. Putting Those Dates in LuaSnip

3. Generating Snippets Variants

The Final Code

Conclusion

From UltiSnips to LuaSnip

You “Own” 16 Milion+ IPv4 Addresses!

Introducing 127.0.0.0/8, the Loopback Range

Other Use Cases

Multiple Servers on the Same Port Number

Naming Things

Future of 127.0.0.0/8

And IPv6?

Configuration Management

A Custom Configuration Makes You Feel at Home

Enter Chezmoi

Account for Variations Between Machines

Even More Variations with Templates

.chezmoiignore

Conclusion

Bonus: Vim Snippet

How I Got Started with NeoVim’s Lua Configuration

Why create your own Vim config from scratch?

Enjoy the Ride!

Guides

Snippets from my Configuration

Mapping Hints

Mapping Choices

Clever-F

Leaders

Buffer Jump

Plugins

Plugins I use

Telescope

Completion-nvim

Complete List

Introducing `127.0.0.0/8`, the Loopback Range

Future of `127.0.0.0/8`