16 releases
new 0.11.15 | Apr 22, 2024 |
---|---|
0.11.14 | Apr 19, 2024 |
0.11.8 | Mar 31, 2024 |
#41 in Value formatting
1,795 downloads per month
72KB
1.5K
SLoC
typstyle
Usage:
Beautiful and reliable typst code formatter
Usage: typstyle [OPTIONS] [INPUT]...
Arguments:
[INPUT]... Path to the input files, if not provided, read from stdin. If multiple files are provided, they will be processed in order
Options:
-c, --column <COLUMN> The column width of the output [default: 80]
-a, --ast Print the AST of the input file
-p, --pretty-doc Print the pretty document
-i, --inplace Format the file in place
-h, --help Print help
-V, --version Print version
Escape Route
If you find typstyle is not working as expected, you can use // @typstyle off
or /* @typstyle off */
to disable the formatter on the next node of code.
typstyle also gives up formatting part of the code if it is not able to format it correctly. Specifically, it will print that part as is if:
- contains syntax error
- contains syntaxes that are not supported by the formatter
And please let us know the issue by creating an issue on the GitHub repository
Design Goals
- Opinionated: We want to have a consistent style across all codebases.
- Code only: We want to format only the code. Contents should be left untouched as much as possible.
- Convergence: Running the formatter twice should not change the code.
- Correctness: The formatter should not change the looking of the rendered output.
Test
cargo test
cargo insta review
We have set up multiple tests:
- Convergence tests: format result must be the same when applied twice
- Snapshot tests: format result are stored in the
snapshots
directory and are compared to the current result when running the tests - Correctness test: We compare the rendered output of the code before and after formatting and ensure they are the same
- E2E Correctness test: We collect a bunch of typst code repo including tablex, cetz, fletcher... and format them to ensure (a) the format result converges and (b) the rendered output is the same.
Use as a library
Known issues
You tell us! Bad formatting? Incorrect output? Please create an issue on the GitHub repository!
We've set up comprehensive test suites to ensure the correctness of the formatter. If you find any issues, please let us know! And we can add more tests to prevent the issue from happening again.
Why another formatter?
Why there is a need for another formatter? We already have typstfmt, typstfmt, prettypst. Why another one?
typstyle started because I had a bunch of ideas on how to improve typst source code formatting but kept finding typstfmt wasn't a good codebase to explore them with. Namely:
- I wanted to use Wadler's pretty printer to get consistent and beautiful output for any width. (Note that it is the same technique used in the prettier formatter)
- I didn't have much energy to maintain a bunch combination of configuration options. It turns out to be very hard to make everything correct. So I decided to make it opinionated.
- I wanted to experiment with more testing techniques and make sure the formatter is correct.
So I decided to write something from scratch. I started it about half a year ago and kept working on it in my spare time. Currently it lacks some advanced features but it is already usable for most of the cases. I hope you like it!
Dependencies
~3–11MB
~120K SLoC