ruby_tree_sitter 0.20.8.3 → 1.0.0

data/ext/tree_sitter/tree_cursor.c

@@ -17,58 +17,220 @@ DATA_UNWRAP(tree_cursor)
 DATA_NEW(cTreeCursor, TSTreeCursor, tree_cursor)
 DATA_FROM_VALUE(TSTreeCursor, tree_cursor)
 
-static VALUE tree_cursor_initialize(VALUE self, VALUE node) {
-  TSNode n = value_to_node(node);
-  tree_cursor_t *ptr = unwrap(self);
-  ptr->data = ts_tree_cursor_new(n);
-  return self;
-}
-
-static VALUE tree_cursor_reset(VALUE self, VALUE node) {
-  ts_tree_cursor_reset(&SELF, value_to_node(node));
-  return Qnil;
+/**
+ * Safely copy a tree cursor.
+ *
+ * @return [TreeCursor]
+ */
+static VALUE tree_cursor_copy(VALUE self) {
+  VALUE res = tree_cursor_allocate(cTreeCursor);
+  tree_cursor_t *ptr = unwrap(res);
+  ptr->data = ts_tree_cursor_copy(&SELF);
+  return res;
 }
 
-static VALUE tree_cursor_current_node(VALUE self) {
-  TSNode node = ts_tree_cursor_current_node(&SELF);
-  return new_node(&node);
+/**
+ * Get the depth of the cursor's current node relative to the original
+ * node that the cursor was constructed with.
+ *
+ * @return [Integer]
+ */
+static VALUE tree_cursor_current_depth(VALUE self) {
+  return UINT2NUM(ts_tree_cursor_current_depth(&SELF));
 }
 
-static VALUE tree_cursor_current_field_name(VALUE self) {
-  return safe_str(ts_tree_cursor_current_field_name(&SELF));
+/**
+ * Get the index of the cursor's current node out of all of the
+ * descendants of the original node that the cursor was constructed with.
+ *
+ * @return [Integer]
+ */
+static VALUE tree_cursor_current_descendant_index(VALUE self) {
+  return UINT2NUM(ts_tree_cursor_current_descendant_index(&SELF));
 }
 
+/**
+ * Get the field id of the tree cursor's current node.
+ *
+ * This returns zero if the current node doesn't have a field.
+ *
+ * @see Node#child_by_field_id
+ * @see Node#field_id_for_name
+ *
+ * @return [Integer]
+ */
 static VALUE tree_cursor_current_field_id(VALUE self) {
   return UINT2NUM(ts_tree_cursor_current_field_id(&SELF));
 }
 
-static VALUE tree_cursor_goto_parent(VALUE self) {
-  return ts_tree_cursor_goto_parent(&SELF) ? Qtrue : Qfalse;
+/**
+ * Get the field name of the tree cursor's current node.
+ *
+ * This returns +nil+ if the current node doesn't have a field.
+ *
+ * @see Node#child_by_field_name
+ *
+ * @return [String]
+ */
+static VALUE tree_cursor_current_field_name(VALUE self) {
+  return safe_str(ts_tree_cursor_current_field_name(&SELF));
 }
 
-static VALUE tree_cursor_goto_next_sibling(VALUE self) {
-  return ts_tree_cursor_goto_next_sibling(&SELF) ? Qtrue : Qfalse;
+/**
+ * Get the tree cursor's current node.
+ *
+ * @return [Node]
+ */
+static VALUE tree_cursor_current_node(VALUE self) {
+  TSNode node = ts_tree_cursor_current_node(&SELF);
+  return new_node(&node);
+}
+
+/**
+ * Move the cursor to the node that is the nth descendant of
+ * the original node that the cursor was constructed with, where
+ * zero represents the original node itself.
+ *
+ * @return [nil]
+ */
+static VALUE tree_cursor_goto_descendant(VALUE self, VALUE descendant_idx) {
+  uint32_t idx = NUM2UINT(descendant_idx);
+  ts_tree_cursor_goto_descendant(&SELF, idx);
+  return Qnil;
 }
 
+/**
+ * Move the cursor to the first child of its current node.
+ *
+ * This returns +true+ if the cursor successfully moved, and returns +false+
+ * if there were no children.
+ *
+ * @return [Boolean]
+ */
 static VALUE tree_cursor_goto_first_child(VALUE self) {
   return ts_tree_cursor_goto_first_child(&SELF) ? Qtrue : Qfalse;
 }
 
+/**
+ * Move the cursor to the first child of its current node that extends beyond
+ * the given byte offset.
+ *
+ * This returns the index of the child node if one was found, and returns -1
+ * if no such child was found.
+ *
+ * @return [Integer]
+ */
 static VALUE tree_cursor_goto_first_child_for_byte(VALUE self, VALUE byte) {
   return LL2NUM(
       ts_tree_cursor_goto_first_child_for_byte(&SELF, NUM2UINT(byte)));
 }
 
+/**
+ * Move the cursor to the first child of its current node that extends beyond
+ * the given or point.
+ *
+ * This returns the index of the child node if one was found, and returns -1
+ * if no such child was found.
+ *
+ * @return [Integer]
+ */
 static VALUE tree_cursor_goto_first_child_for_point(VALUE self, VALUE point) {
   return LL2NUM(
       ts_tree_cursor_goto_first_child_for_point(&SELF, value_to_point(point)));
 }
 
-static VALUE tree_cursor_copy(VALUE self) {
-  VALUE res = tree_cursor_allocate(cTreeCursor);
-  tree_cursor_t *ptr = unwrap(res);
-  ptr->data = ts_tree_cursor_copy(&SELF);
-  return res;
+/**
+ * Move the cursor to the last child of its current node.
+ *
+ * This returns +true+ if the cursor successfully moved, and returns +false+ if
+ * there were no children.
+ *
+ * Note that this function may be slower than {#goto_first_child}
+ * because it needs to iterate through all the children to compute the child's
+ * position.
+ */
+static VALUE tree_cursor_goto_last_child(VALUE self) {
+  return ts_tree_cursor_goto_last_child(&SELF) ? Qtrue : Qfalse;
+}
+
+/**
+ * Move the cursor to the next sibling of its current node.
+ *
+ * This returns +true+ if the cursor successfully moved, and returns +false+
+ * if there was no next sibling node.
+ *
+ * @return Boolean
+ */
+static VALUE tree_cursor_goto_next_sibling(VALUE self) {
+  return ts_tree_cursor_goto_next_sibling(&SELF) ? Qtrue : Qfalse;
+}
+
+/**
+ * Move the cursor to the parent of its current node.
+ *
+ * This returns +true+ if the cursor successfully moved, and returns +false+
+ * if there was no parent node (the cursor was already on the root node).
+ *
+ * @return [Boolean]
+ */
+static VALUE tree_cursor_goto_parent(VALUE self) {
+  return ts_tree_cursor_goto_parent(&SELF) ? Qtrue : Qfalse;
+}
+
+/**
+ * Move the cursor to the previous sibling of its current node.
+ *
+ * This returns +true+ if the cursor successfully moved, and returns +false+ if
+ * there was no previous sibling node.
+ *
+ * Note, that this function may be slower than
+ * {#goto_next_sibling} due to how node positions are stored. In
+ * the worst case, this will need to iterate through all the children upto the
+ * previous sibling node to recalculate its position.
+ *
+ * @return [Boolean]
+ */
+static VALUE tree_cursor_goto_previous_sibling(VALUE self) {
+  return ts_tree_cursor_goto_previous_sibling(&SELF) ? Qtrue : Qfalse;
+}
+
+/**
+ * Create a new tree cursor starting from the given node.
+ *
+ * A tree cursor allows you to walk a syntax tree more efficiently than is
+ * possible using the {Node} functions. It is a mutable object that is always
+ * on a certain syntax node, and can be moved imperatively to different nodes.
+ *
+ * @return [TreeCursor]
+ */
+static VALUE tree_cursor_initialize(VALUE self, VALUE node) {
+  TSNode n = value_to_node(node);
+  tree_cursor_t *ptr = unwrap(self);
+  ptr->data = ts_tree_cursor_new(n);
+  return self;
+}
+
+/**
+ * Re-initialize a tree cursor to start at a different node.
+ *
+ * @return [nil]
+ */
+static VALUE tree_cursor_reset(VALUE self, VALUE node) {
+  ts_tree_cursor_reset(&SELF, value_to_node(node));
+  return Qnil;
+}
+
+/**
+ * Re-initialize a tree cursor to the same position as another cursor.
+ *
+ * Unlike {#reset}, this will not lose parent information and allows reusing
+ * already created cursors.
+ *
+ * @return [nil]
+ */
+VALUE tree_cursor_reset_to(VALUE self, VALUE src) {
+  ts_tree_cursor_reset_to(&SELF, &unwrap(src)->data);
+  return Qnil;
 }
 
 void init_tree_cursor(void) {
@@ -77,21 +239,31 @@ void init_tree_cursor(void) {
   rb_define_alloc_func(cTreeCursor, tree_cursor_allocate);
 
   /* Class methods */
-  rb_define_method(cTreeCursor, "initialize", tree_cursor_initialize, 1);
-  rb_define_method(cTreeCursor, "reset", tree_cursor_reset, 1);
-  rb_define_method(cTreeCursor, "current_node", tree_cursor_current_node, 0);
-  rb_define_method(cTreeCursor, "current_field_name",
-                   tree_cursor_current_field_name, 0);
+  rb_define_method(cTreeCursor, "copy", tree_cursor_copy, 0);
+  rb_define_method(cTreeCursor, "current_depth", tree_cursor_current_depth, 0);
+  rb_define_method(cTreeCursor, "current_descendant_index",
+                   tree_cursor_current_descendant_index, 0);
   rb_define_method(cTreeCursor, "current_field_id",
                    tree_cursor_current_field_id, 0);
-  rb_define_method(cTreeCursor, "goto_parent", tree_cursor_goto_parent, 0);
-  rb_define_method(cTreeCursor, "goto_next_sibling",
-                   tree_cursor_goto_next_sibling, 0);
+  rb_define_method(cTreeCursor, "current_field_name",
+                   tree_cursor_current_field_name, 0);
+  rb_define_method(cTreeCursor, "current_node", tree_cursor_current_node, 0);
+  rb_define_method(cTreeCursor, "goto_descendant", tree_cursor_goto_descendant,
+                   1);
   rb_define_method(cTreeCursor, "goto_first_child",
                    tree_cursor_goto_first_child, 0);
   rb_define_method(cTreeCursor, "goto_first_child_for_byte",
                    tree_cursor_goto_first_child_for_byte, 1);
   rb_define_method(cTreeCursor, "goto_first_child_for_point",
                    tree_cursor_goto_first_child_for_point, 1);
-  rb_define_method(cTreeCursor, "copy", tree_cursor_copy, 0);
+  rb_define_method(cTreeCursor, "goto_last_child", tree_cursor_goto_last_child,
+                   0);
+  rb_define_method(cTreeCursor, "goto_next_sibling",
+                   tree_cursor_goto_next_sibling, 0);
+  rb_define_method(cTreeCursor, "goto_parent", tree_cursor_goto_parent, 0);
+  rb_define_method(cTreeCursor, "goto_previous_sibling",
+                   tree_cursor_goto_previous_sibling, 0);
+  rb_define_method(cTreeCursor, "initialize", tree_cursor_initialize, 1);
+  rb_define_method(cTreeCursor, "reset", tree_cursor_reset, 1);
+  rb_define_method(cTreeCursor, "reset_to", tree_cursor_reset_to, 1);
 }

data/ext/tree_sitter/tree_sitter.c

@@ -5,8 +5,20 @@ VALUE mTreeSitter;
 void Init_tree_sitter() {
   mTreeSitter = rb_define_module("TreeSitter");
 
+  /**
+   * The latest ABI version that is supported by the current version of the
+   * library. When Languages are generated by the Tree-sitter CLI, they are
+   * assigned an ABI version number that corresponds to the current CLI version.
+   * The Tree-sitter library is generally backwards-compatible with languages
+   * generated using older CLI versions, but is not forwards-compatible.
+   */
   rb_define_const(mTreeSitter, "LANGUAGE_VERSION",
                   INT2NUM(TREE_SITTER_LANGUAGE_VERSION));
+
+  /**
+   * The earliest ABI version that is supported by the current version of the
+   * library.
+   */
   rb_define_const(mTreeSitter, "MIN_COMPATIBLE_LANGUAGE_VERSION",
                   TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION);
 

data/lib/tree_sitter/node.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module TreeSitter
+  # Node is a wrapper around a tree-sitter node.
   class Node
+    # @return [Array<Symbol>] the node's named fields
     def fields
       return @fields if @fields
 
@@ -18,6 +20,18 @@ module TreeSitter
       fields.include?(field)
     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
@@ -49,13 +63,11 @@ module TreeSitter
       when 0 then raise "#{self.class.name}##{__method__} requires a key."
       when 1
         case k = keys.first
-        when Numeric        then named_child(k)
+        when Numeric then named_child(k)
         when String, Symbol
-          if fields.include?(k.to_sym)
-            child_by_field_name(k.to_s)
-          else
-            raise "Cannot find field #{k}"
-          end
+          raise "Cannot find field #{k}" unless fields.include?(k.to_sym)
+
+          child_by_field_name(k.to_s)
         else raise <<~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.
@@ -66,6 +78,8 @@ module TreeSitter
       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)
@@ -75,6 +89,8 @@ module TreeSitter
       end
     end
 
+    # @!visibility private
+    #
     def respond_to_missing?(*args)
       args.length == 1 && fields.include?(args[0])
     end
@@ -116,6 +132,7 @@ module TreeSitter
       end
     end
 
+    # @return [Array<TreeSitter::Node>] all the node's children
     def to_a
       each.to_a
     end

data/lib/tree_sitter/version.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module TreeSitter
-  TREESITTER_VERSION = '0.20.8'
-  VERSION = "#{TREESITTER_VERSION}.3".freeze
+  # The version of the tree-sitter library.
+  TREESITTER_VERSION = '0.20.9'
+  # The current version of the gem.
+  VERSION = '1.0.0'
 end

data/lib/tree_sitter.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# TreeSitter is a Ruby interface to the tree-sitter parsing library.
 module TreeSitter
 end
 

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

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,13 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Global configuration for the gem.
+  # @api private
+  class Config
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_accessor :parser_path
+  end
+end