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

Hmrc2ledger

Sun, 21 Aug 2022 08:15:54 +0100

cljoly/hmrc2ledger

Disclaimer: This is not financial advice. It may be outdated or wrong, do your own research.

Convert CSV to ledger price db, to compute foreign transaction CGT (and section 104 holdings).

Contains public sector information licensed under the Open Government Licence v3.0

Ledger.ctags

Sun, 21 Aug 2022 08:15:54 +0100

cljoly/ledger.ctags

If you are using Ledger or one of its variants for your plain text accounting, you get to manage your finances a bit more like you manage code. With plain text files, in your favorite editor.

And yet, as opposed to code in most languages, you don’t have a Language Server Protocol implementation. So it’s a bit harder to get completions on accounts, tags, payees… You have to rely on bespoken support from your editor and that’s often imperfect or slow. Plus, if you declare your accounts and payees, you also can’t jump to the definition easily.

Enter ctags configuration for ledger, which this project provides. It generates tag file that’s understood by your editor, often out of the box (vim/neovim, emacs) or with a generic plugin (Atom, VS Code, TextMate and more). Congrats, your editor now has very fast completions and code navigation!

Installation

You need to have ctags installed¹.

Then drop ledger.ctags in ~/.config/ctags (or whatever ctags is configured to read).

Usage

ctags my/ledger/journal.ldg

will collect all the elements formally declared in the journal file. This means that in the following file:

tag UUID
account Assets
payee Shop
commodity EUR

2022-01-01 * Someone
    Expenses:Food   $10
    Liabilities:Credit Card

only UUID, Assets, Shop and EUR are detected, because they are the only one declared and so the only ones with a definition to jump to. Someone, Expenses, Expenses:Food, $, Liabilities and Liabilities:Credit Card are not declared, so they are ignored by ctags.

Initial List of Accounts, Payees…

As mentioned, ctags only collects elements that are declared. You could write the declarations manually, if you want to have fine-grained control of which accounts you want to actively use and have completions for. But to ease initial bootstrapping, you may want to start by adding everything you currently use in your ledger journals. You can do that with a couple commands.

For accounts, you can use this bash snippet:

ledger accounts | awk '{ print "account", $0}'

For payees:

ledger payees | awk '{ print "payee", $0}'

For tags:

ledger tags | awk '{ print "tag", $0}'

The snippets above output proper ledger definitions for accounts, payees and tags. You can insert these outputs in your journal or in a separate file with all your declarations (say declarations.ledger), that you can then include in your main journal file.

Don’t forget that ctags does not follow includes, so you should pass the file with the definitions to ctags (e.g. ctags declarations.ledger)

Multiple files

If you have multiple ledger journal files, pass them all to ctags (e.g. ctags *.ledger *.ldg) or run it on the current directory:

ctags -R .

Automatic Update with Chezmoi

Chezmoi external feature allows you to auto update and manage the ledger.ctags file, by adding the following to your ~/.local/share/chezmoi/.chezmoiexternal.toml:

[".config/ctags/"]
    type = "archive"
    include = [ "*/ledger.ctags" ]
    url = "https://github.com/cljoly/ledger.ctags/archive/master.zip/"
    stripComponents = 1

Contributing

Contributions (documentation or code improvements in particular) are welcome, see contributing!

Feel free to fill an issue if your declared accounts, tags, payee, alias… are not properly detected.

Acknowledgments

I would like to thank the creators, and all the contributors, of ctags and ledger. This is small configuration to make these two great projects work better together.

Another implementation may work, but it’s untested. Feel free to send a PR though! ↩︎

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

Putting READMEs on your Static Site

Thu, 23 Sep 2021 20:45:11 +0000

⚡ TL;DR

I’m happy to introduce RISS (README In Static Site), a tool that transforms a README like this one and insert it on your website, like so.

Telescope-repo.nvim GitHub page and website, automatically generated from the Readme code.

A README is a Project’s Cover

Your GitHub README is what your visitors on GitHub will encounter first. Thus, it needs to efficiently describe your project. There are a lot of advice online on how to craft a great README.

