syntax_tree 1.2.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4797ffd100da9b050f154cd0ac4a235b342c395e49747ee51574eb0e0f9fcf1a
-  data.tar.gz: 52babf707ae1bf42abaeb51b350644fc50f61fa1b74482abb776e863d2ec48dd
+  metadata.gz: 46b573afdda378e664e11b1f5acab2c89ce0fdd2c8b3d4c6400d74e133aaffc3
+  data.tar.gz: 6be0570ce471fe3f34c53730d7095d9b81be5b7e3e2e84ac5724ba95d7ac7362
 SHA512:
-  metadata.gz: 62e28b7e6b25e81bdfb70817c02152bd640395149c1ac75fa553154ebb636c9c913dbf2ebda7a65f9687dd1bb69d51e0e3d8f5ffba172d0b1eadb5849e64369a
-  data.tar.gz: 6233b01960317929ce137305a08f45d3d756d741b5f6b6d037f2499377a53922f222543f433912cc853ee31726e2306527fbe29c75ad757e6125207b7476956c
+  metadata.gz: 36236536a1dda5e6e2907b82c383b74f207f5e2b64f282490cf26161d62d748d1cdf51b68c393cd60f1777d2c5434c294ad2e243f2575faae34c42ac44155f76
+  data.tar.gz: 5c2e0ee682e5847287cee5a6ca4357c51e4172bacf7aa98b780e427fb7d0912b6bd829bbf6236baa294a919be9be5730d8c7e74b27a0ca630a29a91c37540324

data/.github/workflows/gh-pages.yml

@@ -0,0 +1,26 @@
+name: Github Pages (rdoc)
+on: [push]
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@master
+
+      - name: Set up Ruby 💎
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: '3.1'
+
+      - name: Install rdoc and generate docs 🔧
+        run: |
+          gem install rdoc
+          rdoc --main README.md --op rdocs --exclude={Gemfile,Rakefile,"coverage/*","vendor/*","bin/*","test/*","tmp/*"}
+          cp -r doc rdocs/doc
+
+      - name: Deploy 🚀
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./rdocs

data/.github/workflows/main.yml

@@ -4,6 +4,14 @@ on:
 - pull_request_target
 jobs:
   ci:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+        - '2.7'
+        - '3.0'
+        - '3.1'
+        - head
     name: CI
     runs-on: ubuntu-latest
     env:
@@ -13,7 +21,7 @@ jobs:
     - uses: ruby/setup-ruby@v1
       with:
         bundler-cache: true
-        ruby-version: '3.1'
+        ruby-version: ${{ matrix.ruby }}
     - name: Test
       run: bundle exec rake test
   automerge:

data/.gitignore

@@ -2,9 +2,10 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
+/rdocs/
 /spec/reports/
 /tmp/
+/vendor/
 
 test.rb

data/CHANGELOG.md

@@ -6,6 +6,44 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+## [2.1.0] - 2022-04-12
+
+### Added
+
+- The `SyntaxTree::Visitor` class now implements the visitor pattern for Ruby nodes.
+- The `SyntaxTree::Visitor.visit_method(name)` method.
+- Support for Ruby 2.7.
+- Support for comments on `rescue` and `else` keywords.
+- `SyntaxTree::Location` now additionally has `start_column` and `end_column`.
+- The CLI now accepts content over STDIN for the `ast`, `check`, `debug`, `doc`, `format`, and `write` commands.
+
+### Removed
+
+- The missing hash value inlay hints have been removed.
+
+## [2.0.1] - 2022-03-31
+
+### Changed
+
+- Move the `SyntaxTree.register_handler` method to the correct location.
+
+## [2.0.0] - 2022-03-31
+
+### Added
+
+- The new `SyntaxTree.register_handler` hook for plugins.
+- The new `--plugins=` option on the CLI.
+
+### Changed
+
+- Changed `SyntaxTree` from being a class to being a module. The parser functionality is moved into `SyntaxTree::Parser`.
+- There is now a parent class for all of the nodes named `SyntaxTree::Node`.
+- The `Implicits` class has been renamed to `InlayHints` to match the new LSP spec.
+
+### Removed
+
+- The disassembly code action has been removed to limit the scope of this project overall.
+
 ## [1.2.0] - 2022-01-09
 
 ### Added
