56 lines
1.6 KiB
Markdown
56 lines
1.6 KiB
Markdown
|
---
|
||
|
|
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 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:
|
||
|
|
|
||
|
|
### 1. Files passed as arguments
|
||
|
|
|
||
|
|
In order to be integrated to `treefmt`'s workflow, the formatter's CLI must adhere to the following specification:
|
||
|
|
|
||
|
|
```
|
||
|
|
<command> [options] [...<files>]
|
||
|
|
```
|
||
|
|
|
||
|
|
Where:
|
||
|
|
|
||
|
|
- `<command>` is the name of the formatting tool.
|
||
|
|
- `[options]` is any number of flags and options that the formatter accepts.
|
||
|
|
- `[...<files>]` is one or more files given to the formatter for processing.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### 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.
|
||
|
|
|
||
|
|
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
|
||
|
|
outputs.
|
||
|
|
|
||
|
|
### 4. Reliable
|
||
|
|
|
||
|
|
We expect the formatter to be reliable and not break the semantic of the
|
||
|
|
formatted files.
|