ruby_tree_sitter 1.1.0-x86_64-linux → 1.3.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdd749f5a178b25079aecc1e0c32c620f6f36ec40e8a0a12fb86f8a8f7211d32
-  data.tar.gz: 3c16103df927a99c4aa300bfa01d8795b36cac76d2a67b72759b3ccd0c945f39
+  metadata.gz: a0f7c51b289e769ad5701be586b28d61f41f0979ee6fd3c08f87481ae307f146
+  data.tar.gz: 988052e5b5b5c41e9a9d974398c6c6cae401f2068a2ad4013d80198f3437c029
 SHA512:
-  metadata.gz: 5a98b62297c70ff439a553990617d03746aa837f065d785b5346f68d455b907f700b63decd87de5dde87f7aa6b112085e38dda04543d82a991f2d90fa86c8265
-  data.tar.gz: cf24b69a7afe950423868abd7e383edd2b722deb32412f92a22a8886264e20b9b7f2458674238fdec79539dd44545cca56adab25732d6115ae4896b10d324963
+  metadata.gz: 9ef62c5ea3bd4451b03b43e6efc2c3501191ffcd9ea96dfe12d2e66b249d1f16f58e82d6127d833a6c8105e3f910dda2ba898a138d5e6d2756615bf69fcb2e05
+  data.tar.gz: 5bd46cc66e845c9091005a5eadeccb3db2984e0bbc5bf6d12e9fc4e3fd126f9ab6f1d37970fbe6760eee096ec2c011d4d328d5610a9e873ed313df3842caceb3

data/README.md

@@ -1,6 +1,12 @@
 # Ruby tree-sitter bindings
 
