From a4564eac1029a13624d263b12f4522221d1f1a0c Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 26 Oct 2023 14:37:23 +0000 Subject: [PATCH] build based on 447c38e --- dev/.documenter-siteinfo.json | 2 +- dev/api/index.html | 26 +++++++++++++------------- dev/blue_style/index.html | 4 ++-- dev/config/index.html | 2 +- dev/custom_alignment/index.html | 2 +- dev/custom_styles/index.html | 2 +- dev/how_it_works/index.html | 2 +- dev/index.html | 6 +++--- dev/integrations/index.html | 2 +- dev/sciml_style/index.html | 4 ++-- dev/search_index.js | 2 +- dev/skipping_formatting/index.html | 2 +- dev/style/index.html | 2 +- dev/transforms/index.html | 2 +- dev/yas_style/index.html | 4 ++-- 15 files changed, 32 insertions(+), 32 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 23ce1843a..ebd0cc9da 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-19T22:35:21","documenter_version":"1.1.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-26T14:37:17","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 795b0f9fd..07ba0de14 100644 --- a/dev/api/index.html +++ b/dev/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,16 +34,16 @@
 
 =>
 
-for i = 1:10 body end

always_for_in=nothing disables this normalization behavior.

  • https://github.com/domluna/JuliaFormatter.jl/issues/34
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.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 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 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.

File Options

overwrite

default: true

If true the file will be reformatted in place, overwriting the existing file; if it is false, the formatted version of foo.jl will not be written anywhere.

verbose

default: false

If true details related to formatting the file will be printed to stdout.

format_markdown

default: false

If true, Markdown files are also formatted. Julia code blocks will be formatted in addition to the Markdown being normalized.

Formatting Options

See format_text for description of formatting options.

Output

Returns a boolean indicating whether the file was already formatted (true) or not (false).

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.

File Options

overwrite

default: true

If true the file will be reformatted in place, overwriting the existing file; if it is false, the formatted version of foo.jl will not be written anywhere.

verbose

default: false

If true details related to formatting the file will be printed to stdout.

format_markdown

default: false

If true, Markdown files are also formatted. Julia code blocks will be formatted in addition to the Markdown being normalized.

Formatting Options

See format_text for description of formatting options.

Output

Returns a boolean indicating whether the file was already formatted (true) or not (false).

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,
@@ -184,7 +184,7 @@
 
 Can be used when `always_for_in` is `true` to replace the default `in` with `∈` (`\in`),
 or `=` instead. The replacement options are `("in", "=", "∈")`.
-

julia for a = 1:10 end

formatted with alwaysforin = true, forinreplacement = "∈"

for a ∈ 1:10 end ```

source
JuliaFormatter.has_semicolon — Method
has_semicolon(d::Document, line::Integer)

Returns whether d has a valid semicolon grouping on line.

source
JuliaFormatter.is_dot_op — Method
is_dot_op(x::CSTParser.EXPR)

Checks if the binary operation is a dot operation (e.g. x.y, x..z, x...z). This is different from a dot or broadcast operation.

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.is_standalone_shortcircuit — Method
is_standalone_shortcircuit(cst::CSTParser.EXPR)

Returns true if the cst is a short-circuit expression (uses &&, ||) and is standalone, meaning it's not directly associated with another statement or expression.

Examples

# this IS a standalone short-circuit
+

julia for a = 1:10 end

formatted with alwaysforin = true, forinreplacement = "∈"

for a ∈ 1:10 end ```

source
JuliaFormatter.has_semicolon — Method
has_semicolon(d::Document, line::Integer)

Returns whether d has a valid semicolon grouping on line.

source
JuliaFormatter.is_dot_op — Method
is_dot_op(x::CSTParser.EXPR)

Checks if the binary operation is a dot operation (e.g. x.y, x..z, x...z). This is different from a dot or broadcast operation.

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.is_standalone_shortcircuit — Method
is_standalone_shortcircuit(cst::CSTParser.EXPR)

Returns true if the cst is a short-circuit expression (uses &&, ||) and is standalone, meaning it's not directly associated with another statement or expression.

Examples

# this IS a standalone short-circuit
 a && b
 
 # this IS NOT a standalone short-circuit
@@ -199,21 +199,21 @@
 
 # operation inside parenthesis IS NOT a standalone short-circuit
 # operation outside parenthesis IS a standalone short-circuit
-(a && b) && c
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)
+(a && b) && c
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.p_macrostr_identifier — Method

This is a special prettifier to handle the case of string macros. As such it is not part of pretty.

format"hello"

The above "format" identifier is parsed by CSTParser as if the text is "@format_str". This creates problems when we format without intervention:

  1. "@format_str" is printed instead of "format"
  2. The state offset is incorrect since the length of "@format_str" is greater than "format"
