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.
+API Reference · JuliaFormatter 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.
@@ -7,14 +7,14 @@
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.
sourceJuliaFormatter.DefaultStyle
— TypeDefaultStyle
The default formatting style. See the Style section of the documentation for more details.
See also: BlueStyle
, YASStyle
, SciMLStyle
, MinimalStyle
sourceJuliaFormatter.FST
— TypeFormatted Syntax Tree
sourceJuliaFormatter.MinimalStyle
— TypeMinimalStyle()
sourceJuliaFormatter.add_node!
— Methodadd_node!(
+manually added by the user since the formatter would only use 0 or 1 whitespaces.
sourceJuliaFormatter.DefaultStyle
— TypeDefaultStyle
The default formatting style. See the Style section of the documentation for more details.
See also: BlueStyle
, YASStyle
, SciMLStyle
, MinimalStyle
sourceJuliaFormatter.FST
— TypeFormatted Syntax Tree
sourceJuliaFormatter.MinimalStyle
— TypeMinimalStyle()
sourceJuliaFormatter.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
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.
sourceJuliaFormatter.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.
sourceJuliaFormatter.align_conditional!
— Methodalign_conditional!(fst::FST)
Aligns a conditional expression.
sourceJuliaFormatter.align_matrix!
— MethodAdjust whitespace in between matrix elements such that it's the same as the original source file.
sourceJuliaFormatter.align_struct!
— Methodalign_struct!(fst::FST)
Aligns struct fields.
sourceJuliaFormatter.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.
sourceJuliaFormatter.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
+)
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.
sourceJuliaFormatter.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.
sourceJuliaFormatter.align_conditional!
— Methodalign_conditional!(fst::FST)
Aligns a conditional expression.
sourceJuliaFormatter.align_matrix!
— MethodAdjust whitespace in between matrix elements such that it's the same as the original source file.
sourceJuliaFormatter.align_struct!
— Methodalign_struct!(fst::FST)
Aligns struct fields.
sourceJuliaFormatter.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.
sourceJuliaFormatter.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
@@ -25,7 +25,7 @@
- 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
sourceJuliaFormatter.eq_to_in_normalization!
— Methodeq_to_in_normalization!(fst::FST, always_for_in::Bool, for_in_replacement::String)
+ - 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
sourceJuliaFormatter.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
=>
@@ -34,16 +34,16 @@
=>
-for i = 1:10 body end
always_for_in=nothing
disables this normalization behavior.
- https://github.com/domluna/JuliaFormatter.jl/issues/34
sourceJuliaFormatter.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.
sourceJuliaFormatter.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.
sourceJuliaFormatter.format
— Methodformat(path, style::AbstractStyle; options...)::Bool
sourceJuliaFormatter.format
— Methodformat(
+for i = 1:10 body end
always_for_in=nothing
disables this normalization behavior.
- https://github.com/domluna/JuliaFormatter.jl/issues/34
sourceJuliaFormatter.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.
sourceJuliaFormatter.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.
sourceJuliaFormatter.format
— Methodformat(path, style::AbstractStyle; options...)::Bool
sourceJuliaFormatter.format
— Methodformat(
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
).
sourceJuliaFormatter.format
— Methodformat(mod::Module, args...; options...)
sourceJuliaFormatter.format_file
— Methodformat_file(
+)::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
).
sourceJuliaFormatter.format
— Methodformat(mod::Module, args...; options...)
sourceJuliaFormatter.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
).
sourceJuliaFormatter.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.
sourceJuliaFormatter.format_text
— Methodformat_text(
+)::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
).
sourceJuliaFormatter.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.
sourceJuliaFormatter.format_text
— Methodformat_text(
text::AbstractString;
style::AbstractStyle = DefaultStyle(),
indent::Int = 4,
@@ -75,7 +75,7 @@
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.
sourceJuliaFormatter.has_semicolon
— Methodhas_semicolon(d::Document, line::Integer)
Returns whether d
has a valid semicolon grouping on line
.
sourceJuliaFormatter.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.
sourceJuliaFormatter.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.
sourceJuliaFormatter.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
+)::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.
sourceJuliaFormatter.has_semicolon
— Methodhas_semicolon(d::Document, line::Integer)
Returns whether d
has a valid semicolon grouping on line
.
sourceJuliaFormatter.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.
sourceJuliaFormatter.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.
sourceJuliaFormatter.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
@@ -90,21 +90,21 @@
# operation inside parenthesis IS NOT a standalone short-circuit
# operation outside parenthesis IS a standalone short-circuit
-(a && b) && c
sourceJuliaFormatter.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.
sourceJuliaFormatter.long_to_short_function_def!
— Methodlong_to_short_function_def!(fst::FST, s::State)
Transforms a long function definition
function f(arg2, arg2)
+(a && b) && c
sourceJuliaFormatter.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.
sourceJuliaFormatter.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
sourceJuliaFormatter.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
sourceJuliaFormatter.nest_if_over_margin!
— Methodnest_if_over_margin!(
+end
to a short function definition
f(arg1, arg2) = body
sourceJuliaFormatter.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
sourceJuliaFormatter.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.
sourceJuliaFormatter.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"
sourceJuliaFormatter.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.
sourceJuliaFormatter.pipe_to_function_call_pass!
— Methodpipe_to_function_call_pass!(fst::FST)
Rewrites x |> f
to f(x)
.
sourceJuliaFormatter.prepend_return!
— Methodprepend_return!(fst::FST, s::State)
Prepends return
to the last expression of a block if applicable.
function foo()
+)::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.
sourceJuliaFormatter.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"
sourceJuliaFormatter.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.
sourceJuliaFormatter.pipe_to_function_call_pass!
— Methodpipe_to_function_call_pass!(fst::FST)
Rewrites x |> f
to f(x)
.
sourceJuliaFormatter.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
sourceJuliaFormatter.remove_superfluous_whitespace!
— Methodremove_superfluous_whitespace!(fst::FST)
Soft deletes WHITESPACE
or PLACEHOLDER
that's directly followed by a NEWLINE
or INLINECOMMENT
node.
sourceJuliaFormatter.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)
+end
sourceJuliaFormatter.remove_superfluous_whitespace!
— Methodremove_superfluous_whitespace!(fst::FST)
Soft deletes WHITESPACE
or PLACEHOLDER
that's directly followed by a NEWLINE
or INLINECOMMENT
node.
sourceJuliaFormatter.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)
->
@@ -112,6 +112,6 @@
->
-a = f(; x = 1, y = 2)
sourceJuliaFormatter.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)
+a = f(; x = 1, y = 2)
sourceJuliaFormatter.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
sourceJuliaFormatter.unnestable_node
— Methodcst
is assumed to be a single child node. Returns true if the node is of the syntactic form {...}, [...], or (...)
.
sourceJuliaFormatter.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
.
Note 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.
sourceSettings
This document was generated with Documenter.jl version 1.5.0 on Friday 26 July 2024. Using Julia version 1.10.4.
+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.