erlfmt

The formatter attempts to preserve your existing layout choices in two specific areas by looking at the presence of newlines in the original code:

1. Container Layouts

For containers like lists, tuples, maps, records, and function calls, erlfmt chooses between three layouts:

• Collapsed: The entire collection is on a single line.
• Semi-expanded: The enclosing brackets/braces/parentheses are on their own line, but all elements are on a single line.
• Expanded: Each element is on a separate line.

How to control it:

• To force semi-expanded: Place a newline between the opening bracket and the first element.
• To force expanded: Place a newline between any two elements.
• To force collapsed: Remove all newlines within the container.

2. Clause Layouts

For sequences in functions, case expressions, or receive blocks, the formatter decides if the clause body is printed directly after -> or on a new indented line.

How to control it:

• The layout of the entire sequence is determined by the layout of the first clause. If the first clause has a newline after ->, all subsequent clauses will also have their bodies on new lines. If the first clause is on a single line, the whole sequence will be collapsed.

%% Semi-expanded (newline after opening bracket)
[
    Foo, Bar
]

%% Expanded (newline between elements)
[
    Foo,
    Bar
]

%% Collapsed (no newlines)
[Foo, Bar]

erlfmt is an opinionated formatter that makes specific decisions about comment placement to minimize diff noise and maintain consistency. The project supports two primary styles for comments:

1. Single comments on the same line

This is the chosen layout for erlfmt. Comments are placed on the same line as the code they describe. This style is popular across many languages and minimizes diffs when new fields are added to structures like maps or records.

#{
    A => a, % comment
    B => bb, % another comment
    C => ccc % that comment
}

2. All comments on a new line

An alternative style where comments are placed on their own line above the code. While this is common in Erlang, it does not accommodate trailing comments on the same line, which is a standard practice in many other languages.

#{
    % comment
    A => a,
    % another comment
    B => bb
}

Design Decision: Avoiding Fixed Column Alignment

Unlike some tools (e.g., standard Emacs Erlang mode) that align comments to a fixed column (like 48), erlfmt avoids fixed-column alignment. Fixed alignment causes unnecessary diffs when a line exceeds the chosen column, forcing all subsequent comment lines to be modified. Instead, erlfmt prioritizes minimizing diffs when a single line is changed.

When building tools that consume the erlfmt AST, note that erlfmt_parse deviates from the standard Erlang erl_parse (abstract form) in several key ways. The erlfmt parser introduces more explicit nodes for macros, handles guards differently, and uses more structured representations for lists and functions to facilitate formatting.

Key differences include:

• Record Names: Always represented as a full atom or macro_call node rather than a raw atom.
• Guards: Uses new {guard_or, Anno, GuardAndList} and {guard_and, Anno, Exprs} nodes instead of nested lists.
• Clauses: The clause node structure is {clause, Anno, Head, Guards, Body}. The Head can be a call node, an empty atom (for if), an args node, or a catch node.
• Macros: Introduces {macro_call, Anno, Name, Args}, {macro_string, Anno, Name} (for ??Name syntax), and a special {op, Anno, 'when', Expr, Guard} node for macro arguments.
• Functions and Funs: The function node is {function, Anno, Clauses} (a list of clause or macro_call nodes). The fun node uses a new { 'fun', Anno, Value } structure.
• Lists: Represented as a single list node rather than a chain of cons and nil nodes.
• Concatenation: Implicit string concatenation (e.g., "foo" "bar") is represented by a {concat, Anno, Concatables} node.
• Types: The type node is not used; types follow the same representation as values, with new binary operators like |, ::, and ...

erlfmt enforces a maximum line length by parsing and re-printing code. If a line exceeds the limit, the formatter automatically converts it to a vertical style.

Example of automatic vertical formatting:

Input:

scenario(dial_phone_number(),  ring(), hello(mike),hello(joe), hello(robert),   system_working(), seems_to_be())

Output:

scenario(
    dial_phone_number(),
    ring(),
    hello(mike),
    hello(joe),
    hello(robert),
    system_working(),
    seems_to_be()
)

Note: Line-length enforcement is a best-effort greedy algorithm and may occasionally overrun the selected limit.

Manual Intervention: Because erlfmt is not allowed to change the AST (Abstract Syntax Tree), it cannot perform semantic refactors like extracting variables to shorten lines. If the automatic vertical layout is undesirable, you must manually refactor the code (e.g., extracting a long expression into a variable) to allow it to fit on a single line.