API Documentation

AlignGroup

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

• node_inds. Indices of FST nodes affected by alignment.
• nodes. 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, SciMLStyle, MinimalStyle

Formatted Syntax Tree

MinimalStyle()

add_node!(
    t::FST,
    n::FST,
    s::State;
    join_lines::Bool = false,
    max_padding::Int = -1,
    override_join_lines_based_on_source::Bool = false,
)

Appends n to t.

• join_lines if false a NEWLINE node will be added and n will appear on the next line, otherwise it will appear on the same line as the previous node (when printing).
• max_padding >= 0 indicates margin of t should be based on whether the margin of n + max_padding is greater than the current margin of t. Otherwise the margin n will be added to t.
• override_join_lines_based_on_source is only used when join_lines_based_on_source option is true. In which n is added to t as if join_lines_based_on_source was false.

align_binaryopcalls!(fst::FST, op_inds::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.

Adjust whitespace in between matrix elements such that it's the same as the original source file.

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):

Binary
 - Where
 - OP
 - RHS

It's parsed as (2):

Binary
 - Binary
  - LHS
  - OP
  - Where
   - 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

eq_to_in_normalization!(fst::FST, always_for_in::Bool, for_in_replacement::String)
eq_to_in_normalization!(fst::FST, always_for_in::Nothing, for_in_replacement::String)

Transforms

for i = iter body end

=>

for i in iter body end

AND

for i in 1:10 body end

=>

for i = 1:10 body end

always_for_in=nothing disables this normalization behavior.

• https://github.com/domluna/JuliaFormatter.jl/issues/34

Finds the optimal placeholders to turn into a newlines such that the length of the arguments on each line is as close as possible while following margin constraints.

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, .md, .jmd, or .qmd files.

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(mod::Module, args...; options...)

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, .md, .jmd or .qmd file.

See File Options for details on available 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,
    options...,
)::String

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

See Formatting Options for details on available options.

Returns whether fst can be an iterable argument. For example in the case of a function call, which is of type Call:

(a, b, c; k1=v1)

This would return true for a, b, c and k1=v1 and false for all other nodes.

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

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

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

Transforms a long function definition

function f(arg2, arg2)
    body
end

to a short function definition

f(arg1, arg2) = body

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

Example:

@Module.macro

to

Module.@macro

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

Converts the node at idx to a NEWLINE if the current margin plus the additional margin from fst[idx:stop_idx-1] is greater than the allowed margin.

If stop_idx == nothing the range is fst[idx:end].

Returns whether nesting occurred.

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 if applicable.

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

to

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

remove_superfluous_whitespace!(fst::FST)

Soft deletes WHITESPACE or PLACEHOLDER that's directly followed by a NEWLINE or INLINECOMMENT node.

separate_kwargs_with_semicolon!(fst::FST)

Ensures keyword arguments are separated by 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

unnestable_node(cst::JuliaSyntax.GreenNode)

cst is assumed to be a single child node. Returns true if the node is of the syntactic form {...}, [...], or (...).

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.