ruby_tree_sitter 1.6.0-x86_64-linux-gnu

data/lib/tree_sitter/node.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # Node is a wrapper around a tree-sitter node.
+  class Node
+    include Enumerable
+
+    # @return [Array<Symbol>] the node's named fields
+    def fields
+      return @fields if @fields
+
+      @fields = Set.new
+      child_count.times do |i|
+        name = field_name_for_child(i)
+        @fields << name.to_sym if name
+      end
+
+      @fields.to_a
+    end
+
+    # @param field [String, Symbol]
+    def field?(field)
+      fields.include?(field.to_sym)
+    end
+
+    # Access node's named children.
+    #
+    # It's similar to {#fetch}, but differs in input type, return values, and
+    # the internal implementation.
+    #
+    # Both of these methods exist for separate use cases, but also because
+    # sometime tree-sitter does some monkey business and having both separate
+    # implementations can help.
+    #
+    # Comparison with {#fetch}:
+    #
+    #              []                            | fetch
+    #              ------------------------------+----------------------
+    # input types  Integer, String, Symbol       | Array<String, Symbol>
+    #              Array<Integer, String, Symbol>|
+    #              ------------------------------+----------------------
+    # returns      1-to-1 correspondance with    | unique nodes
+    #              input                         |
+    #              ------------------------------+----------------------
+    # uses         named_child                   | field_name_for_child
+    #              child_by_field_name           |   via each_node
+    #              ------------------------------+----------------------
+    #
+    # @param keys [Integer | String | Symbol | Array<Integer, String, Symbol>, #read]
+    #
+    # @return [Node | Array<Node>]
+    def [](*keys)
+      case keys.length
+      when 0 then raise ArgumentError, "#{self.class.name}##{__method__} requires a key."
+      when 1
+        case k = keys.first
+        when Integer then named_child(k)
+        when String, Symbol
+          raise IndexError, "Cannot find field #{k}. Available: #{fields}" unless fields.include?(k.to_sym)
+
+          child_by_field_name(k.to_s)
+        else raise ArgumentError, <<~ERR
+          #{self.class.name}##{__method__} accepts Integer and returns named child at given index,
+              or a (String | Symbol) and returns the child by given field name.
+        ERR
+        end
+      else
+        keys.map { |key| self[key] }
+      end
+    end
+
+    # @!visibility private
+    #
+    # Allows access to child_by_field_name without using [].
+    def method_missing(method_name, *_args, &_block)
+      if fields.include?(method_name)
+        child_by_field_name(method_name.to_s)
+      else
+        super
+      end
+    end
+
+    # @!visibility private
+    #
+    def respond_to_missing?(*args)
+      args.length == 1 && fields.include?(args[0])
+    end
+
+    # Iterate over a node's children.
+    #
+    # @yieldparam child [Node] the child
+    def each(&_block)
+      return enum_for __method__ if !block_given?
+
+      (0...child_count).each do |i|
+        yield child(i)
+      end
+    end
+
+    # Iterate over a node's children assigned to a field.
+    #
+    # @yieldparam name [NilClass | String] field name.
+    # @yieldparam child [Node] the child.
+    def each_field
+      return enum_for __method__ if !block_given?
+
+      each.with_index do |c, i|
+        f = field_name_for_child(i)
+        next if f.nil? || f.empty?
+
+        yield f, c
+      end
+    end
+
+    # Iterate over a node's named children
+    #
+    # @yieldparam child [Node] the child
+    def each_named
+      return enum_for __method__ if !block_given?
+
+      (0...(named_child_count)).each do |i|
+        yield named_child(i)
+      end
+    end
+
+    # @return [Array<TreeSitter::Node>] all the node's children
+    def to_a
+      each.to_a
+    end
+
+    # Access node's named children.
+    #
+    # It's similar to {#[]}, but differs in input type, return values, and
+    # the internal implementation.
+    #
+    # Both of these methods exist for separate use cases, but also because
+    # sometime tree-sitter does some monkey business and having both separate
+    # implementations can help.
+    #
+    # Comparison with {#fetch}:
+    #
+    #              []                            | fetch
+    #              ------------------------------+----------------------
+    # input types  Integer, String, Symbol       | String, Symbol
+    #              Array<Integer, String, Symbol>| Array<String, Symbol>
+    #              ------------------------------+----------------------
+    # returns      1-to-1 correspondance with    | unique nodes
+    #              input                         |
+    #              ------------------------------+----------------------
+    # uses         named_child                   | field_name_for_child
+    #              child_by_field_name           |   via each_node
+    #              ------------------------------+----------------------
+    #
+    # See {#[]}.
+    def fetch(*keys)
+      keys = keys.map(&:to_s)
+      key_set = keys.to_set
+      fields = {}
+      each_field do |f, _c|
+        fields[f] = self[f] if key_set.delete(f)
+
+        break if key_set.empty?
+      end
+      fields.values_at(*keys)
+    end
+  end
+end

