Skip to content

Commit 8d7a7a1

Browse files
committed
Update README
1 parent cfe9bf7 commit 8d7a7a1

File tree

1 file changed

+31
-57
lines changed

1 file changed

+31
-57
lines changed

README.md

Lines changed: 31 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,7 @@
88
<img width="375" height="375" src="https://user-images.githubusercontent.com/1022054/59317198-f1149b80-8d15-11e9-9b0f-0c5e7d4b8b81.png">
99
</p>
1010

11-
A [Prettier plugin](https://prettier.io/docs/en/plugins.html) for automatically formatting your [Solidity](https://github.com/ethereum/solidity) code.
12-
13-
## Nomic Foundation's Slang
14-
15-
Nomic Foundation has put a lot of effort in providing a set of compiler APIs that helped us rethink our approach to parsing and rely on their flexibility, detail oriented solution and continuos support of new and old Solidity syntaxes.
16-
17-
Since v2.0.0 this package will ship with the Slang parser and this change must be implemented in existing configurations by replacing `parser: 'antlr'` with `parser: 'slang'`.
18-
19-
The `antlr4` parser (`antlr`) is still supported for the time being and will trigger a deprecation warning, since Slang gives us a much more powerful tool, is faster, allowed us to fully transition into typescript (minimizing the introduction of mismatching type bugs), and allows prettier to format the code in a much more decoupled way and position comments with a greater precision.
11+
A [Prettier](https://prettier.io/) plugin for automatically formatting your [Solidity](https://docs.soliditylang.org/en/latest/) code.
2012

2113
## Installation and usage
2214

@@ -28,15 +20,13 @@ Install both `prettier` and `prettier-plugin-solidity`:
2820
npm install --save-dev prettier prettier-plugin-solidity
2921
```
3022

31-
> :package: ** Make sure `prettier`'s version is at least `3.0.0`**
32-
33-
Run prettier in your contracts:
23+
Run prettier on your contracts:
3424

3525
```Bash
3626
npx prettier --write --plugin=prettier-plugin-solidity 'contracts/**/*.sol'
3727
```
3828

39-
You can add a script for running prettier on all your contracts:
29+
You can add an npm script to run prettier on all your contracts:
4030

4131
```
4232
"prettier": "prettier --write --plugin=prettier-plugin-solidity 'contracts/**/*.sol'"
@@ -52,13 +42,11 @@ Or you can use it as part of your linting to check that all your code is prettif
5242
5343
### Using in the Browser
5444

55-
_Added in v1.1.0_
56-
5745
To use this package in the browser, you need to load Prettier's standalone bundle before loading the build provided in this package.
5846

5947
Prettier's unpkg field points to `https://unpkg.com/prettier/standalone.js`, in a similar way this plugin points to `https://unpkg.com/prettier-plugin-solidity/dist/standalone.js`.
6048

61-
Once the scripts are loaded you will have access the globals `prettier` and `prettierPlugins`.
49+
Once the scripts are loaded you will have access to the globals `prettier` and `prettierPlugins`.
6250

6351
We follow Prettier's strategy for populating their plugins in the object `prettierPlugins`, you can load other plugins like `https://unpkg.com/[email protected]/parser-markdown.js` and Prettier will have access to multiple parsers.
6452

@@ -83,17 +71,15 @@ We follow Prettier's strategy for populating their plugins in the object `pretti
8371
</script>
8472
```
8573

86-
For more details and please have a look at [Prettier's documentation](https://prettier.io/docs/en/browser.html).
74+
For more details, have a look at [Prettier's documentation](https://prettier.io/docs/en/browser.html).
8775

8876
### Creating a package for the Browser
8977

90-
_Added in v1.2.0_
91-
9278
If you are creating your own package to be run in a browser, you might want to import the standalone files directly.
9379

9480
```Javascript
95-
import prettier from 'prettier/standalone';
96-
import solidityPlugin from 'prettier-plugin-solidity/standalone';
81+
import prettier from "prettier/standalone";
82+
import solidityPlugin from "prettier-plugin-solidity/standalone";
9783

9884
async function format(code) {
9985
return await prettier.format(code, {
@@ -102,7 +88,7 @@ async function format(code) {
10288
});
10389
}
10490

105-
const originalCode = 'contract Foo {}';
91+
const originalCode = "contract Foo {}";
10692
const formattedCode = format(originalCode);
10793
```
10894

@@ -138,7 +124,7 @@ Most options are described in Prettier's [documentation](https://prettier.io/doc
138124

139125
### Compiler
140126

141-
Many versions of the Solidity compiler have changes that affect how the code should be formatted. This plugin, by default, tries to format the code in the most compatible way that it's possible, but you can use the `compiler` option to nudge it in the right direction.
127+
Many versions of the Solidity compiler have changes that affect how the code should be formatted. This plugin, by default, tries to format the code in the most compatible way that is possible, but you can use the `compiler` option to nudge it in the right direction.
142128

143129
One example of this is import directives. Before `0.7.4`, the compiler didn't accept multi-line import statements, so we always format them in a single line. But if you use the `compiler` option to indicate that you are using a version greater or equal than `0.7.4`, the plugin will use multi-line imports when it makes sense.
144130

@@ -218,9 +204,18 @@ You might have a multi-version project, where different files are compiled with
218204
| ------- | --------------------- | ---------------------- |
219205
| None | `--compiler <string>` | `compiler: "<string>"` |
220206

221-
### Experimental Ternaries
207+
### Parser
208+
209+
You can configure the parser used by Prettier Solidity. Two Solidity parsers are supported:
210+
211+
- [Slang](https://nomicfoundation.github.io/slang) (the default), a more powerful and correct parser that results in better formatting for some edge cases, especially when comments are involved.
212+
- [Solidity Parser for JavaScript](https://github.com/solidity-parser/parser/), an [ANTLR](https://www.antlr.org/)-based parser. This is the version that Prettier Solidity v1 used by default. This parser is still supported in v2, but it's deprecated and will be removed in the next major version. You can use this parser by setting `parser: "antlr"` in your Prettier configuration.
222213

223-
_Added in v1.3.0_
214+
| Default | CLI Override | API Override |
215+
| ------- | ------------------- | -------------------- |
216+
| `slang` | `--parser <string>` | `parser: "<string>"` |
217+
218+
### Experimental Ternaries
224219

225220
Mimicking prettier's [new ternary formatting](https://prettier.io/blog/2023/11/13/curious-ternaries) for the community to try.
226221

@@ -262,8 +257,7 @@ Plug 'prettier/vim-prettier', {
262257
\ 'solidity'] }
263258
```
264259

265-
We modified the `do` instruction to also install this plugin. Then you'll have to configure the plugin to always use the
266-
version installed in the vim plugin's directory. The vim-plug directory depends on value you use in `call plug#begin('~/.vim/<dir>')`:
260+
We modified the `do` instruction to also install this plugin. Then you'll have to configure the plugin to always use the version installed in the vim plugin's directory. The vim-plug directory depends on the value you use in `call plug#begin('~/.vim/<dir>')`:
267261

268262
```vim
269263
let g:prettier#exec_cmd_path = '~/.vim/plugged/vim-prettier/node_modules/.bin/prettier'
@@ -282,34 +276,29 @@ Now Prettier will be run every time the file is saved.
282276

283277
### VSCode
284278

285-
VSCode is not familiar with the Solidity language.
286-
There are 2 extensions that you can install to provide support for Solidity:
279+
VSCode is not familiar with the Solidity language. There are two extensions that you can install to provide support for Solidity:
287280

288-
- [`solidity`](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity)
289281
- [`hardhat-solidity`](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity)
282+
- [`solidity`](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity)
283+
284+
We recommend using the `hardhat-solidity` extension:
290285

291286
```Bash
292-
code --install-extension JuanBlanco.solidity
293-
# or
294287
code --install-extension NomicFoundation.hardhat-solidity
295288
```
296289

297-
> :warning: **These 2 extensions offer similar functionality and will clash with each other**: Please choose which one matches your projects better.
298-
299290
These extensions provide basic integration with Prettier; in most cases, no further action is needed.
300291

301-
Make sure your editor has format on save set to true.
302-
When you save VSCode will ask you what formatter would you like to use for the Solidity language, you can choose `JuanBlanco.solidity` or `NomicFoundation.hardhat-solidity`.
292+
Make sure your editor has format-on-save set to true. When you save, VSCode will ask you what formatter would you like to use for the Solidity language. We recommend choosing `NomicFoundation.hardhat-solidity`.
303293

304294
At this point VSCode's `settings.json` should have a configuration similar to this:
305295

306-
```JSON
296+
```JSON5
307297
{
308298
"editor.formatOnSave": true,
309299
"solidity.formatter": "prettier", // This is the default so it might be missing.
310300
"[solidity]": {
311-
// "editor.defaultFormatter": "JuanBlanco.solidity"
312-
// "editor.defaultFormatter": "NomicFoundation.hardhat-solidity"
301+
"editor.defaultFormatter": "NomicFoundation.hardhat-solidity"
313302
}
314303
}
315304
```
@@ -320,15 +309,15 @@ If you want more control over other details, you should proceed to install [`pre
320309
code --install-extension esbenp.prettier-vscode
321310
```
322311

323-
To interact with 3rd party plugins, `prettier-vscode` will look in the project's npm modules, so you'll need to have `prettier` and `prettier-plugin-solidity` in your `package.json`
312+
To interact with third-party plugins, `prettier-vscode` will look in the project's npm modules, so you'll need to have `prettier` and `prettier-plugin-solidity` in your `package.json`
324313

325314
```Bash
326315
npm install --save-dev prettier prettier-plugin-solidity
327316
```
328317

329318
This will allow you to specify the version of the plugin in case you want to use the latest version of the plugin or need to freeze the formatting since new versions of this plugin will implement tweaks on the possible formats.
330319

331-
You'll have to let VSCode what formatter you prefer.
320+
You'll have to let VSCode know what formatter you prefer.
332321
This can be done by opening the command palette and executing:
333322

334323
```
@@ -351,7 +340,7 @@ Now VSCode's `settings.json` should have this:
351340

352341
Note: By design, Prettier prioritizes a local over a global configuration. If you have a `.prettierrc` file in your project, your VSCode's default settings or rules in `settings.json` are ignored ([prettier/prettier-vscode#1079](https://github.com/prettier/prettier-vscode/issues/1079)).
353342

354-
### Pnpm
343+
### pnpm
355344

356345
To make Prettier Solidity work in your project, you have to add a `.prettierrc` file as shown [here](#configuration-file).
357346

@@ -400,21 +389,6 @@ Notice that the unnecessary parentheses in `modifier2` were removed in the funct
400389
5. Push to the branch (`git push origin feature/fooBar`)
401390
6. Create a new Pull Request
402391

403-
## Who's using it?
404-
405-
These are some of the projects using Prettier Solidity:
406-
407-
- [Bancor](https://app.bancor.network)
408-
- [Gelato](https://gelato.network/)
409-
- [Gnosis Protocol](https://docs.gnosis.io/protocol/)
410-
- [PieDAO](https://www.piedao.org/)
411-
- [Sablier](https://sablier.finance/)
412-
- [Synthetix](https://www.synthetix.io)
413-
- [The Sandbox](https://www.sandbox.game/en/)
414-
- [UMA](https://umaproject.org/)
415-
- [Uniswap](https://uniswap.org)
416-
- [Zora](https://zora.co)
417-
418392
## License
419393

420394
Distributed under the MIT license. See [LICENSE](LICENSE) for more information.

0 commit comments

Comments
 (0)