Merge pull request #189 from ruby-syntax-tree/mutate

Mutations

Author: kddnewton

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+### Added
+
+- Every node now implements the `#copy(**)` method, which provides a copy of the node with the given attributes replaced.
+- Every node now implements the `#===(other)` method, which checks if the given node matches the current node for all attributes except for comments and location.
+- There is a new `SyntaxTree::Visitor::MutationVisitor` and its convenience method `SyntaxTree.mutation` which can be used to mutate a syntax tree. For details on how to use this visitor, check the README.
+
 ### Changed
 
 - Nodes no longer have a `comments:` keyword on their initializers. By default, they initialize to an empty array. If you were previously passing comments into the initializer, you should now create the node first, then call `node.comments.concat` to add your comments.

README.md

@@ -27,17 +27,21 @@ It is built with only standard library dependencies. It additionally ships with
   - [SyntaxTree.read(filepath)](#syntaxtreereadfilepath)
   - [SyntaxTree.parse(source)](#syntaxtreeparsesource)
   - [SyntaxTree.format(source)](#syntaxtreeformatsource)
+  - [SyntaxTree.mutation(&block)](#syntaxtreemutationblock)
   - [SyntaxTree.search(source, query, &block)](#syntaxtreesearchsource-query-block)
 - [Nodes](#nodes)
   - [child_nodes](#child_nodes)
+  - [copy(**)](#copy)
   - [Pattern matching](#pattern-matching)
   - [pretty_print(q)](#pretty_printq)
   - [to_json(*opts)](#to_jsonopts)
   - [format(q)](#formatq)
+  - [===(other)](#other)
   - [construct_keys](#construct_keys)
 - [Visitor](#visitor)
   - [visit_method](#visit_method)
   - [BasicVisitor](#basicvisitor)
+  - [MutationVisitor](#mutationvisitor)
 - [Language server](#language-server)
   - [textDocument/formatting](#textdocumentformatting)
   - [textDocument/inlayHint](#textdocumentinlayhint)
@@ -332,6 +336,10 @@ This function takes an input string containing Ruby code and returns the syntax
 
 This function takes an input string containing Ruby code, parses it into its underlying syntax tree, and formats it back out to a string. You can optionally pass a second argument to this method as well that is the maximum width to print. It defaults to `80`.
 
+### SyntaxTree.mutation(&block)
+
+This function yields a new mutation visitor to the block, and then returns the initialized visitor. It's effectively a shortcut for creating a `SyntaxTree::Visitor::MutationVisitor` without having to remember the class name. For more information on that visitor, see the definition below.
+
 ### SyntaxTree.search(source, query, &block)
 
 This function takes an input string containing Ruby code, an input string containing a valid Ruby `in` clause expression that can be used to match against nodes in the tree (can be generated using `stree expr`, `stree match`, or `Node#construct_keys`), and a block. Each node that matches the given query will be yielded to the block. The block will receive the node as its only argument.
@@ -350,6 +358,20 @@ program.child_nodes.first.child_nodes.first
 # => (binary (int "1") :+ (int "1"))
 ```
 
+### copy
+
+This method returns a copy of the node, with the given attributes replaced.
+
+```ruby
+program = SyntaxTree.parse("1 + 1")
+
+binary = program.statements.body.first
+# => (binary (int "1") + (int "1"))
+
+binary.copy(operator: :-)
+# => (binary (int "1") - (int "1"))
+```
+
 ### Pattern matching
 
 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:
@@ -407,6 +429,18 @@ formatter.output.join
 # => "1 + 1"
 ```
 
+### ===(other)
+
+Every node responds to `===`, which is used to check if the given other node matches all of the attributes of the current node except for location and comments. For example:
+
+```ruby
+program1 = SyntaxTree.parse("1 + 1")
+program2 = SyntaxTree.parse("1 + 1")
+
+program1 === program2
+# => true
+```
+
 ### construct_keys
 
 Every node responds to `construct_keys`, which will return a string that contains a Ruby pattern-matching expression that could be used to match against the current node. It's meant to be used in tooling and through the CLI mostly.
@@ -495,6 +529,42 @@ end
 
 The visitor defined above will error out unless it's only visiting a `SyntaxTree::Int` node. This is useful in a couple of ways, e.g., if you're trying to define a visitor to handle the whole tree but it's currently a work-in-progress.
 
+### MutationVisitor
+
+The `MutationVisitor` is a visitor that can be used to mutate the tree. It works by defining a default `visit_*` method that returns a copy of the given node with all of its attributes visited. This new node will replace the old node in the tree. Typically, you use the `#mutate` method on it to define mutations using patterns. For example:
+
+```ruby
+# Create a new visitor
+visitor = SyntaxTree::Visitor::MutationVisitor.new
+
+# Specify that it should mutate If nodes with assignments in their predicates
+visitor.mutate("If[predicate: Assign | OpAssign]") do |node|
+  # Get the existing If's predicate node
+  predicate = node.predicate
+
+  # Create a new predicate node that wraps the existing predicate node
+  # in parentheses
+  predicate =
+    SyntaxTree::Paren.new(
+      lparen: SyntaxTree::LParen.default,
+      contents: predicate,
+      location: predicate.location
+    )
+
+  # Return a copy of this node with the new predicate
+  node.copy(predicate: predicate)
+end
+
+source = "if a = 1; end"
+program = SyntaxTree.parse(source)
+
+SyntaxTree::Formatter.format(source, program)
+# => "if a = 1\nend\n"
+
+SyntaxTree::Formatter.format(source, program.accept(visitor))
+# => "if (a = 1)\nend\n"
+```
+
 ### WithEnvironment
 
 The `WithEnvironment` module can be included in visitors to automatically keep track of local variables and arguments

lib/syntax_tree.rb

@@ -16,6 +16,7 @@
 require_relative "syntax_tree/visitor/field_visitor"
 require_relative "syntax_tree/visitor/json_visitor"
 require_relative "syntax_tree/visitor/match_visitor"
+require_relative "syntax_tree/visitor/mutation_visitor"
 require_relative "syntax_tree/visitor/pretty_print_visitor"
 require_relative "syntax_tree/visitor/environment"
 require_relative "syntax_tree/visitor/with_environment"
@@ -61,6 +62,13 @@ def self.format(source, maxwidth = DEFAULT_PRINT_WIDTH)
     formatter.output.join
   end
 
+  # A convenience method for creating a new mutation visitor.
+  def self.mutation
+    visitor = Visitor::MutationVisitor.new
+    yield visitor
+    visitor
+  end
+
   # Returns the source from the given filepath taking into account any potential
   # magic encoding comments.
   def self.read(filepath)