From 8cd2bc3bd2b176720d8cc190b45833f58b097d1e Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 26 Sep 2024 02:25:59 +0000 Subject: [PATCH] build based on 81ac989 --- previews/PR870/.documenter-siteinfo.json | 2 +- previews/PR870/api/index.html | 24 +++++++++---------- previews/PR870/blue_style/index.html | 4 ++-- previews/PR870/config/index.html | 2 +- previews/PR870/custom_alignment/index.html | 2 +- previews/PR870/how_it_works/index.html | 2 +- previews/PR870/index.html | 10 ++++++-- previews/PR870/integrations/index.html | 2 +- previews/PR870/sciml_style/index.html | 4 ++-- previews/PR870/search_index.js | 2 +- previews/PR870/skipping_formatting/index.html | 2 +- previews/PR870/style/index.html | 2 +- previews/PR870/transforms/index.html | 2 +- previews/PR870/yas_style/index.html | 4 ++-- 14 files changed, 35 insertions(+), 29 deletions(-) diff --git a/previews/PR870/.documenter-siteinfo.json b/previews/PR870/.documenter-siteinfo.json index 5ae8efbc..a563ed2c 100644 --- a/previews/PR870/.documenter-siteinfo.json +++ b/previews/PR870/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-25T20:03:10","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-26T02:25:52","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/previews/PR870/api/index.html b/previews/PR870/api/index.html index 97b11c8e..f39adfc0 100644 --- a/previews/PR870/api/index.html +++ b/previews/PR870/api/index.html @@ -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.source
JuliaFormatter.DefaultStyle — Type
DefaultStyle

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

See also: BlueStyle, YASStyle, SciMLStyle, MinimalStyle

source
JuliaFormatter.FST — Type

Formatted Syntax Tree

source
JuliaFormatter.MinimalStyle — Type
MinimalStyle()
source
JuliaFormatter.add_node! — Method
add_node!(
+manually added by the user since the formatter would only use 0 or 1 whitespaces.
source
JuliaFormatter.DefaultStyle — Type
DefaultStyle

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

See also: BlueStyle, YASStyle, SciMLStyle, MinimalStyle

source
JuliaFormatter.FST — Type

Formatted Syntax Tree

source
JuliaFormatter.MinimalStyle — Type
MinimalStyle()
source
JuliaFormatter.add_node! — Method
add_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.

source
JuliaFormatter.align_binaryopcalls! — Method
align_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.

source
JuliaFormatter.align_conditional! — Method
align_conditional!(fst::FST)

Aligns a conditional expression.

source
JuliaFormatter.align_matrix! — Method

Adjust whitespace in between matrix elements such that it's the same as the original source file.

source
JuliaFormatter.align_struct! — Method
align_struct!(fst::FST)

Aligns struct fields.

source
JuliaFormatter.annotate_typefields_with_any! — Method
annotate_typefields_with_any!(fst::FST, s::State)

Annotates fields in a type definitions with ::Any if no type annotation is provided.

source
JuliaFormatter.binaryop_to_whereop! — Method
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):

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.

source
JuliaFormatter.align_binaryopcalls! — Method
align_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.

source
JuliaFormatter.align_conditional! — Method
align_conditional!(fst::FST)

Aligns a conditional expression.

source
JuliaFormatter.align_matrix! — Method

Adjust whitespace in between matrix elements such that it's the same as the original source file.

source
JuliaFormatter.align_struct! — Method
align_struct!(fst::FST)

Aligns struct fields.

source
JuliaFormatter.annotate_typefields_with_any! — Method
annotate_typefields_with_any!(fst::FST, s::State)

Annotates fields in a type definitions with ::Any if no type annotation is provided.

source
JuliaFormatter.binaryop_to_whereop! — Method
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):

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

source
JuliaFormatter.eq_to_in_normalization! — Method
eq_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

source
JuliaFormatter.eq_to_in_normalization! — Method
eq_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,36 +34,36 @@
 
 =>
 
-for i = 1:10 body end

always_for_in=nothing disables this normalization behavior.

  • https://github.com/domluna/JuliaFormatter.jl/issues/34
source
JuliaFormatter.find_optimal_nest_placeholders — Method

Finds 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.

source
JuliaFormatter.flatten_binaryopcall — Method

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.

source
JuliaFormatter.format — Method
format(path, style::AbstractStyle; options...)::Bool
source
JuliaFormatter.format — Method
format(
+for i = 1:10 body end

always_for_in=nothing disables this normalization behavior.

  • https://github.com/domluna/JuliaFormatter.jl/issues/34
source
JuliaFormatter.find_optimal_nest_placeholders — Method

Finds 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.

source
JuliaFormatter.flatten_binaryopcall — Method

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.

source
JuliaFormatter.format — Method
format(path, style::AbstractStyle; options...)::Bool
source
JuliaFormatter.format — Method
format(
     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).

source
JuliaFormatter.format — Method
format(mod::Module, args...; options...)
source
JuliaFormatter.format_file — Method
format_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).

source
JuliaFormatter.format — Method
format(mod::Module, args...; options...)
source
JuliaFormatter.format_file — Method
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, .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).

source
JuliaFormatter.format_md — Method
format_md(text::AbstractString; style::AbstractStyle = DefaultStyle(), kwargs...)

Normalizes the Markdown source and formats Julia code blocks.

See format_text for description of formatting options.

source
JuliaFormatter.format_text — Method
format_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).

source
JuliaFormatter.format_md — Method
format_md(text::AbstractString; style::AbstractStyle = DefaultStyle(), kwargs...)

Normalizes the Markdown source and formats Julia code blocks.

See format_text for description of formatting options.

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

source
JuliaFormatter.is_iterable_arg — Method

Returns 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.

source
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.

source
JuliaFormatter.long_to_short_function_def! — Method
long_to_short_function_def!(fst::FST, s::State)

Transforms a long function definition

function f(arg2, arg2)
+)::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.

source
JuliaFormatter.is_iterable_arg — Method

Returns 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.

source
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.

source
JuliaFormatter.long_to_short_function_def! — Method
long_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
source
JuliaFormatter.move_at_sign_to_the_end — Method
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 identifier.

Example:

@Module.macro

to

Module.@macro
source
JuliaFormatter.nest_if_over_margin! — Method
nest_if_over_margin!(
+end

to a short function definition

f(arg1, arg2) = body
source
JuliaFormatter.move_at_sign_to_the_end — Method
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 identifier.

Example:

@Module.macro

to

Module.@macro
source
JuliaFormatter.nest_if_over_margin! — Method
nest_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.

source
JuliaFormatter.pipe_to_function_call_pass! — Method
pipe_to_function_call_pass!(fst::FST)

Rewrites x |> f to f(x).

source
JuliaFormatter.prepend_return! — Method
prepend_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.

source
JuliaFormatter.pipe_to_function_call_pass! — Method
pipe_to_function_call_pass!(fst::FST)

Rewrites x |> f to f(x).

source
JuliaFormatter.prepend_return! — Method
prepend_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
source
JuliaFormatter.remove_superfluous_whitespace! — Method
remove_superfluous_whitespace!(fst::FST)

Soft deletes WHITESPACE or PLACEHOLDER that's directly followed by a NEWLINE or INLINECOMMENT node.

source
JuliaFormatter.separate_kwargs_with_semicolon! — Method
separate_kwargs_with_semicolon!(fst::FST)

Ensures keyword arguments are separated by a ";".

Examples

Replace "," with ";".

a = f(x, y = 3)
+end
source
JuliaFormatter.remove_superfluous_whitespace! — Method
remove_superfluous_whitespace!(fst::FST)

Soft deletes WHITESPACE or PLACEHOLDER that's directly followed by a NEWLINE or INLINECOMMENT node.

source
JuliaFormatter.separate_kwargs_with_semicolon! — Method
separate_kwargs_with_semicolon!(fst::FST)

Ensures keyword arguments are separated by a ";".

Examples

Replace "," with ";".

a = f(x, y = 3)
 
 ->
 
@@ -71,6 +71,6 @@
 
 ->
 
-a = f(; x = 1, y = 2)
source
JuliaFormatter.short_to_long_function_def! — Method
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)
+a = f(; x = 1, y = 2)
source
JuliaFormatter.short_to_long_function_def! — Method
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
source
JuliaFormatter.unnestable_node — Method

cst is assumed to be a single child node. Returnss true if the node is of the syntactic form {...}, [...], or (...).

source
JuliaFormatter.walk — Method
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.

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.

source
+endsource
JuliaFormatter.unnestable_node — Method

cst is assumed to be a single child node. Returnss true if the node is of the syntactic form {...}, [...], or (...).

source
JuliaFormatter.walk — Method
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.

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.

source
diff --git a/previews/PR870/blue_style/index.html b/previews/PR870/blue_style/index.html index 26338832..7a925ce9 100644 --- a/previews/PR870/blue_style/index.html +++ b/previews/PR870/blue_style/index.html @@ -1,3 +1,3 @@ -Blue Style · JuliaFormatter
GitHub

Blue Style

JuliaFormatter.BlueStyle — Type
BlueStyle()

Formatting style based on BlueStyle and JuliaFormatter#283.

Note

This style is still work-in-progress, and does not yet implement all of the BlueStyle guide.

Configurable options with different defaults to DefaultStyle are:

  • always_use_return = true
  • short_to_long_function_def = true
  • whitespace_ops_in_indices = true
  • remove_extra_newlines = true
  • always_for_in = true
  • import_to_using = true
  • pipe_to_function_call = true
  • whitespace_in_kwargs = false
  • annotate_untyped_fields_with_any = false
  • separate_kwargs_with_semicolon = true
source

Configuration File Example

The .JuliaFormatter.toml which represents these settings is

style = "blue"

Or to use BlueStyle except change one of the settings:

style = "blue"
-remove_extra_newlines = false

Direct Usage

format("file.jl", BlueStyle())

Or to use BlueStyle except change one of the settings:

format("file.jl", BlueStyle(), remove_extra_newlines=false)
+Blue Style · JuliaFormatter
GitHub

Blue Style

JuliaFormatter.BlueStyle — Type
BlueStyle()

Formatting style based on BlueStyle and JuliaFormatter#283.

Note

This style is still work-in-progress, and does not yet implement all of the BlueStyle guide.

Configurable options with different defaults to DefaultStyle are:

  • always_use_return = true
  • short_to_long_function_def = true
  • whitespace_ops_in_indices = true
  • remove_extra_newlines = true
  • always_for_in = true
  • import_to_using = true
  • pipe_to_function_call = true
  • whitespace_in_kwargs = false
  • annotate_untyped_fields_with_any = false
  • separate_kwargs_with_semicolon = true
source

Configuration File Example

The .JuliaFormatter.toml which represents these settings is

style = "blue"

Or to use BlueStyle except change one of the settings:

style = "blue"
+remove_extra_newlines = false

Direct Usage

format("file.jl", BlueStyle())

Or to use BlueStyle except change one of the settings:

format("file.jl", BlueStyle(), remove_extra_newlines=false)
diff --git a/previews/PR870/config/index.html b/previews/PR870/config/index.html index a518136b..26dc1c1c 100644 --- a/previews/PR870/config/index.html +++ b/previews/PR870/config/index.html @@ -11,4 +11,4 @@ │ ├─ .JuliaFormatter.toml │ └─ sub_code1.jl └─ subdir2 - └─ sub_code2.jl

and call format("dir"), code.jl and sub_code2.jl will be formatted according to the rules defined in dir/.JuliaFormatter.toml, while formatting sub_code1.jl will be configured by dir/subdir1/.JuliaFormatter.toml.

Ignoring specific files and directories

If there is an entry in .JuliaFormatter.toml with

ignore = ["file.jl", "directory", "file_*.jl"]

then all of these files will be reported as already formatted: ./file.jl, ./directory/something.jl ./other_directory/file.jl, file_1.jl, .other_directory/file_name.jl.

+ └─ sub_code2.jl

and call format("dir"), code.jl and sub_code2.jl will be formatted according to the rules defined in dir/.JuliaFormatter.toml, while formatting sub_code1.jl will be configured by dir/subdir1/.JuliaFormatter.toml.

Ignoring specific files and directories

If there is an entry in .JuliaFormatter.toml with

ignore = ["file.jl", "directory", "file_*.jl"]

then all of these files will be reported as already formatted: ./file.jl, ./directory/something.jl ./other_directory/file.jl, file_1.jl, .other_directory/file_name.jl.

diff --git a/previews/PR870/custom_alignment/index.html b/previews/PR870/custom_alignment/index.html index db2bbca5..a96ca167 100644 --- a/previews/PR870/custom_alignment/index.html +++ b/previews/PR870/custom_alignment/index.html @@ -133,4 +133,4 @@ 100 300 400 1 ee 40000 2 a b -] +] diff --git a/previews/PR870/how_it_works/index.html b/previews/PR870/how_it_works/index.html index 76d4a1b5..6cbea248 100644 --- a/previews/PR870/how_it_works/index.html +++ b/previews/PR870/how_it_works/index.html @@ -31,4 +31,4 @@ ..., argument120 ) # way over margin limit !!! -end

You can read how code is nested in the style section.

Once the FST has been nested it's then printed out to a file and voila! You have a formatted version of your code!

+end

You can read how code is nested in the style section.

Once the FST has been nested it's then printed out to a file and voila! You have a formatted version of your code!

diff --git a/previews/PR870/index.html b/previews/PR870/index.html index 46944dbb..8faeca6d 100644 --- a/previews/PR870/index.html +++ b/previews/PR870/index.html @@ -43,7 +43,7 @@ using B: B using C: C

Exceptions:

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 th

If import is used in the following context it is NOT rewritten. This may change in a future patch.

@everywhere import A, B

pipe_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) = body

to a long function definition if the short function definition exceeds the maximum margin. Or if force_long_function_def is set to true.

function f(arg2, arg2)
     body
-end

force_long_function_def

default: false

If true tweaks the behavior of short_to_long_function_def to force the transformation no matter how short the function definition is.

long_to_short_function_def

default: false

Transforms a long function definition

function f(arg2, arg2)
+end

force_long_function_def

default: false

If true tweaks the behavior of short_to_long_function_def to force the transformation no matter how short the function definition is.

long_to_short_function_def

default: false

Transforms a long function definition

function f(arg2, arg2)
     body
 end

to a short function definition if the short function definition does not exceed the maximum margin.

f(arg1, arg2) = body

always_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
@@ -138,11 +138,17 @@
                            argument5, x, y, z)
     foo(x) + goo(y)
 end

short_circuit_to_if

You can convert short circuit expressions to the equivalent if expression.

b0 && foo()
+
 b1 || bar()

respectively become

if b0
     foo()
+else
+    false
 end
+
 if !b1
     bar()
+else
+    true
 end

disallow_single_arg_nesting

Prevents the nesting of a single argument arg in parenthesis, brackets, and curly braces.

