alanz / rebar3_format

Erlang Formatter for Rebar3

rebar3_format

A rebar plugin for code formatting

Build

$ rebar3 compile

Use

Add the plugin to your rebar config:

{plugins, [rebar3_format]}

Then just call your plugin directly in an existing application:

$ rebar3 format

This will format every Erlang file under /src by default. You can specify the directory/file to format as following:

$ rebar3 format --files src/my_subdir/*.erl
$ rebar3 format --files src/other_subdir/my_file.erl
$ rebar3 format --files test/**/*.erl

To save the formatted files in a different directory you have to pass it as a parameter:

$ rebar3 format --output formatted/

Configuration

The plugin supports the following configuration options in the format section of rebar.config:

• files ([file:filename_all()]):
  • List of wildcard patterns representing the files that will be formatted by default (i.e. when not using --files on command line).
  • The default value is ["src/**/*.?rl"]
• encoding(none | epp:source_encoding()):
  • Encoding to use when writing files.
  • The default value is none.
• paper(pos_integer()):
  • Specifies the preferred maximum number of characters on any line, including indentation.
  • The default value is 100.
• ribbon(pos_integer()):
  • Specifies the preferred maximum number of characters on any line, not counting indentation.
  • The default value is 80.
• break_indent(pos_integer()):
  • Specifies the preferred number of characters to use to indent a line that "breaks" from the previous one (for instance, a clause body after a clause head).
  • The default value is 4.
• sub_indent(pos_integer()):
  • Specifies the preferred number of characters to use to indent a line that "follows" the current one (for instance, a long clause head or a long function application).
  • The default value is 2.
• remove_tabs (boolean()):
  • Erlang's prettypr inserts a tab character each time it has to insert 8 spaces for indentation and that code is in a 100% unconfigurable/unreplaceable/unhookable function. If this setting is true, the formatter will turn those tabs into 8 spaces again.
  • The default value is true.
  • NOTE: We are aware that true is not the actual OTP default but... really? Who wants their code indented with a mixture of tabs and spaces? 🙈

Per-File Configuration

You can tweak any of the options above for a particular file, using the format attribute in it, like this:

-format([{paper, 80}]).

Test

To test the plugin just run rebar3 test. It will essentially run rebar3 format inside test_app. Add modules with any "tricky" formatting you want to test_app/src, and push them to github including the after results. The after results can be tought as the expected output behaviour.

Contribute

To contribute to rebar3_format, please refer to CONTRIBUTING.