data/lib/tree_sitter/query.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative 'helpers'
+
+module TreeSitter
+  # Query is a wrapper around a tree-sitter query.
+  class Query
+    attr_reader :capture_names
+    attr_reader :capture_quantifiers
+    attr_reader :text_predicates
+    attr_reader :property_predicates
+    attr_reader :property_settings
+    attr_reader :general_predicates
+
+    private
+
+    # Called from query.c on initialize.
+    #
+    # Prepares all the predicates so we could process them in places like
+    # {QueryMatch#satisfies_text_predicate?}.
+    #
+    # This is translation from the [rust bindings](https://github.com/tree-sitter/tree-sitter/blob/e553578696fe86071846ed612ee476d0167369c1/lib/binding_rust/lib.rs#L1860)
+    # Because it's a direct translation, it's way too long and we need to shut up rubocop.
+    # TODO: refactor + simplify when stable.
+    def process(source) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+      string_count = self.string_count
+      capture_count = self.capture_count
+      pattern_count = self.pattern_count
+
+      # Build a vector of strings to store the capture names.
+      capture_names = capture_count.times.map { |i| capture_name_for_id(i) }
+
+      # Build a vector to store capture qunatifiers.
+      capture_quantifiers =
+        pattern_count.times.map do |i|
+          capture_count.times.map do |j|
+            capture_quantifier_for_id(i, j)
+          end
+        end
+
+      # Build a vector of strings to represent literal values used in predicates.
+      string_values = string_count.times.map { |i| string_value_for_id(i) }
+
+      # Build a vector of predicates for each pattern.
+      pattern_count.times do |i| # rubocop:disable Metrics/BlockLength
+        predicate_steps = predicates_for_pattern(i)
+        byte_offset = start_byte_for_pattern(i)
+        row =
+          source.chars.map.with_index
+            .take_while { |_, i| i < byte_offset } # rubocop:disable Lint/ShadowingOuterLocalVariable
+            .filter { |c, _| c == "\n" }
+            .size
+        text_predicates = []
+        property_predicates = []
+        property_settings = []
+        general_predicates = []
+
+        array_split_like_rust(predicate_steps) { |s| s.type == QueryPredicateStep::DONE } # rubocop:disable Metrics/BlockLength
+          .each do |p|
+            next if p.empty?
+
+            if p[0] == QueryPredicateStep::STRING
+              cap = capture_names[p[0].value_id]
+              raise ArgumentError, <<~MSG.chomp
+                L#{row}: Expected predicate to start with a function name. Got @#{cap}.
+              MSG
+            end
+
+            # Build a predicate for each of the known predicate function names.
+            operator_name = string_values[p[0].value_id]
+
+            case operator_name
+            in 'any-eq?' | 'any-not-eq?' | 'eq?' | 'not-eq?'
+              if p.size != 3
+                raise ArgumentError, <<~MSG.chomp
+                  L#{row}: Wrong number of arguments to ##{operator_name} predicate. Expected 2, got #{p.size - 1}.
+                MSG
+              end
+
+              if p[1].type != QueryPredicateStep::CAPTURE
+                lit = string_values[p[1].value_id]
+                raise ArgumentError, <<~MSG.chomp
+                  L#{row}: First argument to ##{operator_name} predicate must be a capture name. Got literal "#{lit}".
+                MSG
+              end
+
+              is_positive = %w[eq? any-eq?].include?(operator_name)
+              match_all = %w[eq? not-eq?].include?(operator_name)
+              # NOTE: in the rust impl, match_all can hit an unreachable! but I am simplifying
+              # for readability. Same applies for the other `in` branches.
+              text_predicates <<
+                if p[2].type == QueryPredicateStep::CAPTURE
+                  TextPredicateCapture.eq_capture(p[1].value_id, p[2].value_id, is_positive, match_all)
+                else
+                  TextPredicateCapture.eq_string(p[1].value_id, string_values[p[2].value_id], is_positive, match_all)
+                end
+
+            in 'match?' | 'not-match?' | 'any-match?' | 'any-not-match?'
+              if p.size != 3
+                raise ArgumentError, <<~MSG.chomp
+                  L#{row}: Wrong number of arguments to ##{operator_name} predicate. Expected 2, got #{p.size - 1}.
+                MSG
+              end
+
+              if p[1].type != QueryPredicateStep::CAPTURE
+                lit = string_values[p[1].value_id]
+                raise ArgumentError, <<~MSG.chomp
+                  L#{row}: First argument to ##{operator_name} predicate must be a capture name. Got literal "#{lit}".
+                MSG
+              end
+
+              if p[2].type == QueryPredicateStep::CAPTURE
+                cap = capture_names[p[2].value_id]
+                raise ArgumentError, <<~MSG.chomp
+                  L#{row}: First argument to ##{operator_name} predicate must be a literal. Got capture @#{cap}".
+                MSG
+              end
+
+              is_positive = %w[match? any-match?].include?(operator_name)
+              match_all = %w[match? not-match?].include?(operator_name)
+              regex = /#{string_values[p[2].value_id]}/
+
+              text_predicates << TextPredicateCapture.match_string(p[1].value_id, regex, is_positive, match_all)
+
+            in 'set!'
+              property_settings << 'todo!'
+
+            in 'is?' | 'is-not?'
+              property_predicates << 'todo!'
+
+            in 'any-of?' | 'not-any-of?'
+              if p.size < 2
+                raise ArgumentError, <<~MSG.chomp
+                  L#{row}: Wrong number of arguments to ##{operator_name} predicate. Expected at least 1, got #{p.size - 1}.
+                MSG
+              end
+
+              if p[1].type != QueryPredicateStep::CAPTURE
+                lit = string_values[p[1].value_id]
+                raise ArgumentError, <<~MSG.chomp
+                  L#{row}: First argument to ##{operator_name} predicate must be a capture name. Got literal "#{lit}".
+                MSG
+              end
+
+              is_positive = operator_name == 'any_of'
+              values = []
+
+              p[2..].each do |arg|
+                if arg.type == QueryPredicateStep::CAPTURE
+                  lit = string_values[arg.value_id]
+                  raise ArgumentError, <<~MSG.chomp
+                    L#{row}: First argument to ##{operator_name} predicate must be a capture name. Got literal "#{lit}".
+                  MSG
+                end
+                values << string_values[arg.value_id]
+              end
+
+              # TODO: is the map to to_s necessary in ruby?
+              text_predicates <<
+                TextPredicateCapture.any_string(p[1].value_id, values.map(&:to_s), is_positive, match_all)
+            else
+              general_predicates <<
+                QueryPredicate.new(
+                  operator_name,
+                  p[1..].map do |a|
+                    if a.type == QueryPredicateStep::CAPTURE
+                      { capture: a.value_id }
+                    else
+                      { string: string_values[a.value_id] }
+                    end
+                  end,
+                )
+            end
+
+            @text_predicates << text_predicates
+            @property_predicates << property_predicates
+            @property_settings << property_settings
+            @general_predicates << general_predicates
+          end
+
+        @capture_names = capture_names
+        @capture_quantifiers = capture_quantifiers
+      end
+    end
+
+    # TODO
+    def parse_property
+      # todo
+    end
+  end
+end

