You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Syntax Tree is a suite of tools built on top of the internal CRuby parser. It provides the ability to generate a syntax tree from source, as well as the tools necessary to inspect and manipulate that syntax tree. It can be used to build formatters, linters, language servers, and more.
11
-
12
-
It is built with only standard library dependencies. It additionally ships with a plugin system so that you can build your own syntax trees from other languages and incorporate these tools.
10
+
Syntax Tree is fast Ruby parser built on top of the [prism](https://github.com/ruby/prism) Ruby parser. It is built with only standard library dependencies.
13
11
14
12
-[Installation](#installation)
15
13
-[CLI](#cli)
@@ -19,11 +17,9 @@ It is built with only standard library dependencies. It additionally ships with
Any of the above CLI commands can also read configuration options from a `.streerc` file in the directory where the commands are executed.
143
+
All of the above commands accept additional configuration options. Those are:
144
+
145
+
-`--print-width=?` - The print width is the suggested line length that should be used when formatting the source. Note that this is not a hard limit like a linter. Instead, it is used as a guideline for how long lines _should_ be. For example, if you have the following code:
146
+
147
+
```ruby
148
+
foo do
149
+
bar
150
+
end
151
+
```
152
+
153
+
In this case, the formatter will see that the block fits into the print width and will rewrite it using the `{}` syntax. This will actually make the line longer than originally written. This is why it is helpful to think of it as a suggestion, rather than a limit.
154
+
-`--preferred-quote=?` - The quote to use for string and character literals. This can be either `"` or `'`. It is "preferred" because in the case that the formatter encounters a string that contains interpolation or certain escape sequences, it will not attempt to change the quote style to avoid accidentally changing the semantic meaning of the code.
155
+
-`--[no-]trailing-comma` - Whether or not to add trailing commas to multiline array literals, hash literals, and method calls that can support trailing commas.
148
156
149
-
This should be a text file with each argument on a separate line.
157
+
Any of the above CLI commands can also read configuration options from a `.streerc` file in the directory where the commands are executed. This should be a text file with each argument on a separate line.
150
158
151
159
```txt
152
160
--print-width=100
153
-
--plugins=plugin/trailing_comma
161
+
--trailing-comma
154
162
```
155
163
156
-
If this file is present, it will _always_ be used for CLI commands. You can also pass options from the command line as in the examples above. The options in the `.streerc` file are passed to the CLI first, then the arguments from the command line. In the case of exclusive options (e.g. `--print-width`), this means that the command line options override what's in the config file. In the case of options that can take multiple inputs (e.g. `--plugins`), the effect is additive. That is, the plugins passed from the command line will be loaded _in addition to_ the plugins in the config file.
164
+
If this file is present, it will _always_ be used for CLI commands. The options in the `.streerc` file are passed to the CLI first, then the arguments from the command line. In the case of exclusive options (e.g. `--print-width`), this means that the command line options override what's in the config file. In the case of options that can take multiple inputs (e.g. `--plugins`), the effect is additive. That is, the plugins passed from the command line will be loaded _in addition to_ the plugins in the config file.
157
165
158
166
### Globbing
159
167
@@ -220,32 +228,8 @@ To register plugins, define a file somewhere in your load path named `syntax_tre
220
228
221
229
*`plugin/single_quotes` - This will change all of your string literals to use single quotes instead of the default double quotes.
222
230
*`plugin/trailing_comma` - This will put trailing commas into multiline array literals, hash literals, and method calls that can support trailing commas.
223
-
*`plugin/disable_auto_ternary` - This will prevent the automatic conversion of `if ... else` to ternary expressions.
224
-
225
-
If you're using Syntax Tree as a library, you can require those files directly or manually pass those options to the formatter initializer through the `SyntaxTree::Formatter::Options` class.
In this case, whenever the CLI encounters a filepath that ends with the given extension, it will invoke methods on `MyLanguage` instead of `SyntaxTree` itself. To make sure your object conforms to each of the necessary APIs, it should implement:
236
-
237
-
*`MyLanguage.read(filepath)` - usually this is just an alias to `File.read(filepath)`, but if you need anything else that hook is here.
238
-
*`MyLanguage.parse(source)` - this should return the syntax tree corresponding to the given source. Those objects should implement the `pretty_print` interface.
239
-
*`MyLanguage.format(source)` - this should return the formatted version of the given source.
240
231
241
-
Below are listed all of the "official" language plugins hosted under the same GitHub organization, which can be used as references for how to implement other plugins.
242
-
243
-
*[bf](https://github.com/ruby-syntax-tree/syntax_tree-bf) for the [brainf*** language](https://esolangs.org/wiki/Brainfuck).
244
-
*[css](https://github.com/ruby-syntax-tree/syntax_tree-css) for the [CSS stylesheet language](https://www.w3.org/Style/CSS/).
245
-
*[haml](https://github.com/ruby-syntax-tree/syntax_tree-haml) for the [Haml template language](https://haml.info/).
246
-
*[json](https://github.com/ruby-syntax-tree/syntax_tree-json) for the [JSON notation language](https://www.json.org/).
247
-
*[rbs](https://github.com/ruby-syntax-tree/syntax_tree-rbs) for the [RBS type language](https://github.com/ruby/rbs).
248
-
*[xml](https://github.com/ruby-syntax-tree/syntax_tree-xml) for the [XML markup language](https://www.w3.org/XML/).
232
+
If you're using Syntax Tree as a library, you can require those files directly or manually pass those options to the formatter initializer through the `SyntaxTree::Options` class.
249
233
250
234
## Integration
251
235
@@ -256,12 +240,12 @@ Syntax Tree's goal is to seamlessly integrate into your workflow. To this end, i
256
240
Syntax Tree ships with the ability to define [rake](https://github.com/ruby/rake) tasks that will trigger runs of the CLI. To define them in your application, add the following configuration to your `Rakefile`:
257
241
258
242
```ruby
259
-
require"syntax_tree/rake_tasks"
243
+
require"syntax_tree/rake"
260
244
SyntaxTree::Rake::CheckTask.new
261
245
SyntaxTree::Rake::WriteTask.new
262
246
```
263
247
264
-
These calls will define `rake stree:check` and `rake stree:write` (equivalent to calling `stree check` and `stree write` with the CLI respectively). You can configure them by either passing arguments to the `new` method or by using a block.
248
+
These calls will define `rake stree:check` and `rake stree:write` (equivalent to calling `stree check` and `stree write` with the CLI respectively). You can configure them by either passing arguments to the `new` method or by using a block. In addition to the regular configuration options used for the formatter, there are a few additional options specific to the rake tasks.
265
249
266
250
#### `name`
267
251
@@ -292,26 +276,6 @@ SyntaxTree::Rake::WriteTask.new do |t|
292
276
end
293
277
```
294
278
295
-
#### `print_width`
296
-
297
-
If you want to use a different print width from the default (80), you can pass that to the `print_width` field, as in:
298
-
299
-
```ruby
300
-
SyntaxTree::Rake::WriteTask.newdo |t|
301
-
t.print_width =100
302
-
end
303
-
```
304
-
305
-
#### `plugins`
306
-
307
-
If you're running Syntax Tree with plugins (either your own or the pre-built ones), you can pass that to the `plugins` field, as in:
308
-
309
-
```ruby
310
-
SyntaxTree::Rake::WriteTask.newdo |t|
311
-
t.plugins = ["plugin/single_quotes"]
312
-
end
313
-
```
314
-
315
279
### RuboCop
316
280
317
281
RuboCop and Syntax Tree serve different purposes, but there is overlap with some of RuboCop's functionality. Syntax Tree provides a RuboCop configuration file to disable rules that are redundant with Syntax Tree. To use this configuration file, add the following snippet to the top of your project's `.rubocop.yml`:
0 commit comments