repository·main·Indexed 20 days ago
https://github.com/juliaeditorsupport/juliaformatter.jlA width-sensitive formatter for Julia code inspired by gofmt and black. It provides a Julia API for formatting strings and files, as well as a standalone command-line tool called `jlfmt` (available in version 2.2.0+). Supports multiple pre-defined styles including DefaultStyle, YASStyle, BlueStyle, SciMLStyle, and MinimalStyle, and allows for project-specific configuration via .JuliaFormatter.toml files.
JuliaFormatter.jl is a width-sensitive formatter for Julia code built with JuliaSyntax.jl. Key features include:
.JuliaFormatter.toml file.jlfmt).jlfmt follows standard CLI conventions:
--check flag detected files that were not correctly formatted.--inplace is used).JuliaFormatter manages code density through nesting and unnesting rules:
? :), the : is moved first, then the ? as the margin shrinks.foo() = body, if nesting is required, the RHS is placed on a new line and indented.A where B, A is nested prior to B.To avoid excessive whitespace, JuliaFormatter will 'unnest' certain expressions that were previously broken into multiple lines if they can fit on a single line (e.g., simple function calls).
An idempotent formatter is one that, when run multiple times on the same input, produces the same output every time. Some options can break this property (making the formatting non-idempotent).
Options marked with the 🪃 emoji have the potential to cause non-idempotent formatting. If you enable these, you may need to run the formatter multiple times to reach a stable state (a "fixed point"). You can control the number of passes using the max_iterations option.
Compared to DefaultStyle, YASStyle follows these specific rules:
[, {, ().function_call(arg1,
arg2))) sticks to the final argument.function_call(arg1, arg2,
arg3)= Nesting: Unlike DefaultStyle, assignment operations (=) are not automatically nested.
my_function(arg1, arg2) = arg1 * arg2 will remain on one line unless it exceeds the margin.
Recommendation: Set short_to_long_function_def = true to transform long single-line definitions into standard function ... end blocks.Note on variable_call_indent:
YASStyle supports the variable_call_indent option (defaulting to []). This controls whether certain types (like Dict) allow specific indentation patterns. If a type is not in variable_call_indent, the formatter will enforce a specific style (e.g., moving arguments to new lines) to maintain consistency.
JuliaFormatter.jl distinguishes between two types of configuration settings:
.JuliaFormatter.toml configuration files and cannot be applied to individual strings or via certain direct API calls that bypass filesystem logic.JuliaFormatter uses a hierarchical configuration model. It searches for .JuliaFormatter.toml starting from the directory of the file being formatted and moving upwards through parent directories.
Precedence Rules:
.JuliaFormatter.toml files exist in the hierarchy, the configuration file closest to the file being formatted (the deepest one) takes precedence.format("dir") will apply the configuration found in dir/.JuliaFormatter.toml to all files within dir and its subdirectories, unless a sub-directory contains its own .JuliaFormatter.toml file.The SciMLStyle() represents a collection of styles maintained for compatibility in JuliaFormatter v2.
Warning: The official SciML Style Guide currently recommends using Runic.jl for formatting instead. SciMLStyle() in JuliaFormatter is a legacy implementation that predates the current recommendation and may be renamed in future major releases to avoid confusion with the current SciML standard.
format("file.jl", SciMLStyle())JuliaFormatter follows a default style designed to keep code concise by preferring single-line representations where possible, while using proper indentation and nesting when code exceeds the margin.
Key behaviors include:
where arguments are wrapped in curly brackets.JuliaFormatter processes source code through a four-stage pipeline to transform raw text into formatted code:
String -> CST): The source code is parsed into a Concrete Syntax Tree (CST). Unlike an Abstract Syntax Tree (AST), the CST preserves all non-semantic information like whitespace, comments, and specific parenthesization.CST -> FST): The CST is transformed into a Formatted Syntax Tree (FST). The FST is a richer representation that includes substrings from the original source and special PLACEHOLDER nodes. These placeholders mark potential locations where newlines can be inserted.PLACEHOLDER nodes should be converted into actual NEWLINE nodes. This decision is driven by formatting rules and constraints like the margin.When working with JuliaFormatter, it is important to distinguish between a Concrete Syntax Tree (CST) and an Abstract Syntax Tree (AST):
Meta.parse): Discards non-semantic information. Using an AST for formatting would result in the loss of comments and original parenthesization.JuliaFormatter v2.5 uses JuliaSyntax.jl v1 as its CST parser.
using JuliaSyntax: parseall, GreenNode
text = "x = f(y + z) # comment"
cst = parseall(GreenNode, text)Some formatting options perform syntax transformations, meaning the Abstract Syntax Tree (AST) of the code might change. Use these with caution as they can potentially change the meaning of your code.
JuliaFormatter categorizes options using an emoji legend to indicate risk levels:
pipe_to_function_call is currently the only option in this category.Safety Guard: By default, JuliaFormatter does not perform syntax transformations inside macros or Exprs. To enable transformations inside macros, set transform_syntax_in_macros=true. There is no option to enable transformations inside Exprs as it would change the literal meaning of the expression.