data/lib/tree_sitter/query_captures.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # A sequence of {TreeSitter::QueryCapture} associated with a given {TreeSitter::QueryCursor}.
+  class QueryCaptures
+    include Enumerable
+
+    def initialize(cursor, query, src)
+      @cursor = cursor
+      @query = query
+      @src = src
+    end
+
+    # Iterator over captures.
+    #
+    # @yieldparam match [TreeSitter::QueryMatch]
+    # @yieldparam capture_index [Integer]
+    def each(&_block)
+      return enum_for __method__ if !block_given?
+
+      while (capture_index, match = @cursor.next_capture)
+        next if !match.is_a?(TreeSitter::QueryMatch)
+
+        if match.satisfies_text_predicate?(@query, @src)
+          yield [match, capture_index]
+        end
+      end
+    end
+  end
+end

data/lib/tree_sitter/query_cursor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # A Cursor for {Query}.
+  class QueryCursor
+    # Iterate over all of the matches in the order that they were found.
+    #
+    # Each match contains the index of the pattern that matched, and a list of
+    # captures. Because multiple patterns can match the same set of nodes,
+    # one match may contain captures that appear *before* some of the
+    # captures from a previous match.
+    def matches(query, node, src)
+      self.exec(query, node)
+      QueryMatches.new(self, query, src)
+    end
+
+    # Iterate over all of the individual captures in the order that they
+    # appear.
+    #
+    # This is useful if you don't care about which pattern matched, and just
+    # want a single, ordered sequence of captures.
+    def captures(query, node, src)
+      self.exec(query, node)
+      QueryCaptures.new(self, query, src)
+    end
+  end
+end

