Yesterday, I was working on improving buf’s lsp protobuf semantic tokens, and needed to test out how my changes were working in a real LSP client.

I knew neovim had a couple of helper functions for inspecting the current position; first I tried:

:lua vim.print(vim.inspect_pos())

I figured there must be a function more specifically for semantic tokens:

:lua vim.print(vim.lsp.semantic_tokens.get_at_pos())

But finally I landed on:

:Inspect

(neovim docs)

which prints both treesitter and semantic tokens, but in a much cleaner way than the two lua functions.

I’ve keymapped the underlying vim.show_pos() function to <leader>i in neovim for easier access.

I had assumed that to interact with Tree-sitter in Neovim, you still needed to use the utilities from nvim-treesitter. Apparently that’s not the case — Neovim has had a builtin :InspectTree command that brings up the AST from Tree-sitter in a split window, which is scrollbound to the original window and highlights the selected node in both windows.

It also has a query editor, which I haven’t yet had the need for, but it’s good to know it exists.

TIL about WikiGnomes:

A WikiGnome is a wiki user who makes useful incremental edits without clamoring for attention. WikiGnomes work behind the scenes of a wiki, tying up little loose ends and making things run more smoothly.

Some of the most valuable work can be the tiny changes that leave things in a better place than they were found.

Also, sounds a little like prutsen.

Riffing on Tom MacWright’s “Using super” post from yesterday, I saw the post and immediately thought of using jq.

I thought I might get what he was looking for with my initial attempt, something like:

$ pbpaste | jq '.[].name'
"ALGOLIA_API_KEY"
"AMAZON_AWS_ACCESS_KEY_ID"

… but that left out the wrapper array. I figured I might need some other jq function or pipe, but instead I found that you can just wrap the entire expression in square brackets to wrap the result:

$ pbpaste | jq '[.[].name]'
"ALGOLIA_API_KEY"
"AMAZON_AWS_ACCESS_KEY_ID"

Regardless, jq feels worth the investment, especially given the community (and alternative implementations) built up around it.

neovim released v0.11.0 a little while back, and in the interest of using the defaults, I removed some of my LSP-related keymaps that are now automatically mapped. These are listed at :help lsp-defaults.

TIL about the Postgres citext type (that is, case-insensitive text type), from reading this schema.

Based on this tip from the Postgres docs, this might not be the right type for general text:

Consider using nondeterministic collations (see Section 24.2.2.4) instead of this module. They can be used for case-insensitive comparisons, accent-insensitive comparisons, and other combinations, and they handle more Unicode special cases correctly.

… but if you’re storing something like a username or email address that’s already limited to an ascii-ish character set, and want to keep things unique on a case-insensitive basis, it might be what you’re looking for.

I’ve long struggled with the choice of how to pass around Go values, specifically structs. I was happy to find this article on the topic, specifically the conclusion, reproduced here:

1. Types that are not structs or arrays should be passed by value.
2. Struct types that don’t export their members and are clearly built as immutable value types, like time.Time, should be passed by value. Note that these types are relatively rare, and are even rarer to be defined by you.
3. Arrays and all other struct types should be passed by pointer, whether small, large, stateful, or whatever.
4. If you’re passing data that could be mutated by a concurrent process and its important to you for that data not to be mutated, explicitly make a copy of it before passing it along. Be aware that you can’t just rely on passing the data by value since that does not create a deep copy.

I’ll be referencing this moving forward, and taking the guesswork out of my passing conventions.

Last week I learned that an HTML datetime attribute can represent a duration.

For example:

<time datetime="PT4H18M3S">
  4 hours, 18 minutes and 3 seconds
</time>

The syntax is an ISO 8601 Duration.

Last week, I watched a coworker bring up a file on a different branch using fugitive.vim’s :GBrowse and I was floored: almost daily I find myself using it to open the URL to a file to share (or a few lines).

However, much of the time I’m working on a different branch than the one I want to share, and navigating to the same file on a different branch in the GitHub UI takes too many steps. First, you realize you’re on the wrong branch, then you change branches, then you have to navigate back to the file again.

I had always been vaguely aware of :h fugitive-object, but had never put them to use.

The object you’re looking for is <branch>:%, meaning: bring up this file (%) on branch <branch>.

For example:

:GBrowse main:%

And of course, this just works with all of the :GBrowse variants.

I’ve long wanted to figure out how to get nfnl's directory-local configuration working, but it took me until yesterday to figure it out — mostly by opening a discussion and then realizing my mistakes. 🤡

First, exrc needs to be enabled. This will ultimately load the contents of the generated .nvim.lua file, as described in :help 'exrc'

Next, create an .nfnl.fnl file in the directory. I’ve been creating mine as:

;; .nfnl.fnl
{:source-file-patterns [:.nvim.fnl]}

… which means that nfnl only needs to compile the .nvim.fnl file into .nvim.lua.

From there, I create a .nvim.fnl file with my configuration. Often this is to set up a particular project-local formatter or linter with conform or nvim-lint, so it may look something like:

;; .nvim.fnl
(let [conform (require :conform)]
  (set conform.formatters_by_ft.json [:prettier]))

With this I’ve been able to remove a few $WORK specific formatters.

Lastly, I’ve globally gitignored these files so they aren’t accidentally committed. It’s possible to commit the .nvim.lua files to share with other neovim users that have exrc enabled, but I doubt I’ll use that very often — I’m still undecided on if I’ll commit these for my personal projects.

📁

This isn’t something I’m just learning today, but I’ve looked this up enough to warrant writing it down.

I’m often working on some code, and come across something unrelated that I want to change. So I do — but it really doesn’t belong in this commit or PR/patch/etc.!

(I’ve yet to put in the reps to understand worktrees or jujutsu, which I’m assuming are the “real” answers here.)

For now, you can provide git stash push a filename (or multiple!) to come back to those changes later:

$ git stash push <filename(s)>

I’m sure there’s also a way to do this incrementally with -p or Fugitive’s interface.

📦

TIL of Service Wrappers a technique I’ve used in the past but have never had a name for. It’s essentially an approach to wrapping external APIs. From the article:

• Methods should be named in the language of the service, not the language of the app.
• Arguments should use the domain of the service, not the domain of the app.
• Arguments should be whatever type is directly needed by the service, so passing in complex stuff like Active Record should be avoided.
• The return value should not be a complex object from the third party, but ideally only what data a caller will need (often nothing at all). If it must be a complex object, its name or properties should be in the domain of the service.

The article is written from a Rails perspective, but is broadly useful — always nice to have a name for something useful!

Not sure how I hadn’t seen this before: in Go, you can specify the index of the format argument you want to use for each formatting verb.

Simply enough, from the package docs:

fmt.Sprintf("%[2]d %[1]d\n", 11, 22) // => "22 11"

In the past, I’ve actually done something along the lines of:

s := "test"
fmt.Sprintf("%s %s", s, s) // => "test test"

Instead, you can do:

s := "test"
fmt.Sprintf("%[1]s %[1]s", s) // => "test test"

This came up today at $WORK while providing a table name to a constructed SQL query - the table name needed to be supplied multiple times in an upsert, so we could simply do:

query := fmt.Sprintf(`
INSERT INTO %[1]s (...) VALUES ($1, $2)
ON CONFLICT (...) DO UPDATE SET ... = %[1]s.(...) WHERE %[1]s.(...) = $2;
`, tableName)

Instead of needing to supply tableName three times, it could be supplied once using %[1]s.

These notes are basically cribbed from Ben Johnson’s excellent “Building Production Applications Using Go & SQLite” GopherCon talk, specifically the “Configuring SQLite” section.

Generally speaking, you’ll want to set three PRAGMAs on each SQLite connection:

PRAGMA journal_mode = WAL;
PRAGMA busy_timeout = 5000;
PRAGMA foreign_keys = ON;

In turn,

• PRAGMA journal_mode = WAL; sets the database into WAL journaling mode. Unlike the others, this doesn’t necessarily need to be set on each connection; once a database is in WAL mode it’ll stay in that mode across database connections. WAL journaling mode is recommended for most SQLite server applications, because it makes writers not block readers.

• PRAGMA busy_timeout = 5000; sets the busy_timeout to 5000 milliseconds (5 seconds). Without this setting, if a write transaction is running, and another write transaction starts, the second write transaction will fail immediately.

• PRAGMA foreign_keys = ON; turns on SQLite’s foreign key support. Foreign Keys aren’t enabled by default in SQLite for historical reasons, but foreign keys are great for maintaining data integrity. So – use them!

For a long time, I’ve used commandline as the name for the syntax of code fences in markdown whenever I’ve wanted to denote a shell command or session.

I’ve now realized that I’ve been using the wrong name, and also that there are two separate scenarios to keep in mind:

The first scenario is one-off commands, which should use the syntax sh, or shell. This would be showing something you’d enter directly at the command line.

For example:

brew install git

I leave out the command prompt, because it’s implied by the context that the line is to be entered in a command line. Also, it helps with copy-paste.

The other scenario is showing a shell session, which typically shows the command prompt, an entered command, and the response to the command. In this instance I’d use the console, or sh-session syntax.

For example:

$ git st
?? content/til/markdown-shell.md

🐚

Found a bug in one of our systems at work that deals with jsonb data stored in Postgres today. The quick summary is that one of our systems was looking for the maximum numerical value of a jsonb integer in a table.

