ruby_tree_sitter 0.20.8.3-x86_64-linux → 1.0.0-x86_64-linux

data/lib/tree_stand/node.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around a TreeSitter node and provides convient
+  # methods that are missing on the original node. This class
+  # overrides the `method_missing` method to delegate to a nodes
+  # named children.
+  class Node
+    extend T::Sig
+    extend Forwardable
+    include Enumerable
+
+    # @!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?,
+    )
+
+    sig { returns(TreeStand::Tree) }
+    attr_reader :tree
+
+    sig { returns(TreeSitter::Node) }
+    attr_reader :ts_node
+
+    # @api private
+    sig { params(tree: TreeStand::Tree, ts_node: TreeSitter::Node).void }
+    def initialize(tree, ts_node)
+      @tree = tree
+      @ts_node = ts_node
+      @fields = @ts_node.each_field.to_a.map(&:first)
+    end
+
+    # 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 matches into
+    # an array and each corresponding capture into a hash.
+    #
+    # @example
+    #   # This will return a match for each identifier nodes in the tree.
+    #   tree_matches = tree.query(<<~QUERY)
+    #     (identifier) @identifier
+    #   QUERY
+    #
+    #   # It is equivalent to:
+    #   tree.root_node.query(<<~QUERY)
+    #     (identifier) @identifier
+    #   QUERY
+    sig { params(query_string: String).returns(T::Array[T::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 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
+    sig { params(query_string: String).returns(T.nilable(TreeStand::Node)) }
+    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
+    # @raise [TreeStand::NodeNotFound]
+    sig { params(query_string: String).returns(TreeStand::Node) }
+    def find_node!(query_string)
+      find_node(query_string) || raise(TreeStand::NodeNotFound)
+    end
+
+    sig { returns(TreeStand::Range) }
+    def range
+      TreeStand::Range.new(
+        start_byte: @ts_node.start_byte,
+        end_byte: @ts_node.end_byte,
+        start_point: @ts_node.start_point,
+        end_point: @ts_node.end_point,
+      )
+    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]
+    sig do
+      override
+        .params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
+    def each(&block)
+      enumerator = Enumerator.new do |yielder|
+        @ts_node.each do |child|
+          yielder << TreeStand::Node.new(@tree, child)
+        end
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # (see TreeStand::Visitors::TreeWalker)
+    # Backed by {TreeStand::Visitors::TreeWalker}.
+    #
+    # @example Check the subtree for error nodes
+    #   node.walk.any? { |node| node.type == :error }
+    #
+    # @see TreeStand::Visitors::TreeWalker
+    #
+    # @yieldparam node [TreeStand::Node]
+    sig do
+      params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
+    def walk(&block)
+      enumerator = Enumerator.new do |yielder|
+        Visitors::TreeWalker.new(self) do |child|
+          yielder << child
+        end.visit
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # @example
+    #   node.text # => "4"
+    #   node.parent.text # => "3 * 4"
+    #   node.parent.parent.text # => "1 + 3 * 4"
+    sig { returns(TreeStand::Node) }
+    def parent
+      TreeStand::Node.new(@tree, @ts_node.parent)
+    end
+
+    # @example
+    #   node.text # => "3 * 4"
+    #   node.to_a.map(&:text) # => ["3", "*", "4"]
+    #   node.children.map(&:text) # => ["3", "*", "4"]
+    sig { returns(T::Array[TreeStand::Node]) }
+    def children = to_a
+
+    # A convenience method for getting the text of the node. Each {TreeStand::Node}
+    # wraps the parent {TreeStand::Tree #tree} and has access to the source document.
+    sig { returns(String) }
+    def text
+      T.must(@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.
+    # @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
+    #   @raise [NoMethodError] Raised if the node does not have child with name `field_name`
+    #
+    # @overload method_missing(method_name, *args, &block)
+    #   @raise [NoMethodError]
+    def method_missing(method, *args, &block)
+      return super unless @fields.include?(method.to_s)
+
+      TreeStand::Node.new(@tree, T.unsafe(@ts_node).public_send(method, *args, &block))
+    end
+
+    sig { params(other: Object).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Node)
+
+      T.must(range == other.range && type == other.type && text == other.text)
+    end
+
+    # (see TreeStand::Utils::Printer)
+    # Backed by {TreeStand::Utils::Printer}.
+    #
+    # @see TreeStand::Utils::Printer
+    sig { params(pp: PP).void }
+    def pretty_print(pp)
+      Utils::Printer.new(ralign: 80).print(self, io: pp.output)
+    end
+
+    private
+
+    def respond_to_missing?(method, *)
+      @fields.include?(method.to_s) || super
+    end
+  end
+end

data/lib/tree_stand/parser.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around the TreeSitter parser. It looks up the parser by filename in
+  # the configured parsers directory.
+  # @example
+  #   TreeStand.configure do
+  #     config.parser_path = "path/to/parser/folder/"
+  #   end
+  #
+  #   # Looks for a parser in `path/to/parser/folder/sql.{so,dylib}`
+  #   sql_parser = TreeStand::Parser.new("sql")
+  #
+  #   # Looks for a parser in `path/to/parser/folder/ruby.{so,dylib}`
+  #   ruby_parser = TreeStand::Parser.new("ruby")
+  class Parser
+    extend T::Sig
+
+    sig { returns(TreeSitter::Language) }
+    attr_reader :ts_language
+
+    sig { returns(TreeSitter::Parser) }
+    attr_reader :ts_parser
+
+    # @param language [String]
+    sig { params(language: String).void }
+    def initialize(language)
+      @language_string = language
+      @ts_language = TreeSitter::Language.load(
+        language,
+        "#{TreeStand.config.parser_path}/#{language}.so",
+      )
+      @ts_parser = TreeSitter::Parser.new.tap do |parser|
+        parser.language = @ts_language
+      end
+    end
+
+    # Parse the provided document with the TreeSitter parser.
+    # @param tree [TreeStand::Tree, nil] providing the old tree will allow the
+    #   parser to take advantage of incremental parsing and improve performance
+    #   by re-useing nodes from the old tree.
+    sig { params(document: String, tree: T.nilable(TreeStand::Tree)).returns(TreeStand::Tree) }
+    def parse_string(document, tree: nil)
+      # @todo There's a bug with passing a non-nil tree
+      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]
+    sig { params(document: String, tree: T.nilable(TreeStand::Tree)).returns(TreeStand::Tree) }
+    def parse_string!(document, tree: nil)
+      tree = parse_string(document, tree: tree)
+      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/range.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around a TreeSitter range. This is mainly used to compare ranges.
+  class Range
+    extend T::Sig
+
+    # Point is a Struct containing the row and column from a TreeSitter point.
+    # TreeStand uses this to compare points.
+    # @!attribute [rw] row
+    #   @return [Integer]
+    # @!attribute [rw] column
+    #   @return [Integer]
+    Point = Struct.new(:row, :column)
+
+    sig { returns(Integer) }
+    attr_reader :start_byte
+
+    sig { returns(Integer) }
+    attr_reader :end_byte
+
+    sig { returns(TreeStand::Range::Point) }
+    attr_reader :start_point
+
+    sig { returns(TreeStand::Range::Point) }
+    attr_reader :end_point
+
+    # @api private
+    sig do
+      params(
+        start_byte: Integer,
+        end_byte: Integer,
+        start_point: T.any(TreeStand::Range::Point, TreeSitter::Point),
+        end_point: T.any(TreeStand::Range::Point, TreeSitter::Point),
+      ).void
+    end
+    def initialize(start_byte:, end_byte:, start_point:, end_point:)
+      @start_byte = start_byte
+      @end_byte = end_byte
+      @start_point = Point.new(start_point.row, start_point.column)
+      @end_point = Point.new(end_point.row, end_point.column)
+    end
+
+    sig { params(other: Object).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Range)
+
+      @start_byte == other.start_byte &&
+        @end_byte == other.end_byte &&
+        @start_point == other.start_point &&
+        @end_point == other.end_point
+    end
+  end
+end

data/lib/tree_stand/tree.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around a TreeSitter tree.
+  #
+  # This class exposes a convient API for working with the tree. There are
+  # dangers in using this class. The tree is mutable and the document can be
+  # changed. This class does not protect against that.
+  #
+  # Some of the moetods on this class edit and re-parse the document updating
+  # the tree. Because the document is re-parsed, the tree will be different. Which
+  # means all outstanding nodes & ranges will be invalid.
+  #
+  # Methods that edit the document are suffixed with `!`, e.g. `#edit!`.
+  #
+  # It's often the case that you will want perfrom multiple edits. One such
+  # pattern is to call #query & #edit on all matches in a loop. It's important
+  # to keep the destructive nature of #edit in mind and re-issue the query
+  # after each edit.
+  #
+  # Another thing to keep in mind is that edits done later in the document will
+  # likely not affect the ranges that occur earlier in the document. This can
+  # be a convient property that could allow you to apply edits in a reverse order.
+  # 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 T::Sig
+    extend Forwardable
+    include Enumerable
+
+    sig { returns(String) }
+    attr_reader :document
+
+    sig { returns(TreeSitter::Tree) }
+    attr_reader :ts_tree
+
+    sig { returns(TreeStand::Parser) }
+    attr_reader :parser
+
+    # @!method query(query_string)
+    #   (see TreeStand::Node#query)
+    #   @note This is a convenience method that calls {TreeStand::Node#query} on
+    #     {#root_node}.
+    #
+    # @!method find_node(query_string)
+    #   (see TreeStand::Node#find_node)
+    #   @note This is a convenience method that calls {TreeStand::Node#find_node} on
+    #     {#root_node}.
+    #
+    # @!method find_node!(query_string)
+    #   (see TreeStand::Node#find_node!)
+    #   @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
+    sig { params(parser: TreeStand::Parser, tree: TreeSitter::Tree, document: String).void }
+    def initialize(parser, tree, document)
+      @parser = parser
+      @ts_tree = tree
+      @document = document
+    end
+
+    sig { returns(TreeStand::Node) }
+    def root_node
+      TreeStand::Node.new(self, @ts_tree.root_node)
+    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!
+    sig { params(range: TreeStand::Range, replacement: String).void }
+    def edit!(range, replacement)
+      new_document = +''
+      new_document << @document[0...range.start_byte]
+      new_document << replacement
+      new_document << @document[range.end_byte..]
+      replace_with_new_doc(new_document)
+    end
+
+    # This method deletes the section of the document specified by range. Then
+    # it will reparse the document and update the tree!
+    sig { params(range: TreeStand::Range).void }
+    def delete!(range)
+      new_document = +''
+      new_document << @document[0...range.start_byte]
+      new_document << @document[range.end_byte..]
+      replace_with_new_doc(new_document)
+    end
+
+    private
+
+    def replace_with_new_doc(new_document)
+      @document = new_document
+      new_tree = @parser.parse_string(@document, tree: self)
+      @ts_tree = new_tree.ts_tree
+    end
+  end
+end

data/lib/tree_stand/utils/printer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# typed: true
+
+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
+      extend T::Sig
+
+      # @param ralign the right alignment for the text column.
+      sig { params(ralign: Integer).void }
+      def initialize(ralign:)
+        @ralign = ralign
+      end
+
+      # (see TreeStand::Utils::Printer)
+      sig { params(node: TreeStand::Node, io: T.any(IO, StringIO, String)).returns(T.any(IO, StringIO, String)) }
+      def print(node, io: StringIO.new)
+        lines = pretty_output_lines(node)
+
+        lines.each do |line|
+          if line.text.empty?
+            io << line.sexpr << "\n"
+            next
+          end
+
+          io << "#{line.sexpr}#{' ' * (@ralign - line.sexpr.size)}| #{line.text}\n"
+        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.zero?
+          return [Line.new("#{indent}#{prefix}#{ts_node}", node.text)]
+        end
+
+        lines = T.let([Line.new("#{indent}#{prefix}(#{ts_node.type}", '')], T::Array[Line])
+
+        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
+
+        T.must(lines.last).sexpr << ')'
+        lines
+      end
+    end
+  end
+end

data/lib/tree_stand/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# typed: strong
+
+module TreeStand
+  # The current version of the gem.
+  VERSION = '0.2.0'
+end

data/lib/tree_stand/visitor.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Depth-first traversal through the tree, calling hooks at each stop.
+  #
+  # Hooks are language dependent and are defined by creating methods on the
+  # visitor with the form `on_*` or `around_*`, where `*` is {Node#type}.
+  #
+  # - Hooks prefixed with `on_*` are called *before* visiting a node.
+  # - Hooks prefixed with `around_*` must `yield` to continue visiting child
+  #   nodes.
+  #
+  # You can also define default hooks by implementing an {on} or {around}
+  # method to call when visiting each node.
+  #
+  # @example Create a visitor counting certain nodes
+  #   class CountingVisitor < TreeStand::Visitor
+  #     attr_reader :count
+  #
+  #     def initialize(root, type:)
+  #       super(root)
+  #       @type = type
+  #       @count = 0
+  #     end
+  #
+  #     def on_predicate(node)
+  #       # if this node matches our search, increment the counter
+  #       @count += 1 if node.type == @type
+  #     end
+  #   end
+  #
+  #   # Initialize a visitor
+  #   visitor = CountingVisitor.new(document, :predicate).visit
+  #   # Check the result
+  #   visitor.count
+  #   # => 3
+  #
+  # @example A visitor using around hooks to contruct a tree
+  #   class TreeBuilder < TreeStand::Visitor
+  #     TreeNode = Struct.new(:name, :children)
+  #
+  #     attr_reader :stack
+  #
+  #     def initialize(root)
+  #       super(root)
+  #       @stack = []
+  #     end
+  #
+  #     def around(node)
+  #       @stack << TreeNode.new(node.type, [])
+  #
+  #       # visit all children of this node
+  #       yield
+  #
+  #       # The last node on the stack is the root of the tree.
+  #       return if @stack.size == 1
+  #
+  #       # Pop the last node off the stack and add it to the parent
+  #       @stack[-2].children << @stack.pop
+  #     end
+  #   end
+  class Visitor
+    extend T::Sig
+
+    sig { params(node: TreeStand::Node).void }
+    def initialize(node)
+      @node = node
+    end
+
+    # Run the visitor on the document and return self. Allows chaining create and visit.
+    # @example
+    #   visitor = CountingVisitor.new(node, :predicate).visit
+    sig { returns(T.self_type) }
+    def visit
+      visit_node(@node)
+      self
+    end
+
+    # @abstract The default implementation does nothing.
+    #
+    # @example Create callback to count all nodes in a tree.
+    #   def on(node)
+    #     @count += 1
+    #   end
+    sig { overridable.params(node: TreeStand::Node).void }
+    def on(node) = nil
+
+    # @abstract The default implementation yields to visit all children.
+    #
+    # @example Use around hooks to run logic before & after visiting a node. Pairs will with a stack.
+    #   def around(node)
+    #     @stack << TreeNode.new(node.type, [])
+    #
+    #     # visit all children of this node
+    #     yield
+    #
+    #     # The last node on the stack is the root of the tree.
+    #     return if @stack.size == 1
+    #
+    #     # Pop the last node off the stack and add it to the parent
+    #     @stack[-2].children << @stack.pop
+    #   end
+    sig { overridable.params(node: TreeStand::Node, block: T.proc.void).void }
+    def around(node, &block) = yield
+
+    private
+
+    def visit_node(node)
+      if respond_to?("on_#{node.type}")
+        public_send("on_#{node.type}", node)
+      else
+        on(node)
+      end
+
+      if respond_to?("around_#{node.type}")
+        public_send("around_#{node.type}", node) do
+          node.each { |child| visit_node(child) }
+        end
+      else
+        around(node) do
+          node.each { |child| visit_node(child) }
+        end
+      end
+    end
+  end
+end