ruby_tree_sitter 1.6.0-x86_64-linux-gnu

data/lib/tree_stand/breadth_first_visitor.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Breadth-first traversal through the tree, calling hooks at each stop.
+  class BreadthFirstVisitor
+    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
+      queue = [@node]
+      visit_node(queue) while queue.any?
+      self
+    end
+
+    # @abstract The default implementation does nothing.
+    sig { overridable.params(node: TreeStand::Node).void }
+    def on(node) = nil
+
+    # @abstract The default implementation yields to visit all children.
+    sig { overridable.params(node: TreeStand::Node, block: T.proc.void).void }
+    def around(node, &block) = yield
+
+    private
+
+    def visit_node(queue)
+      node = queue.shift
+
+      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| queue << child }
+        end
+      else
+        around(node) do
+          node.each { |child| queue << child }
+        end
+      end
+    end
+  end
+end

data/lib/tree_stand/config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'pathname'
+
+module TreeStand
+  # Global configuration for the gem.
+  # @api private
+  class Config
+    extend T::Sig
+
+    sig { returns(T.nilable(Pathname)) }
+    attr_reader :parser_path
+
+    def parser_path=(path)
+      @parser_path = Pathname(path)
+    end
+  end
+end

data/lib/tree_stand/node.rb

@@ -0,0 +1,351 @@
+# 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 changed?
+    #   @return [Boolean] true if a syntax node has been edited.
+    # @!method child_count
+    #   @return [Integer] the number of child nodes.
+    # @!method extra?
+    #   @return [Boolean] true if the node is *extra* (e.g. comments).
+    # @!method has_error?
+    #   @return [Boolean] true if the node is a syntax error or contains any syntax errors.
+    # @!method missing?
+    #   @return [Boolean] true if the parser inserted that node to recover from error.
+    # @!method named?
+    #   @return [Boolean] true if the node is not a literal in the grammar.
+    # @!method named_child_count
+    #   @return [Integer] the number of *named* children.
+    # @!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,
+      :changed?,
+      :child_count,
+      :error?,
+      :extra?,
+      :has_error?,
+      :missing?,
+      :named?,
+      :named_child_count,
+      :type,
+    )
+
+    # These are methods defined in {TreeStand::Node} but map to something
+    # in {TreeSitter::Node}, because we want a more idiomatic API.
+    THINLY_REMAPPED_METHODS = {
+      '[]': :[],
+      fetch: :fetch,
+      field: :child_by_field_name,
+      next: :next_sibling,
+      prev: :prev_sibling,
+      next_named: :next_named_sibling,
+      prev_named: :prev_named_sibling,
+      field_names: :fields,
+    }.freeze
+
+    # These are methods from {TreeSitter} that are thinly wrapped to create
+    # {TreeStand::Node} instead.
+    THINLY_WRAPPED_METHODS = (
+      %i[
+        child
+        named_child
+        parent
+      ] + THINLY_REMAPPED_METHODS.keys
+    ).freeze
+
+    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
+    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)
+      TreeSitter::QueryCursor
+        .new
+        .matches(ts_query, @tree.ts_tree.root_node, @tree.document)
+        .each_capture_hash
+        .map { |h| h.transform_values! { |n| TreeStand::Node.new(@tree, n) } }
+    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
+
+    # Enumerate named children.
+    # @example
+    #   node.text # => "3 * 4"
+    #
+    # @example Iterate over the child nodes
+    #   node.each_named do |child|
+    #     print child.text
+    #   end
+    #   # prints: 34
+    #
+    # @example Enumerable methods
+    #   node.each_named.map(&:text) # => ["3", "4"]
+    #
+    # @yieldparam child [TreeStand::Node]
+    sig do
+      params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
+    def each_named(&block)
+      enumerator = Enumerator.new do |yielder|
+        @ts_node.each_named do |child|
+          yielder << TreeStand::Node.new(@tree, child)
+        end
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # Iterate of (field, child).
+    #
+    # @example
+    #   node.text # => "3 * 4"
+    #
+    # @example Iterate over the child nodes
+    #   node.each_field do |field, child|
+    #     puts "#{field}: #{child.text}"
+    #   end
+    #   # prints:
+    #   #  left: 3
+    #   #  right: 4
+    #
+    # @example Enumerable methods
+    #   node.each_field.map { |f, c| "#{f}: #{c}" } # => ["left: 3", "right: 4"]
+    #
+    # @yieldparam field [Symbol]
+    # @yieldparam child [TreeStand::Node]
+    sig do
+      params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[[Symbol, TreeStand::Node]])
+    end
+    def each_field(&block)
+      enumerator = Enumerator.new do |yielder|
+        @ts_node.each_field do |field, child|
+          yielder << [field.to_sym, TreeStand::Node.new(@tree, child)]
+        end
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # @example Enumerable methods
+    #   node.named.map(&:text) # => ["3", "4"]
+    alias_method :named, :each_named
+
+    # @example Enumerable methods
+    #   node.fields.map { |f, c| "#{f}: #{c}" } # => ["left: 3", "right: 4"]
+    alias_method :fields, :each_field
+
+    # (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 # => "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.byteslice(@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, **kwargs, &block)
+      if thinly_wrapped?(method)
+        from(
+          T.unsafe(@ts_node)
+            .public_send(
+              THINLY_REMAPPED_METHODS[method] || method,
+              *args,
+              **kwargs,
+              &block
+            ),
+        )
+      else
+        super
+      end
+    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, *_args, **_kwargs)
+      thinly_wrapped?(method) || super
+    end
+
+    def thinly_wrapped?(method)
+      @ts_node.fields.include?(method) || THINLY_WRAPPED_METHODS.include?(method)
+    end
+
+    # FIXME: Make more generic if needed in other classes.
+
+    # 1 instance of {TreeStand} from a {TreeSitter} equivalent.
+    def from_a(node)
+      node.is_a?(TreeSitter::Node) ? TreeStand::Node.new(@tree, node) : node
+    end
+
+    # {TreeSitter} instance, or a collection ({Array, Hash})
+    def from(obj)
+      case obj
+      when Array
+        obj.map { |n| from(n) }
+      when Hash
+        obj.to_h { |k, v| [from(k), from(v)] }
+      else
+        from_a(obj)
+      end
+    end
+  end
+end

data/lib/tree_stand/parser.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'pathname'
+
+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")
+  #
+  # If no {TreeStand::Config#parser_path} is setup, {TreeStand} will lookup in a
+  # set of default paths.  You can always override any configuration by passing
+  # the environment variable `TREE_SITTER_PARSERS` (colon-separated).
+  #
+  # @see language
+  # @see search_for_lib
+  # @see LIBDIRS
+  class Parser
+    extend T::Sig
+    extend TreeSitter::Mixins::Language
+
+    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)
+      @ts_language = Parser.language(language)
+      @ts_parser = TreeSitter::Parser.new.tap do |parser|
+        parser.language = @ts_language
+      end
+    end
+
+    # The library directories we need to look into.
+    #
+    # @return [Array<Pathname>] the list of candidate places to use when searching for parsers.
+    #
+    # @see ENV_PARSERS
+    # @see LIBDIRS
+    def self.lib_dirs
+      [
+        *TreeSitter::ENV_PARSERS,
+        *(TreeStand.config.parser_path ? [TreeStand.config.parser_path] : TreeSitter::LIBDIRS),
+      ]
+    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