From 8faf11edfd407237c1eb07420bef0bb9a395c121 Mon Sep 17 00:00:00 2001 From: Kevin Newton Date: Wed, 9 Nov 2022 11:58:05 -0500 Subject: [PATCH 1/2] Make the test suite silent --- test/ractor_test.rb | 21 ++++++++++++++++++--- test/rake_test.rb | 7 +++---- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/test/ractor_test.rb b/test/ractor_test.rb index e697b48e..bcdb2a51 100644 --- a/test/ractor_test.rb +++ b/test/ractor_test.rb @@ -20,12 +20,14 @@ def test_formatting source = SyntaxTree.read(filepath) program = SyntaxTree.parse(source) - Ractor.new(source, program, name: filepath) do |source, program| - SyntaxTree::Formatter.format(source, program) + with_silenced_warnings do + Ractor.new(source, program, name: filepath) do |source, program| + SyntaxTree::Formatter.format(source, program) + end end end - ractors.each(&:take) + ractors.each { |ractor| assert_kind_of String, ractor.take } end private @@ -33,5 +35,18 @@ def test_formatting def filepaths Dir.glob(File.expand_path("../lib/syntax_tree/{node,parser}.rb", __dir__)) end + + # Ractors still warn about usage, so I'm disabling that warning here just to + # have clean test output. + def with_silenced_warnings + previous = $VERBOSE + + begin + $VERBOSE = nil + yield + ensure + $VERBOSE = previous + end + end end end diff --git a/test/rake_test.rb b/test/rake_test.rb index d07fc49c..90662519 100644 --- a/test/rake_test.rb +++ b/test/rake_test.rb @@ -46,12 +46,11 @@ def invoke(task_name) invocation = nil stub = ->(args) { invocation = Invocation.new(args) } - begin + assert_raises SystemExit do SyntaxTree::CLI.stub(:run, stub) { ::Rake::Task[task_name].invoke } - flunk - rescue SystemExit - invocation end + + invocation end end end From a1981d70011efa9e7c8a5b97f121635df5cbbeee Mon Sep 17 00:00:00 2001 From: Kevin Newton Date: Wed, 9 Nov 2022 12:07:43 -0500 Subject: [PATCH 2/2] Document ignoring code --- README.md | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 050877ee..a6b01362 100644 --- a/README.md +++ b/README.md @@ -46,8 +46,8 @@ It is built with only standard library dependencies. It additionally ships with - [textDocument/formatting](#textdocumentformatting) - [textDocument/inlayHint](#textdocumentinlayhint) - [syntaxTree/visualizing](#syntaxtreevisualizing) -- [Plugins](#plugins) - - [Customization](#customization) +- [Customization](#customization) + - [Plugins](#plugins) - [Languages](#languages) - [Integration](#integration) - [Rake](#rake) @@ -320,6 +320,10 @@ Baked into this syntax is the ability to provide exceptions to file name pattern stree write "**/{[!schema]*,*}.rb" ``` +## Formatting + + + ## Library Syntax Tree can be used as a library to access the syntax tree underlying Ruby source code. @@ -619,18 +623,45 @@ Implicity, the `2 * 3` is going to be executed first because the `*` operator ha The language server additionally includes this custom request to return a textual representation of the syntax tree underlying the source code of a file. Language server clients can use this to (for example) open an additional tab with this information displayed. -## Plugins +## Customization + +There are multiple ways to customize Syntax Tree's behavior when parsing and formatting code. You can ignore certain sections of the source code, you can register plugins to provide custom formatting behavior, and you can register additional languages to be parsed and formatted. + +### Ignoring code + +To ignore a section of source code, you can a special `# stree-ignore` comment. This comment should be placed immediately above the code that you want to ignore. For example: + +```ruby +numbers = [ + 10000, + 20000, + 30000 +] +``` + +Normally the snippet above would be formatted as `numbers = [10_000, 20_000, 30_000]`. However, sometimes you want to keep the original formatting to improve readability or maintainability. In that case, you can put the ignore comment before it, as in: + +```ruby +# stree-ignore +numbers = [ + 10000, + 20000, + 30000 +] +``` + +Now when Syntax Tree goes to format that code, it will copy the source code exactly as it is, including the newlines and indentation. -You can register additional customization and additional languages that can flow through the same CLI with Syntax Tree's plugin system. When invoking the CLI, you pass through the list of plugins with the `--plugins` options to the commands that accept them. They should be a comma-delimited list. When the CLI first starts, it will require the files corresponding to those names. +### Plugins -### Customization +You can register additional customization that can flow through the same CLI with Syntax Tree's plugin system. When invoking the CLI, you pass through the list of plugins with the `--plugins` options to the commands that accept them. They should be a comma-delimited list. When the CLI first starts, it will require the files corresponding to those names. -To register additional customization, define a file somewhere in your load path named `syntax_tree/my_plugin`. Then when invoking the CLI, you will pass `--plugins=my_plugin`. To require multiple, separate them by a comma. In this way, you can modify Syntax Tree however you would like. Some plugins ship with Syntax Tree itself. They are: +To register plugins, define a file somewhere in your load path named `syntax_tree/my_plugin`. Then when invoking the CLI, you will pass `--plugins=my_plugin`. To require multiple, separate them by a comma. In this way, you can modify Syntax Tree however you would like. Some plugins ship with Syntax Tree itself. They are: * `plugin/single_quotes` - This will change all of your string literals to use single quotes instead of the default double quotes. * `plugin/trailing_comma` - This will put trailing commas into multiline array literals, hash literals, and method calls that can support trailing commas. -If you're using Syntax Tree as a library, you should require those files directly. +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. ### Languages