tree_stand 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dec13e65fde2c739a206944e34805122f065982b6a87bf5720baca17f0fb8a5
-  data.tar.gz: b00f3d2b463196d0336ec45ca38294d5f41bab931f546ce5224e1f695268448b
+  metadata.gz: 14e5005eed3acbb6399f68c0edf358ba15f4565eb4d99e20652158dbd1c2594e
+  data.tar.gz: 8fee6e5e40b9db6adcd72cf72e2705124b9a7e6fcc90ad4673600c1f5074cd69
 SHA512:
-  metadata.gz: e00d9f5b809a264bb19672dc0a0b28b58ea37944004fd2c63ca76042eed15f1c1b9f0d539f627d0565a16492522a51cd69e30574cc540c60d66c66fc1484bb3b
-  data.tar.gz: b28e29fd57802ef79b0a9e88ff2fdaa9f0e79e33ef49173c56f109cdaf2737438f6bb2c23aa5a75fc6af2b4b2c96831a973e921bbcbcfd2f11c2735b525b4085
+  metadata.gz: 1801ffc4ecfa3e7693009267a8a22225f53d04668ca5ddf4c59ba7e0bd2fc5c9e5b5ecfde771aa9631911bd19a0d0e198abcfd18cfe476d3c64ffb7df4480662
+  data.tar.gz: 1fec3247f8836c5bf8175530efe0cb51e692e922c431d2f7d81b4f7dd22d895849cfe1af57996c4dff4a18a29bfdecbd30d0bdba24a94dffc4540609f24c3830

