ruby_tree_sitter 1.1.0-arm64-darwin-22

data/ext/tree_sitter/tree_sitter.c

@@ -0,0 +1,44 @@
+#include "tree_sitter.h"
+
+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);
+
+  init_encoding();
+  init_input();
+  init_input_edit();
+  init_language();
+  init_logger();
+  init_node();
+  init_parser();
+  init_point();
+  init_quantifier();
+  init_query();
+  init_query_capture();
+  init_query_cursor();
+  init_query_error();
+  init_query_match();
+  init_query_predicate_step();
+  init_range();
+  init_symbol_type();
+  init_tree();
+  init_tree_cursor();
+}

data/ext/tree_sitter/tree_sitter.h

@@ -0,0 +1,107 @@
+#ifndef _RB_TREE_SITTER_H
+#define _RB_TREE_SITTER_H
+
+#include "macros.h"
+#include <dlfcn.h>
+#include <fcntl.h>
+#include <ruby.h>
+#include <stdio.h>
+#include <string.h>
+#include <tree_sitter/api.h>
+
+static inline VALUE safe_str(const char *str) {
+  if (str == NULL) {
+    return Qnil;
+  } else {
+    return rb_utf8_str_new_cstr(str);
+  }
+}
+
+static inline VALUE safe_str2(const char *str, uint32_t len) {
+  if (str == NULL) {
+    return Qnil;
+  } else if (len == 0) {
+    return rb_utf8_str_new_cstr("");
+  } else {
+    return rb_utf8_str_new(str, len);
+  }
+}
+
+static inline VALUE safe_symbol(const char *str) {
+  if (str == NULL) {
+    return Qnil;
+  } else {
+    return ID2SYM(rb_intern(str));
+  }
+}
+
+// VALUE to TS* converters
+
+TSInput value_to_input(VALUE);
+TSInputEdit value_to_input_edit(VALUE);
+TSInputEncoding value_to_encoding(VALUE);
+TSLanguage *value_to_language(VALUE);
+TSLogger value_to_logger(VALUE);
+TSNode value_to_node(VALUE);
+TSPoint value_to_point(VALUE);
+TSQuantifier value_to_quantifier(VALUE);
+TSQuery *value_to_query(VALUE);
+TSQueryCursor *value_to_query_cursor(VALUE);
+TSQueryError value_to_query_error(VALUE);
+TSQueryMatch value_to_query_match(VALUE);
+TSQueryPredicateStep value_to_query_predicate_step(VALUE);
+TSQueryPredicateStepType value_to_query_predicate_step_type(VALUE);
+TSRange value_to_range(VALUE);
+TSSymbolType value_to_symbol_type(VALUE);
+TSTree *value_to_tree(VALUE);
+TSTreeCursor value_to_tree_cursor(VALUE);
+
+// TS* to VALUE converters
+VALUE new_input(const TSInput *);
+VALUE new_language(const TSLanguage *);
+VALUE new_logger(const TSLogger *);
+VALUE new_logger_by_val(TSLogger);
+VALUE new_node(const TSNode *);
+VALUE new_node_by_val(TSNode);
+VALUE new_point(const TSPoint *);
+VALUE new_point_by_val(TSPoint);
+VALUE new_query_capture(const TSQueryCapture *);
+VALUE new_query_match(const TSQueryMatch *);
+VALUE new_query_predicate_step(const TSQueryPredicateStep *);
+VALUE new_range(const TSRange *);
+VALUE new_symbol_type(TSSymbolType);
+VALUE new_tree(TSTree *);
+
+// All init_* functions are called from Init_tree_sitter
+void init_encoding(void);
+void init_input(void);
+void init_input_edit(void);
+void init_language(void);
+void init_logger(void);
+void init_node(void);
+void init_parser(void);
+void init_point(void);
+void init_quantifier(void);
+void init_query(void);
+void init_query_capture(void);
+void init_query_cursor(void);
+void init_query_error(void);
+void init_query_match(void);
+void init_query_predicate_step(void);
+void init_range(void);
+void init_symbol_type(void);
+void init_tree(void);
+void init_tree_cursor(void);
+
+// Other helpers
+const char *quantifier_str(TSQuantifier);
+const char *query_error_str(TSQueryError);
+
+// TSTree reference counting
+int tree_rc_free(const TSTree *);
+void tree_rc_new(const TSTree *);
+
+// This is a special entry-point for the extension
+void Init_tree_sitter(void);
+
+#endif

