A rebar plugin for code formatting
$ rebar3 compile
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/
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"]
- List of wildcard patterns representing the files that will be formatted by default (i.e. when not using
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 istrue
, 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? 🙈
- Erlang's
remove_trailing_spaces
(boolean()
):- If this setting is
true
, the formatter will remove all trailing whitespaces. - The default value is
true
.
- If this setting is
inline_items
(boolean()
):- Specifies the desired behavior when using multiple lines for a multi-item structure (i.e. tuple, list, map, etc.).
- When this flag is on, the formatter will try to fit as many items in each line as permitted by
paper
andribbon
. - When the flag is off, the formatter will place each item in its own line.
- The default value is
true
.
inline_expressions
(boolean()
):- Specifies if sequential expressions in a clause should be placed in the same line if
paper
andribbon
allows it or if each expression should be placed in its own line. - The default value is
true
.
- Specifies if sequential expressions in a clause should be placed in the same line if
preserve_empty_lines
(boolean()
):- Specifies if blank lines should be preserved when formatting.
- This option is only used when
inline_expressions
isfalse
. - If this option is
true
, one empty line will preserved for each group of empty lines that are placed between expressions in a clause. - The default value is
false
.
newline_after_attributes
(boolean()
):- Specifies if attributes must be separated from the code below them by an empty line.
- The default value is
true
.
You can tweak any of the options above for a particular file, using the format
attribute in it, like this:
-format([{paper, 80}]).
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.
To contribute to rebar3_format, please refer to CONTRIBUTING.