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 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 https://domluna.github.io/JuliaFormatter.jl/dev/#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,
    always_for_in::Union{Bool,Nothing} = false,
    for_in_replacement::String = "in",
    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,
    long_to_short_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,
    normalize_line_endings = "auto",
    align_matrix::Bool = false,
    trailing_comma::Bool = false,
    trailing_zero::Bool = true,
    indent_submodule::Bool = false,
    separate_kwargs_with_semicolon::Bool = false,
    surround_whereop_typeparameters::Bool = true,
    variable_call_indent::Vector{String} = []
    short_circuit_to_if::Bool = false,
)::String

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

See https://domluna.github.io/JuliaFormatter.jl/dev/#Formatting-Options for details on available options.

has_semicolon(d::Document, line::Integer)

Returns whether d has a valid semicolon grouping on line.

is_dot_op(x::CSTParser.EXPR)

Checks if the binary operation is a dot operation (e.g. x.y, x..z, x...z). This is different from a dot or broadcast operation.

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.

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.

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.

This is a special prettifier to handle the case of string macros. As such it is not part of pretty.

format"hello"

The above "format" identifier is parsed by CSTParser as if the text is "@format_str". This creates problems when we format without intervention:

1. "@format_str" is printed instead of "format"
2. The state offset is incorrect since the length of "@format_str" is greater than "format"

Returns whether the first unignored parent of cst matches the criteria determined by valid, which is a function that returns a boolean. ignore can be used to ignore certain parent nodes if desired, also a function which returns a boolean.

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

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.