So you then go on and create a great README. Wonderful! 🎉

But I want the README on my Website

But then, you want to include your README on your static website, for instance in a portfolio or just to have a GitHub-independent homepage. You also want more control on the layout and theme than GitHub has to offer, and perhaps even privacy-preserving analytics. This is a common question and there are options based on ajax or on one GitHub Pages website per repository.

However, dynamically loading the README on the client side sounds like taking a performance hit for what is actually static content. Furthermore, maintaining one full-blown GitHub Pages static website for each small project, might not be worth it.

What if you could just change your README a bit so that it is ready for inclusion in your Eleventy or Hugo personal website, just like any other markdown page?

Enter RISS!

I wrote RISS (README In Static Site) for this very purpose.

With RISS, your project’s README is the source of truth. You just add simple comments for the small bits that need to differ between GitHub and your website. You then give the GitHub README to RISS as an input and the output is a file suitable for inclusion in your static site sources. As your README change and evolves, updating it is easy, you just rerun the script.

Let’s go over some examples!

Post Metadata

Hugo (and other static-site generators) need some metadata at the start of your post, like so:

---
title: "README In Static Site (RISS)"
date: 2021-08-21T08:15:54
description: "💎 Transform and insert your GitHub README in your static site"
---

Of course, we don’t want to have this on GitHub. We thus put it in a comment, so that it remains hidden on GitHub:

given the above comment as input, RISS outputs:

---
title: "README In Static Site (RISS)"
date: 2021-08-21T08:15:54
description: "💎 Transform and insert your GitHub README in your static site"
---

and the resulting file is usable by Hugo!

GitHub prohibits embedding arbitrary scripts for security reason. But what if you want to embed an asciinema player on your project homepage, so that users can play the asciicast as they would a standard video? You can have a placeholder with the link on GitHub as asciinema documentation advises and then use RISS to replace it with the full player on your website. You will find how to do that in the documentation. Plus, here is an example README this one doing this (and the corresponding website, look for the asciicast that autoplays).

See also how to automate the update of all these READMEs with, for instance, GitHub Action.

Thank you for reading!

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. ↩︎

README In Static Site (RISS)

Sat, 21 Aug 2021 08:15:54 +0100

cljoly/readme-in-static-site

This fast script allows you to insert your GitHub README in your static site and apply transformations. For instance, you can read this README on GitHub and on my website.

Why?

The GitHub README of your repo needs to efficiently describe your project to GitHub’s visitor. But featuring your project on your website allows you to (among other things):

have more control on the theme and layout,
insert scripts that GitHub would prohibit (like asciinema),
have your project’s homepage independent of your hosting platform, if you wish to change at some point.

Chances are that for small projects, the page about your project is very similar to the GitHub README. Don’t duplicate efforts, describe the differences! This has been a long-awaited feature, in one form or another.

See this blog post for more details.

Testimonials

RISS made it to the first page of HackerNews and Lobsters and got comments like:

I never really understood the idea to have a separate README and index page. Glad to see i’m not the only one :)

southerntofu

Kudos for making it reusable and not specific to a single static site generator. […]

hannu

[…] A small but good idea, I like how simple riss.awk is.

lifthrasiir

Run It (Nothing to Install)

To try it with Hugo or Zola, run the following in your static-site sources:

wget https://cj.rs/riss.awk
awk -f riss.awk /path/to/my-project/README.md > content/my-project.md

If you don’t use Hugo or Zola, no problem! It should also work with any markdown-based static-site generator. Just put the markdown file where it makes sense for that generator.

To automatically update these files in your static-site sources, see Automate with GitHub Actions below. Since RISS is based on Awk, there is nothing to install, besides copying the script itself!

Example

Add a Front Matter

Most static site generators require a “front matter” at the beginning of a markdown file to attach some metadata. But you don’t want to add this to your GitHub README! Let’s hide this on GitHub and have it in the script’s output.

In you .md file on GitHub, put:





# README In Static Site (RISS)

The output of the script will be:

---
title: "README In Static Site (RISS)"
date: 2021-08-21T10:15:54
---

and this piece of yaml will be hidden on GitHub!

Replace Asciinema Image

You can’t embed the asciinema player on GitHub for security reasons. So the asciinema documentation suggests using an image there and to link it to a webpage with the player. But on your own website, you can embed this player.

In your .md file, put:


[![Finding the repositories with “telescope” in their name, with the README in the panel on the right](https://asciinema.org/a/427156.svg)](https://asciinema.org/a/427156)

The output will contain only the asciinema player:

Note: you also need to add the JS/CSS files of the asciinema player somewhere in your theme. This Hugo module makes it easy.

See the input file (typically on GitHub) and the output of the script. You can find another real word README converted to a webpage (this gives another example of asciinema conversion using a Hugo shortcode).

With some shell scripting, you could also transform all the markdown files in your repo and put them in a subdirectory of your site, so that your project’s documentation, policy, etc… lives on your site or even on a site of its own.

Your Example!

Have you used this script to transform some markdown (or other) and insert it on your website? Open an issue if you would like a link to your use case from this README!

telescope-repo.nvim: readme, website; features an Asciinema clip.
neovide: readme, first iteration of their website, PR setting this up. They have now moved to mdbook and that’s great! RISS makes the first iteration of your website easy and you are free to move to more complete solutions when your project grows.
Hugo APT Repository: readme, website, PR setting it up.

Transformations Reference

The transformations are driven by HTML comments, so that you can have different results when comments are ignored (e.g. in your GitHub README) and after executing the script on your markdown file.

Escaping

It is important that your comment starts at the beginning of the line: spaces are used for escaping, meaning that if the comment has spaces at the beginning of the line, it is ignored.

So this is escaped

Remove

Use these two comments for text you want to have in your raw .md file, but not in the output

Spread the Word

If you find this script useful, please consider inserting the following in your readme:

This will help other people find the script. Thanks for spreading the word!

If you feel especially charitable, you could put this badge somewhere:

with for instance this code:

[![](https://img.shields.io/badge/powered%20by-riss-lightgrey)](https://cj.rs/riss)

Breaking API Changes

We follow semver and any change that change would cause real world READMEs to be converted differently requires a new major version. In particular, the following is a breaking change:

adding new keywords (like remove or insert), as they may be used in the README prior to their introduction in RISS,
changing a keywords syntax.

Benchmark

Processes 17600 lines in 10 ms

$ for i in {1..100}; do shuf README.md >>bench.md; done # Create a big md file
$ wc -l README.md
176 README.md
$ wc -l bench.md
17600 bench.md
$ hyperfine 'awk -f riss.awk README.md' 'awk -f riss.awk bench.md'

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`awk -f riss.awk README.md`	2.8 ± 0.2	2.4	3.7	1.00
`awk -f riss.awk bench.md`	9.7 ± 0.4	8.9	10.7	3.46 ± 0.30

Automate with GitHub Actions

You can automatically update the markdown file in the sources of your site with GitHub Actions. Add this workflow to, for instance, .github/workflows/readme.yml:

name: Update README files

on:
  schedule:
    - cron: '30 */2 * * *'
  push:
    branches:
    - master
  # To run this workflow manually from GitHub GUI
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Check out the repo
      uses: actions/checkout@v2
    - name: Get the latest READMEs
      run: make readme-update
    - name: Commit and push if there are changes
      run: |-
        git diff
        git config --global user.email "bot@example.com"
        git config --global user.name "bot"
        git diff --quiet || (git add -u && git commit -m "Update READMEs")
        git push

and then your Makefile may contain something like:

readme-update:
	curl https://raw.githubusercontent.com/cljoly/readme-in-static-site/main/README.md | awk -f riss.awk >content/readme-in-static-site.md

Alternatively, you might configure your repositories to trigger a website rebuild when committing on your README, for instance using GitHub actions webhooks.

Contributions are Welcome!

Feel free to open an issue to discuss something or to send a PR.

See also the Spread the Word section if you would like to make more folks aware of this script.

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