Options¶
Every option rainbow-fmt reads, with its values, its default and what it
does. This page is generated from the option declarations
(python -m rainbow_fmt.options.reference; a test fails when it is out of
date). How the levels of configuration combine, how to set an option for
one language or for some files, and the inline directives are in
configuration.md.
Core¶
[core]: layout options every language reads. Any of them may also be set
in a [language.X] section, for that language only.
| Option | Values | Default | Description |
|---|---|---|---|
core.max_width |
integer ≥ 1 | 80 |
The column limit lines are fitted into. |
core.indent_style |
"space", "tab" |
"space" |
Indent with spaces or tabs. |
core.indent_size |
integer ≥ 0 | 4 |
Spaces per indentation level. |
core.tab_width |
integer ≥ 1 | 4 |
Columns a tab counts as when measuring width. |
core.line_ending |
"lf", "crlf", "preserve" |
"lf" |
Line ending of the output; preserve uses the input's first line ending. |
core.max_blank_lines |
integer ≥ 0 | 1 |
Blank lines kept between members, at most (none are added). |
Shared¶
[shared]: options several languages read. A language may give one another
default (listed under the language) or narrow it to fewer values, in
which case the option belongs to the language and [shared] values do not
apply to it.
| Option | Values | Default | Description |
|---|---|---|---|
shared.trailing_comma |
"never", "multiline" |
"never" |
Whether a comma follows the last item of a list broken over several lines. |
Languages¶
[language.X]: the options of each built-in language pack. A plugin pack
documents its own.
JSON¶
trailing_comma narrows shared.trailing_comma: [shared] values do not apply to JSON.
| Option | Values | Default | Description |
|---|---|---|---|
language.json.trailing_comma |
"never" |
"never" |
JSON does not allow trailing commas (narrows shared.trailing_comma). |
language.json.object_wrap |
"preserve", "fit", "always" |
"preserve" |
When objects break: as written, only when too long, or always. |
language.json.align_values |
true, false |
false |
Align the values of a broken object whose values are all scalars. |
CSS¶
| Option | Values | Default | Description |
|---|---|---|---|
language.css.selector_list |
"one_per_line", "fit" |
"one_per_line" |
A rule's selectors: one per line, or on one line when they fit. |
language.css.rule_wrap |
"always", "fit", "preserve" |
"always" |
When a block of declarations breaks: always, when too long, or as written. |
language.css.last_semicolon |
"always", "never", "preserve" |
"always" |
Whether the last declaration of a block ends with a semicolon. |
Python¶
shared.trailing_comma defaults to "multiline" for Python.
| Option | Values | Default | Description |
|---|---|---|---|
language.python.bracket_wrap |
"magic_trailing_comma", "fit", "preserve" |
"magic_trailing_comma" |
When bracketed lists break: when too long or with a trailing comma, only when too long, or as written. |
language.python.binary_operator_break |
"before", "after" |
"before" |
Whether a broken expression breaks before or after its operators. |
language.python.definition_blank_lines |
"enforce", "cap", "preserve" |
"enforce" |
Blank lines around def and class: exactly the counts, at most the counts, or as written. |
language.python.top_level_blank_lines |
integer ≥ 0 | 2 |
Blank lines around top-level definitions (PEP 8: 2). |
language.python.nested_blank_lines |
integer ≥ 0 | 1 |
Blank lines around nested definitions (PEP 8: 1). |
language.python.inline_comment_spaces |
integer ≥ 1 | 2 |
Spaces before a comment that follows code (PEP 8: 2). |
language.python.statement_blank_lines |
"preserve", "separate" |
"preserve" |
Blank lines between the statements of a function: as written, or also around loops and after if statements. |
language.python.docstrings |
"preserve", "aligned" |
"preserve" |
Docstrings: as written, or the closing quotes on their own line and the lines after the first aligned under its first letter. |
language.python.bracket_hug |
true, false |
false |
A list whose items are all dicts hugs them: '[{', '}, {' and '}]'. |
JavaScript¶
shared.trailing_comma defaults to "multiline" for JavaScript.
| Option | Values | Default | Description |
|---|---|---|---|
language.javascript.semicolons |
"as_needed", "always", "preserve" |
"as_needed" |
Statement-final semicolons: only where a line would join the next, always, or as written. |
language.javascript.object_wrap |
"preserve", "fit" |
"preserve" |
When objects break: also when written with a line break after '{', or only when too long. |
language.javascript.bracket_spacing |
true, false |
true |
Spaces inside the braces of objects, patterns and import/export lists. |
language.javascript.binary_operator_break |
"after", "before" |
"after" |
Whether a broken expression breaks after or before its operators. |
language.javascript.return_semicolons |
"as_statements", "unless_last" |
"as_statements" |
With semicolons 'as_needed': a return statement followed by another statement in its block ends with ';'. |
language.javascript.bracket_hug |
true, false |
false |
An array whose items are all objects hugs them: '[{', '}, {' and '}]'. |
TypeScript¶
shared.trailing_comma defaults to "multiline" for TypeScript.
| Option | Values | Default | Description |
|---|---|---|---|
language.typescript.semicolons |
"as_needed", "always", "preserve" |
"as_needed" |
Statement-final semicolons: only where a line would join the next, always, or as written. |
language.typescript.object_wrap |
"preserve", "fit" |
"preserve" |
When objects break: also when written with a line break after '{', or only when too long. |
language.typescript.bracket_spacing |
true, false |
true |
Spaces inside the braces of objects, patterns and import/export lists. |
language.typescript.binary_operator_break |
"after", "before" |
"after" |
Whether a broken expression breaks after or before its operators. |
language.typescript.return_semicolons |
"as_statements", "unless_last" |
"as_statements" |
With semicolons 'as_needed': a return statement followed by another statement in its block ends with ';'. |
language.typescript.bracket_hug |
true, false |
false |
An array whose items are all objects hugs them: '[{', '}, {' and '}]'. |
HTML¶
| Option | Values | Default | Description |
|---|---|---|---|
language.html.whitespace_sensitivity |
"css", "strict", "ignore" |
"css" |
Where whitespace around content matters: in inline elements (as CSS renders it), everywhere, or nowhere. |
language.html.bracket_same_line |
true, false |
false |
Keep the '>' of a tag broken over several lines on the last attribute's line. |
language.html.void_elements |
"no_slash", "slash", "preserve" |
"no_slash" |
Void elements (br, img, input …): ' ', ' ', or as written. |
Svelte¶
| Option | Values | Default | Description |
|---|---|---|---|
language.svelte.whitespace_sensitivity |
"css", "strict", "ignore" |
"css" |
Where whitespace around content matters: in inline elements (as CSS renders it), everywhere, or nowhere. |
language.svelte.bracket_same_line |
true, false |
false |
Keep the '>' of a tag broken over several lines on the last attribute's line. |
language.svelte.void_elements |
"no_slash", "slash", "preserve" |
"no_slash" |
Void elements (br, img, input …): ' ', ' ', or as written. |
TOML¶
TOML has no options of its own.
YAML¶
core.indent_size defaults to 2 for YAML.
| Option | Values | Default | Description |
|---|---|---|---|
language.yaml.sequence_indent |
"indent", "none" |
"indent" |
A sequence that is the value of a key: indented under the key, or at its level. |
SQL¶
| Option | Values | Default | Description |
|---|---|---|---|
language.sql.keyword_case |
"preserve", "upper", "lower" |
"preserve" |
Keywords as written, in upper case, or in lower case. |
language.sql.clause_alignment |
"left", "right" |
"left" |
Clause keywords at the margin, or right-aligned so SELECT, FROM, JOIN, ON and WHERE end in one column (GROUP BY and HAVING in another) and items hang under the first. |
Markdown¶
| Option | Values | Default | Description |
|---|---|---|---|
language.markdown.fenced_code |
"format", "preserve" |
"format" |
Fenced code in a language rainbow-fmt formats: formatted by that pack, or as written. |
language.markdown.table_width |
integer ≥ 1 | 180 |
The widest row an aligned pipe table may have; a wider table is written condensed, one space around each cell. |
Files¶
[files]: which files a run formats and how (read for the working
directory, not per file).
| Option | Values | Default | Description |
|---|---|---|---|
files.exclude |
list of strings | [] |
Patterns (as in [[override]] files, relative to the configuration file) of files and directories a directory walk skips; a file named on the command line is always formatted. |
files.ignore_unknown |
true, false |
false |
Do not warn about explicitly named files of unknown type. |
files.editorconfig |
true, false |
true |
Read .editorconfig files (between presets and the project configuration). |
files.verify |
true, false |
true |
Verify that formatting keeps the meaning and is stable before writing a file. |
files.cache |
true, false |
true |
Skip files a previous run found formatted (with the same options and version). |
files.jobs |
integer ≥ 0 | 0 |
Worker processes for many files (0: one per CPU; 1: none); read for the working directory. |