prettier-plugin-rust - npm Package Compare versions

Comparing version 0.1.1 to 0.1.5

package.json

 {
 	"name": "prettier-plugin-rust",
-	"version": "0.1.1",
+	"version": "0.1.5",
 	"description": "Prettier plugin for Rust",
@@ -58,4 +58,16 @@ "repository": {
 		"useTabs": true,
-		"endOfLine": "lf"
+		"endOfLine": "lf",
+		"overrides": [
+			{
+				"files": [
+					"**/*.md"
+				],
+				"options": {
+					"printWidth": 80,
+					"useTabs": false,
+					"tabWidth": 2
+				}
+			}
+		]
 	}
 }

README.md

@@ -7,2 +7,4 @@ <div align="center">
 
+<div align="center">
+
 ![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg) [![npm version](https://img.shields.io/npm/v/prettier-plugin-rust.svg?style=flat)](https://www.npmjs.com/package/prettier-plugin-rust) ![GitHub Repo stars](https://img.shields.io/github/stars/jinxdash/prettier-plugin-rust?style=social) [![Twitter Follow](https://img.shields.io/twitter/follow/jinxdash?style=social)](https://twitter.com/jinxdash)
@@ -12,60 +14,207 @@
 
--   **Get Started:** Search for the [Prettier - Code formatter (Rust)](https://marketplace.visualstudio.com/items?itemName=jinxdash.prettier-rust) extension in VSCode.
+**Get Started:** Install [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=jinxdash.prettier-rust) `Prettier - Code formatter (Rust)`
 
-### A _formatter_ -- not a linter!
+</div>
 
-Prettier Rust doesn't panic on missing semicolons, _in fact it AUTO-COMPLETES them!_
+## Why Prettier?
 
-Thanks to the specially built [`jinx-rust`](https://www.github.com/jinxdash/jinx-rust/) parser, Prettier is completely independent from Rust's strict validation process.  
-As such, it is able to format rust just like it formats typescript!
+> What usually happens once people start using Prettier is that they realize how much time and mental energy they actually spend formatting their code. With Prettier editor integration, you can just press the `Format Document` key binding and poof, the code is formatted. This is an eye-opening experience if anything.
 
-## Configuration
+- **Beautiful, uniform and consistent** — Prettier is strongly opinionated, it has zero style options.
+- **Life-changing Editor Integration** — Prettier can format WIP code before it can compile _(e.g. missing annotations)_
+- **Stop wasting time on formalities** — Prettier autocorrects bad syntax _(e.g. missing semicolons, blocks, parentheses...)_
 
-Configure `prettier` by creating a `.prettierrc.toml` file, or [any other file format listed in prettier docs](https://prettier.io/docs/en/configuration.html).
+<table align="center">
+<tr> <th>> input</th> <th>> formatted</th> </tr>
+<tr>
+  <td>
 
-To ignore files, list them in `.prettierignore` (like you would `.gitignore`)
+<!-- prettier-ignore -->
+```rs
+const LEET = 1337
+/// My WIP code draft
+#![feature(crate_visibility_modifier)]
+async crate fn foo(arg) {
+  arg.0 *= 3.14 + LEET & 1337
+  arg.1(|b, c| -> T &c).await
+}
+```
 
-| API Option                   | CLI Option                     | Default | Docs                                                                           |
-| ---------------------------- | ------------------------------ | :-----: | ------------------------------------------------------------------------------------- |
-| `tabWidth`                   | --tab-width                    |    4    | _[link](https://prettier.io/docs/en/options.html#tab-width)_   |
-| `printWidth`                 | --print-width                  |   100   | _[link](https://prettier.io/docs/en/options.html#print-width)_ |
-| `endOfLine`                  | --end-of-line                  |  "lf"   | _[link](https://prettier.io/docs/en/options.html#end-of-line)_ |
-| `trailingComma`              | --trailing-comma               |         | Not supported yet.                                                                    |
-| `embeddedLanguageFormatting` | --embedded-language-formatting |         | Not supported yet.                                                                    |
+  </td>
+  <td>
 
-### Ignoring stuff
+<!-- prettier-ignore -->
+```rs
+const LEET = 1337;
+#![feature(crate_visibility_modifier)]
+/// My WIP code draft
+crate async fn foo(arg) {
+    arg.0 *= (3.14 + LEET) & 1337;
+    (arg.1)(|b, c| -> T { &c }).await
+}
+```
 
-To ignore something, add `// prettier-ignore` above it.
+  </td>
+</tr>
+</table>
+<div align="center">
 
-`#[rustfmt::skip]` and `#![rustfmt::skip]` are also supported (locally).
+_Formatting succeeds and fixes 7 syntax errors._
 
-## Installation
+</div>
 
-### VSCode
+## Configuration
 
-- Either install the standalone extension `Prettier - Code formatter (Rust)` or
+https://prettier.io/docs/en/configuration
 
-- use the official one which has issues loading plugins and _will NOT auto-update them_. [Read about plugins in Prettier docs.](https://prettier.io/docs/en/plugins.html)
+```json
+// .prettierrc.json
+{
+  "useTabs": false,
+  "tabWidth": 4,
+  "printWidth": 100,
+  "endOfLine": "lf",
 
+  // -- Not supported yet --
+  // "trailingComma": "es5",
+  // "embeddedLanguageFormatting": "auto",
 
-If you have `rust-analyzer` or another extension that formats `rust` files installed, VSCode will prompt you to choose your preferred formatter the next time you attempt to format a file. If you already had one defined, you may have to adjust your settings:
-
-```JSON
-"[rust]": {
-		"editor.defaultFormatter": "jinxdash.prettier-rust"
+  // Example override
+  "overrides": { "files": ["tests/*.rs"], "options": { "printWidth": 80 } }
 }
 ```
 
-### crate
+<details>
+    <summary>Alternative config using TOML</summary>
 
-_Not available yet_
+```toml
+# .prettierrc.toml
 
-### npm
+useTabs = false
+tabWidth = 4
+printWidth = 100
+endOfLine = "lf"
 
-The plugin is published on npm as `prettier-plugin-rust` and can be used like any other prettier plugin.
+# -- Not supported yet --
+# trailingComma = "es5"
+# embeddedLanguageFormatting = "auto"
 
+# Example override
+overrides = [
+  { files = ["tests/*.rs"], options = { printWidth = 80 } }
+]
 ```
-npm install --save-dev prettier-plugin-rust
-```
 
-Refer to the [Prettier documentation](https://prettier.io/docs/en/cli.html) for available CLI commands.
+</details>
+
+### How to ignore things
+
+- Add `// prettier-ignore` or `#[rustfmt::skip]` above it
+- Add `#![rustfmt::skip]` inside blocks or files
+- Create a `.prettierignore` file to glob-match files, like `.gitignore`
+
+### How are macros formatted?
+
+- Curlies `!{}` format like blocks, `![]` and `!()` like comma-separated expressions
+- Formatting inside macro invocations is more conservative, since macros can be token-sensitive
+- Popular/built-in macros with original syntax rules get custom formatting (e.g. `matches!`, `if_chains!`...)
+- Macro Declarations are only partially formatted (the transformed part isn't yet, but could be in the future)
+- Macros that can't be formatted are silently ignored
+
+### Are nightly features supported?
+
+Yes! Prettier Rust formats most nightly features. Support depends on [`jinx-rust`](https://github.com/jinxdash/jinx-rust).
+
+## Editor integration
+
+- ### `Recommended` Extension Standalone
+
+  _Easy install + auto-updates_
+
+  - VSCode | Search and install `Prettier - Code formatter (Rust)` [[direct link]](https://marketplace.visualstudio.com/items?itemName=jinxdash.prettier-rust)
+
+  - _Request your favorite editor:_ [[file an issue]](https://github.com/jinxdash/prettier-plugin-rust/issues/new)
+
+- ### `Alternative` Core Extension Plugin
+
+  _Requires [NodeJS](https://nodejs.dev/download/) + [Prettier Extension](https://prettier.io/docs/en/editors.html)_ (built-in Jetbrains IDEs)
+
+  ```sh
+  npm install --global prettier-plugin-rust prettier
+  ```
+
+  _Restart IDE after installing._  
+  _To update (manual only!!):_ `npm upgrade --global prettier-plugin-rust prettier`  
+  _To check installed version:_ `npm ls -g --depth=0 prettier-plugin-rust prettier`  
+  _To check latest version:_ `npm info prettier-plugin-rust version`
+
+## Project integration
+
+- ### Command line
+
+  _Requires [NodeJS](https://nodejs.dev/download/)_
+
+  - Install `prettier` and `prettier-plugin-rust` globally
+
+    ```sh
+    npm install --global prettier-plugin-rust prettier
+    ```
+
+  - Use the [prettier CLI](https://prettier.io/docs/en/cli.html) to format rust files. E.g. run:
+
+    ```sh
+    prettier --write **/*.rs
+    ```
+
+- ### NodeJS package
+
+  _Requires [NodeJS](https://nodejs.dev/download/)_
+
+  - Install `prettier` and `prettier-plugin-rust` in the project
+
+    ```sh
+    npm install --save-dev prettier-plugin-rust prettier
+    ```
+
+  - Link to the plugin's location in your prettier config:
+
+    ```json
+    "plugins": ["./node_modules/prettier-plugin-rust"]
+    ```
+
+  - Use the [prettier CLI](https://prettier.io/docs/en/cli.html) to format rust files. E.g. run:
+
+    ```sh
+    npx prettier --write **/*.rs
+    ```
+
+- ### Rust crate
+
+  _No crate yet. Above options are available in the meantime._
+
+---
+
+## Q&A
+
+- ### _Why would I use this and not the established `cargo fmt` ?_
+
+  **It mostly comes down to the Editor Integration.** — With Prettier Rust, you have the ability to hit the `Format Document` keybind on incomplete code and everything fits right into place. Again reiterating on what was said in the introduction, but this is _actually_ life-changing. Just try it out, 1-click install the extension, write a few lines and hit the keybind.
+
+   There's only little difference in terms of how code is printed, so adopting Prettier Rust won't drastically change a codebase. Prettier's only downside against Rustfmt is its troublesome integration into the Rust ecosystem. Fortunately it's only a matter of time before it gets resolved.
+
+  See also:
+
+  - Prettier Rust does not have style options.
+  - Prettier Rust produces slightly more readable code (e.g. parenthesis around compound bin ops)
+  - Prettier Rust supports more things by default (nightly features, macros, ...)
+  - Prettier consistently prints code in the same way, whereas rustfmt preserves arbitrary style at places
+  - Prettier is available for many languages (e.g. markdown, html, typescript, java, python, ruby...)
+  - Prettier supports language embeds. It formats rust code blocks in non-rust files (e.g. markdown), and conversely formats supported languages within rust doc comments.
+
+- ### _How can Prettier Rust format files that the Rust Compiler cannot parse?_
+
+  Prettier Rust is based on `jinx-rust`, a Rust Parser specially built for Rust Tooling. [Learn more about jinx-rust here.](https://github.com/jinxdash/jinx-rust)
+
+- ### _How does Prettier Rust compare to Prettier Typescript?_
+
+  Prettier Rust is essentially a port of Prettier Typescript. The Rust plugin barely introduces style opinions on its own.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

327538

increased by1.27%

Lines of code

8078

increased by0.01%

Number of lines in readme file

218

increased by211.43%

No dependency changes