Formatting Options

JuliaFormatter is intended to be configurable and comes with a number of options to control the output of the formatter. Suggestions for more options are welcome; please open an issue!

All of these formatting options can be specified as:

• keyword arguments to JuliaFormatter.format, JuliaFormatter.format_text and JuliaFormatter.format_file
• entries in a .JuliaFormatter.toml file, or
• command-line arguments to the jlfmt command.

Below is a table of all the currently available formatting options, along with what each style sets each option to. Values that differ from DefaultStyle are shown in bold.

align_...

Default: false

The align_assignment, align_conditional, align_pair_arrow, and align_struct_field options allow you to vertically align operators on consecutive lines. See the Custom Alignment page for more details and examples.

align_matrix

Default: false

If enabled, this option preserves pre-existing whitespace surrounding matrix elements in the original source file. If you want to align matrix elements yourself, you should set this to true.

using JuliaFormatter: format_text

# Elements left-aligned in original source
s = """
a = [
100 300 400
1   eee 40000
2   α   b
]"""

format_text(s, align_matrix=true) |> print

a = [
    100 300 400
    1   eee 40000
    2   α   b
]

# Elements right-aligned in original source
s = """
a = [
100 300   400
  1  ee 40000
  2   a     b
]"""

format_text(s, align_matrix=true) |> print

a = [
    100 300   400
      1  ee 40000
      2   a     b
]

always_for_in

Default: false

If true, = is always replaced with in if part of a for loop condition. For example, for i = 1:10 will be transformed to for i in 1:10. Set this to nothing to leave the choice to the user.

always_use_return

Default: false

If true, return will be prepended to the last expression where applicable in function definitions, macro definitions, and do blocks.

Example:

function foo()
    expr1
    expr2
end

to

function foo()
    expr1
    return expr2
end

annotate_untyped_fields_with_any

Default: true

Annotates fields in a type definitions with ::Any if no type annotation is provided:

struct A
    arg1
end

to

struct A
    arg1::Any
end

conditional_to_if

Default: false

If the conditional E ? A : B exceeds the maximum margin converts it into the equivalent if block:

if E
    A
else
    B
end

disallow_single_arg_nesting

Prevents the nesting of a single argument arg in parenthesis, brackets, and curly braces.

# Without `disallow_single_arg_nesting`:
function_call(
    "String argument"
)
[array_item(
    10
)]
{key => value(
    "String value"
)}

# With `disallow_single_arg_nesting` enabled:
function_call("String argument")
[array_item(10)]
{key => value("String value")}

for_in_replacement

Can be used when always_for_in is true to replace the default in with ∈ (\\in), or = instead. The replacement options are ("in", "=", "∈").

for a = 1:10
end

# formatted with always_for_in = true, for_in_replacement = "∈"
for a ∈ 1:10
end

force_long_function_def

Default: false

If true tweaks the behavior of short_to_long_function_def to force the transformation no matter how short the function definition is.

format_docstrings

Default: false

Format code docstrings with the same options used for the code source.

Markdown is formatted with CommonMark alongside Julia code.

import_to_using

Default: false

If true, import expressions are rewritten to using expressions in the following cases:

import A

import A, B, C

is rewritten to:

using A: A

using A: A
using B: B
using C: C

There are some exceptions to this:

• If as is found in the import expression, using cannot be used in this context. The following example will not be rewritten:

  import Base.Threads as th

• If import is used in the following context it is not rewritten. This may change in a future patch.

  @everywhere import A, B

indent

Default: 4

The number of spaces used for one level of indentation.

There is at present no option to use tabs for indentation: please open an issue if you want this feature.

indent_submodule

Default: false

When set to true, submodule(s) appearing in the same file will be indented.

module A
a = 1

module B
b = 2
module C
c = 3
end
end

d = 4

end

will be formatted to:

module A
a = 1

module B
    b = 2
    module C
        c = 3
    end
end

d = 4

end

join_lines_based_on_source

Default: false

When true lines are joined as they appear in the original source file.

function foo(arg1,
                       arg2, arg3
                       )
       body
end

When false and the maximum margin is > than the length of "function foo(arg1, arg2, arg3)" this is formatted to

function foo(arg1, arg2, arg3)
    body
end

When true, arg1 and arg2, arg3 will remain on separate lines even if they can fit on the same line since it's within maximum margin. The indentation is dependent on the style.

function foo(arg1,
    arg2, arg3,
)
end

There are exceptions to this:

if a body1 elseif b body2 else body3 end

will be formatted to the following, even if this option is set to true:

if a
    body1
elseif b
    body2
else
    body3
end

long_to_short_function_def

Default: false

Transforms a long function definition

function f(arg2, arg2)
    body
end

to a short function definition if the short function definition does not exceed the maximum margin.

f(arg1, arg2) = body

See also: short_to_long_function_def.

margin

Default: 92

The maximum length of a line. Code exceeding this margin will, in general, be formatted across multiple lines.

normalize_line_endings

Default: "auto"

One of "unix" (normalize all \r\n to \n), "windows" (normalize all \n to \r\n), "auto" (automatically choose based on which line ending is more common in the file).

pipe_to_function_call

Default: false

If true, x |> f is rewritten to f(x), and x .|> f to f.(x).

remove_extra_newlines

Default: false

If true, superfluous newlines will be removed. For example:

module M



a = 1

function foo()


    return nothing

end


b = 2


end

is rewritten as

module M

a = 1

function foo()
    return nothing
end

b = 2

end

Modules are the only type of code block where it is permissible to keep a single newline prior to the initial or after the final piece of code.

separate_kwargs_with_semicolon

Default: false

When set to true, keyword arguments in a function call will be separated with a semicolon.

f(a, b=1)

->

f(a; b=1)

short_circuit_to_if

If truer, converts shortcircuiting expressions to the equivalent if-expression.

function foo(a, b)
    a || return "bar"

    "hello"

    b && return "ooo"
end

becomes

function foo(a, b)
    if !(a)
        return "bar"
    end

    "hello"

    if b
        return "ooo"
    else
        false
    end
end

short_to_long_function_def

Default: false

Transforms a short function definition

f(arg1, arg2) = body

to a long function definition if the short function definition exceeds the maximum margin, or if force_long_function_def is set to true.

function f(arg2, arg2)
    body
end

See also: long_to_short_function_def.

surround_whereop_typeparameters

Default: true

If true, surrounds type parameters with curly braces if the braces are not already present.

function func(...) where TPARAM
end

becomes

function func(...) where {TPARAM}
end

trailing_comma

Default: true

One of true, false, or nothing.

Trailing commas are added after the final argument when nesting occurs and the closing punctuation appears on the next line.

For example when the following is nested (assuming DefaultStyle):

funccall(arg1, arg2, arg3)

it turns into:

funccall(
    arg1,
    arg2,
    arg3, # trailing comma added after `arg3` (final argument) !!!
)

• When set to true, the trailing comma is always added during nesting.
• When set to false, the trailing comma is always removed during nesting.
• When set to nothing, the trailing comma appears as it does in the original source.

trailing_zero

Default: true

Add a trailing zero, if needed.

variable_call_indent

Default: []

The SciMLStyle supports the additional option variable_call_indent. It permits continuation lines in calls to not align with the opening parenthesis:

# Allowed with and without `Dict in variable_call_indent`
Dict{Int, Int}(1 => 2,
    3 => 4)

# Allowed when `Dict in variable_call_indent`, but
# will be changed to the first example when `Dict ∉ variable_call_indent`.
Dict{Int, Int}(
    1 => 2,
    3 => 4)

whitespace_in_kwargs

Default: true

If true, = in keyword arguments will be surrounded by whitespace.

f(; a=4)

to

f(; a = 4)

Note that if this option is false, the arguments on either side of the equals may sometimes be parenthesised to avoid parsing ambiguities. For example, f(s! = x) will be transformed to f((s!)=x), and f(t = >=(1)) will be transformed to f(t=(>=(1))).

whitespace_ops_in_indices

Default: false

If true, whitespace is added for binary operations in indices. Make this true if you prefer arr[a + b] to arr[a+b]. Additionally, if there's a colon : involved, parenthesis will be added to the LHS and RHS.

Example: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].

whitespace_typedefs

Default: false

If true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.

yas_style_nesting

Default: false

The option yas_style_nesting is set to false by default. Setting it to true makes the SciMLStyle use the YASStyle nesting rules. For other styles, this option has no effect.

# With `yas_style_nesting = false`
function my_large_function(argument1, argument2,
    argument3, argument4,
    argument5, x, y, z)
    foo(x) + goo(y)
end

# With `yas_style_nesting = true`
function my_large_function(argument1, argument2,
                           argument3, argument4,
                           argument5, x, y, z)
    foo(x) + goo(y)
end