numtide/treefmt
Archived
8
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

doc: refine formatter spec

Browse Source 
Signed-off-by: Brian McGee <brian@bmcgee.ie>
This commit is contained in:
Brian McGee 2024-05-01 14:00:06 +01:00
parent f1c80edcf1
commit d9ee97a0b7
Signed by: brianmcgee
GPG Key ID: D49016E76AD1E8C0
2 changed files with 15 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/.vitepress/config.mts
View File

@ -18,7 +18,7 @@ export default defineConfig({
{ text: 'Quick Start', link: '/quick-start' },
{ text: 'Overview', link: '/overview' },
{ text: 'Usage', link: '/usage' },
{ text: 'Formatter Spec', link: '/formatter-spec' },
{ text: 'Formatter Specification', link: '/formatter-spec' },
{ text: 'Contributing', link: '/contributing' },
{ text: 'FAQ', link: '/faq' },
],

26
docs/formatter-spec.md
View File

@ -4,19 +4,22 @@ outline: deep
# 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
the code formatter on the selected files.
## Rules
In order for the formatter to comply to this spec, it MUST follow the
following rules:
In order for the formatter to comply to this spec, it **MUST** comply with the following:
### 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>]
@ -34,22 +37,21 @@ Example:
$ 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
Whenever there is a change to the code formatting, the code formatter MUST
write to the changes back to the original location.
Whenever there is a change to the code formatting, the code formatter **MUST** write to the changes back to the
original location.
If there is no changes to the original file, the formatter MUST NOT write to
the original location.
If there is no changes to the original file, the formatter **MUST** NOT write to the original location.
### 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.
### 4. Reliable
We expect the formatter to be reliable and not break the semantic of the
formatted files.
We expect the formatter to be reliable and not break the semantics of the formatted files.