A very simplified example:

SELECT
  max(balances)
FROM
  unnest(ARRAY[
    '{"balance": 7}'::jsonb->>'balance',
    '{"balance": 17}'::jsonb->>'balance'
  ]) as balances

This returns 7, because while the “balance” field is a numeric JSON value, the ->> operator turns the value into text! — which makes the comparison a lexicographical one.

Instead, you need to make sure to cast the values before comparing:

SELECT
  max(balances)
FROM
  unnest(ARRAY[
    ('{"balance": 7}'::jsonb->>'balance')::integer,
    ('{"balance": 17}'::jsonb->>'balance')::integer
  ]) as balances

Which returns the expected 17.

I still feel rather new to PostgreSQL, and a few times now in Go I’ve tried to do something along the lines of:

type pgdb struct {
	db *sql.DB
}

func (db *pgdb) getEntityByID(ctx context.Context, ids []string) ([]Entity, error) {
	query := "SELECT * FROM entities WHERE entities.id IN ($1)"

	rows, err := db.db.QueryContext(ctx, query, pq.StringArray(ids))
	/// ...
}

But the query would always fail or retrieve no rows. I’ve always fixed it by switching the IN $1 for a = ANY($1), but never quite understood why.

Researching this a bit more today, I realized that the IN function takes a list of literals, whereas ANY is an array function that takes a single array literal. Thus, when I’m passing a pq.StringArray, it only works with the array function.

I found this out going through lib/pq’s issues, finding this issue with this comment explaining the difference quite well, which also pointed to a simpler case where this comment cleared things up for me.

I wasn’t aware of the Go fmt package %q verb, for quoting strings. Typically, I’ve been escaping the quotes manually and using the %s verb:

fmt.Sprintf("this needs quoting: \"%s\"", "input")

But the %q verb obviates the need for that manual quoting.

From the package documentation:

%s the uninterpreted bytes of the string or slice

%q a double-quoted string safely escaped with Go syntax

And a quick example (on the Go Playground):

package main

import (
	"fmt"
)

func main() {
	test := "I'm a test string"

	fmt.Printf("\"%s\"", test)
	// Output: "I'm a test string"
	fmt.Println()
	fmt.Printf("%q", test)
	// Output: "I'm a test string"
}

When writing HTML templates in Go, knowing about the whitespace modifiers is crucial for keeping both the templates and the output HTML looking good.

For example, if you had the following template, with .SomeText being "foo" and .Something being true:

<a href="/posts">
  <span>
  {{ if .Something }}
  Text
  {{ else }}
  Image
  {{ end }}
  </span>
  {{ .SomeText }}
</a>

The actual output HTML would look something like:

<a href="/posts"><span> Text </span> foo </a>

Which isn’t what you want, because there’s extra spaces — both around “Text” and around “foo”.

Instead, you could do:

<a href="/posts">
  <span>
  {{ if .Something }}
  {{- Text -}}
  {{ else }}
  {{- Image -}}
  {{ end }}
  </span>
  {{- .SomeText -}}
</a>

to get

<a href="/posts"><span>Text</span>foo</a>

Which makes both the source code and HTML nice and neat.

The time.Ticker type in Go is incredibly useful for situations in which polling is needed.

The easiest way to use the Ticker is via the time.Tick function, which just provides access to the ticking channel, which makes it easy to range over:

package main

import (
	"fmt"
	"time"
)

func main() {
	for currentTime := range time.Tick(time.Second) {
		fmt.Println("current time: ", currentTime)
	}
}

For more control, time.NewTicker works wonders — there’s no better example than the one from the docs!

I typically don’t do much with concurrency in Go, but messed around this morning with both oklog/run and sync/errgroup.

I’ve defaulted to using oklog/run in the past, but I realized that while they have similar interfaces, they’re useful for different things:

• oklog/run is useful for long-running processes.
  • think starting up http servers alongside other components, and waiting for one to finish, in which case all other components are signalled to finish.
• sync/errgroup is useful for short-lived, parallel processes.
  • think units of work to be done in parallel, where one process resulting in an error should stop the entire computation.

I’m constantly using jq to deal with JSON via the CLI.

Today I needed to figure out the difference between a key existing with a null value or not existing at all in a bit of JSON.

By default, “querying” a key via jq will return null whether the key exists and is null, or the key doesn’t exist:

△ # NOTE: the following is in fish, but should be straightforward to port to other shells

△ set json '{"test": null}'

△ echo $json | jq .test
null

△ echo $json | jq .nonexistent
null

Instead, you can use the jq’s has function to determine the difference:

△ echo $json | jq 'has("test")'
true

△ echo $json | jq 'has("nonexistent")'
false