API Documentation

Group of FST node indices and required metadata to potentially align them.

• node_idxs. Indices of FST nodes affected by alignment.
• line_offsets. Line offset of the character nodes may be aligned to

in the source file.

• lens. Length of the FST node prior to the alignment character. Used

to calculate extra whitespace padding.

• whitespaces. Number of whitespaces between the alignment character and

the prior FST node. If this is > 1 it signifies additional whitespace was manually added by the user since the formatter would only use 0 or 1 whitespaces.

DefaultStyle

The default formatting style. See the Style section of the documentation for more details.

See also: BlueStyle, YASStyle

FNode is a node used for formatting which does not have a CSTParser equivalent.

Formatted Syntax Tree

align_binaryopcalls!(fst::FST, op_idxs::Vector{Int})

Aligns binary operator expressions.

Additionally handles the case where a keyword such as const is used prior to the binary op call.

align_conditional!(fst::FST)

Aligns a conditional expression.

align_struct!(fst::FST)

Aligns struct fields.

annotate_typefields_with_any!(fst::FST, s::State)

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

binaryop_to_whereop(fst::FST, s::State)

Handles the case of a function def defined as:

foo(a::A)::R where A = body

In this case instead of it being parsed as (1):

CSTParser.BinaryOpCall
 - CSTParser.WhereOpCall
 - OP
 - RHS

It's parsed as (2):

CSTParser.BinaryOpCall
 - CSTParser.BinaryOpCall
  - LHS
  - OP
  - CSTParser.WhereOpCall
   - R
   - ...
 - OP
 - RHS

(1) is preferrable since it's the same parsed result as:

foo(a::A) where A = body

This transformation converts (2) to (1).

ref https://github.com/julia-vscode/CSTParser.jl/issues/93

Flattens a binary operation call tree if the operation repeats 2 or more times. "a && b && c" will be transformed while "a && b" will not.

format(path, style::AbstractStyle; options...)::Bool

format(
    paths; # a path or collection of paths
    options...,
)::Bool

Recursively descend into files and directories, formatting any .jl files by calling format_file on them.

See format_file and format_text for a description of the options.

This function will look for .JuliaFormatter.toml in the location of the file being formatted, and searching up the file tree until a config file is (or isn't) found. When found, the configurations in the file will overwrite the given options. See Configuration File for more details.

Output

Returns a boolean indicating whether the file was already formatted (true) or not (false).

format_file(filename::AbstractString, style::AbstractStyle; kwargs...)::Bool

format_file(
    filename::AbstractString;
    overwrite::Bool = true,
    verbose::Bool = false,
    format_markdown::Bool = false,
    format_options...,
)::Bool

Formats the contents of filename assuming it's a .jl or .md file. If it's a .md file, Julia code blocks will be formatted in addition to the markdown being normalized.

File Options

If overwrite is true the file will be reformatted in place, overwriting the existing file; if it is false, the formatted version of foo.jl will be written to foo_fmt.jl instead.

If verbose is true details related to formatting the file will be printed to stdout.

If format_markdown is true, .md files are formatted.

Formatting Options

See format_text for description of formatting options.

Output

Returns a boolean indicating whether the file was already formatted (true) or not (false).

format_md(text::AbstractString; style::AbstractStyle = DefaultStyle(), kwargs...)

Normalizes the Markdown source and formats Julia code blocks.

See format_text for description of formatting options.

format_text(
    text::AbstractString;
    style::AbstractStyle = DefaultStyle(),
    indent::Int = 4,
    margin::Int = 92,
    always_for_in::Bool = false,
    whitespace_typedefs::Bool = false,
    whitespace_ops_in_indices::Bool = false,
    remove_extra_newlines::Bool = false,
    import_to_using::Bool = false,
    pipe_to_function_call::Bool = false,
    short_to_long_function_def::Bool = false,
    always_use_return::Bool = false,
    whitespace_in_kwargs::Bool = true,
    annotate_untyped_fields_with_any::Bool = true,
    format_docstrings::Bool = false,
    align_struct_field::Bool = false,
    align_conditional::Bool = false,
    align_assignment::Bool = false,
    align_pair_arrow::Bool = false,
    conditional_to_if = false,
)::String

Formats a Julia source passed in as a string, returning the formatted code as another string.

Formatting Options

indent

The number of spaces used for an indentation.

margin

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

always_for_in

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.

whitespace_typedefs

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

whitespace_ops_in_indices

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].

remove_extra_newlines

If true, superflous 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 allowed to keep a single newline prior to the intial or after the final piece of code.

import_to_using

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

pipe_to_function_call

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

short_to_long_function_def

Transforms a short function definition

f(arg1, arg2) = body

to a long function definition

function f(arg2, arg2)
    body
end

always_use_return

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

whitespace_in_kwargs

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

f(; a=4)

to

f(; a = 4)

An exception to this is if the LHS ends with "!" then even if whitespace_in_kwargs is false, = will still be surrounded by whitespace. The logic behind this intervention being on the following parse the ! will be treated as part of =, as in a "not equal" binary operation. This would change the semantics of the code and is therefore disallowed.

annotate_untyped_fields_with_any

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

struct A
    arg1
end

to

struct A
    arg1::Any
end

format_docstrings

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

Markdown is formatted with CommonMark alongside Julia code.

align_*

See Custom Alignment documentation.

conditional_to_if

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

if E
    A
else
    B
end

is_standalone_shortcircuit(cst::CSTParser.EXPR)

Returns true if the cst is a short-circuit expression (uses &&, ||) and is standalone, meaning it's not directly associated with another statement or expression.

Examples

# this IS a standalone short-circuit
a && b

# this IS NOT a standalone short-circuit
if a && b
end

# this IS NOT a standalone short-circuit
var = a && b

# this IS NOT a standalone short-circuit
@macro a && b

# operation inside parenthesis IS NOT a standalone short-circuit
# operation outside parenthesis IS a standalone short-circuit
(a && b) && c

`length_to(x::FST, ntyps; start::Int = 1)`

Returns the length to any node type in ntyps based off the start index.

move_at_sign_to_the_end(fst::FST, s::State)

NOTE: Assumes fst is the caller name of a macrocall such as @macro or Module.@macro.

Moves @ to the last indentifier.

Example:

@Module.macro

to

Module.@macro

nest_if_over_margin!(
    style,
    fst::FST,
    s::State,
    idx::Int;
    stop_idx::Union{Int,Nothing} = nothing,
)

Converts the node at idx to a NEWLINE if the margin until stop_idx is greater than the allowed margin.

If stop_idx is nothing, the margin of all nodes in fst including and after idx will be included.

pipe_to_function_call_pass!(fst::FST)

Rewrites x |> f to f(x).

prepend_return!(fst::FST, s::State)

Prepends return to the last expression of a block.

function foo()
    a = 2 * 3
    a / 3
end

to

function foo()
    a = 2 * 3
    return a / 3
end

separate_kwargs_with_semicolon!(fst::FST)

Ensures keyword arguments are separated with a ";".

Examples

Replace "," with ";".

a = f(x, y = 3)

->

a = f(x; y = 3)

Move ";" to the prior to the first positional argument.

a = f(x = 1; y = 2)

->

a = f(; x = 1, y = 2)

short_to_long_function_def!(fst::FST, s::State)

Transforms a short function definition

f(arg1, arg2) = body

to a long function definition

function f(arg2, arg2)
    body
end

walk(f, fst::FST, s::State)

Walks fst calling f on each node.

In situations where descending further into a subtree is not desirable f should return a value other than nothing.