data/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to TreeStand
+
+## Getting Started
+
+To work on this gem you'll need the tree-sitter CLI tool. See the [offical
+documentation](https://github.com/tree-sitter/tree-sitter/blob/master/cli/README.md#tree-sitter-cli) for installation
+instructions.
+
+Clone the repository and run the setup script.
+
+```
+git clone https://github.com/Shopify/tree_stand.git
+bin/setup
+```
+
+### Testing
+
+```
+bundle exec rake test
+```
+
+### Documentation
+
+To run the documentation server, execute the following command and open [localhost:8808](http://localhost:8808).
+
+```
+$ bundle exec yard server --reload
+```
+
+To get statistics about documentation coverage and which items are missing documentation run the following command.
+
+```
+$ bundle exec yard stats --list-undoc
+Files:          10
+Modules:         2 (    0 undocumented)
+Classes:        11 (    0 undocumented)
+Constants:       1 (    0 undocumented)
+Attributes:     14 (    0 undocumented)
+Methods:        34 (    0 undocumented)
+ 100.00% documented
+```
+
+## Pushing a new Version
+
+Create a new PR to bump the version number in `lib/tree_stand/version.rb`. See
+[github://Shopify/tree_stand#18](https://github.com/Shopify/tree_stand/pull/18) for an example.
+
+```ruby
+$ cat lib/tree_stand/version.rb
+module TreeStand
+  # The current version of the gem.
+  VERSION = "0.1.5"
+end
+```
+
+Once that PR is merged, tag the latest commit with the format `v#{TreeStand::VERSION}` and push the new tag.
+
+```
+git tag v0.1.5
+git push --tags
+```
+
+Draft a new Release [on Github](https://github.com/Shopify/tree_stand/releases).
+
+Finally, we use [shipit](https://github.com/Shopify/shipit-engine) to push gems to rubygems.

data/bin/console

@@ -3,12 +3,20 @@
 require "bundler/setup"
 require "tree_stand"
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
+TreeStand.configure do
+  config.parser_path = File.expand_path(
+    File.join(__dir__, "..", "parsers")
+  )
+end
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+ivars_to_add = <<~RUBY
+  @parser = TreeStand::Parser.new("math")
+  @tree = @parser.parse_string(nil, "1 + x")
+RUBY
 
-require "irb"
-IRB.start(__FILE__)
+eval(ivars_to_add)
+puts("available ivars:")
+puts(ivars_to_add)
+
+require "pry"
+Pry.start

data/bin/setup

@@ -6,15 +6,16 @@ set -vx
 bundle install
 
 # Do any other automated setup that you need to do here
-if [[ ! -d tmp/tree-sitter-sql ]]; then
+if [[ ! -d tmp/tree-sitter-math ]]; then
   mkdir -p tmp
-  git -C tmp/ clone --depth=1 https://github.com/DerekStride/tree-sitter-sql.git
+  git -C tmp/ clone --depth=1 https://github.com/DerekStride/tree-sitter-math.git
 fi
 
-cd tmp/tree-sitter-sql
+cd tmp/tree-sitter-math
 
 npm install
+mkdir -p target
 gcc -shared -o target/parser.so -fPIC src/parser.c -I./src
 
 cd ../..
-cp tmp/tree-sitter-sql/target/parser.so parsers/sql.so
+cp tmp/tree-sitter-math/target/parser.so parsers/math.so

data/lib/tree_stand/node.rb

@@ -7,13 +7,29 @@ module TreeStand
     extend Forwardable
     include Enumerable
 
-    def_delegators :@ts_node, :type, :start_byte, :end_byte, :start_point, :end_point
+    # @!method type
+    #   @return [Symbol] the type of the node in the tree-sitter grammar.
+    # @!method error?
+    #   @return [bool] true if the node is an error node.
+    def_delegators(
+      :@ts_node,
+      :type,
+      :error?,
+    )
 
     # @return [TreeStand::Tree]
     attr_reader :tree
     # @return [TreeSitter::Node]
     attr_reader :ts_node
 
+    # @!method to_a
+    #   @example
+    #     node.text # => "3 * 4"
+    #     node.to_a.map(&:text) # => ["3", "*", "4"]
+    #     node.children.map(&:text) # => ["3", "*", "4"]
+    #   @return [Array<TreeStand::Node>]
+    alias_method :children, :to_a
+
     # @api private
     def initialize(tree, ts_node)
       @tree = tree
@@ -24,8 +40,8 @@ module TreeStand
     # TreeSitter uses a `TreeSitter::Cursor` to iterate over matches by calling
     # `curser#next_match` repeatedly until it returns `nil`.
     #
-    # This method does all of that for you and collects all of the
-    # {TreeStand::Match matches} into an array.
+    # This method does all of that for you and collects all of the matches into
+    # an array and each corresponding capture into a hash.
     #
     # @example
     #   # This will return a match for each identifier nodes in the tree.
@@ -38,21 +54,50 @@ module TreeStand
     #     (identifier) @identifier
     #   QUERY
     #
-    # @see TreeStand::Match
-    # @see TreeStand::Capture
-    #
     # @param query_string [String]
-    # @return [Array<TreeStand::Match>]
+    # @return [Array<Hash<String, TreeStand::Node>>]
     def query(query_string)
       ts_query = TreeSitter::Query.new(@tree.parser.ts_language, query_string)
       ts_cursor = TreeSitter::QueryCursor.exec(ts_query, ts_node)
       matches = []
-      while match = ts_cursor.next_match
-        matches << TreeStand::Match.new(@tree, ts_query, match)
+      while ts_match = ts_cursor.next_match
+        captures = {}
+
+        ts_match.captures.each do |ts_capture|
+          capture_name = ts_query.capture_name_for_id(ts_capture.index)
+          captures[capture_name] = TreeStand::Node.new(@tree, ts_capture.node)
+        end
+
+        matches << captures
       end
       matches
     end
 
+    # Returns the first captured node that matches the query string or nil if
+    # there was no captured node.
+    #
+    # @example Find the first identifier node.
+    #   identifier_node = tree.root_node.find_node("(identifier) @identifier")
+    #
+    # @see #find_node!
+    # @see #query
+    # @param query_string [String]
+    # @return [TreeStand::Node, nil]
+    def find_node(query_string)
+      query(query_string).first&.values&.first
+    end
+
+    # Like {#find_node}, except that if no node is found, raises an
+    # {TreeStand::NodeNotFound} error.
+    #
+    # @see #find_node
+    # @param query_string [String]
+    # @return [TreeStand::Node]
+    # @raise [TreeStand::NodeNotFound]
+    def find_node!(query_string)
+      find_node(query_string) || raise(TreeStand::NodeNotFound)
+    end
+
     # @return [TreeStand::Range]
     def range
       TreeStand::Range.new(
@@ -64,33 +109,74 @@ module TreeStand
     end
 
     # Node includes enumerable so that you can iterate over the child nodes.
+    # @example
+    #   node.text # => "3 * 4"
+    #
+    # @example Iterate over the child nodes
+    #   node.each do |child|
+    #     print child.text
+    #   end
+    #   # prints: 3*4
+    #
+    # @example Enumerable methods
+    #   node.map(&:text) # => ["3", "*", "4"]
+    #
     # @yieldparam child [TreeStand::Node]
     # @return [Enumerator]
-    def each
-      @ts_node.each do |child|
-        yield TreeStand::Node.new(@tree, child)
-      end
+    def each(&block)
+      Enumerator.new do |yielder|
+        @ts_node.each do |child|
+          yielder << TreeStand::Node.new(@tree, child)
+        end
+      end.each(&block)
+    end
+
+    # (see TreeStand::Visitors::TreeWalker)
+    # Backed by {TreeStand::Visitors::TreeWalker}.
+    #
+    # @example Check the subtree for error nodes
+    #   node.walk.any? { |node| node.type == :error }
+    #
+    # @yieldparam node [TreeStand::Node]
+    # @return [Enumerator]
+    #
+    # @see TreeStand::Visitors::TreeWalker
+    def walk(&block)
+      Enumerator.new do |yielder|
+        Visitors::TreeWalker.new(self) do |child|
+          yielder << child
+        end.visit
+      end.each(&block)
     end
 
+    # @example
+    #   node.text # => "4"
+    #   node.parent.text # => "3 * 4"
+    #   node.parent.parent.text # => "1 + 3 * 4"
     # @return [TreeStand::Node]
     def parent
       TreeStand::Node.new(@tree, @ts_node.parent)
     end
 
-    # A convience method for getting the text of the node. Each TreeStand Node
-    # wraps the parent tree and has access to the source document.
+    # A convience method for getting the text of the node. Each {TreeStand::Node}
+    # wraps the parent {#tree} and has access to the source document.
     # @return [String]
     def text
       @tree.document[@ts_node.start_byte...@ts_node.end_byte]
     end
 
     # This class overrides the `method_missing` method to delegate to the
-    # node's named children. This allows you to write code like this:
-    #   root = tree.root_node
-    #   child = root.expression
+    # node's named children.
+    # @example
+    #   node.text          # => "3 * 4"
+    #
+    #   node.left.text     # => "3"
+    #   node.operator.text # => "*"
+    #   node.right.text    # => "4"
+    #   node.operand       # => NoMethodError
     # @overload method_missing(field_name)
     #   @param name [Symbol, String]
-    #   @return [TreeStand::Node] Child node for the given field name
+    #   @return [TreeStand::Node] child node for the given field name
     #   @raise [NoMethodError] Raised if the node does not have child with name `field_name`
     #
     # @overload method_missing(method_name, *args, &block)
@@ -109,5 +195,16 @@ module TreeStand
         type == other.type &&
         text == other.text
     end
+
+    # (see TreeStand::Utils::Printer)
+    # Backed by {TreeStand::Utils::Printer}.
+    #
+    # @param pp [PP]
+    # @return [void]
+    #
+    # @see TreeStand::Utils::Printer
+    def pretty_print(pp)
+      Utils::Printer.new(ralign: 80).print(self, io: pp.output)
+    end
   end
 end

data/lib/tree_stand/parser.rb

@@ -38,5 +38,21 @@ module TreeStand
       ts_tree = @ts_parser.parse_string(nil, document)
       TreeStand::Tree.new(self, ts_tree, document)
     end
+
+    # (see #parse_string)
+    # @note Like {#parse_string}, except that if the tree contains any parse
+    #   errors, raises an {TreeStand::InvalidDocument} error.
+    #
+    # @see #parse_string
+    # @raise [TreeStand::InvalidDocument]
+    def parse_string!(tree, document)
+      tree = parse_string(tree, document)
+      return tree unless tree.any?(&:error?)
+
+      raise(InvalidDocument, <<~ERROR)
+        Encountered errors in the document. Check the tree for more details.
+          #{tree}
+      ERROR
+    end
   end
 end

data/lib/tree_stand/tree.rb

@@ -22,6 +22,9 @@ module TreeStand
   # This is not always possible and depends on the edits you make, beware that
   # the tree will be different after each edit and this approach may cause bugs.
   class Tree
+    extend Forwardable
+    include Enumerable
+
     # @return [String]
     attr_reader :document
     # @return [TreeSitter::Tree]
@@ -29,6 +32,42 @@ module TreeStand
     # @return [TreeStand::Parser]
     attr_reader :parser
 
+    # @!method query(query_string)
+    #   @note This is a convenience method that calls {TreeStand::Node#query} on
+    #     {#root_node}.
+    #
+    # @!method find_node(query_string)
+    #   @note This is a convenience method that calls {TreeStand::Node#find_node} on
+    #     {#root_node}.
+    #
+    # @!method find_node!(query_string)
+    #   @note This is a convenience method that calls {TreeStand::Node#find_node!} on
+    #     {#root_node}.
+    #
+    # @!method walk(&block)
+    #   (see TreeStand::Node#walk)
+    #
+    #   @note This is a convenience method that calls {TreeStand::Node#walk} on
+    #     {#root_node}.
+    #
+    #   @example Tree includes Enumerable
+    #     tree.any? { |node| node.type == :error }
+    #
+    # @!method text
+    #   (see TreeStand::Node#text)
+    #   @note This is a convenience method that calls {TreeStand::Node#text} on
+    #     {#root_node}.
+    def_delegators(
+      :root_node,
+      :query,
+      :find_node,
+      :find_node!,
+      :walk,
+      :text,
+    )
+
+    alias_method :each, :walk
+
     # @api private
     def initialize(parser, tree, document)
       @parser = parser
@@ -41,14 +80,6 @@ module TreeStand
       TreeStand::Node.new(self, @ts_tree.root_node)
     end
 
-    # (see TreeStand::Node#query)
-    # @note This is a convenience method that calls {TreeStand::Node#query} on
-    #   {#root_node}.
-    # @see TreeStand::Node#query
-    def query(query_string)
-      root_node.query(query_string)
-    end
-
     # This method replaces the section of the document specified by range and
     # replaces it with the provided text. Then it will reparse the document and
     # update the tree!
@@ -63,7 +94,7 @@ module TreeStand
       replace_with_new_doc(new_document)
     end
 
-    # This method deletes the section of the document specified by range Then
+    # This method deletes the section of the document specified by range. Then
     # it will reparse the document and update the tree!
     # @param range [TreeStand::Range]
     # @return [void]

data/lib/tree_stand/utils/printer.rb

@@ -0,0 +1,70 @@
+module TreeStand
+  # A collection of useful methods for working with syntax trees.
+  module Utils
+    # Used to {TreeStand::Node#pretty_print pretty-print} the node.
+    #
+    # @example
+    #   pp node
+    #   # (expression
+    #   #  (sum
+    #   #   left: (number)              | 1
+    #   #   ("+")                       | +
+    #   #   right: (variable)))         | x
+    class Printer
+      # @param ralign [Integer] the right alignment for the text column.
+      def initialize(ralign:)
+        @ralign = ralign
+      end
+
+      # (see TreeStand::Utils::Printer)
+      #
+      # @param node [TreeStand::Node]
+      # @param io [IO]
+      # @return [IO]
+      def print(node, io: StringIO.new)
+        lines = pretty_output_lines(node)
+
+        lines.each do |line|
+          if line.text.empty?
+            io.puts line.sexpr
+            next
+          end
+
+          io.puts "#{line.sexpr}#{" " * (@ralign - line.sexpr.size)}| #{line.text}"
+        end
+
+        io
+      end
+
+      private
+
+      Line = Struct.new(:sexpr, :text)
+      private_constant :Line
+
+      def pretty_output_lines(node, prefix: "", depth: 0)
+        indent = " " * depth
+        ts_node = node.ts_node
+        if indent.size + prefix.size + ts_node.to_s.size < @ralign || ts_node.child_count == 0
+          return [Line.new("#{indent}#{prefix}#{ts_node}", node.text)]
+        end
+
+        lines = [Line.new("#{indent}#{prefix}(#{ts_node.type}", "")]
+
+        node.each.with_index do |child, index|
+          lines += if field_name = ts_node.field_name_for_child(index)
+            pretty_output_lines(
+              child,
+              prefix: "#{field_name}: ",
+              depth: depth + 1,
+            )
+          else
+            pretty_output_lines(child, depth: depth + 1)
+          end
+        end
+
+        lines.last.sexpr << ")"
+        lines
+      end
+    end
+  end
+end

data/lib/tree_stand/version.rb

@@ -1,4 +1,4 @@
 module TreeStand
   # The current version of the gem.
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/lib/tree_stand/visitor.rb

@@ -47,7 +47,7 @@ module TreeStand
     def visit_node(node)
       if respond_to?("on_#{node.type}")
         public_send("on_#{node.type}", node)
-      elsif respond_to?(:_on_default)
+      elsif respond_to?(:_on_default, true)
         _on_default(node)
       end
 

data/lib/tree_stand/visitors/tree_walker.rb

@@ -0,0 +1,30 @@
+module TreeStand
+  # A collection of useful visitors for traversing trees.
+  module Visitors
+    # Walks the tree depth-first and yields each node to the provided block.
+    #
+    # @example Create a list of all the nodes in the tree.
+    #   list = []
+    #   TreeStand::Visitors::TreeWalker.new(root) do |node|
+    #     list << node
+    #   end.visit
+    #
+    # @see TreeStand::Node#walk
+    # @see TreeStand::Tree#walk
+    class TreeWalker < Visitor
+      # @param node [TreeStand::Node]
+      # @param block [Proc] A block that will be called for
+      #   each node in the tree.
+      def initialize(node, &block)
+        super(node)
+        @block = block
+      end
+
+      private
+
+      def _on_default(node)
+        @block.call(node)
+      end
+    end
+  end
+end

data/lib/tree_stand.rb

@@ -9,6 +9,11 @@ loader.setup
 module TreeStand
   # Common Ancestor for all TreeStand errors.
   class Error < StandardError; end
+  # Raised when the parsed document contains errors.
+  class InvalidDocument < Error; end
+  # Raised when performing a search on a tree where a return value is expected,
+  # but no match is found.
+  class NodeNotFound < Error; end
 
   class << self
     # Easy configuration of the gem.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tree_stand
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - derekstride
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-12-15 00:00:00.000000000 Z
+date: 2023-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -137,6 +137,7 @@ files:
 - ".shopify-build/VERSION"
 - ".shopify-build/tree-stand-publish-package.yml"
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -146,15 +147,15 @@ files:
 - deploy/install-treesitter
 - lib/tree_stand.rb
 - lib/tree_stand/ast_modifier.rb
-- lib/tree_stand/capture.rb
 - lib/tree_stand/config.rb
-- lib/tree_stand/match.rb
 - lib/tree_stand/node.rb
 - lib/tree_stand/parser.rb
 - lib/tree_stand/range.rb
 - lib/tree_stand/tree.rb
+- lib/tree_stand/utils/printer.rb
 - lib/tree_stand/version.rb
 - lib/tree_stand/visitor.rb
+- lib/tree_stand/visitors/tree_walker.rb
 - parsers/.gitkeep
 - service.yml
 - shipit.production.yml

data/lib/tree_stand/capture.rb

@@ -1,46 +0,0 @@
-module TreeStand
-  # Wrapper around a TreeSitter capture.
-  # @see TreeStand::Tree#query
-  # @see TreeStand::Node#query
-  # @see TreeStand::Match
-  class Capture
-    # @return [TreeStand::Match]
-    attr_reader :match
-    # @return [TreeSitter::Capture]
-    attr_reader :ts_capture
-
-    # @api private
-    def initialize(match, ts_capture)
-      @match = match
-      @ts_capture = ts_capture
-    end
-
-    # The name of the capture. TreeSitter strips the `@` from the capture name.
-    # @example
-    #   match = @tree.query(<<~QUERY).first
-    #     (identifier) @identifier.name
-    #   QUERY
-    #
-    #   capture = match.captures.first
-    #
-    #   assert_equal("identifier.name", capture.name)
-    # @return [String]
-    def name
-      @match.ts_query.capture_name_for_id(@ts_capture.index)
-    end
-
-    # @return [TreeStand::Node]
-    def node
-      TreeStand::Node.new(@match.tree, @ts_capture.node)
-    end
-
-    # @param other [Object]
-    # @return [bool]
-    def ==(other)
-      return false unless other.is_a?(TreeStand::Capture)
-
-      name == other.name &&
-        node == other.node
-    end
-  end
-end

data/lib/tree_stand/match.rb

@@ -1,58 +0,0 @@
-module TreeStand
-  # Wrapper around a TreeSitter match.
-  # @see TreeStand::Tree#query
-  # @see TreeStand::Node#query
-  # @see TreeStand::Capture
-  class Match
-    # @return [TreeStand::Tree]
-    attr_reader :tree
-    # @return [TreeSitter::Query]
-    attr_reader :ts_query
-    # @return [TreeSitter::Match]
-    attr_reader :ts_match
-    # @return [Array<TreeStand::Capture>]
-    attr_reader :captures
-
-    # @api private
-    def initialize(tree, ts_query, ts_match)
-      @tree = tree
-      @ts_query = ts_query
-      @ts_match = ts_match
-
-      # It's important to load all of the captures when a Match is
-      # instantiated, otherwise the ts_match will be invalid after
-      # TreeSitter::Cursor#next_match is called.
-      #
-      # See: https://github.com/Faveod/ruby-tree-sitter/pull/16
-      @captures = @ts_match.captures.map do |capture|
-        TreeStand::Capture.new(self, capture)
-      end
-    end
-
-    # Looks up a capture by name. TreeSitter strips the `@` from the capture name.
-    # @example
-    #   match = @tree.query(<<~QUERY).first
-    #     (identifier) @identifier.name
-    #   QUERY
-    #
-    #   refute_nil(match["identifier.name"])
-    # @param capture_name [String] The name of the capture from the query.
-    # @return [TreeStand::Capture, nil]
-    def [](capture_name)
-      captures.find { |capture| capture.name == capture_name }
-    end
-
-    # @param other [Object]
-    # @return [bool]
-    def ==(other)
-      return false unless other.is_a?(TreeStand::Match)
-
-      captures == other.captures
-    end
-
-    # @return [TreeStand::Capture, nil]
-    def dig(name, *)
-      self[name]
-    end
-  end
-end