source
JuliaFormatter.parent_is — Method

Returns whether the first unignored parent of cst matches the criteria determined by valid, which is a function that returns a boolean. ignore can be used to ignore certain parent nodes if desired, also a function which returns a boolean.

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.p_macrostr_identifier — Method

This is a special prettifier to handle the case of string macros. As such it is not part of pretty.

format"hello"

The above "format" identifier is parsed by CSTParser as if the text is "@format_str". This creates problems when we format without intervention:

  1. "@format_str" is printed instead of "format"
  2. The state offset is incorrect since the length of "@format_str" is greater than "format"
source
JuliaFormatter.parent_is — Method

Returns whether the first unignored parent of cst matches the criteria determined by valid, which is a function that returns a boolean. ignore can be used to ignore certain parent nodes if desired, also a function which returns a boolean.

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)
 
 ->
 
@@ -221,6 +221,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. Returns 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. Returns 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/dev/blue_style/index.html b/dev/blue_style/index.html index 1994d33a6..b47c65284 100644 --- a/dev/blue_style/index.html +++ b/dev/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/dev/config/index.html b/dev/config/index.html index 8c2090b74..821b1c3d3 100644 --- a/dev/config/index.html +++ b/dev/config/index.html @@ -13,4 +13,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/dev/custom_alignment/index.html b/dev/custom_alignment/index.html index 62dbac88c..3bcff0590 100644 --- a/dev/custom_alignment/index.html +++ b/dev/custom_alignment/index.html @@ -133,4 +133,4 @@ 100 300 400 1 ee 40000 2 a b -] +] diff --git a/dev/custom_styles/index.html b/dev/custom_styles/index.html index 23c6bf0fe..832398c40 100644 --- a/dev/custom_styles/index.html +++ b/dev/custom_styles/index.html @@ -32,4 +32,4 @@ foo(a, b, key1 = val1, key3 = val4) julia> format_text(s, style=CustomStyle()) |> print -foo(a, b, key1=val1, key3=val4)

Nice! Looks like it's working.

+foo(a, b, key1=val1, key3=val4)

Nice! Looks like it's working.

diff --git a/dev/how_it_works/index.html b/dev/how_it_works/index.html index 9909390ed..86ca69206 100644 --- a/dev/how_it_works/index.html +++ b/dev/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/dev/index.html b/dev/index.html index ba6bc0d18..5153fa3f8 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,5 +1,5 @@ -Introduction · JuliaFormatter
GitHub

JuliaFormatter.jl

Width-sensitive formatter for Julia code. Inspired by gofmt, refmt, black, and prettier. Built with CSTParser.

  • Sane defaults out of the box with options to customize.
  • Supports YAS, Blue and SciML style guides.
  • .JuliaFormatter.toml configuration file to store options.

Installation

]add JuliaFormatter

Quick Start

julia> using JuliaFormatter
+Introduction · JuliaFormatter
GitHub
JuliaFormatter.jl
Width-sensitive formatter for Julia code. Inspired by gofmt, refmt, black, and prettier. Built with CSTParser.jl.
  • Sane defaults out of the box with options to customize.
  • Supports YAS, Blue and SciML style guides.
  • .JuliaFormatter.toml configuration file to store options.
Installation
]add JuliaFormatter
Quick Start
julia> using JuliaFormatter
 
 # Recursively formats all Julia files in the current directory
 julia> format(".")
@@ -8,7 +8,7 @@
 julia> format_file("foo.jl")
 
 # Formats a string (contents of a Julia file)
-julia> format_text(str)
Check out the docs for further description of the formatter and its options.
Use With Github Actions
Formatting Options
indent
default: 4
The number of spaces used for an indentation.
margin
default: 92
The maximum length of a line. Code exceeding this margin will be formatted across multiple lines.
always_for_in
default: false
If true, = is always replaced with in if part of a for loop condition. For example, for i = 1:10 will be transformed to for i in 1:10. Set this to nothing to leave the choice to the user.
whitespace_typedefs
default: false
If true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.
whitespace_ops_in_indices
default: false
If true, whitespace is added for binary operations in indices. Make this true if you prefer arr[a + b] to arr[a+b]. Additionally, if there's a colon : involved, parenthesis will be added to the LHS and RHS.
Example: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].
remove_extra_newlines
default: false
If true, superfluous newlines will be removed. For example:
module M
+julia> format_text(str)
Check out the docs for further description of the formatter and its options.
Use With GitHub Actions
Formatting Options
indent
default: 4
The number of spaces used for an indentation.
margin
default: 92
The maximum length of a line. Code exceeding this margin will be formatted across multiple lines.
always_for_in
default: false
If true, = is always replaced with in if part of a for loop condition. For example, for i = 1:10 will be transformed to for i in 1:10. Set this to nothing to leave the choice to the user.
whitespace_typedefs
default: false
If true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.
whitespace_ops_in_indices
default: false
If true, whitespace is added for binary operations in indices. Make this true if you prefer arr[a + b] to arr[a+b]. Additionally, if there's a colon : involved, parenthesis will be added to the LHS and RHS.
Example: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].
remove_extra_newlines
default: false
If true, superfluous newlines will be removed. For example:
module M
 
 
 