# Without `disallow_single_arg_nesting`:
 function_call(
     "String argument"
@@ -200,4 +206,4 @@
 
     a * b
     end
-end

Notice the contents of @muladd begin is not indented.

#!: format: noindent can also be nested.

Editor Plugins

For integration with other editors:

+end

Notice the contents of @muladd begin is not indented.

#!: format: noindent can also be nested.

Editor Plugins

For integration with other editors:

diff --git a/previews/PR870/integrations/index.html b/previews/PR870/integrations/index.html index f682702e..efdab82d 100644 --- a/previews/PR870/integrations/index.html +++ b/previews/PR870/integrations/index.html @@ -5,4 +5,4 @@ rev: "v1.0.18" # or whatever the desired release is hooks: - id: "julia-formatter" -# ... other repos you may have

You can find a list of releases here. Be sure to use the entire version string! (You can double-check this by opening the release and looking at the part of the URL that follows .../releases/tag/VERSION.)

+# ... other repos you may have

You can find a list of releases here. Be sure to use the entire version string! (You can double-check this by opening the release and looking at the part of the URL that follows .../releases/tag/VERSION.)

diff --git a/previews/PR870/sciml_style/index.html b/previews/PR870/sciml_style/index.html index 9fdd8019..68913786 100644 --- a/previews/PR870/sciml_style/index.html +++ b/previews/PR870/sciml_style/index.html @@ -1,5 +1,5 @@ -SciML Style · JuliaFormatter
GitHub

SciML Style

JuliaFormatter.SciMLStyle — Type
SciMLStyle()

Formatting style based on SciMLStyle.

Note

This style is still work-in-progress.

Configurable options with different defaults to DefaultStyle are:

  • whitespace_ops_in_indices = true
  • remove_extra_newlines = true
  • always_for_in = true
  • whitespace_typedefs = true,
  • normalize_line_endings = "unix"
source

Configuration File Example

The .JuliaFormatter.toml which represents these settings is

style = "sciml"

Or to use SciMLStyle except change one of the settings:

style = "sciml"
+SciML Style · JuliaFormatter
GitHub
SciML Style
JuliaFormatter.SciMLStyle — Type
SciMLStyle()
Formatting style based on SciMLStyle.
Note
This style is still work-in-progress.
Configurable options with different defaults to DefaultStyle are:
  • whitespace_ops_in_indices = true
  • remove_extra_newlines = true
  • always_for_in = true
  • whitespace_typedefs = true,
  • normalize_line_endings = "unix"
source
Configuration File Example
The .JuliaFormatter.toml which represents these settings is
style = "sciml"
Or to use SciMLStyle except change one of the settings:
style = "sciml"
 remove_extra_newlines = false
Direct Usage
format("file.jl", SciMLStyle())
Or to use SciMLStyle except change one of the settings:
format("file.jl", SciMLStyle(), remove_extra_newlines=false)
Additional Options
The SciMLStyle supports the additional options variable_call_indent and yas_style_nesting.
The option variable_call_indent is set to [] by default. It allows calls without aligning to the opening parenthesis:
# Allowed with and without `Dict in variable_call_indent`
 Dict{Int, Int}(1 => 2,
     3 => 4)
@@ -20,4 +20,4 @@
                            argument3, argument4,
                            argument5, x, y, z)
     foo(x) + goo(y)
-end

