Documentation for search

Author: kddnewton

README.md

@@ -15,6 +15,7 @@ It is built with only standard library dependencies. It additionally ships with
 - [CLI](#cli)
   - [ast](#ast)
   - [check](#check)
+  - [expr](#expr)
   - [format](#format)
   - [json](#json)
   - [match](#match)
@@ -26,6 +27,7 @@ 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.search(source, query, &block)](#syntaxtreesearchsource-query-block)
 - [Nodes](#nodes)
   - [child_nodes](#child_nodes)
   - [Pattern matching](#pattern-matching)
@@ -129,6 +131,24 @@ To change the print width that you are checking against, specify the `--print-wi
 stree check --print-width=100 path/to/file.rb
 ```
 
+### expr
+
+This command will output a Ruby case-match expression that would match correctly against the first expression of the input.
+
+```sh
+stree expr path/to/file.rb
+```
+
+For a file that contains `1 + 1`, you will receive:
+
+```ruby
+SyntaxTree::Binary[
+  left: SyntaxTree::Int[value: "1"],
+  operator: :+,
+  right: SyntaxTree::Int[value: "1"]
+]
+```
+
 ### format
 
 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.
@@ -312,6 +332,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.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.
+
 ## 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.

lib/syntax_tree.rb

@@ -75,4 +75,10 @@ def self.read(filepath)
 
     File.read(filepath, encoding: encoding)
   end
+
+  # Searches through the given source using the given pattern and yields each
+  # node in the tree that matches the pattern to the given block.
+  def self.search(source, query, &block)
+    Search.new(Pattern.new(query).compile).scan(parse(source), &block)
+  end
 end

lib/syntax_tree/pattern.rb

@@ -37,6 +37,8 @@ module SyntaxTree
   # do not yet support) then a SyntaxTree::Pattern::CompilationError will be
   # raised.
   class Pattern
+    # Raised when the query given to a pattern is either invalid Ruby syntax or
+    # is using syntax that we don't yet support.
     class CompilationError < StandardError
       def initialize(repr)
         super(<<~ERROR)
@@ -76,27 +78,27 @@ def compile
     def combine_and(left, right)
       ->(node) { left.call(node) && right.call(node) }
     end
-  
+
     def combine_or(left, right)
       ->(node) { left.call(node) || right.call(node) }
     end
 
-    def compile_node(node)
-      case node
+    def compile_node(root)
+      case root
       in AryPtn[constant:, requireds:, rest: nil, posts: []]
         compiled_constant = compile_node(constant) if constant
-  
+
         preprocessed = requireds.map { |required| compile_node(required) }
-  
+
         compiled_requireds = ->(node) do
           deconstructed = node.deconstruct
-  
+
           deconstructed.length == preprocessed.length &&
-            preprocessed.zip(deconstructed).all? do |(matcher, value)|
-              matcher.call(value)
-            end
+            preprocessed
+              .zip(deconstructed)
+              .all? { |(matcher, value)| matcher.call(value) }
         end
-  
+
         if compiled_constant
           combine_and(compiled_constant, compiled_requireds)
         else
@@ -106,63 +108,65 @@ def compile_node(node)
         combine_or(compile_node(left), compile_node(right))
       in Const[value:] if SyntaxTree.const_defined?(value)
         clazz = SyntaxTree.const_get(value)
-  
+
         ->(node) { node.is_a?(clazz) }
       in Const[value:] if Object.const_defined?(value)
         clazz = Object.const_get(value)
-  
+
         ->(node) { node.is_a?(clazz) }
-      in ConstPathRef[parent: VarRef[value: Const[value: "SyntaxTree"]], constant:]
+      in ConstPathRef[
+           parent: VarRef[value: Const[value: "SyntaxTree"]], constant:
+         ]
         compile_node(constant)
       in DynaSymbol[parts: []]
-        symbol = "".to_sym
+        symbol = :""
 
         ->(node) { node == symbol }
       in DynaSymbol[parts: [TStringContent[value:]]]
         symbol = value.to_sym
-  
+
         ->(attribute) { attribute == value }
       in HshPtn[constant:, keywords:, keyword_rest: nil]
         compiled_constant = compile_node(constant)
-  
+
         preprocessed =
           keywords.to_h do |keyword, value|
             raise NoMatchingPatternError unless keyword.is_a?(Label)
             [keyword.value.chomp(":").to_sym, compile_node(value)]
           end
-  
+
         compiled_keywords = ->(node) do
           deconstructed = node.deconstruct_keys(preprocessed.keys)
-  
+
           preprocessed.all? do |keyword, matcher|
             matcher.call(deconstructed[keyword])
           end
         end
-  
+
         if compiled_constant
           combine_and(compiled_constant, compiled_keywords)
         else
           compiled_keywords
         end
       in RegexpLiteral[parts: [TStringContent[value:]]]
         regexp = /#{value}/
-  
+
         ->(attribute) { regexp.match?(attribute) }
       in StringLiteral[parts: []]
         ->(attribute) { attribute == "" }
       in StringLiteral[parts: [TStringContent[value:]]]
         ->(attribute) { attribute == value }
       in SymbolLiteral[value:]
         symbol = value.value.to_sym
-  
+
         ->(attribute) { attribute == symbol }
       in VarRef[value: Const => value]
         compile_node(value)
       in VarRef[value: Kw[value: "nil"]]
         ->(attribute) { attribute.nil? }
       end
     rescue NoMatchingPatternError
-      raise CompilationError, PP.pp(node, +"").chomp
+      raise CompilationError, PP.pp(root, +"").chomp
     end
   end
 end