API Documentation
JuliaFormatter.AlignGroup — TypeAlignGroupGroup 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 — TypeDefaultStyleThe 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_linesiffalsea NEWLINE node will be added andnwill appear
on the next line, otherwise it will appear on the same line as the previous node (when printing).
max_padding>= 0 indicates margin oftshould 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_sourceis only used whenjoin_lines_based_on_sourceoption 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 = bodyIn this case instead of it being parsed as (1):
Binary
+ - Where
+ - OP
+ - RHSIt'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 = bodyThis 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 endAND
for i in 1:10 body end
+
+=>
+
+for i = 1:10 body endalways_for_in=nothing disables this normalization behavior.
- https://github.com/domluna/JuliaFormatter.jl/issues/34
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...)::BoolJuliaFormatter.format — Methodformat(
+ paths; # a path or collection of paths
+ options...,
+)::BoolRecursively 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...,
+)::BoolFormats the contents of filename assuming it's a .jl, .md, .jmd or .qmd file.
File Options
overwrite
default:
true
If true the file will be reformatted in place, overwriting the existing file; if it is false, the formatted version of foo.jl will not be written anywhere.
verbose
default:
false
If true details related to formatting the file will be printed to stdout.
format_markdown
default:
false
If true, Markdown files are also formatted. Julia code blocks will be formatted in addition to the Markdown being normalized.
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).
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} = []
+)::StringFormats a Julia source passed in as a string, returning the formatted code as another string.
Formatting Options
indent
default:
4
The number of spaces used for an indentation.
margin
default:
92
The maximum length of a line. Code exceeding this margin will be formatted across multiple lines.
always_for_in
default:
false
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. Set this to nothing to leave the choice to the user.
whitespace_typedefs
default:
false
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
default:
false
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
default:
false
If true, superfluous newlines will be removed. For example:
module M
+
+
+
+a = 1
+
+function foo()
+
+
+ return nothing
+
+end
+
+
+b = 2
+
+
+endis rewritten as
module M
+
+a = 1
+
+function foo()
+ return nothing
+end
+
+b = 2
+
+endModules are the only type of code block allowed to keep a single newline prior to the initial or after the final piece of code.
import_to_using
default:
false
If true, import expressions are rewritten to using expressions in the following cases:
import A
+
+import A, B, Cis rewritten to:
using A: A
+
+using A: A
+using B: B
+using C: CExceptions:
If as is found in the import expression. using CANNOT be used in this context. The following example will NOT BE rewritten.
import Base.Threads as thIf import is used in the following context it is NOT rewritten. This may change in a future patch.
@everywhere import A, Bpipe_to_function_call
default:
false
If true, x |> f is rewritten to f(x).
short_to_long_function_def
default:
false
Transforms a short function definition
f(arg1, arg2) = bodyto a long function definition if the short function definition exceeds the maximum margin.
function f(arg2, arg2)
+ body
+endlong_to_short_function_def
default:
false
Transforms a long function definition
function f(arg2, arg2)
+ body
+endto a short function definition if the short function definition does not exceed the maximum margin.
f(arg1, arg2) = bodyalways_use_return
default:
false
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
+endto
function foo()
+ expr1
+ return expr2
+endwhitespace_in_kwargs
default:
true
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
default:
true
Annotates fields in a type definitions with ::Any if no type annotation is provided:
struct A
+ arg1
+endto
struct A
+ arg1::Any
+endformat_docstrings
default:
false
Format code docstrings with the same options used for the code source.
Markdown is formatted with CommonMark alongside Julia code.
align_*
default:
false
See Custom Alignment documentation.
conditional_to_if
default:
false
If the conditional E ? A : B exceeds the maximum margin converts it into the equivalent if block:
if E
+ A
+else
+ B
+endnormalize_line_endings
default:
"auto"
One of "unix" (normalize all to ), "windows" (normalize all to ), "auto" (automatically choose based on which line ending is more common in the file).
trailing_comma
default:
true
One of true, false, or nothing.
Trailing commas are added after the final argument when nesting occurs and the closing punctuation appears on the next line.
For example when the following is nested (assuming DefaultStyle):
funccall(arg1, arg2, arg3)it turns into:
funccall(
+ arg1,
+ arg2,
+ arg3, # trailing comma added after `arg3` (final argument) !!!
+)- When set to
true, the trailing comma is always added during nesting. - When set to
false, the trailing comma is always removed during nesting. - When set to
nothing, the trailing comma appears as it does in the original source.
In the Configuration File, a nothing value can be set as the string value "nothing":
trailing_comma = "nothing"trailing_zero
default:
true
Add a trailing zero, if needed.
join_lines_based_on_source
default:
false
When true lines are joined as they appear in the original source file.
function foo(arg1,
+ arg2, arg3
+ )
+ body
+endWhen false and the maximum margin is > than the length of "function foo(arg1, arg2, arg3)" this is formatted to
function foo(arg1, arg2, arg3)
+ body
+endWhen true, arg1 and arg2, arg3 will remain on separate lines even if they can fit on the same line since it's within maximum margin. The indentation is dependent on the style.
function foo(arg1,
+ arg2, arg3,
+)
+endThere are exceptions to this:
if a body1 elseif b body2 else body3 endwill be formatted to the following, even if this option is set to true:
if a
+ body1
+elseif b
+ body2
+else
+ body3
+endThe maximum margin still applies even when this option is set to true.
indent_submodule
default:
false
When set to true, submodule(s) appearing in the same file will be indented.
module A
+a = 1
+
+module B
+b = 2
+module C
+c = 3
+end
+end
+
+d = 4
+
+endwill be formatted to:
module A
+a = 1
+
+module B
+ b = 2
+ module C
+ c = 3
+ end
+end
+
+d = 4
+
+endseparate_kwargs_with_semicolon
default:
false
When set to true, keyword arguments in a function call will be separated with a semicolon.
f(a, b=1)
+
+->
+
+f(a; b=1)surround_whereop_typeparameters
default:
true
Surrounds type parameters with curly brackets when set to true if the brackets are not already present.
function func(...) where TPARAM
+end
+
+->
+
+function func(...) where {TPARAM}
+end
+
+### `for_in_replacement`
+
+Can be used when `always_for_in` is `true` to replace the default `in` with `∈` (`\in`),
+or `=` instead. The replacement options are `("in", "=", "∈")`.
+julia for a = 1:10 end
formatted with alwaysforin = true, forinreplacement = "∈"
for a ∈ 1:10 end ```
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) && cJuliaFormatter.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
+endto a short function definition
f(arg1, arg2) = bodyJuliaFormatter.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.macroto
Module.@macroJuliaFormatter.nest_if_over_margin! — Methodnest_if_over_margin!(
+ style,
+ fst::FST,
+ s::State,
+ idx::Int;
+ stop_idx::Union{Int,Nothing} = nothing,
+)::BoolConverts 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
+endto
function foo()
+ a = 2 * 3
+ return a / 3
+endJuliaFormatter.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) = bodyto a long function definition
function f(arg2, arg2)
+ body
+endJuliaFormatter.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.