@@ -180,4 +180,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/dev/integrations/index.html b/dev/integrations/index.html index 71260795a..c99cc9a3f 100644 --- a/dev/integrations/index.html +++ b/dev/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/dev/sciml_style/index.html b/dev/sciml_style/index.html index bb582dba3..45e06361f 100644 --- a/dev/sciml_style/index.html +++ b/dev/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/dev/search_index.js b/dev/search_index.js index 10eb91ef1..9f4cf8bd5 100644 --- a/dev/search_index.js +++ b/dev/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/","page":"Configuration File","title":"Configuration File","text":"note: Note\nJuno, a Julia IDE that offers formatting feature using this package, also respects configuration file. When you use Julia-Client: Format-Code command, Juno will automatically search for a configuration file with the same rule as format does from the directory of current editor.","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/","page":"Configuration File","title":"Configuration File","text":"warning: Custom Style\nCurrently the configuration file doesn't support user-defined Custom Styles. For the time being, we only provide specs for YAS Style, Blue Style and SciML Style in configuration file. In order to use YAS style instead of the default style, you can just specify:.JuliaFormatter.toml...\nstyle = \"yas\"\n...In the same way as above, you can specify style = \"blue\" to use Blue style.","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.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 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\nFile Options\n\noverwrite\n\ndefault: true\n\nIf 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.\n\nverbose\n\ndefault: false\n\nIf true details related to formatting the file will be printed to stdout.\n\nformat_markdown\n\ndefault: false\n\nIf true, Markdown files are also formatted. Julia code blocks will be formatted in addition to the Markdown being normalized.\n\nFormatting Options\n\nSee format_text for description of formatting 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 always_for_in::Union{Bool,Nothing} = false,\n for_in_replacement::String = \"in\",\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 long_to_short_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_field::Bool = false,\n align_conditional::Bool = false,\n align_assignment::Bool = false,\n align_pair_arrow::Bool = false,\n conditional_to_if = false,\n normalize_line_endings = \"auto\",\n align_matrix::Bool = false,\n trailing_comma::Bool = false,\n trailing_zero::Bool = true,\n indent_submodule::Bool = false,\n separate_kwargs_with_semicolon::Bool = false,\n surround_whereop_typeparameters::Bool = true,\n variable_call_indent::Vector{String} = []\n)::String\n\nFormats a Julia source passed in as a string, returning the formatted code as another string.\n\nFormatting Options\n\nindent\n\ndefault: 4\n\nThe number of spaces used for an indentation.\n\nmargin\n\ndefault: 92\n\nThe maximum length of a line. Code exceeding this margin will be formatted across multiple lines.\n\nalways_for_in\n\ndefault: false\n\nIf 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.\n\nwhitespace_typedefs\n\ndefault: false\n\nIf true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.\n\nwhitespace_ops_in_indices\n\ndefault: false\n\nIf 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.\n\nExample: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].\n\nremove_extra_newlines\n\ndefault: false\n\nIf true, superfluous newlines will be removed. For example:\n\nmodule M\n\n\n\na = 1\n\nfunction foo()\n\n\n return nothing\n\nend\n\n\nb = 2\n\n\nend\n\nis rewritten as\n\nmodule M\n\na = 1\n\nfunction foo()\n return nothing\nend\n\nb = 2\n\nend\n\nModules are the only type of code block allowed to keep a single newline prior to the initial or after the final piece of code.\n\nimport_to_using\n\ndefault: false\n\nIf true, import expressions are rewritten to using expressions in the following cases:\n\nimport A\n\nimport A, B, C\n\nis rewritten to:\n\nusing A: A\n\nusing A: A\nusing B: B\nusing C: C\n\nExceptions:\n\nIf as is found in the import expression. using CANNOT be used in this context. The following example will NOT BE rewritten.\n\nimport Base.Threads as th\n\nIf import is used in the following context it is NOT rewritten. This may change in a future patch.\n\n@everywhere import A, B\n\npipe_to_function_call\n\ndefault: false\n\nIf true, x |> f is rewritten to f(x).\n\nshort_to_long_function_def\n\ndefault: false\n\nTransforms a short function definition\n\nf(arg1, arg2) = body\n\nto a long function definition if the short function definition exceeds the maximum margin.\n\nfunction f(arg2, arg2)\n body\nend\n\nlong_to_short_function_def\n\ndefault: false\n\nTransforms a long function definition\n\nfunction f(arg2, arg2)\n body\nend\n\nto a short function definition if the short function definition does not exceed the maximum margin.\n\nf(arg1, arg2) = body\n\nalways_use_return\n\ndefault: false\n\nIf true, return will be prepended to the last expression where applicable in function definitions, macro definitions, and do blocks.\n\nExample:\n\nfunction foo()\n expr1\n expr2\nend\n\nto\n\nfunction foo()\n expr1\n return expr2\nend\n\nwhitespace_in_kwargs\n\ndefault: true\n\nIf true, = in keyword arguments will be surrounded by whitespace.\n\nf(; a=4)\n\nto\n\nf(; a = 4)\n\nAn 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.\n\nannotate_untyped_fields_with_any\n\ndefault: true\n\nAnnotates fields in a type definitions with ::Any if no type annotation is provided:\n\nstruct A\n arg1\nend\n\nto\n\nstruct A\n arg1::Any\nend\n\nformat_docstrings\n\ndefault: false\n\nFormat code docstrings with the same options used for the code source.\n\nMarkdown is formatted with CommonMark alongside Julia code.\n\nalign_*\n\ndefault: false\n\nSee Custom Alignment documentation.\n\nconditional_to_if\n\ndefault: false\n\nIf the conditional E ? A : B exceeds the maximum margin converts it into the equivalent if block:\n\nif E\n A\nelse\n B\nend\n\nnormalize_line_endings\n\ndefault: \"auto\"\n\nOne of \"unix\" (normalize all to ), \"windows\" (normalize all to ), \"auto\" (automatically choose based on which line ending is more common in the file).\n\ntrailing_comma\n\ndefault: true\n\nOne of true, false, or nothing.\n\nTrailing commas are added after the final argument when nesting occurs and the closing punctuation appears on the next line.\n\nFor example when the following is nested (assuming DefaultStyle):\n\nfunccall(arg1, arg2, arg3)\n\nit turns into:\n\nfunccall(\n arg1,\n arg2,\n arg3, # trailing comma added after `arg3` (final argument) !!!\n)\n\nWhen 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.\n\nIn the Configuration File, a nothing value can be set as the string value \"nothing\":\n\ntrailing_comma = \"nothing\"\n\ntrailing_zero\n\ndefault: true\n\nAdd a trailing zero, if needed.\n\njoin_lines_based_on_source\n\ndefault: false\n\nWhen true lines are joined as they appear in the original source file.\n\nfunction foo(arg1,\n arg2, arg3\n )\n body\nend\n\nWhen false and the maximum margin is > than the length of \"function foo(arg1, arg2, arg3)\" this is formatted to\n\nfunction foo(arg1, arg2, arg3)\n body\nend\n\nWhen 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.\n\nfunction foo(arg1,\n arg2, arg3,\n)\nend\n\nThere are exceptions to this:\n\nif a body1 elseif b body2 else body3 end\n\nwill be formatted to the following, even if this option is set to true:\n\nif a\n body1\nelseif b\n body2\nelse\n body3\nend\n\nwarning: Warning\nThe maximum margin still applies even when this option is set to true.\n\nindent_submodule\n\ndefault: false\n\nWhen set to true, submodule(s) appearing in the same file will be indented.\n\nmodule A\na = 1\n\nmodule B\nb = 2\nmodule C\nc = 3\nend\nend\n\nd = 4\n\nend\n\nwill be formatted to:\n\nmodule A\na = 1\n\nmodule B\n b = 2\n module C\n c = 3\n end\nend\n\nd = 4\n\nend\n\nseparate_kwargs_with_semicolon\n\ndefault: false\n\nWhen set to true, keyword arguments in a function call will be separated with a semicolon.\n\nf(a, b=1)\n\n->\n\nf(a; b=1)\n\nsurround_whereop_typeparameters\n\ndefault: true\n\nSurrounds type parameters with curly brackets when set to true if the brackets are not already present.\n\nfunction func(...) where TPARAM\nend\n\n->\n\nfunction func(...) where {TPARAM}\nend\n\n### `for_in_replacement`\n\nCan be used when `always_for_in` is `true` to replace the default `in` with `∈` (`\\in`),\nor `=` instead. The replacement options are `(\"in\", \"=\", \"∈\")`.\n\n\njulia for a = 1:10 end\n\nformatted with alwaysforin = true, forinreplacement = \"∈\"\n\nfor a ∈ 1:10 end ```\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.has_semicolon-Tuple{JuliaFormatter.Document, Integer}","page":"API Reference","title":"JuliaFormatter.has_semicolon","text":"has_semicolon(d::Document, line::Integer)\n\nReturns whether d has a valid semicolon grouping on line.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.is_dot_op-Tuple{CSTParser.EXPR}","page":"API Reference","title":"JuliaFormatter.is_dot_op","text":"is_dot_op(x::CSTParser.EXPR)\n\nChecks if the binary operation is a dot operation (e.g. x.y, x..z, x...z). This is different from a dot or broadcast operation.\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.is_standalone_shortcircuit-Tuple{CSTParser.EXPR}","page":"API Reference","title":"JuliaFormatter.is_standalone_shortcircuit","text":"is_standalone_shortcircuit(cst::CSTParser.EXPR)\n\nReturns true if the cst is a short-circuit expression (uses &&, ||) and is standalone, meaning it's not directly associated with another statement or expression.\n\nExamples\n\n# this IS a standalone short-circuit\na && b\n\n# this IS NOT a standalone short-circuit\nif a && b\nend\n\n# this IS NOT a standalone short-circuit\nvar = a && b\n\n# this IS NOT a standalone short-circuit\n@macro a && b\n\n# operation inside parenthesis IS NOT a standalone short-circuit\n# operation outside parenthesis IS a standalone short-circuit\n(a && b) && c\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!-Union{Tuple{S}, Tuple{S, JuliaFormatter.FST, JuliaFormatter.State, Int64}} where S<:JuliaFormatter.AbstractStyle","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.p_macrostr_identifier-Tuple{DefaultStyle, CSTParser.EXPR, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.p_macrostr_identifier","text":"This is a special prettifier to handle the case of string macros. As such it is not part of pretty.\n\nformat\"hello\"\n\nThe above \"format\" identifier is parsed by CSTParser as if the text is \"@format_str\". This creates problems when we format without intervention:\n\n\"@format_str\" is printed instead of \"format\"\nThe state offset is incorrect since the length of \"@format_str\" is greater than \"format\"\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.parent_is-Tuple{CSTParser.EXPR, Any}","page":"API Reference","title":"JuliaFormatter.parent_is","text":"Returns whether the first unignored parent of cst matches the criteria determined by valid, which is a function that returns a boolean. ignore can be used to ignore certain parent nodes if desired, also a function which returns a boolean.\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}","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{CSTParser.EXPR}","page":"API Reference","title":"JuliaFormatter.unnestable_node","text":"cst is assumed to be a single child node. Returns true if the node is of the syntactic form {...}, [...], or (...).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.walk-Tuple{Any, 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":"custom_styles/#Custom-Styles","page":"Custom Styles","title":"Custom Styles","text":"","category":"section"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"The default style surrounds keyword arguments with whitespace. Suppose we wanted to have no spaces, how could we do this? Using custom styles this turns out to be easy.","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"First we'll define the style:","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"using JuliaFormatter, CSTParser\nusing JuliaFormatter: AbstractStyle, FST, State, add_node!\nimport JuliaFormatter: pretty, p_kw\n\nstruct CustomStyle <: AbstractStyle end\n\n# this must be defined\ngetstyle(s::CustomStyle) = s","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"Next we'll create a function for the p_kw to dispatch on CustomStyle.","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"function p_kw(style::CustomStyle, cst::CSTParser.EXPR, s::State)\n t = FST(cst, 0)\n for a in cst\n add_node!(t, pretty(style, a, s), s, join_lines = true)\n end\n t\nend","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"For comparison here's the default definition:","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"function p_kw(style::DefaultStyle, cst::CSTParser.EXPR, s::State)\n style = getstyle(style)\n t = FST(cst, nspaces(s))\n for a in cst\n if a.kind === Tokens.EQ\n add_node!(t, Whitespace(1), s)\n add_node!(t, pretty(style, a, s), s, join_lines = true)\n add_node!(t, Whitespace(1), s)\n else\n add_node!(t, pretty(style, a, s), s, join_lines = true)\n end\n end\n t\nend","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"And that's it! All other functions will fallback to use DefaultStyle.","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"Finally, let's check the output:","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"julia> s = \"foo(a,b, key1=val1, key3=val4)\"\n\"foo(a,b, key1=val1, key3=val4)\"\n\njulia> format_text(s) |> print\nfoo(a, b, key1 = val1, key3 = val4)\n\njulia> format_text(s, style=CustomStyle()) |> print\nfoo(a, b, key1=val1, key3=val4)","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"Nice! Looks like it's working.","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.","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.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function f(arg2, arg2)\n body\nend","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":"#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 inent\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 inent\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":"Atom\nEmacs\nVSCode\nVim","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/","page":"Configuration File","title":"Configuration File","text":"note: Note\nJuno, a Julia IDE that offers formatting feature using this package, also respects configuration file. When you use Julia-Client: Format-Code command, Juno will automatically search for a configuration file with the same rule as format does from the directory of current editor.","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/","page":"Configuration File","title":"Configuration File","text":"warning: Custom Style\nCurrently the configuration file doesn't support user-defined Custom Styles. For the time being, we only provide specs for YAS Style, Blue Style and SciML Style in configuration file. In order to use YAS style instead of the default style, you can just specify:.JuliaFormatter.toml...\nstyle = \"yas\"\n...In the same way as above, you can specify style = \"blue\" to use Blue style.","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.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 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\nFile Options\n\noverwrite\n\ndefault: true\n\nIf 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.\n\nverbose\n\ndefault: false\n\nIf true details related to formatting the file will be printed to stdout.\n\nformat_markdown\n\ndefault: false\n\nIf true, Markdown files are also formatted. Julia code blocks will be formatted in addition to the Markdown being normalized.\n\nFormatting Options\n\nSee format_text for description of formatting 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 always_for_in::Union{Bool,Nothing} = false,\n for_in_replacement::String = \"in\",\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 long_to_short_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_field::Bool = false,\n align_conditional::Bool = false,\n align_assignment::Bool = false,\n align_pair_arrow::Bool = false,\n conditional_to_if = false,\n normalize_line_endings = \"auto\",\n align_matrix::Bool = false,\n trailing_comma::Bool = false,\n trailing_zero::Bool = true,\n indent_submodule::Bool = false,\n separate_kwargs_with_semicolon::Bool = false,\n surround_whereop_typeparameters::Bool = true,\n variable_call_indent::Vector{String} = []\n)::String\n\nFormats a Julia source passed in as a string, returning the formatted code as another string.\n\nFormatting Options\n\nindent\n\ndefault: 4\n\nThe number of spaces used for an indentation.\n\nmargin\n\ndefault: 92\n\nThe maximum length of a line. Code exceeding this margin will be formatted across multiple lines.\n\nalways_for_in\n\ndefault: false\n\nIf 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.\n\nwhitespace_typedefs\n\ndefault: false\n\nIf true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.\n\nwhitespace_ops_in_indices\n\ndefault: false\n\nIf 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.\n\nExample: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].\n\nremove_extra_newlines\n\ndefault: false\n\nIf true, superfluous newlines will be removed. For example:\n\nmodule M\n\n\n\na = 1\n\nfunction foo()\n\n\n return nothing\n\nend\n\n\nb = 2\n\n\nend\n\nis rewritten as\n\nmodule M\n\na = 1\n\nfunction foo()\n return nothing\nend\n\nb = 2\n\nend\n\nModules are the only type of code block allowed to keep a single newline prior to the initial or after the final piece of code.\n\nimport_to_using\n\ndefault: false\n\nIf true, import expressions are rewritten to using expressions in the following cases:\n\nimport A\n\nimport A, B, C\n\nis rewritten to:\n\nusing A: A\n\nusing A: A\nusing B: B\nusing C: C\n\nExceptions:\n\nIf as is found in the import expression. using CANNOT be used in this context. The following example will NOT BE rewritten.\n\nimport Base.Threads as th\n\nIf import is used in the following context it is NOT rewritten. This may change in a future patch.\n\n@everywhere import A, B\n\npipe_to_function_call\n\ndefault: false\n\nIf true, x |> f is rewritten to f(x).\n\nshort_to_long_function_def\n\ndefault: false\n\nTransforms a short function definition\n\nf(arg1, arg2) = body\n\nto a long function definition if the short function definition exceeds the maximum margin.\n\nfunction f(arg2, arg2)\n body\nend\n\nlong_to_short_function_def\n\ndefault: false\n\nTransforms a long function definition\n\nfunction f(arg2, arg2)\n body\nend\n\nto a short function definition if the short function definition does not exceed the maximum margin.\n\nf(arg1, arg2) = body\n\nalways_use_return\n\ndefault: false\n\nIf true, return will be prepended to the last expression where applicable in function definitions, macro definitions, and do blocks.\n\nExample:\n\nfunction foo()\n expr1\n expr2\nend\n\nto\n\nfunction foo()\n expr1\n return expr2\nend\n\nwhitespace_in_kwargs\n\ndefault: true\n\nIf true, = in keyword arguments will be surrounded by whitespace.\n\nf(; a=4)\n\nto\n\nf(; a = 4)\n\nAn 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.\n\nannotate_untyped_fields_with_any\n\ndefault: true\n\nAnnotates fields in a type definitions with ::Any if no type annotation is provided:\n\nstruct A\n arg1\nend\n\nto\n\nstruct A\n arg1::Any\nend\n\nformat_docstrings\n\ndefault: false\n\nFormat code docstrings with the same options used for the code source.\n\nMarkdown is formatted with CommonMark alongside Julia code.\n\nalign_*\n\ndefault: false\n\nSee Custom Alignment documentation.\n\nconditional_to_if\n\ndefault: false\n\nIf the conditional E ? A : B exceeds the maximum margin converts it into the equivalent if block:\n\nif E\n A\nelse\n B\nend\n\nnormalize_line_endings\n\ndefault: \"auto\"\n\nOne of \"unix\" (normalize all to ), \"windows\" (normalize all to ), \"auto\" (automatically choose based on which line ending is more common in the file).\n\ntrailing_comma\n\ndefault: true\n\nOne of true, false, or nothing.\n\nTrailing commas are added after the final argument when nesting occurs and the closing punctuation appears on the next line.\n\nFor example when the following is nested (assuming DefaultStyle):\n\nfunccall(arg1, arg2, arg3)\n\nit turns into:\n\nfunccall(\n arg1,\n arg2,\n arg3, # trailing comma added after `arg3` (final argument) !!!\n)\n\nWhen 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.\n\nIn the Configuration File, a nothing value can be set as the string value \"nothing\":\n\ntrailing_comma = \"nothing\"\n\ntrailing_zero\n\ndefault: true\n\nAdd a trailing zero, if needed.\n\njoin_lines_based_on_source\n\ndefault: false\n\nWhen true lines are joined as they appear in the original source file.\n\nfunction foo(arg1,\n arg2, arg3\n )\n body\nend\n\nWhen false and the maximum margin is > than the length of \"function foo(arg1, arg2, arg3)\" this is formatted to\n\nfunction foo(arg1, arg2, arg3)\n body\nend\n\nWhen 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.\n\nfunction foo(arg1,\n arg2, arg3,\n)\nend\n\nThere are exceptions to this:\n\nif a body1 elseif b body2 else body3 end\n\nwill be formatted to the following, even if this option is set to true:\n\nif a\n body1\nelseif b\n body2\nelse\n body3\nend\n\nwarning: Warning\nThe maximum margin still applies even when this option is set to true.\n\nindent_submodule\n\ndefault: false\n\nWhen set to true, submodule(s) appearing in the same file will be indented.\n\nmodule A\na = 1\n\nmodule B\nb = 2\nmodule C\nc = 3\nend\nend\n\nd = 4\n\nend\n\nwill be formatted to:\n\nmodule A\na = 1\n\nmodule B\n b = 2\n module C\n c = 3\n end\nend\n\nd = 4\n\nend\n\nseparate_kwargs_with_semicolon\n\ndefault: false\n\nWhen set to true, keyword arguments in a function call will be separated with a semicolon.\n\nf(a, b=1)\n\n->\n\nf(a; b=1)\n\nsurround_whereop_typeparameters\n\ndefault: true\n\nSurrounds type parameters with curly brackets when set to true if the brackets are not already present.\n\nfunction func(...) where TPARAM\nend\n\n->\n\nfunction func(...) where {TPARAM}\nend\n\n### `for_in_replacement`\n\nCan be used when `always_for_in` is `true` to replace the default `in` with `∈` (`\\in`),\nor `=` instead. The replacement options are `(\"in\", \"=\", \"∈\")`.\n\n\njulia for a = 1:10 end\n\nformatted with alwaysforin = true, forinreplacement = \"∈\"\n\nfor a ∈ 1:10 end ```\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.has_semicolon-Tuple{JuliaFormatter.Document, Integer}","page":"API Reference","title":"JuliaFormatter.has_semicolon","text":"has_semicolon(d::Document, line::Integer)\n\nReturns whether d has a valid semicolon grouping on line.\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.is_dot_op-Tuple{CSTParser.EXPR}","page":"API Reference","title":"JuliaFormatter.is_dot_op","text":"is_dot_op(x::CSTParser.EXPR)\n\nChecks if the binary operation is a dot operation (e.g. x.y, x..z, x...z). This is different from a dot or broadcast operation.\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.is_standalone_shortcircuit-Tuple{CSTParser.EXPR}","page":"API Reference","title":"JuliaFormatter.is_standalone_shortcircuit","text":"is_standalone_shortcircuit(cst::CSTParser.EXPR)\n\nReturns true if the cst is a short-circuit expression (uses &&, ||) and is standalone, meaning it's not directly associated with another statement or expression.\n\nExamples\n\n# this IS a standalone short-circuit\na && b\n\n# this IS NOT a standalone short-circuit\nif a && b\nend\n\n# this IS NOT a standalone short-circuit\nvar = a && b\n\n# this IS NOT a standalone short-circuit\n@macro a && b\n\n# operation inside parenthesis IS NOT a standalone short-circuit\n# operation outside parenthesis IS a standalone short-circuit\n(a && b) && c\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!-Union{Tuple{S}, Tuple{S, JuliaFormatter.FST, JuliaFormatter.State, Int64}} where S<:JuliaFormatter.AbstractStyle","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.p_macrostr_identifier-Tuple{DefaultStyle, CSTParser.EXPR, JuliaFormatter.State}","page":"API Reference","title":"JuliaFormatter.p_macrostr_identifier","text":"This is a special prettifier to handle the case of string macros. As such it is not part of pretty.\n\nformat\"hello\"\n\nThe above \"format\" identifier is parsed by CSTParser as if the text is \"@format_str\". This creates problems when we format without intervention:\n\n\"@format_str\" is printed instead of \"format\"\nThe state offset is incorrect since the length of \"@format_str\" is greater than \"format\"\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.parent_is-Tuple{CSTParser.EXPR, Any}","page":"API Reference","title":"JuliaFormatter.parent_is","text":"Returns whether the first unignored parent of cst matches the criteria determined by valid, which is a function that returns a boolean. ignore can be used to ignore certain parent nodes if desired, also a function which returns a boolean.\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}","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{CSTParser.EXPR}","page":"API Reference","title":"JuliaFormatter.unnestable_node","text":"cst is assumed to be a single child node. Returns true if the node is of the syntactic form {...}, [...], or (...).\n\n\n\n\n\n","category":"method"},{"location":"api/#JuliaFormatter.walk-Tuple{Any, 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":"custom_styles/#Custom-Styles","page":"Custom Styles","title":"Custom Styles","text":"","category":"section"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"The default style surrounds keyword arguments with whitespace. Suppose we wanted to have no spaces, how could we do this? Using custom styles this turns out to be easy.","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"First we'll define the style:","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"using JuliaFormatter, CSTParser\nusing JuliaFormatter: AbstractStyle, FST, State, add_node!\nimport JuliaFormatter: pretty, p_kw\n\nstruct CustomStyle <: AbstractStyle end\n\n# this must be defined\ngetstyle(s::CustomStyle) = s","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"Next we'll create a function for the p_kw to dispatch on CustomStyle.","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"function p_kw(style::CustomStyle, cst::CSTParser.EXPR, s::State)\n t = FST(cst, 0)\n for a in cst\n add_node!(t, pretty(style, a, s), s, join_lines = true)\n end\n t\nend","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"For comparison here's the default definition:","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"function p_kw(style::DefaultStyle, cst::CSTParser.EXPR, s::State)\n style = getstyle(style)\n t = FST(cst, nspaces(s))\n for a in cst\n if a.kind === Tokens.EQ\n add_node!(t, Whitespace(1), s)\n add_node!(t, pretty(style, a, s), s, join_lines = true)\n add_node!(t, Whitespace(1), s)\n else\n add_node!(t, pretty(style, a, s), s, join_lines = true)\n end\n end\n t\nend","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"And that's it! All other functions will fallback to use DefaultStyle.","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"Finally, let's check the output:","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"julia> s = \"foo(a,b, key1=val1, key3=val4)\"\n\"foo(a,b, key1=val1, key3=val4)\"\n\njulia> format_text(s) |> print\nfoo(a, b, key1 = val1, key3 = val4)\n\njulia> format_text(s, style=CustomStyle()) |> print\nfoo(a, b, key1=val1, key3=val4)","category":"page"},{"location":"custom_styles/","page":"Custom Styles","title":"Custom Styles","text":"Nice! Looks like it's working.","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.","category":"page"},{"location":"","page":"Introduction","title":"Introduction","text":"function f(arg2, arg2)\n body\nend","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":"#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 inent\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 inent\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":"Atom\nEmacs\nVSCode\nVim","category":"page"}] } diff --git a/dev/skipping_formatting/index.html b/dev/skipping_formatting/index.html index c56664ef1..c222770f3 100644 --- a/dev/skipping_formatting/index.html +++ b/dev/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/dev/style/index.html b/dev/style/index.html index dcea28665..698c0a61e 100644 --- a/dev/style/index.html +++ b/dev/style/index.html @@ -206,4 +206,4 @@ arg1, arg2, arg3, -) +) diff --git a/dev/transforms/index.html b/dev/transforms/index.html index af2e9d215..2eb788f8e 100644 --- a/dev/transforms/index.html +++ b/dev/transforms/index.html @@ -42,4 +42,4 @@ -> -Module.@macro +Module.@macro diff --git a/dev/yas_style/index.html b/dev/yas_style/index.html index 65912dc0d..5afbe1c39 100644 --- a/dev/yas_style/index.html +++ b/dev/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)