API Documentation
JuliaFormatter.AlignGroup
— TypeAlignGroup
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.
JuliaFormatter.DefaultStyle
— TypeDefaultStyle
The default formatting style. See the Style section of the documentation for more details.
See also: BlueStyle
, YASStyle
, SciMLStyle
, MinimalStyle
JuliaFormatter.FST
— TypeFormatted Syntax Tree
JuliaFormatter.MinimalStyle
— TypeMinimalStyle()
JuliaFormatter.add_node!
— Methodadd_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
iffalse
a NEWLINE node will be added andn
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 oft
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 whenjoin_lines_based_on_source
option istrue
. In which
n
is added to t
as if join_lines_based_on_source
was false.
JuliaFormatter.align_binaryopcalls!
— Methodalign_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.
JuliaFormatter.align_conditional!
— Methodalign_conditional!(fst::FST)
Aligns a conditional expression.
JuliaFormatter.align_matrix!
— MethodAdjust whitespace in between matrix elements such that it's the same as the original source file.
JuliaFormatter.align_struct!
— Methodalign_struct!(fst::FST)
Aligns struct fields.
JuliaFormatter.annotate_typefields_with_any!
— Methodannotate_typefields_with_any!(fst::FST, s::State)
Annotates fields in a type definitions with ::Any
if no type annotation is provided.
JuliaFormatter.binaryop_to_whereop!
— Methodbinaryop_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
JuliaFormatter.eq_to_in_normalization!
— Methodeq_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
JuliaFormatter.find_optimal_nest_placeholders
— MethodFinds 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.
JuliaFormatter.flatten_binaryopcall
— MethodFlattens a binary operation call tree if the operation repeats 2 or more times. "a && b && c" will be transformed while "a && b" will not.
JuliaFormatter.format
— Methodformat(path, style::AbstractStyle; options...)::Bool
JuliaFormatter.format
— Methodformat(
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
).
JuliaFormatter.format
— Methodformat(mod::Module, args...; options...)
JuliaFormatter.format_file
— Methodformat_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
).
JuliaFormatter.format_md
— Methodformat_md(text::AbstractString; style::AbstractStyle = DefaultStyle(), kwargs...)
Normalizes the Markdown source and formats Julia code blocks.
See format_text
for description of formatting options.
JuliaFormatter.format_text
— Methodformat_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.
JuliaFormatter.has_semicolon
— Methodhas_semicolon(d::Document, line::Integer)
Returns whether d
has a valid semicolon grouping on line
.
JuliaFormatter.is_dot_op
— Methodis_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.
JuliaFormatter.is_iterable_arg
— MethodReturns 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.
JuliaFormatter.is_standalone_shortcircuit
— Methodis_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
JuliaFormatter.length_to
— Method`length_to(x::FST, ntyps; start::Int = 1)`
Returns the length to any node type in ntyps
based off the start
index.
JuliaFormatter.long_to_short_function_def!
— Methodlong_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
JuliaFormatter.move_at_sign_to_the_end
— Methodmove_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
JuliaFormatter.nest_if_over_margin!
— Methodnest_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.
JuliaFormatter.p_macrostr_identifier
— MethodThis 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:
- "@format_str" is printed instead of "format"
- The state offset is incorrect since the length of "@format_str" is greater than "format"
JuliaFormatter.parent_is
— MethodReturns 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.
JuliaFormatter.pipe_to_function_call_pass!
— Methodpipe_to_function_call_pass!(fst::FST)
Rewrites x |> f
to f(x)
.
JuliaFormatter.prepend_return!
— Methodprepend_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
JuliaFormatter.remove_superfluous_whitespace!
— Methodremove_superfluous_whitespace!(fst::FST)
Soft deletes WHITESPACE
or PLACEHOLDER
that's directly followed by a NEWLINE
or INLINECOMMENT
node.
JuliaFormatter.separate_kwargs_with_semicolon!
— Methodseparate_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)
JuliaFormatter.short_to_long_function_def!
— Methodshort_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
JuliaFormatter.unnestable_node
— Methodcst
is assumed to be a single child node. Returns true if the node is of the syntactic form {...}, [...], or (...)
.
JuliaFormatter.walk
— Methodwalk(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
.
This function mutates the State's (s
) line_offset
. If this is not desired you should save the value before calling this function and restore it after.