data/lib/tree_sitter/query_match.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'query_captures'
+
+module TreeSitter
+  # A match for a {Query}.
+  class QueryMatch
+    # All nodes at a given capture index.
+    #
+    # @param index [Integer]
+    #
+    # @return [TreeSitter::Node]
+    def nodes_for_capture_index(index) = captures.filter_map { |capture| capture.node if capture.index == index }
+
+    # Whether the {QueryMatch} satisfies the text predicates in the query.
+    #
+    # This is a translation from the [rust bindings](https://github.com/tree-sitter/tree-sitter/blob/e553578696fe86071846ed612ee476d0167369c1/lib/binding_rust/lib.rs#L2502).
+    # Because it's a direct translation, it's way too long and we need to shut up rubocop.
+    # TODO: refactor + simplify when satable.
+    def satisfies_text_predicate?(query, src) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+      return true if query.text_predicates[pattern_index].nil?
+
+      query # rubocop:disable Metrics/BlockLength
+        .text_predicates[pattern_index]
+        .all? do |predicate|
+          case predicate.type
+          in TextPredicateCapture::EQ_CAPTURE
+            fst_nodes = nodes_for_capture_index(predicate.fst)
+            snd_nodes = nodes_for_capture_index(predicate.snd)
+            res = nil
+            consumed = 0
+            fst_nodes.zip(snd_nodes).each do |node1, node2|
+              text1 = node_text(node1, src)
+              text2 = node_text(node2, src)
+              if (text1 == text2) != predicate.positive? && predicate.match_all?
+                res = false
+                break
+              end
+              if (text1 == text2) == predicate.positive? && !predicate.match_all?
+                res = true
+                break
+              end
+              consumed += 1
+            end
+            (res.nil? && consumed == fst_nodes.length && consumed == snd_nodes.length) \
+              || res
+
+          in TextPredicateCapture::EQ_STRING
+            nodes = nodes_for_capture_index(predicate.fst)
+            res = true
+            nodes.each do |node|
+              text = node_text(node, src)
+              if (predicate.snd == text) != predicate.positive? && predicate.match_all?
+                res = false
+                break
+              end
+              if (predicate.snd == text) == predicate.positive? && !predicate.match_all?
+                res = true
+                break
+              end
+            end
+            res
+
+          in TextPredicateCapture::MATCH_STRING
+            nodes = nodes_for_capture_index(predicate.fst)
+            res = true
+            nodes.each do |node|
+              text = node_text(node, src)
+              if predicate.snd.match?(text) != predicate.positive? && predicate.match_all?
+                res = false
+                break
+              end
+              if predicate.snd.match?(text) == predicate.positive? && !predicate.match_all?
+                res = true
+                break
+              end
+            end
+            res
+
+          in TextPredicateCapture::ANY_STRING
+            nodes = nodes_for_capture_index(predicate.fst)
+            res = true
+            nodes.each do |node|
+              text = node_text(node, src)
+              if predicate.snd.any? { |v| v == text } != predicate.positive?
+                res = false
+                break
+              end
+            end
+            res
+
+          end
+        end
+    end
+
+    private
+
+    def node_text(node, text) = text.byteslice(node.start_byte...node.end_byte)
+  end
+end