@@ -105,9 +143,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 - 🎉 Initial release! 🎉
 
-[unreleased]: https://github.com/kddnewton/syntax_tree/compare/v1.2.0...HEAD
-[1.2.0]: https://github.com/kddnewton/syntax_tree/compare/v1.1.1...v1.2.0
-[1.1.1]: https://github.com/kddnewton/syntax_tree/compare/v1.1.0...v1.1.1
-[1.1.0]: https://github.com/kddnewton/syntax_tree/compare/v1.0.0...v1.1.0
-[1.0.0]: https://github.com/kddnewton/syntax_tree/compare/v0.1.0...v1.0.0
-[0.1.0]: https://github.com/kddnewton/syntax_tree/compare/8aa1f5...v0.1.0
+[unreleased]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.0.1...v2.1.0
+[2.0.1]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v1.2.0...v2.0.0
+[1.2.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/8aa1f5...v0.1.0

data/Gemfile.lock

@@ -1,19 +1,19 @@
 PATH
   remote: .
   specs:
-    syntax_tree (1.2.0)
+    syntax_tree (2.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    benchmark-ips (2.9.2)
+    benchmark-ips (2.10.0)
     docile (1.4.0)
     minitest (5.15.0)
-    parser (3.1.0.0)
+    parser (3.1.2.0)
       ast (~> 2.4.1)
     rake (13.0.6)
-    ruby_parser (3.18.1)
+    ruby_parser (3.19.1)
       sexp_processor (~> 4.16)
     sexp_processor (4.16.0)
     simplecov (0.21.2)
@@ -22,9 +22,11 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.3)
-    stackprof (0.2.17)
+    stackprof (0.2.19)
 
 PLATFORMS
+  arm64-darwin-21
+  ruby
   x86_64-darwin-19
   x86_64-darwin-21
   x86_64-linux

data/README.md

@@ -1,13 +1,56 @@
+<div align="center">
+  <img alt="Syntax Tree" height="400px" src="./doc/logo.svg">
+</div>
+
 # SyntaxTree
 
-[![Build Status](https://github.com/kddnewton/syntax_tree/workflows/Main/badge.svg)](https://github.com/kddnewton/syntax_tree/actions)
+[![Build Status](https://github.com/ruby-syntax-tree/syntax_tree/actions/workflows/main.yml/badge.svg)](https://github.com/ruby-syntax-tree/syntax_tree/actions/workflows/main.yml)
 [![Gem Version](https://img.shields.io/gem/v/syntax_tree.svg)](https://rubygems.org/gems/syntax_tree)
 
-A fast Ruby parser and formatter with only standard library dependencies.
+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.
+
+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.
+
+- [Installation](#installation)
+- [CLI](#cli)
+  - [ast](#ast)
+  - [check](#check)
+  - [format](#format)
+  - [write](#write)
+- [Library](#library)
+  - [SyntaxTree.read(filepath)](#syntaxtreereadfilepath)
+  - [SyntaxTree.parse(source)](#syntaxtreeparsesource)
+  - [SyntaxTree.format(source)](#syntaxtreeformatsource)
+- [Nodes](#nodes)
+  - [child_nodes](#child_nodes)
+  - [Pattern matching](#pattern-matching)
+  - [pretty_print(q)](#pretty_printq)
+  - [to_json(*opts)](#to_jsonopts)
+  - [format(q)](#formatq)
+- [Visitor](#visitor)
+  - [visit_method](#visit_method)
+- [Language server](#language-server)
+  - [textDocument/formatting](#textdocumentformatting)
+  - [textDocument/inlayHints](#textdocumentinlayhints)
+  - [syntaxTree/visualizing](#syntaxtreevisualizing)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Syntax Tree is both a command-line interface and a library. If you're only looking to use the command-line interface, then we recommend installing the gem globally, as in:
+
+```sh
+gem install syntax_tree
+```
+
+To run the CLI with the gem installed globally, you would run:
+
+```sh
+stree version
+```
+
+If you're planning on using Syntax Tree as a library within your own project, we recommend installing it as part of your gem bundle. First, add this line to your application's Gemfile:
 
 ```ruby
 gem "syntax_tree"
@@ -15,61 +58,259 @@ gem "syntax_tree"
 
 And then execute:
 
-    $ bundle install
+```sh
+bundle install
+```
+
+To run the CLI with the gem installed in your gem bundle, you would run:
+
+```sh
+bundle exec stree version
+```
 
-Or install it yourself as:
+## CLI
 
-    $ gem install syntax_tree
+Syntax Tree ships with the `stree` CLI, which can be used to inspect and manipulate Ruby code. Below are listed all of the commands built into the CLI that you can use. Note that for all commands that operate on files, you can also pass in content through STDIN.
 
-## Usage
+### ast
 
-From code:
+This command will print out a textual representation of the syntax tree associated with each of the files it finds. To execute, run:
 
-```ruby
-require "syntax_tree"
+```sh
+stree ast path/to/file.rb
+```
+
+For a file that contains `1 + 1`, you will receive:
 
-pp SyntaxTree.parse(source) # print out the AST
-puts SyntaxTree.format(source) # format the AST
 ```
+(program (statements (binary (int "1") + (int "1"))))
+```
+
+### check
 
-From the CLI:
+This command is meant to be used in the context of a continuous integration or git hook. It checks each file given to make sure that it matches the expected format. It can be used to ensure unformatted content never makes it into a codebase.
 
 ```sh
-$ stree ast program.rb
-(program
-  (statements
-    ...
+stree check path/to/file.rb
+```
+
+For a file that matches the expected format, you will receive:
+
+```
+All files matched expected format.
+```
+
+If there are files with unformatted code, you will receive:
+
 ```
+[warn] path/to/file.rb
+The listed files did not match the expected format.
+```
+
+### format
 
-or
+This command will output the formatted version of each of the listed files. Importantly, it will not write that content back to the source files. It is meant to display the formatted version only.
 
 ```sh
-$ stree format program.rb
-class MyClass
-  ...
+stree format path/to/file.rb
+```
+
+For a file that contains `1 + 1`, you will receive:
+
+```ruby
+1 + 1
 ```
 
-or
+### write
+
+This command will format the listed files and write that formatted version back to the source files. Note that this overwrites the original content, to be sure to be using a version control system.
 
 ```sh
-$ stree write program.rb
-program.rb 1ms
+stree write path/to/file.rb
+```
+
+This will list every file that is being formatted. It will output light gray if the file already matches the expected format. It will output in regular color if it does not.
+
+```
+path/to/file.rb 0ms
+```
+
+## Library
+
+Syntax Tree can be used as a library to access the syntax tree underlying Ruby source code.
+
+### SyntaxTree.read(filepath)
+
+This function takes a filepath and returns a string associated with the content of that file. It is similar in functionality to `File.read`, except htat it takes into account Ruby-level file encoding (through magic comments at the top of the file).
+
+### SyntaxTree.parse(source)
+
+This function takes an input string containing Ruby code and returns the syntax tree associated with it. The top-level node is always a `SyntaxTree::Program`, which contains a list of top-level expression nodes.
+
+### SyntaxTree.format(source)
+
+This function takes an input string containing Ruby code, parses it into its underlying syntax tree, and formats it back out to a string.
+
+## Nodes
+
+There are many different node types in the syntax tree. They are meant to be treated as immutable structs containing links to child nodes with minimal logic contained within their implementation. However, for the most part they all respond to a certain set of APIs, listed below.
+
+### child_nodes
+
+One of the easiest ways to descend the tree is to use the `child_nodes` function. It is implemented on every node type (leaf nodes return an empty array). If the goal is to simply walk through the tree, this is the easiest way to go.
+
+```ruby
+program = SyntaxTree.parse("1 + 1")
+program.child_nodes.first.child_nodes.first
+# => (binary (int "1") :+ (int "1"))
 ```
 
-## Development
+### Pattern matching
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Pattern matching is another way to descend the tree which is more specific than using `child_nodes`. Using Ruby's built-in pattern matching, you can extract the same information but be as specific about your constraints as you like. For example, with minimal constraints:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+program = SyntaxTree.parse("1 + 1")
+program => { statements: { body: [binary] } }
+binary
+# => (binary (int "1") :+ (int "1"))
+```
+
+Or, with more constraints on the types to ensure we're getting exactly what we expect:
+
+```ruby
+program = SyntaxTree.parse("1 + 1")
+program => SyntaxTree::Program[statements: SyntaxTree::Statements[body: [SyntaxTree::Binary => binary]]]
+binary
+# => (binary (int "1") :+ (int "1"))
+```
+
+### pretty_print(q)
+
+Every node responds to the `pretty_print` Ruby interface, which makes it usable by the `pp` library. You _can_ use this API manually, but it's mostly there for compatibility and not meant to be directly invoked. For example:
+
+```ruby
+pp SyntaxTree.parse("1 + 1")
+# (program (statements (binary (int "1") + (int "1"))))
+```
+
+### to_json(*opts)
+
+Every node responds to the `to_json` Ruby interface, which makes it usable by the `json` library. Much like `pretty_print`, you could use this API manually, but it's mostly used by `JSON` to dump the nodes to a serialized format. For example:
+
+```ruby
+program = SyntaxTree.parse("1 + 1")
+program => { statements: { body: [{ left: }] } }
+puts JSON.dump(left)
+# {"type":"int","value":"1","loc":[1,0,1,1],"cmts":[]}
+```
+
+### format(q)
+
+Every node responds to `format`, which formats the content nicely. The API mirrors that used by the `pretty_print` gem in that it accepts a formatter object and calls methods on it to generate its own internal representation of the text that will be outputted. Because of this, it's easier to not use this API directly and instead to call `SyntaxTree.format`. You _can_ however use this directly if you create the formatter yourself, as in:
+
+```ruby
+source = "1+1"
+program = SyntaxTree.parse(source)
+program => { statements: { body: [binary] } }
+
+formatter = SyntaxTree::Formatter.new(source, [])
+binary.format(formatter)
+
+formatter.flush
+formatter.output.join
+# => "1 + 1"
+```
+
+## Visitor
+
+If you want to operate over a set of nodes in the tree but don't want to walk the tree manually, the `Visitor` class makes it easy. `SyntaxTree::Visitor` is an implementation of the double dispatch visitor pattern. It works by the user defining visit methods that process nodes in the tree, which then call back to other visit methods to continue the descent. This is easier shown in code.
+
+Let's say, for instance, that you wanted to find every place in source where you have an arithmetic problem between two integers (this is pretty contrived, but it's just for illustration). You could define a visitor that only explicitly visits the `SyntaxTree::Binary` node, as in:
+
+```ruby
+class ArithmeticVisitor < SyntaxTree::Visitor
+  def visit_binary(node)
+    if node in { left: SyntaxTree::Int, operator: :+ | :- | :* | :/, right: SyntaxTree::Int }
+      puts "The result is: #{node.left.value.to_i.public_send(node.operator, node.right.value.to_i)}"
+    end
+  end
+end
+
+visitor = ArithmeticVisitor.new
+visitor.visit(SyntaxTree.parse("1 + 1"))
+# The result is: 2
+```
+
+With visitors, you only define handlers for the nodes that you need. You can find the names of the methods that you will need to define within the base visitor, as they're all aliased to the default behavior (visiting the child nodes). Note that when you define a handler for a node, you have to tell Syntax Tree how to walk further. In the example above, we don't need to go any further because we already know the child nodes are `SyntaxTree::Int`, so they can't possibly contain more `SyntaxTree::Binary` nodes. In other circumstances you may not know though, so you can either:
+
+* call `super` (which will do the default and visit all child nodes)
+* call `visit_child_nodes` manually
+* call `visit(child)` with each child that you want to visit
+* call nothing if you're sure you don't want to descend further
+
+There are a couple of visitors that ship with Syntax Tree that can be used as examples. They live in the [lib/syntax_tree/visitor](lib/syntax_tree/visitor) directory.
+
+### visit_method
+
+When you're creating a visitor, it's very easy to accidentally mistype a visit method. Unfortunately, there's no way to tell Ruby to explicitly override a parent method, so it would then be easy to define a method that never gets called. To mitigate this risk, there's `Visitor.visit_method(name)`. This method accepts a symbol that is checked against the list of known visit methods. If it's not in the list, then an error will be raised. It's meant to be used like:
+
+```ruby
+class ArithmeticVisitor < SyntaxTree::Visitor
+  visit_method def visit_binary(node)
+    # ...
+  end
+end
+```
+
+This will only be checked once when the file is first required. If there is a typo in your method name (or the method no longer exists for whatever reason), you will receive an error like so:
+
+```
+~/syntax_tree/lib/syntax_tree/visitor.rb:46:in `visit_method': Invalid visit method: visit_binar (SyntaxTree::Visitor::VisitMethodError)
+Did you mean?  visit_binary
+               visit_in
+               visit_ivar
+	from (irb):2:in `<class:ArithmeticVisitor>'
+	from (irb):1:in `<main>'
+	from bin/console:8:in `<main>'
+```
+
+## Language server
+
+Syntax Tree additionally ships with a language server conforming to the [language server protocol](https://microsoft.github.io/language-server-protocol/). It can be invoked through the CLI by running:
+
+```sh
+stree lsp
+```
+
+By default, the language server is relatively minimal, mostly meant to provide a registered formatter for the Ruby language. However there are a couple of additional niceties baked in. There are related projects that configure and use this language server within IDEs. For example, to use this code with VSCode, see [ruby-syntax-tree/vscode-syntax-tree](https://github.com/ruby-syntax-tree/vscode-syntax-tree).
+
+### textDocument/formatting
+
+As mentioned above, the language server responds to formatting requests with the formatted document. It typically responds on the order of tens of milliseconds, so it should be fast enough for any IDE.
+
+### textDocument/inlayHints
+
+The language server also responds to the relatively new inlay hints request. This request allows the language server to define additional information that should exist in the source code as helpful hints to the developer. In our case we use it to display things like implicit parentheses. For example, if you had the following code:
+
+```ruby
+1 + 2 * 3
+```
+
+Implicity, the `2 * 3` is going to be executed first because the `*` operator has higher precedence than the `+` operator. However, to ease mental overhead, our language server includes small parentheses to make this explicit, as in:
+
+```ruby
+1 + ₍2 * 3₎
+```
+
+### syntaxTree/visualizing
+
+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.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kddnewton/syntax_tree. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/kddnewton/syntax_tree/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby-syntax-tree/syntax_tree.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the syntax_tree project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kddnewton/syntax_tree/blob/main/CODE_OF_CONDUCT.md).

data/bin/bench

@@ -1,23 +1,23 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'benchmark/ips'
+require "bundler/setup"
+require "benchmark/ips"
 
-require_relative '../lib/syntax_tree'
-require 'ruby_parser'
-require 'parser/current'
+require_relative "../lib/syntax_tree"
+require "ruby_parser"
+require "parser/current"
 
 def compare(filepath)
-  prefix = "#{File.expand_path('..', __dir__)}/"
+  prefix = "#{File.expand_path("..", __dir__)}/"
   puts "=== #{filepath.delete_prefix(prefix)} ==="
 
   source = File.read(filepath)
 
   Benchmark.ips do |x|
-    x.report('syntax_tree') { SyntaxTree.new(source).parse }
-    x.report('parser') { Parser::CurrentRuby.parse(source) }
-    x.report('ruby_parser') { RubyParser.new.parse(source) }
+    x.report("syntax_tree") { SyntaxTree.parse(source) }
+    x.report("parser") { Parser::CurrentRuby.parse(source) }
+    x.report("ruby_parser") { RubyParser.new.parse(source) }
     x.compare!
   end  
 end
@@ -29,8 +29,8 @@ filepaths = ARGV
 # file).
 if filepaths.empty?
   filepaths = [
-    File.expand_path('bench', __dir__),
-    File.expand_path('../lib/syntax_tree.rb', __dir__)
+    File.expand_path("bench", __dir__),
+    File.expand_path("../lib/syntax_tree.rb", __dir__)
   ]
 end
 

data/bin/console

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'syntax_tree'
+require "bundler/setup"
+require "syntax_tree"
 
-require 'irb'
+require "irb"
 IRB.start(__FILE__)

data/bin/profile

@@ -1,10 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'stackprof'
+require "bundler/setup"
+require "stackprof"
 
-filepath = File.expand_path('../lib/syntax_tree', __dir__)
+filepath = File.expand_path("../lib/syntax_tree", __dir__)
 require_relative filepath
 
 GC.disable