+end
diff --git a/previews/PR870/search_index.js b/previews/PR870/search_index.js index 08dca119..802245f0 100644 --- a/previews/PR870/search_index.js +++ b/previews/PR870/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"sciml_style/#SciML-Style","page":"SciML Style","title":"SciML Style","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"SciMLStyle","category":"page"},{"location":"sciml_style/#JuliaFormatter.SciMLStyle","page":"SciML Style","title":"JuliaFormatter.SciMLStyle","text":"SciMLStyle()\n\nFormatting style based on SciMLStyle.\n\nnote: Note\nThis style is still work-in-progress.\n\nConfigurable options with different defaults to DefaultStyle are:\n\nwhitespace_ops_in_indices = true\nremove_extra_newlines = true\nalways_for_in = true\nwhitespace_typedefs = true,\nnormalize_line_endings = \"unix\"\n\n\n\n\n\n","category":"type"},{"location":"sciml_style/#Configuration-File-Example","page":"SciML Style","title":"Configuration File Example","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The .JuliaFormatter.toml which represents these settings is","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"style = \"sciml\"","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"Or to use SciMLStyle except change one of the settings:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"style = \"sciml\"\nremove_extra_newlines = false","category":"page"},{"location":"sciml_style/#Direct-Usage","page":"SciML Style","title":"Direct Usage","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"format(\"file.jl\", SciMLStyle())","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"Or to use SciMLStyle except change one of the settings:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"format(\"file.jl\", SciMLStyle(), remove_extra_newlines=false)","category":"page"},{"location":"sciml_style/#Additional-Options","page":"SciML Style","title":"Additional Options","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The SciMLStyle supports the additional options variable_call_indent and yas_style_nesting.","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The option variable_call_indent is set to [] by default. It allows calls without aligning to the opening parenthesis:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"# Allowed with and without `Dict in variable_call_indent`\nDict{Int, Int}(1 => 2,\n 3 => 4)\n\n# Allowed when `Dict in variable_call_indent`, but\n# will be changed to the first example when `Dict ∉ variable_call_indent`.\nDict{Int, Int}(\n 1 => 2,\n 3 => 4)","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The option yas_style_nesting is set to false by default. Setting it to true makes the SciMLStyle use the YASStyle nesting rules:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"# With `yas_style_nesting = false`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend\n\n# With `yas_style_nesting = true`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"CurrentModule = JuliaFormatter","category":"page"},{"location":"config/#Configuration-File","page":"Configuration File","title":"Configuration File","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"From v0.4.3, JuliaFormatter offers .prettierrc style configuration file support. This means you can specify formatting options shown in format_text in .JuliaFormatter.toml file and share that with others.","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"When format is called, it 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.","category":"page"},{"location":"config/#Basic-Configuration","page":"Configuration File","title":"Basic Configuration","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"In .JuliaFormatter.toml, you can specify any of the formatting options shown in format_text in TOML, e.g. if you have","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"somedir/.JuliaFormatter.toml","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"indent = 2\nmargin = 100","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"then files under somedir will be formatted with 2 spaces indentation and the maximum line length 100.","category":"page"},{"location":"config/#Non-Default-Style","page":"Configuration File","title":"Non Default Style","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"If you would use another style, such as YASStyle you can write this in your configuration like so:","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"style = \"yas\"","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"Styles choices are:","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"\"default\" (default choice if nothing is specified)\n\"yas\"\n\"blue\"\n\"sciml\"\n\"minimal\"","category":"page"},{"location":"config/#Search-Rule","page":"Configuration File","title":"Search Rule","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":".JuliaFormatter.toml will be searched up from the directory of the file being formatted. So if you have:","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"dir\n├─ .JuliaFormatter.toml\n├─ code.jl\n└─ subdir\n └─ sub_code.jl","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"then format(\"subdir/sub_code.jl\") will be automatically configured by the dir/.JuliaFormatter.toml, as well as format(\"dir\") will format both dir/code.jl and dir/subdir/sub_code.jl according to the same configuration.","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"What will happen when we have multiple .JuliaFormatter.toml files ? In that case, the deepest configuration has the precedence. For example, if you have","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"dir\n├─ .JuliaFormatter.toml\n├─ code.jl\n├─ subdir1\n│ ├─ .JuliaFormatter.toml\n│ └─ sub_code1.jl\n└─ subdir2\n └─ sub_code2.jl","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"and call format(\"dir\"), code.jl and sub_code2.jl will be formatted according to the rules defined in dir/.JuliaFormatter.toml, while formatting sub_code1.jl will be configured by dir/subdir1/.JuliaFormatter.toml.","category":"page"},{"location":"config/#ignore","page":"Configuration File","title":"Ignoring specific files and directories","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"If there is an entry in .JuliaFormatter.toml with","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"ignore = [\"file.jl\", \"directory\", \"file_*.jl\"]","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"then all of these files will be reported as already formatted: ./file.jl, ./directory/something.jl ./other_directory/file.jl, file_1.jl, .other_directory/file_name.jl.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"CurrentModule = JuliaFormatter","category":"page"},{"location":"style/#Style","page":"Code Style","title":"Style","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"This is meant to give an impression of how the output of a formatted file looks like. Additional examples can be found in the test files.","category":"page"},{"location":"style/#Initial-FST","page":"Code Style","title":"Initial FST","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"All examples assume indentation of 4 spaces","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Functions, macros, structs with no arguments are placed on a single line:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"function foo\nend\n\n->\n\nfunction foo end","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"This also applies to abstract and primitive types:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"abstract type\nAbstractFoo\nend\n\n->\n\nabstract type AbstractFoo end","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Functions calls foo(args...), tuples (args...), arrays [args...], braces {args...}, struct or where definitions Foo{args...} are placed on a single line. This applies to any code which has opening and closing punctuation: (...), {...}, [...].","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"f(\n\na,b\n\n,c )\n\n->\n\nf(a, b, c)","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"By default type definitions have no whitespace after commas:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Foo{\na,b\n,c }\n\n->\n\nFoo{a,b,c}","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Blocks and their bodies are spread across multiple lines properly indented.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"begin\n a\n b; c\n end\n\n->\n\nbegin\n a\n b\n c\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"struct Foo{A, B}\n a::A\n b::B\nend\n\n->\n\nstruct Foo{A,B}\n a::A\n b::B\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Binary calls are placed on a single line and separated by whitespace. The exception to this are colon operations and operations inside an indexing expression. The latter being optional.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"a+b\n\n-> \n\na + b","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"a : a : c\n\n->\n\na:b:c","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 3:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"list[a + b]\n\n->\n\nlist[a+b]","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Conditionals are placed on a single line and separated by whitespace.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"cond1 ?\nexpr1 : expr2\n\n->\n\ncond1 ? expr1 : expr2","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Comments are aligned to surrounding code blocks.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"# comment\nif a\n# comment\nelseif b\n# comment\nelseif c\n# comment\nelse\n# comment\nend\n# comment\n\n->\n\n# comment\nif a\n # comment\nelseif b\n # comment\nelseif c\n # comment\nelse\n # comment\nend\n# comment","category":"page"},{"location":"style/#Nesting-FST","page":"Code Style","title":"Nesting FST","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Binary operations and conditionals are nested back-to-front.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"arg1 + arg2\n\n->\n\narg1 + \narg2","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"cond ? e1 : e2\n\n->\n\ncond ? e1 :\ne2\n\n->\n\ncond ? \ne1 :\ne2","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"If nesting is required for a = binary operation, the RHS is placed on the following line and indented.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"foo() = body\n\n->\n\nfoo() =\n body","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Lazy && and || operations are nested according to is_standalone_shortcircuit rules.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"All arguments of a function call (applies to any opening/closing punctuation type) are nested if the expression exceeds the margin. The arguments are indented one level.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"function longfunctionname_that_is_long(lots, of, args, even, more, args)\n body\nend\n\n->\n\nfunction longfunctionname_that_is_long(\n lots, \n of, \n args,\n even, \n more, \n args,\n)\n body\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"With where operations (A where B), A is nested prior to B.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"function f(arg1::A, key1 = val1; key2 = val2) where {A,B,C}\n body\nend\n\n->\n\nfunction f(\n arg1::A,\n key1 = val1;\n key2 = val2,\n) where {A,B,C}\n body\nend\n\n-> \n\nfunction f(\n arg1::A,\n key1 = val1;\n key2 = val2,\n) where {\n A,\n B,\n C,\n}\n body\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"If a comment is detected inside of an expression, that expression is automatically nested:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"var = foo(\n a, b, # comment\n c,\n)\n\n->\n\nvar = foo(\n a,\n b, # comment\n c,\n)","category":"page"},{"location":"style/#Unnesting-FST","page":"Code Style","title":"Unnesting FST","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"In certain cases it's desirable to unnest parts of a FST.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"# short function def\nfunction foo(arg1, arg2, arg3) = body\n\n-> \n\nfunction foo(arg1, arg2, arg3) =\n body\n\n->\n\nfunction foo(\n arg1,\n arg2,\n arg3,\n) =\n body\n\n# If the margin allows it, `body` will be joined back\n# with the previous line.\n\nfunction foo(\n arg1,\n arg2,\n arg3,\n) = body","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"var = funccall(arg1, arg2, arg3)\n\n-> \n\nvar =\n funccall(arg1, arg2, arg3)\n\n->\n\nvar =\n funccall(\n arg1,\n arg2,\n arg3,\n )\n\n# If the margin allows it, the RHS will be joined back\n# with the previous line.\n\nvar = funccall(\n arg1,\n arg2,\n arg3,\n)","category":"page"},{"location":"yas_style/#YAS-Style","page":"YAS Style","title":"YAS Style","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"YASStyle","category":"page"},{"location":"yas_style/#JuliaFormatter.YASStyle","page":"YAS Style","title":"JuliaFormatter.YASStyle","text":"YASStyle()\n\nFormatting style based on YASGuide and JuliaFormatter#198.\n\nConfigurable options with different defaults to DefaultStyle are:\n\nalways_for_in = true\nwhitespace_ops_in_indices = true\nremove_extra_newlines = true\nimport_to_using = true\npipe_to_function_call = true\nshort_to_long_function_def = true\nalways_use_return = true\nwhitespace_in_kwargs = false\njoin_lines_based_on_source = true\nseparate_kwargs_with_semicolon = true\n\n\n\n\n\n","category":"type"},{"location":"yas_style/#Configuration-File-Example","page":"YAS Style","title":"Configuration File Example","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"The .JuliaFormatter.toml which represents these settings is","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"style = \"yas\"","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Or to use YASStyle except change one of the settings:","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"style = \"yas\"\nremove_extra_newlines = false","category":"page"},{"location":"yas_style/#Direct-Usage","page":"YAS Style","title":"Direct Usage","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"format(\"file.jl\", YASStyle())","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Or to use YASStyle except change one of the settings:","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"format(\"file.jl\", YASStyle(), remove_extra_newlines=false)","category":"page"},{"location":"yas_style/#Differences-from-DefaultStyle","page":"YAS Style","title":"Differences from DefaultStyle","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"There are three main differences between YASStyle and DefaultStyle. They are based on alignment and line break behaviors.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Arguments are aligned to just after the start of the opener [, {, (, etc.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"function_call(arg1,\n arg2)","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"As you can see from the above the closer sticks to the final argument.\nNesting (line breaks) only occur when the margin of the next argument exceeds the maximim limit.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"function_call(arg1, arg2,\n arg3)","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"arg3 exceeded the margin limit and so it was placed on the following line.","category":"page"},{"location":"yas_style/#Nesting","page":"YAS Style","title":"Nesting =","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Unlike DefaultStyle, assignment operations = are not nested. That is, the following","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"my_function(arg1, arg2) = arg1 * arg2","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Is not nested to","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"my_function(arg1, arg2) =\n arg1 * arg2","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"It is highly recommended setting short_to_long_function_def to true. This option transforms the above to a long function definition if it exceeds the maximum margin.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"function my_function(arg1, arg2)\n arg1 * arg2\nend","category":"page"},{"location":"yas_style/#Additional-Options","page":"YAS Style","title":"Additional Options","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"The YASStyle supports the additional option variable_call_indent, which is set to [] by default. It allows calls without aligning to the opening parenthesis:","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"# Allowed with and without `Dict in variable_call_indent`\nDict{Int,Int}(1 => 2,\n 3 => 4)\n\n# Allowed when `Dict in variable_call_indent`, but\n# will be changed to the first example when `Dict ∉ variable_call_indent`.\nDict{Int,Int}(\n 1 => 2,\n 3 => 4)","category":"page"},{"location":"integrations/#Integrations","page":"Integrations","title":"Integrations","text":"","category":"section"},{"location":"integrations/#pre-commit","page":"Integrations","title":"pre-commit","text":"","category":"section"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"To learn more about pre-commit, check out their docs.","category":"page"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"With Pull 674, support for pre-commit was added. To add JuliaFormatter.jl to your own pre-commit workflow, add the following to your .pre-commit-config.yaml.","category":"page"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"repos:\n# ... other repos you may have\n- repo: \"https://github.com/domluna/JuliaFormatter.jl\"\n rev: \"v1.0.18\" # or whatever the desired release is\n hooks:\n - id: \"julia-formatter\"\n# ... other repos you may have","category":"page"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"You can find a list of releases here. Be sure to use the entire version string! (You can double-check this by opening the release and looking at the part of the URL that follows .../releases/tag/VERSION.)","category":"page"},{"location":"blue_style/#Blue-Style","page":"Blue Style","title":"Blue Style","text":"","category":"section"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"BlueStyle","category":"page"},{"location":"blue_style/#JuliaFormatter.BlueStyle","page":"Blue Style","title":"JuliaFormatter.BlueStyle","text":"BlueStyle()\n\nFormatting style based on BlueStyle and JuliaFormatter#283.\n\nnote: Note\nThis style is still work-in-progress, and does not yet implement all of the BlueStyle guide.\n\nConfigurable options with different defaults to DefaultStyle are:\n\nalways_use_return = true\nshort_to_long_function_def = true\nwhitespace_ops_in_indices = true\nremove_extra_newlines = true\nalways_for_in = true\nimport_to_using = true\npipe_to_function_call = true\nwhitespace_in_kwargs = false\nannotate_untyped_fields_with_any = false\nseparate_kwargs_with_semicolon = true\n\n\n\n\n\n","category":"type"},{"location":"blue_style/#Configuration-File-Example","page":"Blue Style","title":"Configuration File Example","text":"","category":"section"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"The .JuliaFormatter.toml which represents these settings is","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"style = \"blue\"","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"Or to use BlueStyle except change one of the settings:","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"style = \"blue\"\nremove_extra_newlines = false","category":"page"},{"location":"blue_style/#Direct-Usage","page":"Blue Style","title":"Direct Usage","text":"","category":"section"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"format(\"file.jl\", BlueStyle())","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"Or to use BlueStyle except change one of the settings:","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"format(\"file.jl\", BlueStyle(), remove_extra_newlines=false)","category":"page"},{"location":"api/#API-Documentation","page":"API Reference","title":"API Documentation","text":"","category":"section"},{"location":"api/","page":"API Reference","title":"API Reference","text":"Modules = [JuliaFormatter]\nFilter = t -> (t != YASStyle && t != BlueStyle && t != SciMLStyle) # on their own pages","category":"page"},{"location":"api/#JuliaFormatter.AlignGroup","page":"API Reference","title":"JuliaFormatter.AlignGroup","text":"AlignGroup\n\nGroup of FST node indices and required metadata to potentially align them.\n\n- `node_inds`. Indices of FST nodes affected by alignment.\n- `nodes`. FST nodes affected by alignment.\n- `line_offsets`. Line offset of the character nodes may be aligned to\nin the source file.\n- `lens`. Length of the FST node prior to the alignment character. Used\nto calculate extra whitespace padding.\n- `whitespaces`. Number of whitespaces between the alignment character and\nthe prior FST node. If this is > 1 it signifies additional whitespace was\nmanually added by the user since the formatter would only use 0 or 1 whitespaces.\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.DefaultStyle","page":"API Reference","title":"JuliaFormatter.DefaultStyle","text":"DefaultStyle\n\nThe default formatting style. See the Style section of the documentation for more details.\n\nSee also: BlueStyle, YASStyle, SciMLStyle, MinimalStyle\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.FST","page":"API Reference","title":"JuliaFormatter.FST","text":"Formatted Syntax Tree\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.MinimalStyle","page":"API Reference","title":"JuliaFormatter.MinimalStyle","text":"MinimalStyle()\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.add_node!-Tuple{JuliaFormatter.FST, JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.add_node!","text":"add_node!(\n t::FST,\n n::FST,\n s::State;\n join_lines::Bool = false,\n max_padding::Int = -1,\n override_join_lines_based_on_source::Bool = false,\n)\n\nAppends n to t.\n\njoin_lines if false a NEWLINE node will be added and n will appear\n\non the next line, otherwise it will appear on the same line as the previous node (when printing).\n\nmax_padding >= 0 indicates margin of t should be based on whether the margin\n\nof n + max_padding is greater than the current margin of t. Otherwise the margin n will be added to t.\n\noverride_join_lines_based_on_source is only used when join_lines_based_on_source option is true. In which\n\nn is added to t as if join_lines_based_on_source was false.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_binaryopcalls!-Tuple{JuliaFormatter.FST, Vector{Int64}}","page":"API Reference","title":"JuliaFormatter.align_binaryopcalls!","text":"align_binaryopcalls!(fst::FST, op_inds::Vector{Int})\n\nAligns binary operator expressions.\n\nAdditionally handles the case where a keyword such as const is used prior to the binary op call.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_conditional!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.align_conditional!","text":"align_conditional!(fst::FST)\n\nAligns a conditional expression.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_matrix!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.align_matrix!","text":"Adjust whitespace in between matrix elements such that it's the same as the original source file.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_struct!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.align_struct!","text":"align_struct!(fst::FST)\n\nAligns struct fields.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.annotate_typefields_with_any!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.annotate_typefields_with_any!","text":"annotate_typefields_with_any!(fst::FST, s::State)\n\nAnnotates fields in a type definitions with ::Any if no type annotation is provided.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.binaryop_to_whereop!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.binaryop_to_whereop!","text":"binaryop_to_whereop(fst::FST, s::State)\n\nHandles the case of a function def defined as:\n\nfoo(a::A)::R where A = body\n\nIn this case instead of it being parsed as (1):\n\nBinary\n - Where\n - OP\n - RHS\n\nIt's parsed as (2):\n\nBinary\n - Binary\n - LHS\n - OP\n - Where\n - R\n - ...\n - OP\n - RHS\n\n(1) is preferrable since it's the same parsed result as:\n\nfoo(a::A) where A = body\n\nThis transformation converts (2) to (1).\n\nref https://github.com/julia-vscode/CSTParser.jl/issues/93\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.eq_to_in_normalization!-Tuple{JuliaFormatter.FST, Bool, String}","page":"API Reference","title":"JuliaFormatter.eq_to_in_normalization!","text":"eq_to_in_normalization!(fst::FST, always_for_in::Bool, for_in_replacement::String)\neq_to_in_normalization!(fst::FST, always_for_in::Nothing, for_in_replacement::String)\n\nTransforms\n\nfor i = iter body end\n\n=>\n\nfor i in iter body end\n\nAND\n\nfor i in 1:10 body end\n\n=>\n\nfor i = 1:10 body end\n\nalways_for_in=nothing disables this normalization behavior.\n\nhttps://github.com/domluna/JuliaFormatter.jl/issues/34\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.find_optimal_nest_placeholders-Tuple{JuliaFormatter.FST, Int64, Int64}","page":"API Reference","title":"JuliaFormatter.find_optimal_nest_placeholders","text":"Finds 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.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.flatten_binaryopcall-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.flatten_binaryopcall","text":"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.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format-Tuple{Any, JuliaFormatter.AbstractStyle}","page":"API Reference","title":"JuliaFormatter.format","text":"format(path, style::AbstractStyle; options...)::Bool\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format-Tuple{Any}","page":"API Reference","title":"JuliaFormatter.format","text":"format(\n paths; # a path or collection of paths\n options...,\n)::Bool\n\nRecursively descend into files and directories, formatting any .jl, .md, .jmd, or .qmd files.\n\nSee format_file and format_text for a description of the options.\n\nThis 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.\n\nOutput\n\nReturns a boolean indicating whether the file was already formatted (true) or not (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format-Tuple{Module, Vararg{Any}}","page":"API Reference","title":"JuliaFormatter.format","text":"format(mod::Module, args...; options...)\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format_file-Tuple{AbstractString}","page":"API Reference","title":"JuliaFormatter.format_file","text":"format_file(\n filename::AbstractString;\n overwrite::Bool = true,\n verbose::Bool = false,\n format_markdown::Bool = false,\n format_options...,\n)::Bool\n\nFormats the contents of filename assuming it's a .jl, .md, .jmd or .qmd file.\n\nSee https://domluna.github.io/JuliaFormatter.jl/dev/#File-Options for details on available options.\n\nOutput\n\nReturns a boolean indicating whether the file was already formatted (true) or not (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format_md-Tuple{AbstractString}","page":"API Reference","title":"JuliaFormatter.format_md","text":"format_md(text::AbstractString; style::AbstractStyle = DefaultStyle(), kwargs...)\n\nNormalizes the Markdown source and formats Julia code blocks.\n\nSee format_text for description of formatting options.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format_text-Tuple{AbstractString}","page":"API Reference","title":"JuliaFormatter.format_text","text":"format_text(\n text::AbstractString;\n style::AbstractStyle = DefaultStyle(),\n indent::Int = 4,\n margin::Int = 92,\n options...,\n)::String\n\nFormats a Julia source passed in as a string, returning the formatted code as another string.\n\nSee https://domluna.github.io/JuliaFormatter.jl/dev/#Formatting-Options for details on available options.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.is_iterable_arg-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.is_iterable_arg","text":"Returns whether fst can be an iterable argument. For example in the case of a function call, which is of type Call:\n\n(a, b, c; k1=v1)\n\nThis would return true for a, b, c and k1=v1 and false for all other nodes.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.length_to-Tuple{JuliaFormatter.FST, Any}","page":"API Reference","title":"JuliaFormatter.length_to","text":"`length_to(x::FST, ntyps; start::Int = 1)`\n\nReturns the length to any node type in ntyps based off the start index.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.long_to_short_function_def!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.long_to_short_function_def!","text":"long_to_short_function_def!(fst::FST, s::State)\n\nTransforms a long function definition\n\nfunction f(arg2, arg2)\n body\nend\n\nto a short function definition\n\nf(arg1, arg2) = body\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.move_at_sign_to_the_end-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.move_at_sign_to_the_end","text":"move_at_sign_to_the_end(fst::FST, s::State)\n\nNOTE: Assumes fst is the caller name of a macrocall such as @macro or Module.@macro.\n\nMoves @ to the last identifier.\n\nExample:\n\n@Module.macro\n\nto\n\nModule.@macro\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.nest_if_over_margin!-Tuple{JuliaFormatter.AbstractStyle, JuliaFormatter.FST, JuliaFormatter.State, Int64, Vector{Tuple{JuliaFormatter.FNode, Union{Nothing, JuliaFormatter.Metadata}}}}","page":"API Reference","title":"JuliaFormatter.nest_if_over_margin!","text":"nest_if_over_margin!(\n style,\n fst::FST,\n s::State,\n idx::Int;\n stop_idx::Union{Int,Nothing} = nothing,\n)::Bool\n\nConverts 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.\n\nIf stop_idx == nothing the range is fst[idx:end].\n\nReturns whether nesting occurred.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.pipe_to_function_call_pass!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.pipe_to_function_call_pass!","text":"pipe_to_function_call_pass!(fst::FST)\n\nRewrites x |> f to f(x).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.prepend_return!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.prepend_return!","text":"prepend_return!(fst::FST, s::State)\n\nPrepends return to the last expression of a block if applicable.\n\nfunction foo()\n a = 2 * 3\n a / 3\nend\n\nto\n\nfunction foo()\n a = 2 * 3\n return a / 3\nend\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.remove_superfluous_whitespace!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.remove_superfluous_whitespace!","text":"remove_superfluous_whitespace!(fst::FST)\n\nSoft deletes WHITESPACE or PLACEHOLDER that's directly followed by a NEWLINE or INLINECOMMENT node.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.separate_kwargs_with_semicolon!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.separate_kwargs_with_semicolon!","text":"separate_kwargs_with_semicolon!(fst::FST)\n\nEnsures keyword arguments are separated by a \";\".\n\nExamples\n\nReplace \",\" with \";\".\n\na = f(x, y = 3)\n\n->\n\na = f(x; y = 3)\n\nMove \";\" to the prior to the first positional argument.\n\na = f(x = 1; y = 2)\n\n->\n\na = f(; x = 1, y = 2)\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.short_to_long_function_def!-Tuple{JuliaFormatter.FST, JuliaFormatter.State, Vector{Tuple{JuliaFormatter.FNode, Union{Nothing, JuliaFormatter.Metadata}}}}","page":"API Reference","title":"JuliaFormatter.short_to_long_function_def!","text":"short_to_long_function_def!(fst::FST, s::State)\n\nTransforms a short function definition\n\nf(arg1, arg2) = body\n\nto a long function definition\n\nfunction f(arg2, arg2)\n body\nend\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.unnestable_node-Tuple{JuliaSyntax.GreenNode}","page":"API Reference","title":"JuliaFormatter.unnestable_node","text":"cst is assumed to be a single child node. Returnss true if the node is of the syntactic form {...}, [...], or (...).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.walk-Tuple{Function, JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.walk","text":"walk(f, fst::FST, s::State)\n\nWalks fst calling f on each node.\n\nIn situations where descending further into a subtree is not desirable f should return a value other than nothing.\n\nnote: Note\nThis 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.\n\n\n\n\n\n","category":"method"},{"location":"transforms/#Syntax-Tree-Transformations","page":"Syntax Transforms","title":"Syntax Tree Transformations","text":"","category":"section"},{"location":"transforms/#for-in-vs.-for","page":"Syntax Transforms","title":"for in vs. for =","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"By default if the RHS is a range, i.e. 1:10 then for in is converted to for =. Otherwise for = is converted to for in. See this issue for the rationale and further explanation.","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"Alternative to the above - setting always_for_in to true, i.e. format_text(..., always_for_in = true) will always convert = to in even if the RHS is a range. always_for_in=nothing will leave the choice of in vs = up to the user.","category":"page"},{"location":"transforms/#Trailing-Commas","page":"Syntax Transforms","title":"Trailing Commas","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If the node is iterable, for example a function call or list and is nested, a trailing comma is added to the last argument. The trailing comma is removed if unnested:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"func(a, b, c)\n\n->\n\nfunc(\n a,\n b,\n c,\n)","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Trailing-Semicolons","page":"Syntax Transforms","title":"Trailing Semicolons","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If a matrix node is nested the semicolons are removed.","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"A = [1 0; 0 1]\n\n->\n\nA = [\n 1 0\n 0 1\n]","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Leading-and-trailing-0s-for-float-literals","page":"Syntax Transforms","title":"Leading and trailing 0s for float literals","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If a float literal is missing a trailing 0 it is added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"a = 1.\n\n->\n\na = 1.0","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If a float literal is missing a leading 0 it is added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"a = .1\n\n->\n\na = 0.1","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"For Float32 if there is no decimal point, .0 is added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"a = 1f0\n\n->\n\na = 1.0f0","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Surround-where-arguments-with-curly-brackets","page":"Syntax Transforms","title":"Surround where arguments with curly brackets","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If the arguments of a where call are not surrounded by curly brackets, they are added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"foo(x::T) where T = ...\n\n->\n\nfoo(x::T) where {T} = ...","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Annotate-unannotated-type-fields-with-Any","page":"Syntax Transforms","title":"Annotate unannotated type fields with Any","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"struct Foo\n field\nend\n\n->\n\nstruct Foo\n field::Any\nend","category":"page"},{"location":"transforms/#Move-@-in-macro-calls-to-the-final-identifier","page":"Syntax Transforms","title":"Move @ in macro calls to the final identifier","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"@Module.macro\n\n->\n\nModule.@macro","category":"page"},{"location":"custom_alignment/#Custom-Alignment","page":"Custom Alignment","title":"Custom Alignment","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Solution for issue 179","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Custom alignment is determined by a whitespace heuristic:","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"A token (typically an operator, i.e. =, ?, ::, etc) is custom aligned if there are > 1 whitespaces from the previous expression since the formatter only outputs 0 or 1 whitespaces for separation. If custom alignment is determined then all expressions in the code block will be aligned to the furthest aligned token.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"NOTE: alignment overrides nesting behavior, meaning it ignores the allowed maximum margin","category":"page"},{"location":"custom_alignment/#Example","page":"Custom Alignment","title":"Example","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Suppose the source text is as follows","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = 2\nconst var3 = 3\nconst var4 = 4\nconst var5 = 5","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"If the align_assignment option is enabled the formatter will detect that var2 is aligned to variable1 AND var2 has several whitespaces (>1) prior to =. Since var3,var4, and var5 are part of the same code block (no comments or newlines separating code) they will also be aligned.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"So the output would be","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = 2\nconst var3 = 3\nconst var4 = 4\nconst var5 = 5","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Notice how the = operator for var5 is correctly positioned despite it being located further to the right than other = operators.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"However, if the source code is","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst variable2 = 2\nconst var3 = 3\nconst var4 = 4\nconst var5 = 5","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"It's now ambiguous whether this is meant to be aligned and so the formatter will proceed with normal behavior.","category":"page"},{"location":"custom_alignment/#Alignment-Options","page":"Custom Alignment","title":"Alignment Options","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"In order for alignment to occur the option must be set to true. Available options:","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"align_assignment\nalign_struct_field\nalign_conditional\nalign_pair_arrow\nalign_matrix","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Caveat: Since nesting is disabled when alignment occurs be careful when adding comments to the RHS expression. This will be fixed in a future release","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"For example:","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = foo(10,\n # comment,\n 20)","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"This will be formatted to","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = foo(10, # comment, 20)","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"which causes a parsing error.","category":"page"},{"location":"custom_alignment/#align_assignment","page":"Custom Alignment","title":"align_assignment","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align to =-like operators. This covers variable assignments and short definition functions.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const UTF8PROC_STABLE = (1 << 1)\nconst UTF8PROC_COMPAT = (1 << 2)\nconst UTF8PROC_COMPOSE = (1 << 3)\nconst UTF8PROC_DECOMPOSE = (1 << 4)\nconst UTF8PROC_IGNORE = (1 << 5)\nconst UTF8PROC_REJECTNA = (1 << 6)\nconst UTF8PROC_NLF2LS = (1 << 7)\nconst UTF8PROC_NLF2PS = (1 << 8)\nconst UTF8PROC_NLF2LF = (UTF8PROC_NLF2LS | UTF8PROC_NLF2PS)\nconst UTF8PROC_STRIPCC = (1 << 9)\nconst UTF8PROC_CASEFOLD = (1 << 10)\nconst UTF8PROC_CHARBOUND = (1 << 11)\nconst UTF8PROC_LUMP = (1 << 12)\nconst UTF8PROC_STRIP = (1 << 13)\n\n\nvcat(X::T...) where {T} = T[X[i] for i = 1:length(X)]\nvcat(X::T...) where {T<:Number} = T[X[i] for i = 1:length(X)]\nhcat(X::T...) where {T} = T[X[j] for i = 1:1, j = 1:length(X)]\nhcat(X::T...) where {T<:Number} = T[X[j] for i = 1:1, j = 1:length(X)]\n\na = 1\nbc = 2\n\nlong_variable = 1\nother_var = 2","category":"page"},{"location":"custom_alignment/#align_struct_field","page":"Custom Alignment","title":"align_struct_field","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align struct field definitions to :: or = - whichever has higher precedence.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Base.@kwdef struct Options\n indent::Int = 4\n margin::Int = 92\n always_for_in::Bool = false\n whitespace_typedefs::Bool = false\n whitespace_ops_in_indices::Bool = false\n remove_extra_newlines::Bool = false\n import_to_using::Bool = false\n pipe_to_function_call::Bool = false\n short_to_long_function_def::Bool = false\n always_use_return::Bool = false\n whitespace_in_kwargs::Bool = true\n annotate_untyped_fields_with_any::Bool = true\n format_docstrings::Bool = false\n align_struct_fields::Bool = false\n\n # no custom whitespace so this block is not aligned\n another_field1::BlahBlahBlah = 10\n field2::Foo = 10\n\n # no custom whitespace but single line blocks are not aligned\n # either way\n Options() = new()\nend\n\n\nmutable struct Foo\n a :: T\n longfieldname :: T\nend","category":"page"},{"location":"custom_alignment/#align_conditional","page":"Custom Alignment","title":"align_conditional","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align conditional expressions to either ?, :, or both.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"# This will remain like this if using YASStyle\nindex = zeros(n <= typemax(Int8) ? Int8 :\n n <= typemax(Int16) ? Int16 :\n n <= typemax(Int32) ? Int32 : Int64, n)\n\n# Using DefaultStyle\nindex = zeros(\n n <= typemax(Int8) ? Int8 :\n n <= typemax(Int16) ? Int16 :\n n <= typemax(Int32) ? Int32 : Int64,\n n,\n)\n\n# Note even if the maximum margin is set to 1, the alignment remains intact\nindex =\n zeros(\n n <= typemax(Int8) ? Int8 :\n n <= typemax(Int16) ? Int16 :\n n <= typemax(Int32) ? Int32 : Int64,\n n,\n )\n","category":"page"},{"location":"custom_alignment/#align_pair_arrow","page":"Custom Alignment","title":"align_pair_arrow","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align pair arrows (=>).","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"pages = [\n \"Introduction\" => \"index.md\",\n \"How It Works\" => \"how_it_works.md\",\n \"Code Style\" => \"style.md\",\n \"Skipping Formatting\" => \"skipping_formatting.md\",\n \"Syntax Transforms\" => \"transforms.md\",\n \"Custom Alignment\" => \"custom_alignment.md\",\n \"Custom Styles\" => \"custom_styles.md\",\n \"YAS Style\" => \"yas_style.md\",\n \"Configuration File\" => \"config.md\",\n \"API Reference\" => \"api.md\",\n]","category":"page"},{"location":"custom_alignment/#align_matrix","page":"Custom Alignment","title":"align_matrix","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"TLDR: If you want to align matrix elements yourself set this to true","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Whitespace surrounding matrix elements in the original source file is maintained. Differs from other alignment options since it does not try to \"detect\" alignment and then adjust other elements.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"# Elements left-aligned in original source\njulia> s = \"\"\"\n a = [\n 100 300 400\n 1 eee 40000\n 2 α b\n ]\"\"\"\n\"a = [\\n100 300 400\\n1 eee 40000\\n2 α b\\n]\"\n\njulia> format_text(s, align_matrix=true) |> print\na = [\n 100 300 400\n 1 eee 40000\n 2 α b\n]\n\n# Elements right-aligned in original source\njulia> s = \"\"\"\n a = [\n 100 300 400\n 1 ee 40000\n 2 a b\n ]\"\"\"\n\"a = [\\n100 300 400\\n 1 ee 40000\\n 2 a b\\n]\"\n\njulia>\n\njulia> format_text(s, align_matrix=true) |> print\na = [\n 100 300 400\n 1 ee 40000\n 2 a b\n]","category":"page"},{"location":"how_it_works/#How-It-Works","page":"How It Works","title":"How It Works","text":"","category":"section"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"The formatter takes a .jl file as input and produce a idealized, formatted .jl as output. Some formatters mutate the state of the current file, JuliaFormatter takes a different approach - first generating a canonical output, and then mutating that canonical output; adhering to the indent and margin constraints.","category":"page"},{"location":"how_it_works/#Generating-an-FST","page":"How It Works","title":"Generating an FST","text":"","category":"section"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"The source code is parsed with CSTParser.jl which returns a CST (Concrete Syntax Tree). A CST is a one-to-one mapping of the language to a tree form. In most cases a more compact AST (Abstract Syntax Tree) representation is desired. However, since formatting manipulate the source text itself, the richer representation of a CST is incredibly useful.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Once the CST is created it's then used to generate a FST (Formatted Syntax Tree).","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Note: this is not an actual term, just something I made up. Essentially it's a CST with additional formatting specific metadata.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"The important part of an FST is any .jl file that is syntactically the same (whitespace is irrelevant) produce an identical FST.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"For example:","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"# p1.jl\na = \n foo(a, b, \n c,d)","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"and","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"# p2.jl\na = foo(a,\nb,\nc,d)","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"will produce the same FST, which printed would look like:","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"# fst output\na = foo(a, b, c, d)","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"So what does a typical FST look like?","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Code and comments are indented to match surrounding code blocks. Unnecessary whitespace is removed. Newlines in between code blocks are untouched.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"If the expression can be put on a single line it will be. It doesn't matter it's a function call which 120 arguments, making it 1000 characters long. During this initial stage it will be put on a single line.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"If the expression has a structure to it, such as a try, if, or 'struct' definition. It will be spread across multiple lines appropriately:","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"\n# original source\ntry a1;a2 catch e b1;b2 finally c1;c2 end\n\n-> \n\n# printed FST\ntry\n a1\n a2\ncatch e\n b1\n b2\nfinally\n c1\n c2\nend","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"With this FST representation it's much easier to determine when and how lines should be broken.","category":"page"},{"location":"how_it_works/#Nesting-breaking-lines","page":"How It Works","title":"Nesting - breaking lines","text":"","category":"section"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"During the nesting stage and original FST is mutated to adhere to the margin specification.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Throughout the previous stage, while the FST was being generated, PLACEHOLDER nodes were being inserted at various points. These can be converted to NEWLINE nodes during nesting, which is how lines are broken.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Assume we had a function call which went over the margin.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"begin\n foo = funccall(argument1, argument2, ..., argument120) # way over margin limit !!!\nend","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"It would be nested to","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"begin\n foo = funccall(\n argument1,\n argument2,\n ...,\n argument120\n ) # way over margin limit !!!\nend","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"You can read how code is nested in the style section.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Once the FST has been nested it's then printed out to a file and voila! You have a formatted version of your code!","category":"page"},{"location":"skipping_formatting/#Skipping-Formatting","page":"Skipping Formatting","title":"Skipping Formatting","text":"","category":"section"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"By default formatting is always on but can be toggled with the following comments:","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"#! format: off\n# Turns off formatting from this point onwards\n...\n\n#! format: on\n# Turns formatting back on from this point onwards","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"These can be used throughout a file, or, for an entire file not be formatted add \"format: off\" at the top of the file:","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"#! format: off\n#\n# It doesn't actually matter if it's on\n# the first line of the line but anything\n# onwards will NOT be formatted.\n\nmodule Foo\n...\nend","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"note: Ignoring files\nYou can also ignore entire files and directories by supplying the ignore option in .JuliaFormatter.toml.","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"Note the formatter expects #! format: on and #! format: off to be on its own line and the whitespace to be an exact match.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"CurrentModule = JuliaFormatter","category":"page"},{"location":"#JuliaFormatter.jl","page":"Introduction","title":"JuliaFormatter.jl","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Width-sensitive formatter for Julia code. Inspired by gofmt, refmt, black, and prettier. Built with CSTParser.jl.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Sane defaults out of the box with options to customize.\nSupports YAS, Blue and SciML style guides.\n.JuliaFormatter.toml configuration file to store options.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"(Image: )","category":"page"},{"location":"#Installation","page":"Introduction","title":"Installation","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"]add JuliaFormatter","category":"page"},{"location":"#Quick-Start","page":"Introduction","title":"Quick Start","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"julia> using JuliaFormatter\n\n# Recursively formats all Julia files in the current directory\njulia> format(\".\")\n\n# Formats an individual file\njulia> format_file(\"foo.jl\")\n\n# Formats a string (contents of a Julia file)\njulia> format_text(str)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Check out the docs for further description of the formatter and its options.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Use With GitHub Actions","category":"page"},{"location":"#Formatting-Options","page":"Introduction","title":"Formatting Options","text":"","category":"section"},{"location":"#indent","page":"Introduction","title":"indent","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: 4","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The number of spaces used for an indentation.","category":"page"},{"location":"#margin","page":"Introduction","title":"margin","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: 92","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The maximum length of a line. Code exceeding this margin will be formatted across multiple lines.","category":"page"},{"location":"#always_for_in","page":"Introduction","title":"always_for_in","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"#whitespace_typedefs","page":"Introduction","title":"whitespace_typedefs","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.","category":"page"},{"location":"#whitespace_ops_in_indices","page":"Introduction","title":"whitespace_ops_in_indices","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Example: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].","category":"page"},{"location":"#remove_extra_newlines","page":"Introduction","title":"remove_extra_newlines","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, superfluous newlines will be removed. For example:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module M\n\n\n\na = 1\n\nfunction foo()\n\n\n return nothing\n\nend\n\n\nb = 2\n\n\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"is rewritten as","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module M\n\na = 1\n\nfunction foo()\n return nothing\nend\n\nb = 2\n\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Modules are the only type of code block allowed to keep a single newline prior to the initial or after the final piece of code.","category":"page"},{"location":"#import_to_using","page":"Introduction","title":"import_to_using","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, import expressions are rewritten to using expressions in the following cases:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"import A\n\nimport A, B, C","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"is rewritten to:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"using A: A\n\nusing A: A\nusing B: B\nusing C: C","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Exceptions:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If as is found in the import expression. using CANNOT be used in this context. The following example will NOT BE rewritten.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"import Base.Threads as th","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If import is used in the following context it is NOT rewritten. This may change in a future patch.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"@everywhere import A, B","category":"page"},{"location":"#pipe_to_function_call","page":"Introduction","title":"pipe_to_function_call","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, x |> f is rewritten to f(x).","category":"page"},{"location":"#short_to_long_function_def","page":"Introduction","title":"short_to_long_function_def","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Transforms a short function definition","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(arg1, arg2) = body","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to a long function definition if the short function definition exceeds the maximum margin. Or if force_long_function_def is set to true.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function f(arg2, arg2)\n body\nend","category":"page"},{"location":"#force_long_function_def","page":"Introduction","title":"force_long_function_def","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true tweaks the behavior of short_to_long_function_def to force the transformation no matter how short the function definition is.","category":"page"},{"location":"#long_to_short_function_def","page":"Introduction","title":"long_to_short_function_def","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Transforms a long function definition","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function f(arg2, arg2)\n body\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to a short function definition if the short function definition does not exceed the maximum margin.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(arg1, arg2) = body","category":"page"},{"location":"#always_use_return","page":"Introduction","title":"always_use_return","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, return will be prepended to the last expression where applicable in function definitions, macro definitions, and do blocks.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Example:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo()\n expr1\n expr2\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo()\n expr1\n return expr2\nend","category":"page"},{"location":"#whitespace_in_kwargs","page":"Introduction","title":"whitespace_in_kwargs","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, = in keyword arguments will be surrounded by whitespace.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(; a=4)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(; a = 4)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"#annotate_untyped_fields_with_any","page":"Introduction","title":"annotate_untyped_fields_with_any","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Annotates fields in a type definitions with ::Any if no type annotation is provided:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"struct A\n arg1\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"struct A\n arg1::Any\nend","category":"page"},{"location":"#format_docstrings","page":"Introduction","title":"format_docstrings","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Format code docstrings with the same options used for the code source.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Markdown is formatted with CommonMark alongside Julia code.","category":"page"},{"location":"#align_*","page":"Introduction","title":"align_*","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"See Custom Alignment documentation.","category":"page"},{"location":"#conditional_to_if","page":"Introduction","title":"conditional_to_if","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If the conditional E ? A : B exceeds the maximum margin converts it into the equivalent if block:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if E\n A\nelse\n B\nend","category":"page"},{"location":"#normalize_line_endings","page":"Introduction","title":"normalize_line_endings","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: \"auto\"","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"One of \"unix\" (normalize all \\r\\n to \\n), \"windows\" (normalize all \\n to \\r\\n), \"auto\" (automatically choose based on which line ending is more common in the file).","category":"page"},{"location":"#trailing_comma","page":"Introduction","title":"trailing_comma","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"One of true, false, or nothing.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Trailing commas are added after the final argument when nesting occurs and the closing punctuation appears on the next line.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"For example when the following is nested (assuming DefaultStyle):","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"funccall(arg1, arg2, arg3)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"it turns into:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"funccall(\n arg1,\n arg2,\n arg3, # trailing comma added after `arg3` (final argument) !!!\n)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When set to true, the trailing comma is always added during nesting.\nWhen set to false, the trailing comma is always removed during nesting.\nWhen set to nothing, the trailing comma appears as it does in the original source.","category":"page"},{"location":"#trailing_zero","page":"Introduction","title":"trailing_zero","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Add a trailing zero, if needed.","category":"page"},{"location":"#join_lines_based_on_source","page":"Introduction","title":"join_lines_based_on_source","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When true lines are joined as they appear in the original source file.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo(arg1,\n arg2, arg3\n )\n body\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When false and the maximum margin is > than the length of \"function foo(arg1, arg2, arg3)\" this is formatted to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo(arg1, arg2, arg3)\n body\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When 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.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo(arg1,\n arg2, arg3,\n)\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"There are exceptions to this:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if a body1 elseif b body2 else body3 end","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"will be formatted to the following, even if this option is set to true:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if a\n body1\nelseif b\n body2\nelse\n body3\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"warning: Warning\nThe maximum margin still applies even when this option is set to true.","category":"page"},{"location":"#indent_submodule","page":"Introduction","title":"indent_submodule","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When set to true, submodule(s) appearing in the same file will be indented.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module A\na = 1\n\nmodule B\nb = 2\nmodule C\nc = 3\nend\nend\n\nd = 4\n\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"will be formatted to:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module A\na = 1\n\nmodule B\n b = 2\n module C\n c = 3\n end\nend\n\nd = 4\n\nend","category":"page"},{"location":"#separate_kwargs_with_semicolon","page":"Introduction","title":"separate_kwargs_with_semicolon","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When set to true, keyword arguments in a function call will be separated with a semicolon.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(a, b=1)\n\n->\n\nf(a; b=1)","category":"page"},{"location":"#surround_whereop_typeparameters","page":"Introduction","title":"surround_whereop_typeparameters","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Surrounds type parameters with curly brackets when set to true if the brackets are not already present.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function func(...) where TPARAM\nend\n\n->\n\nfunction func(...) where {TPARAM}\nend","category":"page"},{"location":"#for_in_replacement","page":"Introduction","title":"for_in_replacement","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Can be used when always_for_in is true to replace the default in with ∈ (\\\\in), or = instead. The replacement options are (\"in\", \"=\", \"∈\").","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"for a = 1:10\nend\n\n# formatted with always_for_in = true, for_in_replacement = \"∈\"\nfor a ∈ 1:10\nend","category":"page"},{"location":"#variable_call_indent-and-and-yas_style_nesting","page":"Introduction","title":"variable_call_indent && yas_style_nesting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"The SciMLStyle supports the additional options variable_call_indent and yas_style_nesting.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The option variable_call_indent is set to [] by default. It allows calls without aligning to the opening parenthesis:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"# Allowed with and without `Dict in variable_call_indent`\nDict{Int, Int}(1 => 2,\n 3 => 4)\n\n# Allowed when `Dict in variable_call_indent`, but\n# will be changed to the first example when `Dict ∉ variable_call_indent`.\nDict{Int, Int}(\n 1 => 2,\n 3 => 4)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The option yas_style_nesting is set to false by default. Setting it to true makes the SciMLStyle use the YASStyle nesting rules:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"# With `yas_style_nesting = false`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend\n\n# With `yas_style_nesting = true`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend","category":"page"},{"location":"#short_circuit_to_if","page":"Introduction","title":"short_circuit_to_if","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"You can convert short circuit expressions to the equivalent if expression.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"b0 && foo()\nb1 || bar()","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"respectively become","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if b0\n foo()\nend\nif !b1\n bar()\nend","category":"page"},{"location":"#disallow_single_arg_nesting","page":"Introduction","title":"disallow_single_arg_nesting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Prevents the nesting of a single argument arg in parenthesis, brackets, and curly braces.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"# Without `disallow_single_arg_nesting`:\nfunction_call(\n \"String argument\"\n)\n[array_item(\n 10\n)]\n{key => value(\n \"String value\"\n)}\n\n# With `disallow_single_arg_nesting` enabled:\nfunction_call(\"String argument\")\n[array_item(10)]\n{key => value(\"String value\")}","category":"page"},{"location":"#File-Options","page":"Introduction","title":"File Options","text":"","category":"section"},{"location":"#overwrite","page":"Introduction","title":"overwrite","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"#verbose","page":"Introduction","title":"verbose","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true details related to formatting the file will be printed to stdout.","category":"page"},{"location":"#format_markdown","page":"Introduction","title":"format_markdown","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, Markdown files are also formatted. Julia code blocks will be formatted in addition to the Markdown being normalized.","category":"page"},{"location":"#ignore","page":"Introduction","title":"ignore","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"An array of paths to files and directories (with possible Glob wildcards) which will not be formatted.","category":"page"},{"location":"#Special-Format-Comments","page":"Introduction","title":"Special Format Comments","text":"","category":"section"},{"location":"#Turn-off/on-formatting","page":"Introduction","title":"Turn off/on formatting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"You can skip sections of code by using the #! format: off and #! format: on comments.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"\n# this should be formatted\na = f(aaa, bbb, ccc)\n\n# this should not be formatted\n#! format: off\na = f(aaa,\n bbb,ccc)\n\nc = 102000\n\nd = @foo 10 20\n\ne = \"what the foocho\"\n#! format: on\n\n# this should be formatted\na = f(aaa, bbb, ccc)\n\n# ok","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If you wish to not format an entire file just add #!: format: off to the top of the file.","category":"page"},{"location":"#Stopping-a-block-of-code-from-indenting","page":"Introduction","title":"Stopping a block of code from indenting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Sometimes you may wish for a block of code to not be indented. You can achieve this with #!: format: noindent.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"begin\n@muladd begin\n #! format: noindent\n a = 10\n b = 20\n begin\n # another indent\n z = 33\n end\n\n a * b\nend\n end","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"is formatted to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"begin\n @muladd begin\n #! format: noindent\n a = 10\n b = 20\n begin\n # another indent\n z = 33\n end\n\n a * b\n end\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Notice the contents of @muladd begin is not indented.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"#!: format: noindent can also be nested.","category":"page"},{"location":"#Editor-Plugins","page":"Introduction","title":"Editor Plugins","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"For integration with other editors:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"VSCode\nEmacs\nVim\nAtom (deprecated)","category":"page"}] +[{"location":"sciml_style/#SciML-Style","page":"SciML Style","title":"SciML Style","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"SciMLStyle","category":"page"},{"location":"sciml_style/#JuliaFormatter.SciMLStyle","page":"SciML Style","title":"JuliaFormatter.SciMLStyle","text":"SciMLStyle()\n\nFormatting style based on SciMLStyle.\n\nnote: Note\nThis style is still work-in-progress.\n\nConfigurable options with different defaults to DefaultStyle are:\n\nwhitespace_ops_in_indices = true\nremove_extra_newlines = true\nalways_for_in = true\nwhitespace_typedefs = true,\nnormalize_line_endings = \"unix\"\n\n\n\n\n\n","category":"type"},{"location":"sciml_style/#Configuration-File-Example","page":"SciML Style","title":"Configuration File Example","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The .JuliaFormatter.toml which represents these settings is","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"style = \"sciml\"","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"Or to use SciMLStyle except change one of the settings:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"style = \"sciml\"\nremove_extra_newlines = false","category":"page"},{"location":"sciml_style/#Direct-Usage","page":"SciML Style","title":"Direct Usage","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"format(\"file.jl\", SciMLStyle())","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"Or to use SciMLStyle except change one of the settings:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"format(\"file.jl\", SciMLStyle(), remove_extra_newlines=false)","category":"page"},{"location":"sciml_style/#Additional-Options","page":"SciML Style","title":"Additional Options","text":"","category":"section"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The SciMLStyle supports the additional options variable_call_indent and yas_style_nesting.","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The option variable_call_indent is set to [] by default. It allows calls without aligning to the opening parenthesis:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"# Allowed with and without `Dict in variable_call_indent`\nDict{Int, Int}(1 => 2,\n 3 => 4)\n\n# Allowed when `Dict in variable_call_indent`, but\n# will be changed to the first example when `Dict ∉ variable_call_indent`.\nDict{Int, Int}(\n 1 => 2,\n 3 => 4)","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"The option yas_style_nesting is set to false by default. Setting it to true makes the SciMLStyle use the YASStyle nesting rules:","category":"page"},{"location":"sciml_style/","page":"SciML Style","title":"SciML Style","text":"# With `yas_style_nesting = false`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend\n\n# With `yas_style_nesting = true`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"CurrentModule = JuliaFormatter","category":"page"},{"location":"config/#Configuration-File","page":"Configuration File","title":"Configuration File","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"From v0.4.3, JuliaFormatter offers .prettierrc style configuration file support. This means you can specify formatting options shown in format_text in .JuliaFormatter.toml file and share that with others.","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"When format is called, it 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.","category":"page"},{"location":"config/#Basic-Configuration","page":"Configuration File","title":"Basic Configuration","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"In .JuliaFormatter.toml, you can specify any of the formatting options shown in format_text in TOML, e.g. if you have","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"somedir/.JuliaFormatter.toml","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"indent = 2\nmargin = 100","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"then files under somedir will be formatted with 2 spaces indentation and the maximum line length 100.","category":"page"},{"location":"config/#Non-Default-Style","page":"Configuration File","title":"Non Default Style","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"If you would use another style, such as YASStyle you can write this in your configuration like so:","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"style = \"yas\"","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"Styles choices are:","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"\"default\" (default choice if nothing is specified)\n\"yas\"\n\"blue\"\n\"sciml\"\n\"minimal\"","category":"page"},{"location":"config/#Search-Rule","page":"Configuration File","title":"Search Rule","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":".JuliaFormatter.toml will be searched up from the directory of the file being formatted. So if you have:","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"dir\n├─ .JuliaFormatter.toml\n├─ code.jl\n└─ subdir\n └─ sub_code.jl","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"then format(\"subdir/sub_code.jl\") will be automatically configured by the dir/.JuliaFormatter.toml, as well as format(\"dir\") will format both dir/code.jl and dir/subdir/sub_code.jl according to the same configuration.","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"What will happen when we have multiple .JuliaFormatter.toml files ? In that case, the deepest configuration has the precedence. For example, if you have","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"dir\n├─ .JuliaFormatter.toml\n├─ code.jl\n├─ subdir1\n│ ├─ .JuliaFormatter.toml\n│ └─ sub_code1.jl\n└─ subdir2\n └─ sub_code2.jl","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"and call format(\"dir\"), code.jl and sub_code2.jl will be formatted according to the rules defined in dir/.JuliaFormatter.toml, while formatting sub_code1.jl will be configured by dir/subdir1/.JuliaFormatter.toml.","category":"page"},{"location":"config/#ignore","page":"Configuration File","title":"Ignoring specific files and directories","text":"","category":"section"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"If there is an entry in .JuliaFormatter.toml with","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"ignore = [\"file.jl\", \"directory\", \"file_*.jl\"]","category":"page"},{"location":"config/","page":"Configuration File","title":"Configuration File","text":"then all of these files will be reported as already formatted: ./file.jl, ./directory/something.jl ./other_directory/file.jl, file_1.jl, .other_directory/file_name.jl.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"CurrentModule = JuliaFormatter","category":"page"},{"location":"style/#Style","page":"Code Style","title":"Style","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"This is meant to give an impression of how the output of a formatted file looks like. Additional examples can be found in the test files.","category":"page"},{"location":"style/#Initial-FST","page":"Code Style","title":"Initial FST","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"All examples assume indentation of 4 spaces","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Functions, macros, structs with no arguments are placed on a single line:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"function foo\nend\n\n->\n\nfunction foo end","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"This also applies to abstract and primitive types:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"abstract type\nAbstractFoo\nend\n\n->\n\nabstract type AbstractFoo end","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Functions calls foo(args...), tuples (args...), arrays [args...], braces {args...}, struct or where definitions Foo{args...} are placed on a single line. This applies to any code which has opening and closing punctuation: (...), {...}, [...].","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"f(\n\na,b\n\n,c )\n\n->\n\nf(a, b, c)","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"By default type definitions have no whitespace after commas:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Foo{\na,b\n,c }\n\n->\n\nFoo{a,b,c}","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Blocks and their bodies are spread across multiple lines properly indented.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"begin\n a\n b; c\n end\n\n->\n\nbegin\n a\n b\n c\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"struct Foo{A, B}\n a::A\n b::B\nend\n\n->\n\nstruct Foo{A,B}\n a::A\n b::B\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Binary calls are placed on a single line and separated by whitespace. The exception to this are colon operations and operations inside an indexing expression. The latter being optional.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"a+b\n\n-> \n\na + b","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"a : a : c\n\n->\n\na:b:c","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 3:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"list[a + b]\n\n->\n\nlist[a+b]","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Conditionals are placed on a single line and separated by whitespace.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"cond1 ?\nexpr1 : expr2\n\n->\n\ncond1 ? expr1 : expr2","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Comments are aligned to surrounding code blocks.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"# comment\nif a\n# comment\nelseif b\n# comment\nelseif c\n# comment\nelse\n# comment\nend\n# comment\n\n->\n\n# comment\nif a\n # comment\nelseif b\n # comment\nelseif c\n # comment\nelse\n # comment\nend\n# comment","category":"page"},{"location":"style/#Nesting-FST","page":"Code Style","title":"Nesting FST","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Binary operations and conditionals are nested back-to-front.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"arg1 + arg2\n\n->\n\narg1 + \narg2","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"cond ? e1 : e2\n\n->\n\ncond ? e1 :\ne2\n\n->\n\ncond ? \ne1 :\ne2","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"If nesting is required for a = binary operation, the RHS is placed on the following line and indented.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"foo() = body\n\n->\n\nfoo() =\n body","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Lazy && and || operations are nested according to is_standalone_shortcircuit rules.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"All arguments of a function call (applies to any opening/closing punctuation type) are nested if the expression exceeds the margin. The arguments are indented one level.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"function longfunctionname_that_is_long(lots, of, args, even, more, args)\n body\nend\n\n->\n\nfunction longfunctionname_that_is_long(\n lots, \n of, \n args,\n even, \n more, \n args,\n)\n body\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"With where operations (A where B), A is nested prior to B.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"function f(arg1::A, key1 = val1; key2 = val2) where {A,B,C}\n body\nend\n\n->\n\nfunction f(\n arg1::A,\n key1 = val1;\n key2 = val2,\n) where {A,B,C}\n body\nend\n\n-> \n\nfunction f(\n arg1::A,\n key1 = val1;\n key2 = val2,\n) where {\n A,\n B,\n C,\n}\n body\nend","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"If a comment is detected inside of an expression, that expression is automatically nested:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"var = foo(\n a, b, # comment\n c,\n)\n\n->\n\nvar = foo(\n a,\n b, # comment\n c,\n)","category":"page"},{"location":"style/#Unnesting-FST","page":"Code Style","title":"Unnesting FST","text":"","category":"section"},{"location":"style/","page":"Code Style","title":"Code Style","text":"In certain cases it's desirable to unnest parts of a FST.","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 1:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"# short function def\nfunction foo(arg1, arg2, arg3) = body\n\n-> \n\nfunction foo(arg1, arg2, arg3) =\n body\n\n->\n\nfunction foo(\n arg1,\n arg2,\n arg3,\n) =\n body\n\n# If the margin allows it, `body` will be joined back\n# with the previous line.\n\nfunction foo(\n arg1,\n arg2,\n arg3,\n) = body","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"Example 2:","category":"page"},{"location":"style/","page":"Code Style","title":"Code Style","text":"var = funccall(arg1, arg2, arg3)\n\n-> \n\nvar =\n funccall(arg1, arg2, arg3)\n\n->\n\nvar =\n funccall(\n arg1,\n arg2,\n arg3,\n )\n\n# If the margin allows it, the RHS will be joined back\n# with the previous line.\n\nvar = funccall(\n arg1,\n arg2,\n arg3,\n)","category":"page"},{"location":"yas_style/#YAS-Style","page":"YAS Style","title":"YAS Style","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"YASStyle","category":"page"},{"location":"yas_style/#JuliaFormatter.YASStyle","page":"YAS Style","title":"JuliaFormatter.YASStyle","text":"YASStyle()\n\nFormatting style based on YASGuide and JuliaFormatter#198.\n\nConfigurable options with different defaults to DefaultStyle are:\n\nalways_for_in = true\nwhitespace_ops_in_indices = true\nremove_extra_newlines = true\nimport_to_using = true\npipe_to_function_call = true\nshort_to_long_function_def = true\nalways_use_return = true\nwhitespace_in_kwargs = false\njoin_lines_based_on_source = true\nseparate_kwargs_with_semicolon = true\n\n\n\n\n\n","category":"type"},{"location":"yas_style/#Configuration-File-Example","page":"YAS Style","title":"Configuration File Example","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"The .JuliaFormatter.toml which represents these settings is","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"style = \"yas\"","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Or to use YASStyle except change one of the settings:","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"style = \"yas\"\nremove_extra_newlines = false","category":"page"},{"location":"yas_style/#Direct-Usage","page":"YAS Style","title":"Direct Usage","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"format(\"file.jl\", YASStyle())","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Or to use YASStyle except change one of the settings:","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"format(\"file.jl\", YASStyle(), remove_extra_newlines=false)","category":"page"},{"location":"yas_style/#Differences-from-DefaultStyle","page":"YAS Style","title":"Differences from DefaultStyle","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"There are three main differences between YASStyle and DefaultStyle. They are based on alignment and line break behaviors.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Arguments are aligned to just after the start of the opener [, {, (, etc.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"function_call(arg1,\n arg2)","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"As you can see from the above the closer sticks to the final argument.\nNesting (line breaks) only occur when the margin of the next argument exceeds the maximim limit.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"function_call(arg1, arg2,\n arg3)","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"arg3 exceeded the margin limit and so it was placed on the following line.","category":"page"},{"location":"yas_style/#Nesting","page":"YAS Style","title":"Nesting =","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Unlike DefaultStyle, assignment operations = are not nested. That is, the following","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"my_function(arg1, arg2) = arg1 * arg2","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"Is not nested to","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"my_function(arg1, arg2) =\n arg1 * arg2","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"It is highly recommended setting short_to_long_function_def to true. This option transforms the above to a long function definition if it exceeds the maximum margin.","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"function my_function(arg1, arg2)\n arg1 * arg2\nend","category":"page"},{"location":"yas_style/#Additional-Options","page":"YAS Style","title":"Additional Options","text":"","category":"section"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"The YASStyle supports the additional option variable_call_indent, which is set to [] by default. It allows calls without aligning to the opening parenthesis:","category":"page"},{"location":"yas_style/","page":"YAS Style","title":"YAS Style","text":"# Allowed with and without `Dict in variable_call_indent`\nDict{Int,Int}(1 => 2,\n 3 => 4)\n\n# Allowed when `Dict in variable_call_indent`, but\n# will be changed to the first example when `Dict ∉ variable_call_indent`.\nDict{Int,Int}(\n 1 => 2,\n 3 => 4)","category":"page"},{"location":"integrations/#Integrations","page":"Integrations","title":"Integrations","text":"","category":"section"},{"location":"integrations/#pre-commit","page":"Integrations","title":"pre-commit","text":"","category":"section"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"To learn more about pre-commit, check out their docs.","category":"page"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"With Pull 674, support for pre-commit was added. To add JuliaFormatter.jl to your own pre-commit workflow, add the following to your .pre-commit-config.yaml.","category":"page"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"repos:\n# ... other repos you may have\n- repo: \"https://github.com/domluna/JuliaFormatter.jl\"\n rev: \"v1.0.18\" # or whatever the desired release is\n hooks:\n - id: \"julia-formatter\"\n# ... other repos you may have","category":"page"},{"location":"integrations/","page":"Integrations","title":"Integrations","text":"You can find a list of releases here. Be sure to use the entire version string! (You can double-check this by opening the release and looking at the part of the URL that follows .../releases/tag/VERSION.)","category":"page"},{"location":"blue_style/#Blue-Style","page":"Blue Style","title":"Blue Style","text":"","category":"section"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"BlueStyle","category":"page"},{"location":"blue_style/#JuliaFormatter.BlueStyle","page":"Blue Style","title":"JuliaFormatter.BlueStyle","text":"BlueStyle()\n\nFormatting style based on BlueStyle and JuliaFormatter#283.\n\nnote: Note\nThis style is still work-in-progress, and does not yet implement all of the BlueStyle guide.\n\nConfigurable options with different defaults to DefaultStyle are:\n\nalways_use_return = true\nshort_to_long_function_def = true\nwhitespace_ops_in_indices = true\nremove_extra_newlines = true\nalways_for_in = true\nimport_to_using = true\npipe_to_function_call = true\nwhitespace_in_kwargs = false\nannotate_untyped_fields_with_any = false\nseparate_kwargs_with_semicolon = true\n\n\n\n\n\n","category":"type"},{"location":"blue_style/#Configuration-File-Example","page":"Blue Style","title":"Configuration File Example","text":"","category":"section"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"The .JuliaFormatter.toml which represents these settings is","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"style = \"blue\"","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"Or to use BlueStyle except change one of the settings:","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"style = \"blue\"\nremove_extra_newlines = false","category":"page"},{"location":"blue_style/#Direct-Usage","page":"Blue Style","title":"Direct Usage","text":"","category":"section"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"format(\"file.jl\", BlueStyle())","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"Or to use BlueStyle except change one of the settings:","category":"page"},{"location":"blue_style/","page":"Blue Style","title":"Blue Style","text":"format(\"file.jl\", BlueStyle(), remove_extra_newlines=false)","category":"page"},{"location":"api/#API-Documentation","page":"API Reference","title":"API Documentation","text":"","category":"section"},{"location":"api/","page":"API Reference","title":"API Reference","text":"Modules = [JuliaFormatter]\nFilter = t -> (t != YASStyle && t != BlueStyle && t != SciMLStyle) # on their own pages","category":"page"},{"location":"api/#JuliaFormatter.AlignGroup","page":"API Reference","title":"JuliaFormatter.AlignGroup","text":"AlignGroup\n\nGroup of FST node indices and required metadata to potentially align them.\n\n- `node_inds`. Indices of FST nodes affected by alignment.\n- `nodes`. FST nodes affected by alignment.\n- `line_offsets`. Line offset of the character nodes may be aligned to\nin the source file.\n- `lens`. Length of the FST node prior to the alignment character. Used\nto calculate extra whitespace padding.\n- `whitespaces`. Number of whitespaces between the alignment character and\nthe prior FST node. If this is > 1 it signifies additional whitespace was\nmanually added by the user since the formatter would only use 0 or 1 whitespaces.\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.DefaultStyle","page":"API Reference","title":"JuliaFormatter.DefaultStyle","text":"DefaultStyle\n\nThe default formatting style. See the Style section of the documentation for more details.\n\nSee also: BlueStyle, YASStyle, SciMLStyle, MinimalStyle\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.FST","page":"API Reference","title":"JuliaFormatter.FST","text":"Formatted Syntax Tree\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.MinimalStyle","page":"API Reference","title":"JuliaFormatter.MinimalStyle","text":"MinimalStyle()\n\n\n\n\n\n","category":"type"},{"location":"api/#JuliaFormatter.add_node!-Tuple{JuliaFormatter.FST, JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.add_node!","text":"add_node!(\n t::FST,\n n::FST,\n s::State;\n join_lines::Bool = false,\n max_padding::Int = -1,\n override_join_lines_based_on_source::Bool = false,\n)\n\nAppends n to t.\n\njoin_lines if false a NEWLINE node will be added and n will appear\n\non the next line, otherwise it will appear on the same line as the previous node (when printing).\n\nmax_padding >= 0 indicates margin of t should be based on whether the margin\n\nof n + max_padding is greater than the current margin of t. Otherwise the margin n will be added to t.\n\noverride_join_lines_based_on_source is only used when join_lines_based_on_source option is true. In which\n\nn is added to t as if join_lines_based_on_source was false.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_binaryopcalls!-Tuple{JuliaFormatter.FST, Vector{Int64}}","page":"API Reference","title":"JuliaFormatter.align_binaryopcalls!","text":"align_binaryopcalls!(fst::FST, op_inds::Vector{Int})\n\nAligns binary operator expressions.\n\nAdditionally handles the case where a keyword such as const is used prior to the binary op call.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_conditional!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.align_conditional!","text":"align_conditional!(fst::FST)\n\nAligns a conditional expression.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_matrix!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.align_matrix!","text":"Adjust whitespace in between matrix elements such that it's the same as the original source file.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.align_struct!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.align_struct!","text":"align_struct!(fst::FST)\n\nAligns struct fields.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.annotate_typefields_with_any!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.annotate_typefields_with_any!","text":"annotate_typefields_with_any!(fst::FST, s::State)\n\nAnnotates fields in a type definitions with ::Any if no type annotation is provided.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.binaryop_to_whereop!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.binaryop_to_whereop!","text":"binaryop_to_whereop(fst::FST, s::State)\n\nHandles the case of a function def defined as:\n\nfoo(a::A)::R where A = body\n\nIn this case instead of it being parsed as (1):\n\nBinary\n - Where\n - OP\n - RHS\n\nIt's parsed as (2):\n\nBinary\n - Binary\n - LHS\n - OP\n - Where\n - R\n - ...\n - OP\n - RHS\n\n(1) is preferrable since it's the same parsed result as:\n\nfoo(a::A) where A = body\n\nThis transformation converts (2) to (1).\n\nref https://github.com/julia-vscode/CSTParser.jl/issues/93\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.eq_to_in_normalization!-Tuple{JuliaFormatter.FST, Bool, String}","page":"API Reference","title":"JuliaFormatter.eq_to_in_normalization!","text":"eq_to_in_normalization!(fst::FST, always_for_in::Bool, for_in_replacement::String)\neq_to_in_normalization!(fst::FST, always_for_in::Nothing, for_in_replacement::String)\n\nTransforms\n\nfor i = iter body end\n\n=>\n\nfor i in iter body end\n\nAND\n\nfor i in 1:10 body end\n\n=>\n\nfor i = 1:10 body end\n\nalways_for_in=nothing disables this normalization behavior.\n\nhttps://github.com/domluna/JuliaFormatter.jl/issues/34\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.find_optimal_nest_placeholders-Tuple{JuliaFormatter.FST, Int64, Int64}","page":"API Reference","title":"JuliaFormatter.find_optimal_nest_placeholders","text":"Finds 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.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.flatten_binaryopcall-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.flatten_binaryopcall","text":"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.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format-Tuple{Any, JuliaFormatter.AbstractStyle}","page":"API Reference","title":"JuliaFormatter.format","text":"format(path, style::AbstractStyle; options...)::Bool\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format-Tuple{Any}","page":"API Reference","title":"JuliaFormatter.format","text":"format(\n paths; # a path or collection of paths\n options...,\n)::Bool\n\nRecursively descend into files and directories, formatting any .jl, .md, .jmd, or .qmd files.\n\nSee format_file and format_text for a description of the options.\n\nThis 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.\n\nOutput\n\nReturns a boolean indicating whether the file was already formatted (true) or not (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format-Tuple{Module, Vararg{Any}}","page":"API Reference","title":"JuliaFormatter.format","text":"format(mod::Module, args...; options...)\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format_file-Tuple{AbstractString}","page":"API Reference","title":"JuliaFormatter.format_file","text":"format_file(\n filename::AbstractString;\n overwrite::Bool = true,\n verbose::Bool = false,\n format_markdown::Bool = false,\n format_options...,\n)::Bool\n\nFormats the contents of filename assuming it's a .jl, .md, .jmd or .qmd file.\n\nSee https://domluna.github.io/JuliaFormatter.jl/dev/#File-Options for details on available options.\n\nOutput\n\nReturns a boolean indicating whether the file was already formatted (true) or not (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format_md-Tuple{AbstractString}","page":"API Reference","title":"JuliaFormatter.format_md","text":"format_md(text::AbstractString; style::AbstractStyle = DefaultStyle(), kwargs...)\n\nNormalizes the Markdown source and formats Julia code blocks.\n\nSee format_text for description of formatting options.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.format_text-Tuple{AbstractString}","page":"API Reference","title":"JuliaFormatter.format_text","text":"format_text(\n text::AbstractString;\n style::AbstractStyle = DefaultStyle(),\n indent::Int = 4,\n margin::Int = 92,\n options...,\n)::String\n\nFormats a Julia source passed in as a string, returning the formatted code as another string.\n\nSee https://domluna.github.io/JuliaFormatter.jl/dev/#Formatting-Options for details on available options.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.is_iterable_arg-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.is_iterable_arg","text":"Returns whether fst can be an iterable argument. For example in the case of a function call, which is of type Call:\n\n(a, b, c; k1=v1)\n\nThis would return true for a, b, c and k1=v1 and false for all other nodes.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.length_to-Tuple{JuliaFormatter.FST, Any}","page":"API Reference","title":"JuliaFormatter.length_to","text":"`length_to(x::FST, ntyps; start::Int = 1)`\n\nReturns the length to any node type in ntyps based off the start index.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.long_to_short_function_def!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.long_to_short_function_def!","text":"long_to_short_function_def!(fst::FST, s::State)\n\nTransforms a long function definition\n\nfunction f(arg2, arg2)\n body\nend\n\nto a short function definition\n\nf(arg1, arg2) = body\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.move_at_sign_to_the_end-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.move_at_sign_to_the_end","text":"move_at_sign_to_the_end(fst::FST, s::State)\n\nNOTE: Assumes fst is the caller name of a macrocall such as @macro or Module.@macro.\n\nMoves @ to the last identifier.\n\nExample:\n\n@Module.macro\n\nto\n\nModule.@macro\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.nest_if_over_margin!-Tuple{JuliaFormatter.AbstractStyle, JuliaFormatter.FST, JuliaFormatter.State, Int64, Vector{Tuple{JuliaFormatter.FNode, Union{Nothing, JuliaFormatter.Metadata}}}}","page":"API Reference","title":"JuliaFormatter.nest_if_over_margin!","text":"nest_if_over_margin!(\n style,\n fst::FST,\n s::State,\n idx::Int;\n stop_idx::Union{Int,Nothing} = nothing,\n)::Bool\n\nConverts 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.\n\nIf stop_idx == nothing the range is fst[idx:end].\n\nReturns whether nesting occurred.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.pipe_to_function_call_pass!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.pipe_to_function_call_pass!","text":"pipe_to_function_call_pass!(fst::FST)\n\nRewrites x |> f to f(x).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.prepend_return!-Tuple{JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.prepend_return!","text":"prepend_return!(fst::FST, s::State)\n\nPrepends return to the last expression of a block if applicable.\n\nfunction foo()\n a = 2 * 3\n a / 3\nend\n\nto\n\nfunction foo()\n a = 2 * 3\n return a / 3\nend\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.remove_superfluous_whitespace!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.remove_superfluous_whitespace!","text":"remove_superfluous_whitespace!(fst::FST)\n\nSoft deletes WHITESPACE or PLACEHOLDER that's directly followed by a NEWLINE or INLINECOMMENT node.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.separate_kwargs_with_semicolon!-Tuple{JuliaFormatter.FST}","page":"API Reference","title":"JuliaFormatter.separate_kwargs_with_semicolon!","text":"separate_kwargs_with_semicolon!(fst::FST)\n\nEnsures keyword arguments are separated by a \";\".\n\nExamples\n\nReplace \",\" with \";\".\n\na = f(x, y = 3)\n\n->\n\na = f(x; y = 3)\n\nMove \";\" to the prior to the first positional argument.\n\na = f(x = 1; y = 2)\n\n->\n\na = f(; x = 1, y = 2)\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.short_to_long_function_def!-Tuple{JuliaFormatter.FST, JuliaFormatter.State, Vector{Tuple{JuliaFormatter.FNode, Union{Nothing, JuliaFormatter.Metadata}}}}","page":"API Reference","title":"JuliaFormatter.short_to_long_function_def!","text":"short_to_long_function_def!(fst::FST, s::State)\n\nTransforms a short function definition\n\nf(arg1, arg2) = body\n\nto a long function definition\n\nfunction f(arg2, arg2)\n body\nend\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.unnestable_node-Tuple{JuliaSyntax.GreenNode}","page":"API Reference","title":"JuliaFormatter.unnestable_node","text":"cst is assumed to be a single child node. Returnss true if the node is of the syntactic form {...}, [...], or (...).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.walk-Tuple{Function, JuliaFormatter.FST, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.walk","text":"walk(f, fst::FST, s::State)\n\nWalks fst calling f on each node.\n\nIn situations where descending further into a subtree is not desirable f should return a value other than nothing.\n\nnote: Note\nThis 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.\n\n\n\n\n\n","category":"method"},{"location":"transforms/#Syntax-Tree-Transformations","page":"Syntax Transforms","title":"Syntax Tree Transformations","text":"","category":"section"},{"location":"transforms/#for-in-vs.-for","page":"Syntax Transforms","title":"for in vs. for =","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"By default if the RHS is a range, i.e. 1:10 then for in is converted to for =. Otherwise for = is converted to for in. See this issue for the rationale and further explanation.","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"Alternative to the above - setting always_for_in to true, i.e. format_text(..., always_for_in = true) will always convert = to in even if the RHS is a range. always_for_in=nothing will leave the choice of in vs = up to the user.","category":"page"},{"location":"transforms/#Trailing-Commas","page":"Syntax Transforms","title":"Trailing Commas","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If the node is iterable, for example a function call or list and is nested, a trailing comma is added to the last argument. The trailing comma is removed if unnested:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"func(a, b, c)\n\n->\n\nfunc(\n a,\n b,\n c,\n)","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Trailing-Semicolons","page":"Syntax Transforms","title":"Trailing Semicolons","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If a matrix node is nested the semicolons are removed.","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"A = [1 0; 0 1]\n\n->\n\nA = [\n 1 0\n 0 1\n]","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Leading-and-trailing-0s-for-float-literals","page":"Syntax Transforms","title":"Leading and trailing 0s for float literals","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If a float literal is missing a trailing 0 it is added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"a = 1.\n\n->\n\na = 1.0","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If a float literal is missing a leading 0 it is added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"a = .1\n\n->\n\na = 0.1","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"For Float32 if there is no decimal point, .0 is added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"a = 1f0\n\n->\n\na = 1.0f0","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Surround-where-arguments-with-curly-brackets","page":"Syntax Transforms","title":"Surround where arguments with curly brackets","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"If the arguments of a where call are not surrounded by curly brackets, they are added:","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"foo(x::T) where T = ...\n\n->\n\nfoo(x::T) where {T} = ...","category":"page"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"See this issue for more details.","category":"page"},{"location":"transforms/#Annotate-unannotated-type-fields-with-Any","page":"Syntax Transforms","title":"Annotate unannotated type fields with Any","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"struct Foo\n field\nend\n\n->\n\nstruct Foo\n field::Any\nend","category":"page"},{"location":"transforms/#Move-@-in-macro-calls-to-the-final-identifier","page":"Syntax Transforms","title":"Move @ in macro calls to the final identifier","text":"","category":"section"},{"location":"transforms/","page":"Syntax Transforms","title":"Syntax Transforms","text":"@Module.macro\n\n->\n\nModule.@macro","category":"page"},{"location":"custom_alignment/#Custom-Alignment","page":"Custom Alignment","title":"Custom Alignment","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Solution for issue 179","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Custom alignment is determined by a whitespace heuristic:","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"A token (typically an operator, i.e. =, ?, ::, etc) is custom aligned if there are > 1 whitespaces from the previous expression since the formatter only outputs 0 or 1 whitespaces for separation. If custom alignment is determined then all expressions in the code block will be aligned to the furthest aligned token.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"NOTE: alignment overrides nesting behavior, meaning it ignores the allowed maximum margin","category":"page"},{"location":"custom_alignment/#Example","page":"Custom Alignment","title":"Example","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Suppose the source text is as follows","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = 2\nconst var3 = 3\nconst var4 = 4\nconst var5 = 5","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"If the align_assignment option is enabled the formatter will detect that var2 is aligned to variable1 AND var2 has several whitespaces (>1) prior to =. Since var3,var4, and var5 are part of the same code block (no comments or newlines separating code) they will also be aligned.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"So the output would be","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = 2\nconst var3 = 3\nconst var4 = 4\nconst var5 = 5","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Notice how the = operator for var5 is correctly positioned despite it being located further to the right than other = operators.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"However, if the source code is","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst variable2 = 2\nconst var3 = 3\nconst var4 = 4\nconst var5 = 5","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"It's now ambiguous whether this is meant to be aligned and so the formatter will proceed with normal behavior.","category":"page"},{"location":"custom_alignment/#Alignment-Options","page":"Custom Alignment","title":"Alignment Options","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"In order for alignment to occur the option must be set to true. Available options:","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"align_assignment\nalign_struct_field\nalign_conditional\nalign_pair_arrow\nalign_matrix","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Caveat: Since nesting is disabled when alignment occurs be careful when adding comments to the RHS expression. This will be fixed in a future release","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"For example:","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = foo(10,\n # comment,\n 20)","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"This will be formatted to","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const variable1 = 1\nconst var2 = foo(10, # comment, 20)","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"which causes a parsing error.","category":"page"},{"location":"custom_alignment/#align_assignment","page":"Custom Alignment","title":"align_assignment","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align to =-like operators. This covers variable assignments and short definition functions.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"const UTF8PROC_STABLE = (1 << 1)\nconst UTF8PROC_COMPAT = (1 << 2)\nconst UTF8PROC_COMPOSE = (1 << 3)\nconst UTF8PROC_DECOMPOSE = (1 << 4)\nconst UTF8PROC_IGNORE = (1 << 5)\nconst UTF8PROC_REJECTNA = (1 << 6)\nconst UTF8PROC_NLF2LS = (1 << 7)\nconst UTF8PROC_NLF2PS = (1 << 8)\nconst UTF8PROC_NLF2LF = (UTF8PROC_NLF2LS | UTF8PROC_NLF2PS)\nconst UTF8PROC_STRIPCC = (1 << 9)\nconst UTF8PROC_CASEFOLD = (1 << 10)\nconst UTF8PROC_CHARBOUND = (1 << 11)\nconst UTF8PROC_LUMP = (1 << 12)\nconst UTF8PROC_STRIP = (1 << 13)\n\n\nvcat(X::T...) where {T} = T[X[i] for i = 1:length(X)]\nvcat(X::T...) where {T<:Number} = T[X[i] for i = 1:length(X)]\nhcat(X::T...) where {T} = T[X[j] for i = 1:1, j = 1:length(X)]\nhcat(X::T...) where {T<:Number} = T[X[j] for i = 1:1, j = 1:length(X)]\n\na = 1\nbc = 2\n\nlong_variable = 1\nother_var = 2","category":"page"},{"location":"custom_alignment/#align_struct_field","page":"Custom Alignment","title":"align_struct_field","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align struct field definitions to :: or = - whichever has higher precedence.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Base.@kwdef struct Options\n indent::Int = 4\n margin::Int = 92\n always_for_in::Bool = false\n whitespace_typedefs::Bool = false\n whitespace_ops_in_indices::Bool = false\n remove_extra_newlines::Bool = false\n import_to_using::Bool = false\n pipe_to_function_call::Bool = false\n short_to_long_function_def::Bool = false\n always_use_return::Bool = false\n whitespace_in_kwargs::Bool = true\n annotate_untyped_fields_with_any::Bool = true\n format_docstrings::Bool = false\n align_struct_fields::Bool = false\n\n # no custom whitespace so this block is not aligned\n another_field1::BlahBlahBlah = 10\n field2::Foo = 10\n\n # no custom whitespace but single line blocks are not aligned\n # either way\n Options() = new()\nend\n\n\nmutable struct Foo\n a :: T\n longfieldname :: T\nend","category":"page"},{"location":"custom_alignment/#align_conditional","page":"Custom Alignment","title":"align_conditional","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align conditional expressions to either ?, :, or both.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"# This will remain like this if using YASStyle\nindex = zeros(n <= typemax(Int8) ? Int8 :\n n <= typemax(Int16) ? Int16 :\n n <= typemax(Int32) ? Int32 : Int64, n)\n\n# Using DefaultStyle\nindex = zeros(\n n <= typemax(Int8) ? Int8 :\n n <= typemax(Int16) ? Int16 :\n n <= typemax(Int32) ? Int32 : Int64,\n n,\n)\n\n# Note even if the maximum margin is set to 1, the alignment remains intact\nindex =\n zeros(\n n <= typemax(Int8) ? Int8 :\n n <= typemax(Int16) ? Int16 :\n n <= typemax(Int32) ? Int32 : Int64,\n n,\n )\n","category":"page"},{"location":"custom_alignment/#align_pair_arrow","page":"Custom Alignment","title":"align_pair_arrow","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Align pair arrows (=>).","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"pages = [\n \"Introduction\" => \"index.md\",\n \"How It Works\" => \"how_it_works.md\",\n \"Code Style\" => \"style.md\",\n \"Skipping Formatting\" => \"skipping_formatting.md\",\n \"Syntax Transforms\" => \"transforms.md\",\n \"Custom Alignment\" => \"custom_alignment.md\",\n \"Custom Styles\" => \"custom_styles.md\",\n \"YAS Style\" => \"yas_style.md\",\n \"Configuration File\" => \"config.md\",\n \"API Reference\" => \"api.md\",\n]","category":"page"},{"location":"custom_alignment/#align_matrix","page":"Custom Alignment","title":"align_matrix","text":"","category":"section"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"TLDR: If you want to align matrix elements yourself set this to true","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"Whitespace surrounding matrix elements in the original source file is maintained. Differs from other alignment options since it does not try to \"detect\" alignment and then adjust other elements.","category":"page"},{"location":"custom_alignment/","page":"Custom Alignment","title":"Custom Alignment","text":"# Elements left-aligned in original source\njulia> s = \"\"\"\n a = [\n 100 300 400\n 1 eee 40000\n 2 α b\n ]\"\"\"\n\"a = [\\n100 300 400\\n1 eee 40000\\n2 α b\\n]\"\n\njulia> format_text(s, align_matrix=true) |> print\na = [\n 100 300 400\n 1 eee 40000\n 2 α b\n]\n\n# Elements right-aligned in original source\njulia> s = \"\"\"\n a = [\n 100 300 400\n 1 ee 40000\n 2 a b\n ]\"\"\"\n\"a = [\\n100 300 400\\n 1 ee 40000\\n 2 a b\\n]\"\n\njulia>\n\njulia> format_text(s, align_matrix=true) |> print\na = [\n 100 300 400\n 1 ee 40000\n 2 a b\n]","category":"page"},{"location":"how_it_works/#How-It-Works","page":"How It Works","title":"How It Works","text":"","category":"section"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"The formatter takes a .jl file as input and produce a idealized, formatted .jl as output. Some formatters mutate the state of the current file, JuliaFormatter takes a different approach - first generating a canonical output, and then mutating that canonical output; adhering to the indent and margin constraints.","category":"page"},{"location":"how_it_works/#Generating-an-FST","page":"How It Works","title":"Generating an FST","text":"","category":"section"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"The source code is parsed with CSTParser.jl which returns a CST (Concrete Syntax Tree). A CST is a one-to-one mapping of the language to a tree form. In most cases a more compact AST (Abstract Syntax Tree) representation is desired. However, since formatting manipulate the source text itself, the richer representation of a CST is incredibly useful.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Once the CST is created it's then used to generate a FST (Formatted Syntax Tree).","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Note: this is not an actual term, just something I made up. Essentially it's a CST with additional formatting specific metadata.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"The important part of an FST is any .jl file that is syntactically the same (whitespace is irrelevant) produce an identical FST.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"For example:","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"# p1.jl\na = \n foo(a, b, \n c,d)","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"and","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"# p2.jl\na = foo(a,\nb,\nc,d)","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"will produce the same FST, which printed would look like:","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"# fst output\na = foo(a, b, c, d)","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"So what does a typical FST look like?","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Code and comments are indented to match surrounding code blocks. Unnecessary whitespace is removed. Newlines in between code blocks are untouched.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"If the expression can be put on a single line it will be. It doesn't matter it's a function call which 120 arguments, making it 1000 characters long. During this initial stage it will be put on a single line.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"If the expression has a structure to it, such as a try, if, or 'struct' definition. It will be spread across multiple lines appropriately:","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"\n# original source\ntry a1;a2 catch e b1;b2 finally c1;c2 end\n\n-> \n\n# printed FST\ntry\n a1\n a2\ncatch e\n b1\n b2\nfinally\n c1\n c2\nend","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"With this FST representation it's much easier to determine when and how lines should be broken.","category":"page"},{"location":"how_it_works/#Nesting-breaking-lines","page":"How It Works","title":"Nesting - breaking lines","text":"","category":"section"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"During the nesting stage and original FST is mutated to adhere to the margin specification.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Throughout the previous stage, while the FST was being generated, PLACEHOLDER nodes were being inserted at various points. These can be converted to NEWLINE nodes during nesting, which is how lines are broken.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Assume we had a function call which went over the margin.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"begin\n foo = funccall(argument1, argument2, ..., argument120) # way over margin limit !!!\nend","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"It would be nested to","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"begin\n foo = funccall(\n argument1,\n argument2,\n ...,\n argument120\n ) # way over margin limit !!!\nend","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"You can read how code is nested in the style section.","category":"page"},{"location":"how_it_works/","page":"How It Works","title":"How It Works","text":"Once the FST has been nested it's then printed out to a file and voila! You have a formatted version of your code!","category":"page"},{"location":"skipping_formatting/#Skipping-Formatting","page":"Skipping Formatting","title":"Skipping Formatting","text":"","category":"section"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"By default formatting is always on but can be toggled with the following comments:","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"#! format: off\n# Turns off formatting from this point onwards\n...\n\n#! format: on\n# Turns formatting back on from this point onwards","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"These can be used throughout a file, or, for an entire file not be formatted add \"format: off\" at the top of the file:","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"#! format: off\n#\n# It doesn't actually matter if it's on\n# the first line of the line but anything\n# onwards will NOT be formatted.\n\nmodule Foo\n...\nend","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"note: Ignoring files\nYou can also ignore entire files and directories by supplying the ignore option in .JuliaFormatter.toml.","category":"page"},{"location":"skipping_formatting/","page":"Skipping Formatting","title":"Skipping Formatting","text":"Note the formatter expects #! format: on and #! format: off to be on its own line and the whitespace to be an exact match.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"CurrentModule = JuliaFormatter","category":"page"},{"location":"#JuliaFormatter.jl","page":"Introduction","title":"JuliaFormatter.jl","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Width-sensitive formatter for Julia code. Inspired by gofmt, refmt, black, and prettier. Built with CSTParser.jl.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Sane defaults out of the box with options to customize.\nSupports YAS, Blue and SciML style guides.\n.JuliaFormatter.toml configuration file to store options.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"(Image: )","category":"page"},{"location":"#Installation","page":"Introduction","title":"Installation","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"]add JuliaFormatter","category":"page"},{"location":"#Quick-Start","page":"Introduction","title":"Quick Start","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"julia> using JuliaFormatter\n\n# Recursively formats all Julia files in the current directory\njulia> format(\".\")\n\n# Formats an individual file\njulia> format_file(\"foo.jl\")\n\n# Formats a string (contents of a Julia file)\njulia> format_text(str)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Check out the docs for further description of the formatter and its options.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Use With GitHub Actions","category":"page"},{"location":"#Formatting-Options","page":"Introduction","title":"Formatting Options","text":"","category":"section"},{"location":"#indent","page":"Introduction","title":"indent","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: 4","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The number of spaces used for an indentation.","category":"page"},{"location":"#margin","page":"Introduction","title":"margin","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: 92","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The maximum length of a line. Code exceeding this margin will be formatted across multiple lines.","category":"page"},{"location":"#always_for_in","page":"Introduction","title":"always_for_in","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"#whitespace_typedefs","page":"Introduction","title":"whitespace_typedefs","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.","category":"page"},{"location":"#whitespace_ops_in_indices","page":"Introduction","title":"whitespace_ops_in_indices","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Example: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].","category":"page"},{"location":"#remove_extra_newlines","page":"Introduction","title":"remove_extra_newlines","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, superfluous newlines will be removed. For example:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module M\n\n\n\na = 1\n\nfunction foo()\n\n\n return nothing\n\nend\n\n\nb = 2\n\n\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"is rewritten as","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module M\n\na = 1\n\nfunction foo()\n return nothing\nend\n\nb = 2\n\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Modules are the only type of code block allowed to keep a single newline prior to the initial or after the final piece of code.","category":"page"},{"location":"#import_to_using","page":"Introduction","title":"import_to_using","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, import expressions are rewritten to using expressions in the following cases:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"import A\n\nimport A, B, C","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"is rewritten to:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"using A: A\n\nusing A: A\nusing B: B\nusing C: C","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Exceptions:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If as is found in the import expression. using CANNOT be used in this context. The following example will NOT BE rewritten.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"import Base.Threads as th","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If import is used in the following context it is NOT rewritten. This may change in a future patch.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"@everywhere import A, B","category":"page"},{"location":"#pipe_to_function_call","page":"Introduction","title":"pipe_to_function_call","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, x |> f is rewritten to f(x).","category":"page"},{"location":"#short_to_long_function_def","page":"Introduction","title":"short_to_long_function_def","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Transforms a short function definition","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(arg1, arg2) = body","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to a long function definition if the short function definition exceeds the maximum margin. Or if force_long_function_def is set to true.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function f(arg2, arg2)\n body\nend","category":"page"},{"location":"#force_long_function_def","page":"Introduction","title":"force_long_function_def","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true tweaks the behavior of short_to_long_function_def to force the transformation no matter how short the function definition is.","category":"page"},{"location":"#long_to_short_function_def","page":"Introduction","title":"long_to_short_function_def","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Transforms a long function definition","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function f(arg2, arg2)\n body\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to a short function definition if the short function definition does not exceed the maximum margin.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(arg1, arg2) = body","category":"page"},{"location":"#always_use_return","page":"Introduction","title":"always_use_return","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, return will be prepended to the last expression where applicable in function definitions, macro definitions, and do blocks.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Example:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo()\n expr1\n expr2\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo()\n expr1\n return expr2\nend","category":"page"},{"location":"#whitespace_in_kwargs","page":"Introduction","title":"whitespace_in_kwargs","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, = in keyword arguments will be surrounded by whitespace.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(; a=4)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(; a = 4)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"#annotate_untyped_fields_with_any","page":"Introduction","title":"annotate_untyped_fields_with_any","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Annotates fields in a type definitions with ::Any if no type annotation is provided:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"struct A\n arg1\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"struct A\n arg1::Any\nend","category":"page"},{"location":"#format_docstrings","page":"Introduction","title":"format_docstrings","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Format code docstrings with the same options used for the code source.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Markdown is formatted with CommonMark alongside Julia code.","category":"page"},{"location":"#align_*","page":"Introduction","title":"align_*","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"See Custom Alignment documentation.","category":"page"},{"location":"#conditional_to_if","page":"Introduction","title":"conditional_to_if","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If the conditional E ? A : B exceeds the maximum margin converts it into the equivalent if block:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if E\n A\nelse\n B\nend","category":"page"},{"location":"#normalize_line_endings","page":"Introduction","title":"normalize_line_endings","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: \"auto\"","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"One of \"unix\" (normalize all \\r\\n to \\n), \"windows\" (normalize all \\n to \\r\\n), \"auto\" (automatically choose based on which line ending is more common in the file).","category":"page"},{"location":"#trailing_comma","page":"Introduction","title":"trailing_comma","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"One of true, false, or nothing.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Trailing commas are added after the final argument when nesting occurs and the closing punctuation appears on the next line.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"For example when the following is nested (assuming DefaultStyle):","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"funccall(arg1, arg2, arg3)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"it turns into:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"funccall(\n arg1,\n arg2,\n arg3, # trailing comma added after `arg3` (final argument) !!!\n)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When set to true, the trailing comma is always added during nesting.\nWhen set to false, the trailing comma is always removed during nesting.\nWhen set to nothing, the trailing comma appears as it does in the original source.","category":"page"},{"location":"#trailing_zero","page":"Introduction","title":"trailing_zero","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Add a trailing zero, if needed.","category":"page"},{"location":"#join_lines_based_on_source","page":"Introduction","title":"join_lines_based_on_source","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When true lines are joined as they appear in the original source file.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo(arg1,\n arg2, arg3\n )\n body\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When false and the maximum margin is > than the length of \"function foo(arg1, arg2, arg3)\" this is formatted to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo(arg1, arg2, arg3)\n body\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When 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.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function foo(arg1,\n arg2, arg3,\n)\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"There are exceptions to this:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if a body1 elseif b body2 else body3 end","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"will be formatted to the following, even if this option is set to true:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if a\n body1\nelseif b\n body2\nelse\n body3\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"warning: Warning\nThe maximum margin still applies even when this option is set to true.","category":"page"},{"location":"#indent_submodule","page":"Introduction","title":"indent_submodule","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When set to true, submodule(s) appearing in the same file will be indented.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module A\na = 1\n\nmodule B\nb = 2\nmodule C\nc = 3\nend\nend\n\nd = 4\n\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"will be formatted to:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"module A\na = 1\n\nmodule B\n b = 2\n module C\n c = 3\n end\nend\n\nd = 4\n\nend","category":"page"},{"location":"#separate_kwargs_with_semicolon","page":"Introduction","title":"separate_kwargs_with_semicolon","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"When set to true, keyword arguments in a function call will be separated with a semicolon.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"f(a, b=1)\n\n->\n\nf(a; b=1)","category":"page"},{"location":"#surround_whereop_typeparameters","page":"Introduction","title":"surround_whereop_typeparameters","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Surrounds type parameters with curly brackets when set to true if the brackets are not already present.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function func(...) where TPARAM\nend\n\n->\n\nfunction func(...) where {TPARAM}\nend","category":"page"},{"location":"#for_in_replacement","page":"Introduction","title":"for_in_replacement","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Can be used when always_for_in is true to replace the default in with ∈ (\\\\in), or = instead. The replacement options are (\"in\", \"=\", \"∈\").","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"for a = 1:10\nend\n\n# formatted with always_for_in = true, for_in_replacement = \"∈\"\nfor a ∈ 1:10\nend","category":"page"},{"location":"#variable_call_indent-and-and-yas_style_nesting","page":"Introduction","title":"variable_call_indent && yas_style_nesting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"The SciMLStyle supports the additional options variable_call_indent and yas_style_nesting.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The option variable_call_indent is set to [] by default. It allows calls without aligning to the opening parenthesis:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"# Allowed with and without `Dict in variable_call_indent`\nDict{Int, Int}(1 => 2,\n 3 => 4)\n\n# Allowed when `Dict in variable_call_indent`, but\n# will be changed to the first example when `Dict ∉ variable_call_indent`.\nDict{Int, Int}(\n 1 => 2,\n 3 => 4)","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"The option yas_style_nesting is set to false by default. Setting it to true makes the SciMLStyle use the YASStyle nesting rules:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"# With `yas_style_nesting = false`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend\n\n# With `yas_style_nesting = true`\nfunction my_large_function(argument1, argument2,\n argument3, argument4,\n argument5, x, y, z)\n foo(x) + goo(y)\nend","category":"page"},{"location":"#short_circuit_to_if","page":"Introduction","title":"short_circuit_to_if","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"You can convert short circuit expressions to the equivalent if expression.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"b0 && foo()\n\nb1 || bar()","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"respectively become","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"if b0\n foo()\nelse\n false\nend\n\nif !b1\n bar()\nelse\n true\nend","category":"page"},{"location":"#disallow_single_arg_nesting","page":"Introduction","title":"disallow_single_arg_nesting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Prevents the nesting of a single argument arg in parenthesis, brackets, and curly braces.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"# Without `disallow_single_arg_nesting`:\nfunction_call(\n \"String argument\"\n)\n[array_item(\n 10\n)]\n{key => value(\n \"String value\"\n)}\n\n# With `disallow_single_arg_nesting` enabled:\nfunction_call(\"String argument\")\n[array_item(10)]\n{key => value(\"String value\")}","category":"page"},{"location":"#File-Options","page":"Introduction","title":"File Options","text":"","category":"section"},{"location":"#overwrite","page":"Introduction","title":"overwrite","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: true","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"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.","category":"page"},{"location":"#verbose","page":"Introduction","title":"verbose","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true details related to formatting the file will be printed to stdout.","category":"page"},{"location":"#format_markdown","page":"Introduction","title":"format_markdown","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"default: false","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If true, Markdown files are also formatted. Julia code blocks will be formatted in addition to the Markdown being normalized.","category":"page"},{"location":"#ignore","page":"Introduction","title":"ignore","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"An array of paths to files and directories (with possible Glob wildcards) which will not be formatted.","category":"page"},{"location":"#Special-Format-Comments","page":"Introduction","title":"Special Format Comments","text":"","category":"section"},{"location":"#Turn-off/on-formatting","page":"Introduction","title":"Turn off/on formatting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"You can skip sections of code by using the #! format: off and #! format: on comments.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"\n# this should be formatted\na = f(aaa, bbb, ccc)\n\n# this should not be formatted\n#! format: off\na = f(aaa,\n bbb,ccc)\n\nc = 102000\n\nd = @foo 10 20\n\ne = \"what the foocho\"\n#! format: on\n\n# this should be formatted\na = f(aaa, bbb, ccc)\n\n# ok","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"If you wish to not format an entire file just add #!: format: off to the top of the file.","category":"page"},{"location":"#Stopping-a-block-of-code-from-indenting","page":"Introduction","title":"Stopping a block of code from indenting","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"Sometimes you may wish for a block of code to not be indented. You can achieve this with #!: format: noindent.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"begin\n@muladd begin\n #! format: noindent\n a = 10\n b = 20\n begin\n # another indent\n z = 33\n end\n\n a * b\nend\n end","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"is formatted to","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"begin\n @muladd begin\n #! format: noindent\n a = 10\n b = 20\n begin\n # another indent\n z = 33\n end\n\n a * b\n end\nend","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"Notice the contents of @muladd begin is not indented.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"#!: format: noindent can also be nested.","category":"page"},{"location":"#Editor-Plugins","page":"Introduction","title":"Editor Plugins","text":"","category":"section"},{"location":"","page":"Introduction","title":"Introduction","text":"For integration with other editors:","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"VSCode\nEmacs\nVim\nAtom (deprecated)","category":"page"}] } diff --git a/previews/PR870/skipping_formatting/index.html b/previews/PR870/skipping_formatting/index.html index 383bd9d8..4d8cccc8 100644 --- a/previews/PR870/skipping_formatting/index.html +++ b/previews/PR870/skipping_formatting/index.html @@ -12,4 +12,4 @@ module Foo ... -end
Ignoring files