data/lib/tree_sitter/query_matches.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # A sequence of {QueryMatch} associated with a given {QueryCursor}.
+  class QueryMatches
+    include Enumerable
+
+    def initialize(cursor, query, src)
+      @cursor = cursor
+      @query = query
+      @src = src
+    end
+
+    # Iterator over matches.
+    #
+    # @yieldparam match [TreeSitter::QueryMatch]
+    def each(&_block)
+      return enum_for __method__ if !block_given?
+
+      while match = @cursor.next_match
+        if match.satisfies_text_predicate?(@query, @src)
+          yield match
+        end
+      end
+    end
+
+    # Iterate over all the results presented as hashes of `capture name => node`.
+    #
+    # @yieldparam match [Hash<String, TreeSitter::Node>]
+    def each_capture_hash(&_block)
+      # TODO: should we return [Array<Hash<Symbol, TreeSitter::Node]>>] instead?
+      return enum_for __method__ if !block_given?
+
+      each do |match|
+        yield match.captures.to_h { |cap| [@query.capture_name_for_id(cap.index), cap.node] }
+      end
+    end
+  end
+end

data/lib/tree_sitter/query_predicate.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # A {Query} predicate generic representation.
+  class QueryPredicate
+    attr_accessor :operator
+    attr_accessor :args
+
+    def initialize(operator, args)
+      @operator = operator
+      @args = args
+    end
+  end
+end

data/lib/tree_sitter/text_predicate_capture.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # A representation for text predicates.
+  class TextPredicateCapture
+    EQ_CAPTURE = 0   # Equality Capture
+    EQ_STRING = 1    # Equality String
+    MATCH_STRING = 2 # Match String
+    ANY_STRING = 3   # Any String
+
+    attr_reader :fst
+    attr_reader :snd
+    attr_reader :type
+
+    # Create a TextPredicateCapture for {EQ_CAPTURE}.
+    def self.eq_capture(...) = new(EQ_CAPTURE, ...)
+    # Create a TextPredicateCapture for {EQ_STRING}.
+    def self.eq_string(...) = new(EQ_STRING, ...)
+    # Create a TextPredicateCapture for {MATCH_STRING}.
+    def self.match_string(...) = new(MATCH_STRING, ...)
+    # Create a TextPredicateCapture for {ANY_STRING}.
+    def self.any_string(...) = new(ANY_STRING, ...)
+
+    def initialize(type, fst, snd, positive, match_all)
+      @type = type
+      @fst = fst
+      @snd = snd
+      @positive = positive
+      @match_all = match_all
+    end
+
+    # `#eq` is positive, `#not-eq` is not.
+    def positive? = @positive
+    # `#any-` means don't match all.
+    def match_all? = @match_all
+  end
+end

data/lib/tree_sitter/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # The version of the tree-sitter library.
+  TREESITTER_VERSION = '0.22.6'
+  # The current version of the gem.
+  VERSION = '1.6.0'
+end

data/lib/tree_sitter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'set'
+
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "tree_sitter/#{Regexp.last_match(1)}/tree_sitter"
+rescue LoadError
+  require 'tree_sitter/tree_sitter'
+end
+
+require 'tree_sitter/version'
+
+require 'tree_sitter/mixins/language'
+
+require 'tree_sitter/node'
+require 'tree_sitter/query'
+require 'tree_sitter/query_captures'
+require 'tree_sitter/query_cursor'
+require 'tree_sitter/query_match'
+require 'tree_sitter/query_matches'
+require 'tree_sitter/query_predicate'
+require 'tree_sitter/text_predicate_capture'
+
+# TreeSitter is a Ruby interface to the tree-sitter parsing library.
+module TreeSitter
+  extend Mixins::Language
+
+  class << self
+    alias_method :lang, :language
+  end
+end
+
+ObjectSpace.define_finalizer(TreeSitter::Tree.class, proc { TreeSitter::Tree.finalizer })

data/lib/tree_stand/ast_modifier.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # An experimental class to modify the AST. It re-runs the query on the
+  # modified document every loop to ensure that the match is still valid.
+  # @see TreeStand::Tree
+  # @api experimental
+  class AstModifier
+    extend T::Sig
+
+    sig { params(tree: TreeStand::Tree).void }
+    def initialize(tree)
+      @tree = tree
+    end
+
+    # @param query [String]
+    # @yieldparam self [self]
+    # @yieldparam match [TreeStand::Match]
+    # @return [void]
+    def on_match(query)
+      matches = @tree.query(query)
+
+      while !matches.empty?
+        yield self, matches.first
+        matches = @tree.query(query)
+      end
+    end
+  end
+end