API Documentation

DefaultStyle

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

YASStyle()

Formatting style based on https://github.com/jrevels/YASGuide and https://github.com/domluna/JuliaFormatter.jl/issues/198.

Recommended options are:

• always_for_in = true
• whitespace_ops_in_indices = true
• whitespace_typedefs = false
• remove_extra_newlines = true
• import_to_using = true
• pipe_to_function_call = true
• short_to_long_function_def = true
• always_use_return = true
• whitespace_in_kwargs = false

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;
    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 .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;
    indent::Int = 4,
    margin::Int = 92,
    style::AbstractStyle = DefaultStyle(),
    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,
)::String

Normalizes the Markdown source and formats Julia code blocks.

See format_text for description of formatting options.

format_text(
    text::AbstractString;
    indent::Int = 4,
    margin::Int = 92,
    style::AbstractStyle = DefaultStyle(),
    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,
)::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:

a = 1



b = 2

is rewritten as

a = 1

b = 2

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.

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

Formatted Syntax Tree

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.

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

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.