You can also ignore entire files and directories by supplying the ignore option in .JuliaFormatter.toml.

Note the formatter expects #! format: on and #! format: off to be on its own line and the whitespace to be an exact match.

+end
Ignoring files

You can also ignore entire files and directories by supplying the ignore option in .JuliaFormatter.toml.

Note the formatter expects #! format: on and #! format: off to be on its own line and the whitespace to be an exact match.

diff --git a/previews/PR870/style/index.html b/previews/PR870/style/index.html index 1cec476e..a436aa11 100644 --- a/previews/PR870/style/index.html +++ b/previews/PR870/style/index.html @@ -206,4 +206,4 @@ arg1, arg2, arg3, -) +) diff --git a/previews/PR870/transforms/index.html b/previews/PR870/transforms/index.html index b42d1440..4c595efe 100644 --- a/previews/PR870/transforms/index.html +++ b/previews/PR870/transforms/index.html @@ -42,4 +42,4 @@ -> -Module.@macro +Module.@macro diff --git a/previews/PR870/yas_style/index.html b/previews/PR870/yas_style/index.html index 9d3ad92d..db8f2d2f 100644 --- a/previews/PR870/yas_style/index.html +++ b/previews/PR870/yas_style/index.html @@ -1,5 +1,5 @@ -YAS Style · JuliaFormatter
GitHub

