efmt

efmt hex.pm version Documentation Actions Status License

An Erlang code formatter.

Online demo.

Features

An Formatting Example

Before

```erlang -module(example). -export( [fac/1] ).

fac(1)-> 1;fac(N ) -> N*fac( N-1). ```

After

```erlang -module(example). -export([fac/1]).

fac(1) -> 1; fac(N) -> N * fac(N - 1). ```

Installation

With Rebar3

Just add the following line to your rebar.config.

erlang {project_plugins, [rebar3_efmt]}.

Then, you can run the $ rebar3 efmt command.

If you want to provide the default options via rebar.config, please specify an entry that has efmt as the key and efmt's options as the value. erlang {efmt, [{exclude_file, "rebar.config"}]}.

Note that rebar3_efmt tries to automatically download a pre-built binary (see the next section) for your environment. However, if there is not a suitable one, you need to build the efmt binary on your own.

Pre-built binaries

Pre-built binaries for Linux and MacOS are available in the releases page.

console // An example to download the binary for Linux. $ VERSION=0.7.0 $ curl -L https://github.com/sile/efmt/releases/download/${VERSION}/efmt-${VERSION}.x86_64-unknown-linux-musl -o efmt $ chmod +x efmt $ ./efmt

With Cargo

If you have installed cargo (the package manager for Rust), you can install efmt with the following command: console $ cargo install efmt $ efmt

Usage

Formats an Erlang file (assuming example.erl in the above example is located in the current directory): ``console $ efmt example.erl # orrebar3 efmt example.erl`

// You can specify multiple files. $ efmt example.erl rebar.config ... ```

Checks diff between the original text and the formatted one: ``console $ efmt -c example.erl # orrebar3 efmt -c example.erl` --- a/example.erl +++ b/example.erl @@ -1,9 +1,8 @@ -module(example). --export( - [fac/1] -). +-export([fac/1]).

-fac(1)-> -1;fac(N ) --> N*fac( -N-1). + +fac(1) -> + 1; +fac(N) -> + N * fac(N - 1).

// If you omit the filename, all the Erlang-like files (i.e., *.{erl, hrl, app.src} and rebar.config) // are included in the target (if you're in a git repository the files specified by .gitignore are excluded). $ efmt -c ```

Overwrites the original file with the formatted one: ``console $ efmt -w example.erl # orrebar3 efmt -w example.erl`

// As with -c option, you can omit the filename arg. $ emf -w ```

For the other command-line options, please see the help document: ``console // Short doc. $ efmt -h # orrebar3 efmt -h`

// Long doc. $ efmt --help # or rebar3 efmt --help ```

How to keep some areas from being formatted

If you want to keep the style of some areas in your input text, please use @efmt:off and @efmt:on comments as follows:

```erlang foo() -> %% @efmt:off LargeList = [1,2,3,..., 998,999,1000], %% @efmt:on

bar(LargeList).

```

Editor Integrations

Differences with other Erlang formatters

Since I'm not familiar with other Erlang formatters, and the README.md of erlfmt already provides a good comparison table among various formatters, I only describe the differences between efmt and erlfmt here.

Note that in the following examples, I used efmt-v0.7.0 and erlfmt-v1.0.0.

Formatting style

I think the formatting style of efmt is much different from erlfmt. IMO, this is a major point when you decide which one you should choose. If you like the erlfmt style. It's okay. I recommend using erlfmt. But, if you like the efmt style. It's welcomed. Please use efmt.

It's hard work to pick up all difference points here. So I just give you some formatted code examples and hope they give you a sense.

Original code

```erlang -module(foo).

-spec hello(term(), integer()) -> {ok, integer()} | {error, Reason :: term()} | timeout. hello({, _, A, _, [B, _, C]}, D) -> {ok, A + B + C + D}; hello(Error, X) when not isinteger(X); isatom(X) -> {error, Error}; hello(#record{foo=[,_], bar=#{qux := 10}}, World) -> World. ```

Let's see how erlfmt and efmt format the above code.

erlfmt formatted code

$ erlfmt foo.erl ```erlang -module(foo).

-spec hello(term(), integer()) -> {ok, integer()} | {error, Reason :: term()} | timeout. hello({, _, A, _, [B, _, C]}, D) -> {ok, A + B + C + D}; hello(Error, X) when not isinteger(X); isatom(X) -> {error, Error}; hello( #record{ foo = [, _], bar = #{qux := 10} }, World ) -> World. ```

efmt formatted code

$ efmt foo.erl ```erlang -module(foo).

-spec hello(term(), integer()) -> {ok, integer()} | {error, Reason :: term()} | timeout. hello({, _, A, _, [B, _, C]}, D) -> {ok, A + B + C + D}; hello(Error, X) when not isinteger(X); isatom(X) -> {error, Error}; hello(#record{ foo = [, _], bar = #{qux := 10} }, World) -> World. ```

No line width limit

Unlike erlfmt, efmt doesn't provide a feature to ensure each line of the formatted code is within a specified line width (columns).

Error handling

erlfmt seems to try formatting the remaining part of code even if it detected a syntax error. In contrast, efmt aborts once it detects an error.

For instance, let's format the following code. ```erlang -module(bar).

invalid_fun() -> : foo, ok.

valid_fun ()-> ok. ```

Using erlfmt: ```console $ erlfmt bar.erl -module(bar).

