doc: refine formatter spec
Signed-off-by: Brian McGee <brian@bmcgee.ie>
This commit is contained in:
parent
3fbe2d1b6f
commit
dc63ac923c
|
@ -18,7 +18,7 @@ export default defineConfig({
|
||||||
{ text: 'Quick Start', link: '/quick-start' },
|
{ text: 'Quick Start', link: '/quick-start' },
|
||||||
{ text: 'Overview', link: '/overview' },
|
{ text: 'Overview', link: '/overview' },
|
||||||
{ text: 'Usage', link: '/usage' },
|
{ text: 'Usage', link: '/usage' },
|
||||||
{ text: 'Formatter Spec', link: '/formatter-spec' },
|
{ text: 'Formatter Specification', link: '/formatter-spec' },
|
||||||
{ text: 'Contributing', link: '/contributing' },
|
{ text: 'Contributing', link: '/contributing' },
|
||||||
{ text: 'FAQ', link: '/faq' },
|
{ text: 'FAQ', link: '/faq' },
|
||||||
],
|
],
|
||||||
|
|
|
@ -4,19 +4,22 @@ outline: deep
|
||||||
|
|
||||||
# Formatter Specification
|
# Formatter Specification
|
||||||
|
|
||||||
In order to keep the design of `treefmt` simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification.
|
In order to keep the design of `treefmt` simple, we only supports formatters that adhere to a certain standard. This
|
||||||
|
document outlines that standard.
|
||||||
|
|
||||||
|
If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script
|
||||||
|
that transforms the usage to match the specification.
|
||||||
|
|
||||||
In this design, we rely on `treefmt` to do the tree traversal, and only invoke
|
In this design, we rely on `treefmt` to do the tree traversal, and only invoke
|
||||||
the code formatter on the selected files.
|
the code formatter on the selected files.
|
||||||
|
|
||||||
## Rules
|
## Rules
|
||||||
|
|
||||||
In order for the formatter to comply to this spec, it MUST follow the
|
In order for the formatter to comply to this spec, it **MUST** comply with the following:
|
||||||
following rules:
|
|
||||||
|
|
||||||
### 1. Files passed as arguments
|
### 1. Files passed as arguments
|
||||||
|
|
||||||
In order to be integrated to `treefmt`'s workflow, the formatter's CLI must adhere to the following specification:
|
In order to be integrated with `treefmt`'s workflow, the formatter's CLI must be of the form:
|
||||||
|
|
||||||
```
|
```
|
||||||
<command> [options] [...<files>]
|
<command> [options] [...<files>]
|
||||||
|
@ -34,22 +37,21 @@ Example:
|
||||||
$ rustfmt --edition 2018 src/main.rs src/lib.rs
|
$ rustfmt --edition 2018 src/main.rs src/lib.rs
|
||||||
```
|
```
|
||||||
|
|
||||||
It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted.
|
> [!IMPORTANT]
|
||||||
|
> It _SHOULD_ processes only the specified files. Files that are not passed _SHOULD_ never be formatted.
|
||||||
|
|
||||||
### 2. Write to changed files
|
### 2. Write to changed files
|
||||||
|
|
||||||
Whenever there is a change to the code formatting, the code formatter MUST
|
Whenever there is a change to the code formatting, the code formatter **MUST** write to the changes back to the
|
||||||
write to the changes back to the original location.
|
original location.
|
||||||
|
|
||||||
If there is no changes to the original file, the formatter MUST NOT write to
|
If there is no changes to the original file, the formatter **MUST** NOT write to the original location.
|
||||||
the original location.
|
|
||||||
|
|
||||||
### 3. Idempotent
|
### 3. Idempotent
|
||||||
|
|
||||||
The code formatter SHOULD be indempotent. Meaning that it produces stable
|
The code formatter _SHOULD_ be indempotent. Meaning that it produces stable
|
||||||
outputs.
|
outputs.
|
||||||
|
|
||||||
### 4. Reliable
|
### 4. Reliable
|
||||||
|
|
||||||
We expect the formatter to be reliable and not break the semantic of the
|
We expect the formatter to be reliable and not break the semantics of the formatted files.
|
||||||
formatted files.
|
|
||||||
|
|
Reference in New Issue
Block a user