-[![ci](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml) [![valgrind](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml) [![asan/ubsan](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml)
+[![docs](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/publish-docs.yml/badge.svg)](https://faveod.github.io/ruby-tree-sitter)
+[![rubygems.org](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/publish.yml/badge.svg)](https://rubygems.org/gems/ruby_tree_sitter)
+[![ci](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml)
+<!--
+[![valgrind](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml)
+[![asan/ubsan](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml)
+-->
 
 Ruby bindings for [tree-sitter](https://github.com/tree-sitter/tree-sitter).
 
@@ -63,8 +69,7 @@ This gem is a binding for `tree-sitter`. It doesn't have a version of
 
 You must install `tree-sitter` and make sure that their dynamic library is
 accessible from `$PATH`, or build the gem with `--disable-sys-libs`, which will
-download the latest tagged `tree-sitter` and build against it (see [Build from
-source](docs/Contributing.md#build-from-source) .)
+download the latest tagged `tree-sitter` and build against it (see [Build from source](docs/Contributing.md#build-from-source) .)
 
 You can either install `tree-sitter` from source or through your go-to package manager.
 
@@ -133,8 +138,7 @@ bundle config set build.ruby_tree_sitter --disable-sys-libs
 If you don't want to install from `rubygems`, `git`, or if you don't want to
 compile on install, then download a native gem from this repository's
 [releases](https://github.com/Faveod/ruby-tree-sitter/releases), or you can
-compile it yourself (see [Build from
-source](docs/Contributing.md#build-from-source) .)
+compile it yourself (see [Build from source](docs/Contributing.md#build-from-source) .)
 
 In that case, you'd have to point your `Gemfile` to the `gem` as such:
 
@@ -171,7 +175,7 @@ See `examples` directory.
 
 ## Development
 
-See [`docs/README.md`](docs/Contributing.md).
+See [`docs/Contributing.md`](docs/Contributing.md).
 
 ## 🚧 👷‍♀️ Notes 👷 🚧
 
@@ -186,7 +190,7 @@ don't copy them left and right, and then expect them to work without
 `SEGFAULT`ing and creating a black-hole in your living-room.  Assume that you
 have to work locally with them. If you get a `SEGFAULT`, you can debug the
 native `C` code using `gdb`.  You can read more on `SEGFAULT`s
-[here](docs/SIGSEGV.md), and debugging [here](docs/Contributing.md#Debugging).
+[here](docs/SIGSEGV.md), and debugging [here](docs/Contributing#Debugging.md).
 
 That said, we do aim at providing an idiomatic `Ruby` interface.  It should also
 provide a _safer_ interface, where you don't have to worry about when and how

data/ext/tree_sitter/language.c

@@ -32,7 +32,7 @@ VALUE new_language(const TSLanguage *language) {
  * with this gem.
  *
  * @param name [String] the parser's name.
- * @param path [String] the parser's shared library (so, dylib) path on disk.
+ * @param path [String, Pathname] the parser's shared library (so, dylib) path on disk.
  *
  * @return [Language]
  */

data/ext/tree_sitter/logger.c

@@ -154,9 +154,9 @@ static void logger_initialize_stderr(logger_t *logger) {
  *
  * You can provide your proper backend. You have to make sure that it
  * exposes a +printf+, +puts+, or +write+ (lookup is done in that specific
- * order). {StringIO} is a perfect candidate.
+ * order). {::StringIO} is a perfect candidate.
  *
- * You can also provide a format ({String}) if your backend supports a +printf+.
+ * You can also provide a format ({::String}) if your backend supports a +printf+.
  *
  * @example
  *   backend = StringIO.new

data/ext/tree_sitter/node.c

@@ -166,14 +166,19 @@ static VALUE node_child_by_field_id(VALUE self, VALUE field_id) {
 /**
  * Get the node's child with the given field name.
  *
- * @param field_name [String]
+ * @param field_name [String, Symbol]
  *
  * @return [Node]
  */
 static VALUE node_child_by_field_name(VALUE self, VALUE field_name) {
-  const char *name = StringValuePtr(field_name);
-  uint32_t length = (uint32_t)RSTRING_LEN(field_name);
-  return new_node_by_val(ts_node_child_by_field_name(SELF, name, length));
+  if (Qtrue == rb_funcall(self, rb_intern("field?"), 1, field_name)) {
+    VALUE field_str = rb_funcall(field_name, rb_intern("to_s"), 0);
+    const char *name = StringValuePtr(field_str);
+    uint32_t length = (uint32_t)RSTRING_LEN(field_str);
+    return new_node_by_val(ts_node_child_by_field_name(SELF, name, length));
+  } else {
+    return Qnil;
+  }
 }
 
 /**

data/ext/tree_sitter/parser.c

@@ -208,7 +208,7 @@ static VALUE parser_set_logger(VALUE self, VALUE logger) {
  *    same arguments. Or you can start parsing from scratch by first calling
  *    {Parser#reset}.
  * 3. Parsing was cancelled using a cancellation flag that was set by an
- *    earlier call to {Parsert#cancellation_flag=}. You can resume parsing
+ *    earlier call to {Parser#cancellation_flag=}. You can resume parsing
  *    from where the parser left out by calling {Parser#parse} again with
  *    the same arguments.
  *

data/ext/tree_sitter/query.c

@@ -140,6 +140,13 @@ static VALUE query_initialize(VALUE self, VALUE language, VALUE source) {
     SELF = res;
   }
 
+  rb_iv_set(self, "@text_predicates", rb_ary_new());
+  rb_iv_set(self, "@property_predicates", rb_ary_new());
+  rb_iv_set(self, "@property_settings", rb_ary_new());
+  rb_iv_set(self, "@general_predicates", rb_ary_new());
+
+  rb_funcall(self, rb_intern("process"), 1, source);
+
   return self;
 }
 

data/ext/tree_sitter/query_cursor.c

@@ -49,7 +49,7 @@ DATA_FROM_VALUE(TSQueryCursor *, query_cursor)
  *
  * @return [QueryCursor]
  */
-static VALUE query_cursor_exec(VALUE self, VALUE query, VALUE node) {
+static VALUE query_cursor_exec_static(VALUE self, VALUE query, VALUE node) {
   VALUE res = query_cursor_allocate(cQueryCursor);
   query_cursor_t *query_cursor = unwrap(res);
   ts_query_cursor_exec(query_cursor->data, value_to_query(query),
@@ -57,6 +57,21 @@ static VALUE query_cursor_exec(VALUE self, VALUE query, VALUE node) {
   return res;
 }
 
+/**
+ * Start running a given query on a given node.
+ *
+ * @param query [Query]
+ * @param node  [Node]
+ *
+ * @return [QueryCursor]
+ */
+static VALUE query_cursor_exec(VALUE self, VALUE query, VALUE node) {
+  query_cursor_t *query_cursor = unwrap(self);
+  ts_query_cursor_exec(query_cursor->data, value_to_query(query),
+                       value_to_node(node));
+  return self;
+}
+
 /**
  * Manage the maximum number of in-progress matches allowed by this query
  * cursor.
@@ -190,13 +205,14 @@ void init_query_cursor(void) {
   rb_define_alloc_func(cQueryCursor, query_cursor_allocate);
 
   /* Module methods */
-  rb_define_module_function(cQueryCursor, "exec", query_cursor_exec, 2);
+  rb_define_module_function(cQueryCursor, "exec", query_cursor_exec_static, 2);
 
   /* Class methods */
   // Accessors
   DECLARE_ACCESSOR(cQueryCursor, query_cursor, match_limit)
 
   // Other
+  rb_define_method(cQueryCursor, "exec", query_cursor_exec, 2);
   rb_define_method(cQueryCursor, "exceed_match_limit?",
                    query_cursor_did_exceed_match_limit, 0);
   rb_define_method(cQueryCursor, "match_limit", query_cursor_get_match_limit,

data/lib/tree_sitter/helpers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# splits an array like [rust](https://doc.rust-lang.org/std/primitive.slice.html#method.split)
+def array_split_like_rust(array, &block)
+  return enum_for(__method__, array) if !block_given?
+
+  return [] if array.empty?
+
+  result = []
+  current_slice = []
+
+  array.each do |element|
+    if yield(element)
+      result << current_slice
+      current_slice = []
+    else
+      current_slice << element
+    end
+  end
+
+  result << current_slice
+  result
+end

data/lib/tree_sitter/node.rb

@@ -13,28 +13,17 @@ module TreeSitter
         @fields << name.to_sym if name
       end
 
-      @fields
+      @fields.to_a
     end
 
+    # @param field [String, Symbol]
     def field?(field)
-      fields.include?(field)
+      fields.include?(field.to_sym)
     end
 
-    # FIXME: These APIs (`[]` and `fetch`) need absolute fixing.
-    # 1. The documentation with the table doesn't work.
-    # 1. The APIs are very confusing! Make them act similarly to Hash's
-    #    `fetch` and `[]`.
-    #    1. `[]` should take a single input and return nil if nothing found
-    #       (no exceptions).
-    #    1. `fetch` should should accept a single argument, potentially a
-    #       default, and raise exception if no default was provided.
-    #       Also allow for the `all:` kwarg.
-    #    1. `values_at` takes many arguments.
-    # And I don't think we can move to 1.0 without adressing them.
-    #
     # Access node's named children.
     #
-    # It's similar to {#fetch}, but differes in input type, return values, and
+    # 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
@@ -60,15 +49,15 @@ module TreeSitter
     # @return [Node | Array<Node>]
     def [](*keys)
       case keys.length
-      when 0 then raise "#{self.class.name}##{__method__} requires a key."
+      when 0 then raise ArgumentError, "#{self.class.name}##{__method__} requires a key."
       when 1
         case k = keys.first
-        when Numeric then named_child(k)
+        when Integer then named_child(k)
         when String, Symbol
-          raise "Cannot find field #{k}" unless fields.include?(k.to_sym)
+          raise IndexError, "Cannot find field #{k}. Available: #{fields}" unless fields.include?(k.to_sym)
 
           child_by_field_name(k.to_s)
-        else raise <<~ERR
+        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
@@ -139,7 +128,7 @@ module TreeSitter
 
     # Access node's named children.
     #
-    # It's similar to {#fetch}, but differes in input type, return values, and
+    # 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
@@ -159,39 +148,18 @@ module TreeSitter
     # uses         named_child                   | field_name_for_child
     #              child_by_field_name           |   via each_node
     #              ------------------------------+----------------------
-    # @param all [Boolean] If `true`, return an array of nodes for all the
-    # demanded keys, putting `nil` for missing ones.  If `false`, return the
-    # same array after calling `compact`. Defaults to `false`.
-    #
-    # See {#fetch_all}.
-    def fetch(*keys, all: false, **_kwargs)
-      dict = {}
-      keys.each.with_index do |k, i|
-        dict[k.to_s] = i
-      end
+    #
+    # 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)
 
-      res = {}
-      each_field do |f, c|
-        if dict.key?(f)
-          res[f] = c
-          dict.delete(f)
-        end
-        break if dict.empty?
+        break if key_set.empty?
       end
-
-      res = keys.uniq.map { |k| res[k.to_s] }
-      res = res.compact if !all
-      res
-    end
-
-    # Access all named children of a node, returning `nil` for missing ones.
-    #
-    # Equivalent to `fetch(…, all: true)`.
-    #
-    # See {#fetch}.
-    def fetch_all(*keys, **kwargs)
-      kwargs[:all] = true
-      fetch(*keys, **kwargs)
+      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,28 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # A sequence of {TreeSitter::QueryCapture} associated with a given {TreeSitter::QueryCursor}.
+  class QueryCaptures
+    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
+      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,25 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  # A sequence of {QueryMatch} associated with a given {QueryCursor}.
+  class QueryMatches
+    def initialize(cursor, query, src)
+      @cursor = cursor
+      @query = query
+      @src = src
+    end
+
+    # Iterator over matches.
+    #
+    # @yieldparam match [TreeSitter::QueryMatch]
+    def each
+      return enum_for __method__ if !block_given?
+
+      while match = @cursor.next_match
+        if match.satisfies_text_predicate?(@query, @src)
+          yield match
+        end
+      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

@@ -4,5 +4,5 @@ module TreeSitter
   # The version of the tree-sitter library.
   TREESITTER_VERSION = '0.22.6'
   # The current version of the gem.
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
 end

data/lib/tree_sitter.rb

@@ -6,9 +6,16 @@ end
 
 require 'set'
 
+require 'tree_sitter/tree_sitter'
 require 'tree_sitter/version'
 
-require 'tree_sitter/tree_sitter'
 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'
 
 ObjectSpace.define_finalizer(TreeSitter::Tree.class, proc { TreeSitter::Tree.finalizer })

data/lib/tree_stand/config.rb

@@ -1,13 +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(String) }
-    attr_accessor :parser_path
+    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

@@ -11,16 +11,60 @@ module TreeStand
     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,
-      :type,
+      :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
 
@@ -32,7 +76,6 @@ module TreeStand
     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
@@ -131,6 +174,74 @@ module TreeStand
       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}.
     #
@@ -154,15 +265,6 @@ module TreeStand
       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"]
@@ -174,7 +276,7 @@ module TreeStand
     # 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])
+      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
@@ -193,10 +295,20 @@ module TreeStand
     #
     # @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))
+    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) }
@@ -217,8 +329,31 @@ module TreeStand
 
     private
 
-    def respond_to_missing?(method, *)
-      @fields.include?(method.to_s) || super
+    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

@@ -1,6 +1,8 @@
 # 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.
@@ -14,6 +16,14 @@ module TreeStand
   #
   #   # 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
 
@@ -23,14 +33,160 @@ module TreeStand
     sig { returns(TreeSitter::Parser) }
     attr_reader :ts_parser
 
+    # A colon-seprated list of paths pointing to directories that can contain parsers.
+    # Order matters.
+    # Takes precedence over default lookup paths.
+    ENV_PARSERS =
+      ENV['TREE_SITTER_PARSERS']
+        &.split(':')
+        &.map { |v| Pathname(v) }
+        .freeze
+
+    # The default paths we use to lookup parsers when no specific
+    # {TreeStand::Config#parser_path} is `nil`.
+    # Order matters.
+    LIBDIRS = [
+      'tree-sitter-parsers',
+      '/opt/local/lib',
+      '/opt/lib',
+      '/usr/local/lib',
+      '/usr/lib',
+    ].map { |p| Pathname(p) }.freeze
+
+    # 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
+    sig { returns(T::Array[Pathname]) }
+    def self.lib_dirs = [
+      *ENV_PARSERS,
+      *(TreeStand.config.parser_path ? [TreeStand.config.parser_path] : LIBDIRS),
+    ].compact
+
+    # The platform-specific extension of the parser.
+    # @return [String] `dylib` or `so` for mac or linux.
+    sig { returns(String) }
+    def self.ext
+      case Gem::Platform.local.os
+      in   /darwin/ then 'dylib'
+      else               'so'
+      end
+    end
+
+    # Lookup a parser by name.
+    #
+    # Precedence:
+    # 1. `Env['TREE_SITTER_PARSERS]`
+    # 2. {TreeStand::Config#parser_path}
+    # 3. {LIBDIRS}
+    #
+    # If a {TreeStand::Config#parser_path} is `nil`, {LIBDIRS} is used.
+    # If a {TreeStand::Config#parser_path} is a {::Pathname}, {LIBDIRS} is ignored.
+    sig { params(name: String).returns(T.nilable(Pathname)) }
+    def self.search_for_lib(name)
+      files = [
+        name,
+        "tree-sitter-#{name}",
+        "libtree-sitter-#{name}",
+      ].map { |v| "#{v}.#{ext}" }
+
+      res = lib_dirs
+        .product(files)
+        .find do |dir, so|
+          path = dir / so
+          path = dir / name / so if !path.exist?
+          break path.expand_path if path.exist?
+        end
+      res.is_a?(Array) ? nil : res
+    end
+
+    # Generates a string message on where parser lookup happens.
+    #
+    # @return [String] A pretty message.
+    sig { returns(String) }
+    def self.search_lib_message
+      indent = 2
+      pretty = ->(arr) {
+        if arr
+          arr
+            .compact
+            .map { |v| "#{' ' * indent}#{v.expand_path}" }
+            .join("\n")
+        end
+      }
+      <<~MSG
+        From ENV['TREE_SITTER_PARSERS']:
+        #{pretty.call(ENV_PARSERS)}
+
+        From TreeStand.config.parser_path:
+        #{pretty.call([TreeStand.config.parser_path])}
+
+        From Defaults:
+        #{pretty.call(LIBDIRS)}
+      MSG
+    end
+
+    # Load a language from configuration or default lookup paths.
+    #
+    # @example Load java from default paths
+    #    # This will look for:
+    #    #
+    #    #   tree-sitter-parsers/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /opt/local/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /opt/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /usr/local/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /usr/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #
+    #    java = TreeStand::Parser.language('java')
+    #
+    # @example Load java from a configured path
+    #    # This will look for:
+    #    #
+    #    #   /my/path/(java/)?(libtree-sitter-)?java.{ext}
+    #    #
+    #    TreeStand.config.parser_path = '/my/path'
+    #    java = TreeStand::Parser.language('java')
+    #
+    # @example Load java from environment variables
+    #    # This will look for:
+    #    #
+    #    #   /my/forced/env/path/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /my/path/(java/)?(libtree-sitter-)?java.{ext}
+    #    #
+    #    # … and the same works for the default paths if `TreeStand.config.parser_path`
+    #    # was `nil`
+    #    ENV['TREE_SITTER_PARSERS'] = '/my/forced/env/path'
+    #    TreeStand.config.parser_path = '/my/path'
+    #    java = TreeStand::Parser.language('java')
+    #
+    # @param name [String] the name of the parser.
+    #   This name is used to load the symbol from the compiled parser, replacing `-` with `_`.
+    # @return [TreeSitter:language] a language object to use in your parsers.
+    # @raise [RuntimeError] if the parser was not found.
+    # @see search_for_lib
+    sig { params(name: String).returns(TreeSitter::Language) }
+    def self.language(name)
+      lib = search_for_lib(name)
+
+      if lib.nil?
+        raise <<~MSG
+          Failed to load a parser for #{name}.
+
+          #{search_lib_message}
+        MSG
+      end
+
+      # We know that the bindings will accept `lib`, but I don't know how to tell sorbet
+      # the types in ext/tree_sitter where `load` is defined.
+      TreeSitter::Language.load(name.tr('-', '_'), T.unsafe(lib))
+    end
+
     # @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_language = Parser.language(language)
       @ts_parser = TreeSitter::Parser.new.tap do |parser|
         parser.language = @ts_language
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_tree_sitter
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: x86_64-linux
 authors:
 - Firas al-Khalil
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-10 00:00:00.000000000 Z
+date: 2024-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -74,7 +74,15 @@ files:
 - ext/tree_sitter/tree_sitter.c
 - ext/tree_sitter/tree_sitter.h
 - lib/tree_sitter.rb
+- lib/tree_sitter/helpers.rb
 - lib/tree_sitter/node.rb
+- lib/tree_sitter/query.rb
+- lib/tree_sitter/query_captures.rb
+- lib/tree_sitter/query_cursor.rb
+- lib/tree_sitter/query_match.rb
+- lib/tree_sitter/query_matches.rb
+- lib/tree_sitter/query_predicate.rb
+- lib/tree_sitter/text_predicate_capture.rb
 - lib/tree_sitter/tree_sitter.so
 - lib/tree_sitter/version.rb
 - lib/tree_stand.rb