invalid_fun() -> : foo, ok.

valid_fun() -> ok. bar.erl:4:5: syntax error before: ':' // valid_fun/0 was formatted and the program exited with 0 (success) ```

Using efmt: ```console $ efmt bar.erl [2021-11-28T11:30:06Z ERROR efmt] Failed to format "bar.erl" Parse failed: --> bar.erl:4:5 4 | : foo, | ^ unexpected token

Error: Failed to format the following files: - bar.erl // The program exited with 1 (error) ```

Macro handling

efmt, as much as possible, processes macros as the Erlang preprocessor does.

Thus, it can cover a wide range of tricky cases. Let's format the following code which is based on a macro usage in sile/jsone/src/jsone.erl: ```erlang -module(baz).

-ifdef('OTPRELEASE'). %% The 'OTPRELEASE' macro introduced at OTP-21, %% so we can use it for detecting whether the Erlang compiler supports new try/catch syntax or not. -define(CAPTURESTACKTRACE, :StackTrace). -define(GETSTACKTRACE, _StackTrace). -else. -define(CAPTURESTACKTRACE,). -define(GETSTACKTRACE, erlang:getstacktrace()). -endif.

decode(Json, Options) -> try {ok, Value, Remainings} = trydecode(Json, Options), checkdecoderemainings(Remainings), Value catch error:{badmatch, {error, {Reason, [StackItem]}}} ?CAPTURESTACKTRACE -> erlang:raise(error, Reason, [StackItem]) end. ```

Using efmt: ```console $ efmt baz.erl -module(baz).

-ifdef('OTPRELEASE'). %% The 'OTPRELEASE' macro introduced at OTP-21, %% so we can use it for detecting whether the Erlang compiler supports new try/catch syntax or not. -define(CAPTURESTACKTRACE, :StackTrace). -define(GETSTACKTRACE, _StackTrace). -else. -define(CAPTURESTACKTRACE, ). -define(GETSTACKTRACE, erlang:getstacktrace()). -endif.

decode(Json, Options) -> try {ok, Value, Remainings} = trydecode(Json, Options), checkdecoderemainings(Remainings), Value catch error:{badmatch, {error, {Reason, [StackItem]}}} ?CAPTURESTACKTRACE-> erlang:raise(error, Reason, [StackItem]) end. ```

Using erlfmt: ```console $ erlfmt baz.erl baz.erl:6:29: syntax error before: ':' -module(baz).

-ifdef('OTPRELEASE'). %% The 'OTPRELEASE' macro introduced at OTP-21, %% so we can use it for detecting whether the Erlang compiler supports new try/catch syntax or not. -define(CAPTURESTACKTRACE, :StackTrace). -define(GETSTACKTRACE, _StackTrace). -else. -define(CAPTURESTACKTRACE,). -define(GETSTACKTRACE, erlang:getstacktrace()). -endif.

decode(Json, Options) -> try {ok, Value, Remainings} = trydecode(Json, Options), checkdecoderemainings(Remainings), Value catch error:{badmatch, {error, {Reason, [StackItem]}}} ?CAPTURESTACKTRACE -> erlang:raise(error, Reason, [StackItem]) end. baz.erl:19:50: syntax error before: '?' ```

Formatting speed

The following benchmark compares the time to format all "*.erl" files contained in the OTP-24 source distribution. ```console // OS and CPU spec. $ uname -a Linux TABLET-GC0A6KVD 5.10.16.3-microsoft-standard-WSL2 #1 SMP Fri Apr 2 22:23:49 UTC 2021 x8664 x8664 x86_64 GNU/Linux $ cat /proc/cpuinfo | grep 'model name' | head -1 model name : 11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz

// Downloads OTP source code. There are 3,737 ".erl" files. $ wget https://erlang.org/download/otp_src_24.1.tar.gz $ tar zxvf otp_src_24.1.tar.gz $ cd otp_src_24.1/ $ find . -name '.erl' | wc -l 3737

// Erlang version: Erlang/OTP 24 [erts-12.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit]

// erlfmt: 17.30s $ time erlfmt (find . -name '*.erl') > /dev/null 2> /dev/null

Executed in 17.30 secs usr time 97.73 secs sys time 10.20 secs

// efmt (w/o include cache): 15.10s $ time efmt --parallel $(find . -name '*.erl') > /dev/null 2> /dev/null

Executed in 15.10 secs usr time 98.83 secs sys time 9.67 secs

// efmt (w/ include cache): 5.84s $ time efmt --parallel $(find . -name '*.erl') > /dev/null 2> /dev/null

Executed in 5.84 secs usr time 43.88 secs sys time 1.28 secs ```

Note that efmt needs to process --include and --include_lib to collect macro definitions in the included files. Once an include file is processed, efmt stores the result into a cache file under .efmt/cache/ dir. The efmt second execution in the above benchmark just reused the cached results instead of processing hole include files. So the execution time was much faster than the first execution.

Development phase

erlfmt has released the stable version (v1), but efmt hasn't. Perhaps some parts of the efmt style will change in future releases until it releases v1.

Limitations

There are some limitations that are not planned to be addressed in the future: - Only supports UTF-8 files - Doesn't process parse transforms - That is, if a parse transform has introduced custom syntaxes in your Erlang code, efmt could fail