dx notes / user log

[josharian]

Hi! One hard thing about software is you never get to know how folks interact with it. So--purely in the spirit of being helpful--here's a quick rundown of my experience with topiary so far. No asks, no request for feedback, no judgment, just giving you visibility. :)

• Heard about topiary on the Future Of Coding slack. Got really excited, seemed like an excellent idea.
• Decided I should try it out on Go HTML templates. I started writing a bespoke formatter for them a while ago after finding that the only existing formatter was unusable, but ran out of steam.
• Cloned, pleased to see it was in Rust (I have ~0 rust experience, but been meaning for ages to learn).
• Got distracted for a few months.
• Picked it up as a holiday project. Build instructions were clear and functional, even for a non-Rust user. I didn't figure out how to get the TOPIARY_LANGUAGE_DIR set at build time. Ignored everything around nix and pre-commit hooks.
• I worried a little that even if I did get the formatter working, I wouldn't be able to distribute it effectively to others. (Can't ask people to use nix. Missing a VSCode integration. Don't want them to have to set env vars; prefer the gofmt "there is only one true formatting" approach over configurability. Would want to unbundle from all the other formatters. Etc.) But decided to just have fun making the formatter and worry about that later.
• Figured a new language would be "experimental", but hit immediate bumps in the docs getting existing experimental formatters working. (Plus I actually would use a good scm formatter, if it was easy to install/use and had good VSCode integration, so there's that.) Delightfully helpful, rapid responses got me unstuck.
• Found it pleasingly easy to hack in a new language, even without docs.
• Struggled a bit to get the existing tree-sitter grammar to play nicely with topiary, presumably because it had never been used with Rust before.
• Got frustrated a bit because the existing grammar I found didn't seem well-suited to formatting; in particular, it didn't materialize intermediate nodes (such as action nodes rather than specific action types, like if nodes, with nodes, etc.), and didn’t materialize end nodes. Decided to ignore that for the moment.
• Didn't figure out a good, efficient workflow for hacking on the grammar, but that's ok.
• Step zero was marking most things as leaf nodes, so the diff was minimal and all whitespace. Then I set about cleaning up whitespace.
• Got stuck. Couldn't figure out how to use prepend_space in a way that preserved idempotency. append_space worked as expected. Looked at existing formatting query files, no insights. Felt like I wanted prepend_space not to insert spaces if they already exist, just like append_space did. But maybe that's because of the details of how this grammar was constructed? Better understand the grammar more...
• Played with topiary visualize. Very helpful.
• ...but still didn't understand what was wrong with prepend_space. Re-read the docs again, still no insight.
• Decided to work on multi-line alignment instead. Discovered that, in this context, fixed alignment isn't very helpful, need something like alignment blocks. Sympathetic to the preferences for elastic tabstops expressed there...but also, I had a practical problem to solve today. The discussion on that issue indicated that alignment blocks probably weren't coming, and mightn't even be welcome if contributed.
• Concluded that topiary isn't a good fit for the problem I have today (formatting Go templates).
• Still excited about the project, would use an scm formatter given sufficient support, and may return to it in the future. But I'm turning my holiday hacking time elsewhere.

Hope that's helpful. I look forward to seeing where topiary has gotten to next time it comes around on the guitar.

[ErinvanderVeen]

Your feedback is very much appreciated!

It is clear we need to communicate much better, and this is absolutely part of our strategy.

We are of course aware of how tree-sitter grammars are typically not well suited for formatting. We have in the past contributed to grammars to make them a little more so, but I expect Topiary will probably always struggle with this regard.

Regarding TOPIARY_LANGUAGE_DIR, that is definitely something we need to improve, thank you for your feedback.

[josharian]

We are of course aware of how tree-sitter grammars are typically not well suited for formatting.

I would enjoy reading about how to design/adapt a grammar to make it more suitable for formatting. And about how to design a good set of topiary formatting queries that play well together, given such a grammar.

Nothing too formal, maybe just a short section in the docs about whatever tips/tricks/guidance/philosophy you’ve learned to date.

[yannham]

@josharian I entirely concur! Although Topiary is still relatively new, so I guess we are figuring this out as we use it. One of the target of Topiary is to make it easy to make a formatter for a new language you are developing. In this case, it's probably more straightforward: you have access (and designed, and implemented yourself) to the original grammar/parser. Usually the tree-sitter grammar is just a coarse oversimplification of this grammar, and you can make it more precise by distinguishing more and syntactical categories and nodes as you need to, by looking at the original grammar, when you start to implement your queries and have an idea of what you want to do in practice.

For example, @ErinvanderVeen basically translated Nickel's LALRPOP grammar to tree-sitter almost one to one (and even before Topiary existed, in fact, just as a principled way to write the tree-sitter grammar from scratch). This happened to serve us well, because we didn't need to update it really to make it work for formatting purpose.

However, it's probably harder for languages you didn't author (even if open-source). And language with an existing tree-sitter grammar written with highlighting in mind.

If possible, looking at the original parser/grammar might help, but I imagine it can be a bit daunting. I think it doesn't take anything away from Topiary, because upgrading an existing tree-sitter grammar (that you'd write anyway for highlighting, probably) is still miles away from having to write a bespoke incremental lossless parser (and transformer, and pretty-printer!), but it's a very valid point, and one that we already ran into when using Topiary on existing languages.

We need to figure out a principled way to adapt a grammar for formatting, indeed.