TQFormat

Applying the TruQu formatting preferences to our Erlang-ish code

TQFormat is a rebar3 plugin for applying our formatting preferences to our code.

It is highly opinionated and very much unconfigurable. The only configuration option concerns the page-width.

It is roughly based on Jean-Philippe Bernardy's A Pretty But Not Greedy Printer, and uses erlfmt for parsing Erlang-ish code into an AST. That AST is then fed to the formatter, which turns the AST into a document-tree. The document-tree, finally, is evaluated given the paper-width, which produces a set of printable lines.

Examples

Our formatting style is largely based on how Emacs formats comma-first Erlang code. Hence, a map like this:

#{this => is, a => record, with => many, keys => and_, values => and_, wont => fit, on => a, single => line}.

will result in the following:

#{ this => is
 , a => record
 , with => many
 , keys => and_
 , values => and_
 , wont => fit
 , on => a
 , single => line
 }.

We inline singular clauses in case (etc) expressions, though multiple expressions will always be laid out as an indented block.

Therefore, this code:

case Foo of bar -> do(something), ok; baz -> help end.

Will be formatted like so:

case Foo of
  bar ->
    do(something),
    ok;
  baz -> help
end.

Usage

tqformat can be used as a standalone escript or as a rebar3 plugin.

As a rebar3 plugin

tqformat can be used as a rebar3 plugin.

{plugins, [tqformat]}.

After adding the plugin, running rebar3 format can be used to figure out what flags and configuration options are available. As an example, the following configuration in rebar.config will cause rebar3 format to format all relevant files in an umbrella application, and cause rebar3 format --verify to verify formatting in those same files.

{ tqformat
, [ { files
    , ["apps/*/{src,test,include}/*.{hrl,erl,app.src}", "rebar.config", "config/*.config"]
    }
  ]
}.

As a standalone escript

tqformat also exists as a standalone escript. This requires having Erlang installed (but then, most Erlang developers do), and accepts the same command line options as the rebar3 plugin.

You can download an escript from the Releases page, or compile your own using rebar3 as release escriptize. This will build an escript into _build/release/bin/tqformat.

Integration with editors

Missing configuration for your favourite editor? Please let us know by opening an issue!

Emacs

Using reformatter.el, setting up tqformat as a formatter can be as simple as this:

(reformatter-define tqformat
    :program "tqformat"
    :args '("-")
    :lighter " TQF")

See also the instructions in the reformatter readme for how to set up format-on-save.

JetBrains IDE

The intellij-tqformat plugin allows using tqformat in all JetBrains IDE products.

VSCode

The tqformat VSCode extension allows using tqformat to format Erlang code in VSCode.

License

TQFormat is released under the Apache 2.0 license, as found in the LICENSE file.