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.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...)::BoolJuliaFormatter.format — Methodformat(
+ paths; # a path or collection of paths
+ options...,
+)::BoolRecursively 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).
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.
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,
+)::StringFormats 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) && 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.