data/lib/tree_sitter/node.rb

@@ -0,0 +1,197 @@
+# 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
+
+      @fields = Set.new
+      child_count.times do |i|
+        name = field_name_for_child(i)
+        @fields << name.to_sym if name
+      end
+
+      @fields
+    end
+
+    def field?(field)
+      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
+    # 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 "#{self.class.name}##{__method__} requires a key."
+      when 1
+        case k = keys.first
+        when Numeric then named_child(k)
+        when String, Symbol
+          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.
+        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
+      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 {#fetch}, but differes 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
+    #              ------------------------------+----------------------
+    # @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
+
+      res = {}
+      each_field do |f, c|
+        if dict.key?(f)
+          res[f] = c
+          dict.delete(f)
+        end
+        break if dict.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)
+    end
+  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.1.0'
+end

data/lib/tree_sitter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# TreeSitter is a Ruby interface to the tree-sitter parsing library.
+module TreeSitter
+end
+
+require 'set'
+
+require 'tree_sitter/version'
+
+require 'tree_sitter/tree_sitter'
+require 'tree_sitter/node'
+
+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

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

data/lib/tree_stand/node.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around a TreeSitter node and provides convient
+  # methods that are missing on the original node. This class
+  # overrides the `method_missing` method to delegate to a nodes
+  # named children.
+  class Node
+    extend T::Sig
+    extend Forwardable
+    include Enumerable
+
+    # @!method type
+    #   @return [Symbol] the type of the node in the tree-sitter grammar.
+    # @!method error?
+    #   @return [bool] true if the node is an error node.
+    def_delegators(
+      :@ts_node,
+      :type,
+      :error?,
+    )
+
+    sig { returns(TreeStand::Tree) }
+    attr_reader :tree
+
+    sig { returns(TreeSitter::Node) }
+    attr_reader :ts_node
+
+    # @api private
+    sig { params(tree: TreeStand::Tree, ts_node: TreeSitter::Node).void }
+    def initialize(tree, ts_node)
+      @tree = tree
+      @ts_node = ts_node
+      @fields = @ts_node.each_field.to_a.map(&:first)
+    end
+
+    # TreeSitter uses a `TreeSitter::Cursor` to iterate over matches by calling
+    # `curser#next_match` repeatedly until it returns `nil`.
+    #
+    # This method does all of that for you and collects all of the matches into
+    # an array and each corresponding capture into a hash.
+    #
+    # @example
+    #   # This will return a match for each identifier nodes in the tree.
+    #   tree_matches = tree.query(<<~QUERY)
+    #     (identifier) @identifier
+    #   QUERY
+    #
+    #   # It is equivalent to:
+    #   tree.root_node.query(<<~QUERY)
+    #     (identifier) @identifier
+    #   QUERY
+    sig { params(query_string: String).returns(T::Array[T::Hash[String, TreeStand::Node]]) }
+    def query(query_string)
+      ts_query = TreeSitter::Query.new(@tree.parser.ts_language, query_string)
+      ts_cursor = TreeSitter::QueryCursor.exec(ts_query, ts_node)
+      matches = []
+      while ts_match = ts_cursor.next_match
+        captures = {}
+
+        ts_match.captures.each do |ts_capture|
+          capture_name = ts_query.capture_name_for_id(ts_capture.index)
+          captures[capture_name] = TreeStand::Node.new(@tree, ts_capture.node)
+        end
+
+        matches << captures
+      end
+      matches
+    end
+
+    # Returns the first captured node that matches the query string or nil if
+    # there was no captured node.
+    #
+    # @example Find the first identifier node.
+    #   identifier_node = tree.root_node.find_node("(identifier) @identifier")
+    #
+    # @see #find_node!
+    # @see #query
+    sig { params(query_string: String).returns(T.nilable(TreeStand::Node)) }
+    def find_node(query_string)
+      query(query_string).first&.values&.first
+    end
+
+    # Like {#find_node}, except that if no node is found, raises an
+    # {TreeStand::NodeNotFound} error.
+    #
+    # @see #find_node
+    # @raise [TreeStand::NodeNotFound]
+    sig { params(query_string: String).returns(TreeStand::Node) }
+    def find_node!(query_string)
+      find_node(query_string) || raise(TreeStand::NodeNotFound)
+    end
+
+    sig { returns(TreeStand::Range) }
+    def range
+      TreeStand::Range.new(
+        start_byte: @ts_node.start_byte,
+        end_byte: @ts_node.end_byte,
+        start_point: @ts_node.start_point,
+        end_point: @ts_node.end_point,
+      )
+    end
+
+    # Node includes enumerable so that you can iterate over the child nodes.
+    # @example
+    #   node.text # => "3 * 4"
+    #
+    # @example Iterate over the child nodes
+    #   node.each do |child|
+    #     print child.text
+    #   end
+    #   # prints: 3*4
+    #
+    # @example Enumerable methods
+    #   node.map(&:text) # => ["3", "*", "4"]
+    #
+    # @yieldparam child [TreeStand::Node]
+    sig do
+      override
+        .params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
+    def each(&block)
+      enumerator = Enumerator.new do |yielder|
+        @ts_node.each do |child|
+          yielder << TreeStand::Node.new(@tree, child)
+        end
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # (see TreeStand::Visitors::TreeWalker)
+    # Backed by {TreeStand::Visitors::TreeWalker}.
+    #
+    # @example Check the subtree for error nodes
+    #   node.walk.any? { |node| node.type == :error }
+    #
+    # @see TreeStand::Visitors::TreeWalker
+    #
+    # @yieldparam node [TreeStand::Node]
+    sig do
+      params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
+    def walk(&block)
+      enumerator = Enumerator.new do |yielder|
+        Visitors::TreeWalker.new(self) do |child|
+          yielder << child
+        end.visit
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # @example
+    #   node.text # => "4"
+    #   node.parent.text # => "3 * 4"
+    #   node.parent.parent.text # => "1 + 3 * 4"
+    sig { returns(TreeStand::Node) }
+    def parent
+      TreeStand::Node.new(@tree, @ts_node.parent)
+    end
+
+    # @example
+    #   node.text # => "3 * 4"
+    #   node.to_a.map(&:text) # => ["3", "*", "4"]
+    #   node.children.map(&:text) # => ["3", "*", "4"]
+    sig { returns(T::Array[TreeStand::Node]) }
+    def children = to_a
+
+    # A convenience method for getting the text of the node. Each {TreeStand::Node}
+    # wraps the parent {TreeStand::Tree #tree} and has access to the source document.
+    sig { returns(String) }
+    def text
+      T.must(@tree.document[@ts_node.start_byte...@ts_node.end_byte])
+    end
+
+    # This class overrides the `method_missing` method to delegate to the
+    # node's named children.
+    # @example
+    #   node.text          # => "3 * 4"
+    #
+    #   node.left.text     # => "3"
+    #   node.operator.text # => "*"
+    #   node.right.text    # => "4"
+    #   node.operand       # => NoMethodError
+    # @overload method_missing(field_name)
+    #   @param name [Symbol, String]
+    #   @return [TreeStand::Node] child node for the given field name
+    #   @raise [NoMethodError] Raised if the node does not have child with name `field_name`
+    #
+    # @overload method_missing(method_name, *args, &block)
+    #   @raise [NoMethodError]
+    def method_missing(method, *args, &block)
+      return super unless @fields.include?(method.to_s)
+
+      TreeStand::Node.new(@tree, T.unsafe(@ts_node).public_send(method, *args, &block))
+    end
+
+    sig { params(other: Object).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Node)
+
+      T.must(range == other.range && type == other.type && text == other.text)
+    end
+
+    # (see TreeStand::Utils::Printer)
+    # Backed by {TreeStand::Utils::Printer}.
+    #
+    # @see TreeStand::Utils::Printer
+    sig { params(pp: PP).void }
+    def pretty_print(pp)
+      Utils::Printer.new(ralign: 80).print(self, io: pp.output)
+    end
+
+    private
+
+    def respond_to_missing?(method, *)
+      @fields.include?(method.to_s) || super
+    end
+  end
+end