YAS Style

JuliaFormatter.YASStyle — Type
YASStyle()

Formatting style based on YASGuide and JuliaFormatter#198.

Configurable options with different defaults to DefaultStyle are:

  • always_for_in = true
  • whitespace_ops_in_indices = true
  • 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
  • join_lines_based_on_source = true
  • separate_kwargs_with_semicolon = true
source

Configuration File Example

The .JuliaFormatter.toml which represents these settings is

style = "yas"

Or to use YASStyle except change one of the settings:

style = "yas"
+YAS Style · JuliaFormatter
GitHub
YAS Style
JuliaFormatter.YASStyle — Type
YASStyle()
Formatting style based on YASGuide and JuliaFormatter#198.
Configurable options with different defaults to DefaultStyle are:
  • always_for_in = true
  • whitespace_ops_in_indices = true
  • 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
  • join_lines_based_on_source = true
  • separate_kwargs_with_semicolon = true
source
Configuration File Example
The .JuliaFormatter.toml which represents these settings is
style = "yas"
Or to use YASStyle except change one of the settings:
style = "yas"
 remove_extra_newlines = false
Direct Usage
format("file.jl", YASStyle())
Or to use YASStyle except change one of the settings:
format("file.jl", YASStyle(), remove_extra_newlines=false)
Differences from DefaultStyle
There are three main differences between YASStyle and DefaultStyle. They are based on alignment and line break behaviors.
  1. Arguments are aligned to just after the start of the opener [, {, (, etc.
function_call(arg1,
               arg2)
  1. As you can see from the above the closer sticks to the final argument.
  2. Nesting (line breaks) only occur when the margin of the next argument exceeds the maximim limit.
function_call(arg1, arg2,
               arg3)
arg3 exceeded the margin limit and so it was placed on the following line.
Nesting =
Unlike DefaultStyle, assignment operations = are not nested. That is, the following
my_function(arg1, arg2) = arg1 * arg2
Is not nested to
my_function(arg1, arg2) =
@@ -13,4 +13,4 @@
 # will be changed to the first example when `Dict ∉ variable_call_indent`.
 Dict{Int,Int}(
     1 => 2,
-    3 => 4)

+    3 => 4)