## How to use
+You'll need a pretty up to date version of the **nightly** version of Rust.
+You will need a default.toml file in the current working directory when you run
+the rustfmt command. You can look at this repo for an example default.toml file.
+
`cargo build` to build.
`cargo test` to run all tests.
-`cargo run filename` to run on a file, if the file includes out of line modules,
+`cargo run -- filename` to run on a file, if the file includes out of line modules,
then we reformat those too. So to run on a whole module or crate, you just need
-to run on the top file. You'll probably want to set the `WriteMode` in the call
-to `run` in `main()`. Eventually you should be able to set the mode from the
-command line or from a config file or something.
+to run on the top file.
+
+You'll probably want to specify the write mode. Currently, there are the replace,
+overwrite and display mode. The replace mode is the default and overwrites the
+original files after renaming them. In overwrite mode, rustfmt does not backup
+the source files. To print the output to stdout, use the display mode. The write
+mode can be set by passing the `--write-mode` flag on the command line.
-You'll need a pretty up to date version of the nightly version of Rust.
+`cargo run -- filename --write-mode=display` prints the output of rustfmt to the
+screen, for example.
## Use cases
However, we will not change the names of variables or make any changes which
*could* change the semantics. To be ever so slightly formal, we might imagine
a compilers high level intermediate representation, we should strive to only
-make changes which do change the HIR, even if they do change the AST.
+make changes which do not change the HIR, even if they do change the AST.
I would like to be able to output refactoring scripts for making deeper changes
though. (E.g., renaming variables to satisfy our style guidelines).
The advantage of the tokens approach are that you can operate on non-parsable
code. I don't care too much about that, it would be nice, but I think being able
-to sophisticated transformations is more important. In the future I hope to
+to perform sophisticated transformations is more important. In the future I hope to
(optionally) be able to use type information for informing reformatting too. One
specific case of unparsable code is macros. Using tokens is certainly easier
here, but I believe it is perfectly solvable with the AST approach. At the limit,
issues where it does something you don't expect.
A really useful thing to do that on a crate from the Rust repo. If it does
-something unexpected, file an issue; if not, make a PR to the Rust repo with the
-reformatted code. I hope to get the whole repo consistently rustfmt'ed and to
+something unexpected, file an issue; if not, make a PR to the Rust repo with the reformatted code. I hope to get the whole repo consistently rustfmt'ed and to
replace `make tidy` with rustfmt as a medium-term goal.
### Create test cases
projects / rust.git / blobdiff