Experience with formatting a code base with topiary

Community
1

At LexiFi we are in the same boat: we have been using ocp-indent for ages, and continue to do so, and are happy with it. However, and mostly for the benefit of beginners and general user-friendliness of the codebase, we would be interested in switching to something more normative. We did some experiments with OCamlFormat but we find that it simply discards too much of the source formatting (which can encode subtle aspects of the underlying code), and this is a pity in a codebase that has ~20y of history. Also, we find some of the stylistic choices debatable (but this is cosmetic). So we never took the plunge.

Given this, I am also quite interested in the Topiary approach which in my view has two clear advantages over OCamlFormat:

  • It uses a CST (like all TreeSitter-based grammarware), so by construction it is well-placed to preserve the source formatting when this is desired;
  • The actual formatting specification is an explicit input of the tool (the TreeSitter “query”), which means that the user has full power to customize the formatting style without needing any special support or toggles from the tool.

I did some experiments with Topiary. I found that it was a bit slow for interactive use (eg format-on-save), see Topiary slow? · Issue #442 · tweag/topiary · GitHub. But this is something that could be adressed with some architectural changes (eg a “server mode”). Also the included formatting style exhibits quadratic behaviours on some constructions, but this is probably easy to fix, hence minor.

In the end, I haven’t yet decided to invest more time in investigating Topiary because it is hard to know if the approach (and the project) will stick and perdure in the long term or if it will shrivel and die :slight_smile: (having some assurance about the longevity of technical choices is a big thing in industrial settings).

Cheers,
Nicolas

9 Likes
2

This is actually something that always bothered me with these whole file formatting approaches. I don’t really want the code to suddenly format when I save, I want a more ocp-indent experience where formatting gradually happens as I code. Perhaps ocp-indent with a sligthly larger formatting context.

1 Like
3

It uses a CST (like all TreeSitter-based grammarware), so by construction it is well-placed to preserve the source formatting when this is desired;

With regards to this, ocamlformat has been moving towards a CST for a while. There was an option to preserve begin/end for a while, but we have added a bunch recently. There is no plan to finish it yet, but it might already be better in that regard than it was a few years ago.

The actual formatting specification is an explicit input of the tool (the TreeSitter “query”), which means that the user has full power to customize the formatting style without needing any special support or toggles from the tool.

This is clearly outside the scope of ocamlformat, using topiary if you need it seems like a good idea.

4

Slow or not, topiary supports tab indentation for accessibility which the alternatives do not–so it will stay my preferred formatter.

$ cd $PROJECT
$ mkdir .topiary
$ $EDITOR .topiary/languages.toml

[[language]]
name = "ocaml"
extensions = [ "ml", "mli" ]
indent = "	"
1 Like