ruby_tree_sitter 1.1.0-arm64-darwin-22

data/lib/tree_stand/parser.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around the TreeSitter parser. It looks up the parser by filename in
+  # the configured parsers directory.
+  # @example
+  #   TreeStand.configure do
+  #     config.parser_path = "path/to/parser/folder/"
+  #   end
+  #
+  #   # Looks for a parser in `path/to/parser/folder/sql.{so,dylib}`
+  #   sql_parser = TreeStand::Parser.new("sql")
+  #
+  #   # Looks for a parser in `path/to/parser/folder/ruby.{so,dylib}`
+  #   ruby_parser = TreeStand::Parser.new("ruby")
+  class Parser
+    extend T::Sig
+
+    sig { returns(TreeSitter::Language) }
+    attr_reader :ts_language
+
+    sig { returns(TreeSitter::Parser) }
+    attr_reader :ts_parser
+
+    # @param language [String]
+    sig { params(language: String).void }
+    def initialize(language)
+      @language_string = language
+      @ts_language = TreeSitter::Language.load(
+        language,
+        "#{TreeStand.config.parser_path}/#{language}.so",
+      )
+      @ts_parser = TreeSitter::Parser.new.tap do |parser|
+        parser.language = @ts_language
+      end
+    end
+
+    # Parse the provided document with the TreeSitter parser.
+    # @param tree [TreeStand::Tree, nil] providing the old tree will allow the
+    #   parser to take advantage of incremental parsing and improve performance
+    #   by re-useing nodes from the old tree.
+    sig { params(document: String, tree: T.nilable(TreeStand::Tree)).returns(TreeStand::Tree) }
+    def parse_string(document, tree: nil)
+      # @todo There's a bug with passing a non-nil tree
+      ts_tree = @ts_parser.parse_string(nil, document)
+      TreeStand::Tree.new(self, ts_tree, document)
+    end
+
+    # (see #parse_string)
+    # @note Like {#parse_string}, except that if the tree contains any parse
+    #   errors, raises an {TreeStand::InvalidDocument} error.
+    #
+    # @see #parse_string
+    # @raise [TreeStand::InvalidDocument]
+    sig { params(document: String, tree: T.nilable(TreeStand::Tree)).returns(TreeStand::Tree) }
+    def parse_string!(document, tree: nil)
+      tree = parse_string(document, tree: tree)
+      return tree unless tree.any?(&:error?)
+
+      raise(InvalidDocument, <<~ERROR)
+        Encountered errors in the document. Check the tree for more details.
+          #{tree}
+      ERROR
+    end
+  end
+end

data/lib/tree_stand/range.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around a TreeSitter range. This is mainly used to compare ranges.
+  class Range
+    extend T::Sig
+
+    # Point is a Struct containing the row and column from a TreeSitter point.
+    # TreeStand uses this to compare points.
+    # @!attribute [rw] row
+    #   @return [Integer]
+    # @!attribute [rw] column
+    #   @return [Integer]
+    Point = Struct.new(:row, :column)
+
+    sig { returns(Integer) }
+    attr_reader :start_byte
+
+    sig { returns(Integer) }
+    attr_reader :end_byte
+
+    sig { returns(TreeStand::Range::Point) }
+    attr_reader :start_point
+
+    sig { returns(TreeStand::Range::Point) }
+    attr_reader :end_point
+
+    # @api private
+    sig do
+      params(
+        start_byte: Integer,
+        end_byte: Integer,
+        start_point: T.any(TreeStand::Range::Point, TreeSitter::Point),
+        end_point: T.any(TreeStand::Range::Point, TreeSitter::Point),
+      ).void
+    end
+    def initialize(start_byte:, end_byte:, start_point:, end_point:)
+      @start_byte = start_byte
+      @end_byte = end_byte
+      @start_point = Point.new(start_point.row, start_point.column)
+      @end_point = Point.new(end_point.row, end_point.column)
+    end
+
+    sig { params(other: Object).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Range)
+
+      @start_byte == other.start_byte &&
+        @end_byte == other.end_byte &&
+        @start_point == other.start_point &&
+        @end_point == other.end_point
+    end
+  end
+end

data/lib/tree_stand/tree.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Wrapper around a TreeSitter tree.
+  #
+  # This class exposes a convient API for working with the tree. There are
+  # dangers in using this class. The tree is mutable and the document can be
+  # changed. This class does not protect against that.
+  #
+  # Some of the moetods on this class edit and re-parse the document updating
+  # the tree. Because the document is re-parsed, the tree will be different. Which
+  # means all outstanding nodes & ranges will be invalid.
+  #
+  # Methods that edit the document are suffixed with `!`, e.g. `#edit!`.
+  #
+  # It's often the case that you will want perfrom multiple edits. One such
+  # pattern is to call #query & #edit on all matches in a loop. It's important
+  # to keep the destructive nature of #edit in mind and re-issue the query
+  # after each edit.
+  #
+  # Another thing to keep in mind is that edits done later in the document will
+  # likely not affect the ranges that occur earlier in the document. This can
+  # be a convient property that could allow you to apply edits in a reverse order.
+  # This is not always possible and depends on the edits you make, beware that
+  # the tree will be different after each edit and this approach may cause bugs.
+  class Tree
+    extend T::Sig
+    extend Forwardable
+    include Enumerable
+
+    sig { returns(String) }
+    attr_reader :document
+
+    sig { returns(TreeSitter::Tree) }
+    attr_reader :ts_tree
+
+    sig { returns(TreeStand::Parser) }
+    attr_reader :parser
+
+    # @!method query(query_string)
+    #   (see TreeStand::Node#query)
+    #   @note This is a convenience method that calls {TreeStand::Node#query} on
+    #     {#root_node}.
+    #
+    # @!method find_node(query_string)
+    #   (see TreeStand::Node#find_node)
+    #   @note This is a convenience method that calls {TreeStand::Node#find_node} on
+    #     {#root_node}.
+    #
+    # @!method find_node!(query_string)
+    #   (see TreeStand::Node#find_node!)
+    #   @note This is a convenience method that calls {TreeStand::Node#find_node!} on
+    #     {#root_node}.
+    #
+    # @!method walk(&block)
+    #   (see TreeStand::Node#walk)
+    #
+    #   @note This is a convenience method that calls {TreeStand::Node#walk} on
+    #     {#root_node}.
+    #
+    #   @example Tree includes Enumerable
+    #     tree.any? { |node| node.type == :error }
+    #
+    # @!method text
+    #   (see TreeStand::Node#text)
+    #   @note This is a convenience method that calls {TreeStand::Node#text} on
+    #     {#root_node}.
+    def_delegators(
+      :root_node,
+      :query,
+      :find_node,
+      :find_node!,
+      :walk,
+      :text,
+    )
+
+    alias_method :each, :walk
+
+    # @api private
+    sig { params(parser: TreeStand::Parser, tree: TreeSitter::Tree, document: String).void }
+    def initialize(parser, tree, document)
+      @parser = parser
+      @ts_tree = tree
+      @document = document
+    end
+
+    sig { returns(TreeStand::Node) }
+    def root_node
+      TreeStand::Node.new(self, @ts_tree.root_node)
+    end
+
+    # This method replaces the section of the document specified by range and
+    # replaces it with the provided text. Then it will reparse the document and
+    # update the tree!
+    sig { params(range: TreeStand::Range, replacement: String).void }
+    def edit!(range, replacement)
+      new_document = +''
+      new_document << @document[0...range.start_byte]
+      new_document << replacement
+      new_document << @document[range.end_byte..]
+      replace_with_new_doc(new_document)
+    end
+
+    # This method deletes the section of the document specified by range. Then
+    # it will reparse the document and update the tree!
+    sig { params(range: TreeStand::Range).void }
+    def delete!(range)
+      new_document = +''
+      new_document << @document[0...range.start_byte]
+      new_document << @document[range.end_byte..]
+      replace_with_new_doc(new_document)
+    end
+
+    private
+
+    def replace_with_new_doc(new_document)
+      @document = new_document
+      new_tree = @parser.parse_string(@document, tree: self)
+      @ts_tree = new_tree.ts_tree
+    end
+  end
+end

data/lib/tree_stand/utils/printer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # A collection of useful methods for working with syntax trees.
+  module Utils
+    # Used to {TreeStand::Node#pretty_print pretty-print} the node.
+    #
+    # @example
+    #   pp node
+    #   # (expression
+    #   #  (sum
+    #   #   left: (number)              | 1
+    #   #   ("+")                       | +
+    #   #   right: (variable)))         | x
+    class Printer
+      extend T::Sig
+
+      # @param ralign the right alignment for the text column.
+      sig { params(ralign: Integer).void }
+      def initialize(ralign:)
+        @ralign = ralign
+      end
+
+      # (see TreeStand::Utils::Printer)
+      sig { params(node: TreeStand::Node, io: T.any(IO, StringIO, String)).returns(T.any(IO, StringIO, String)) }
+      def print(node, io: StringIO.new)
+        lines = pretty_output_lines(node)
+
+        lines.each do |line|
+          if line.text.empty?
+            io << line.sexpr << "\n"
+            next
+          end
+
+          io << "#{line.sexpr}#{' ' * [(@ralign - line.sexpr.size), 0].max}| #{line.text}\n"
+        end
+
+        io
+      end
+
+      private
+
+      Line = Struct.new(:sexpr, :text)
+      private_constant :Line
+
+      def pretty_output_lines(node, prefix: '', depth: 0)
+        indent = ' ' * depth
+        ts_node = node.ts_node
+        if indent.size + prefix.size + ts_node.to_s.size < @ralign || ts_node.child_count.zero?
+          return [Line.new("#{indent}#{prefix}#{ts_node}", node.text)]
+        end
+
+        lines = T.let([Line.new("#{indent}#{prefix}(#{ts_node.type}", '')], T::Array[Line])
+
+        node.each.with_index do |child, index|
+          lines += if field_name = ts_node.field_name_for_child(index)
+            pretty_output_lines(
+              child,
+              prefix: "#{field_name}: ",
+              depth: depth + 1,
+            )
+          else
+            pretty_output_lines(child, depth: depth + 1)
+          end
+        end
+
+        T.must(lines.last).sexpr << ')'
+        lines
+      end
+    end
+  end
+end

data/lib/tree_stand/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# typed: strong
+
+module TreeStand
+  # The current version of the gem.
+  VERSION = '0.2.0'
+end

data/lib/tree_stand/visitor.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # Depth-first traversal through the tree, calling hooks at each stop.
+  #
+  # Hooks are language dependent and are defined by creating methods on the
+  # visitor with the form `on_*` or `around_*`, where `*` is {Node#type}.
+  #
+  # - Hooks prefixed with `on_*` are called *before* visiting a node.
+  # - Hooks prefixed with `around_*` must `yield` to continue visiting child
+  #   nodes.
+  #
+  # You can also define default hooks by implementing an {on} or {around}
+  # method to call when visiting each node.
+  #
+  # @example Create a visitor counting certain nodes
+  #   class CountingVisitor < TreeStand::Visitor
+  #     attr_reader :count
+  #
+  #     def initialize(root, type:)
+  #       super(root)
+  #       @type = type
+  #       @count = 0
+  #     end
+  #
+  #     def on_predicate(node)
+  #       # if this node matches our search, increment the counter
+  #       @count += 1 if node.type == @type
+  #     end
+  #   end
+  #
+  #   # Initialize a visitor
+  #   visitor = CountingVisitor.new(document, :predicate).visit
+  #   # Check the result
+  #   visitor.count
+  #   # => 3
+  #
+  # @example A visitor using around hooks to contruct a tree
+  #   class TreeBuilder < TreeStand::Visitor
+  #     TreeNode = Struct.new(:name, :children)
+  #
+  #     attr_reader :stack
+  #
+  #     def initialize(root)
+  #       super(root)
+  #       @stack = []
+  #     end
+  #
+  #     def around(node)
+  #       @stack << TreeNode.new(node.type, [])
+  #
+  #       # visit all children of this node
+  #       yield
+  #
+  #       # The last node on the stack is the root of the tree.
+  #       return if @stack.size == 1
+  #
+  #       # Pop the last node off the stack and add it to the parent
+  #       @stack[-2].children << @stack.pop
+  #     end
+  #   end
+  class Visitor
+    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
+      visit_node(@node)
+      self
+    end
+
+    # @abstract The default implementation does nothing.
+    #
+    # @example Create callback to count all nodes in a tree.
+    #   def on(node)
+    #     @count += 1
+    #   end
+    sig { overridable.params(node: TreeStand::Node).void }
+    def on(node) = nil
+
+    # @abstract The default implementation yields to visit all children.
+    #
+    # @example Use around hooks to run logic before & after visiting a node. Pairs will with a stack.
+    #   def around(node)
+    #     @stack << TreeNode.new(node.type, [])
+    #
+    #     # visit all children of this node
+    #     yield
+    #
+    #     # The last node on the stack is the root of the tree.
+    #     return if @stack.size == 1
+    #
+    #     # Pop the last node off the stack and add it to the parent
+    #     @stack[-2].children << @stack.pop
+    #   end
+    sig { overridable.params(node: TreeStand::Node, block: T.proc.void).void }
+    def around(node, &block) = yield
+
+    private
+
+    def visit_node(node)
+      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| visit_node(child) }
+        end
+      else
+        around(node) do
+          node.each { |child| visit_node(child) }
+        end
+      end
+    end
+  end
+end

data/lib/tree_stand/visitors/tree_walker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  # A collection of useful visitors for traversing trees.
+  module Visitors
+    # Walks the tree depth-first and yields each node to the provided block.
+    #
+    # @example Create a list of all the nodes in the tree.
+    #   list = []
+    #   TreeStand::Visitors::TreeWalker.new(root) do |node|
+    #     list << node
+    #   end.visit
+    #
+    # @see TreeStand::Node#walk
+    # @see TreeStand::Tree#walk
+    class TreeWalker < Visitor
+      extend T::Sig
+
+      # @param block [Proc] A block that will be called for
+      #   each node in the tree.
+      sig do
+        params(
+          node: TreeStand::Node,
+          block: T.proc.params(node: TreeStand::Node).void,
+        ).void
+      end
+      def initialize(node, &block)
+        super(node)
+        @block = block
+      end
+
+      sig { override.params(node: TreeStand::Node).void }
+      def on(node) = @block.call(node)
+    end
+  end
+end

data/lib/tree_stand.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'forwardable'
+require 'sorbet-runtime'
+require 'stringio'
+require 'tree_sitter'
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/tree_sitter")
+loader.ignore("#{__dir__}/tree_sitter.rb")
+loader.setup
+
+# TreeStand is a high-level Ruby wrapper for {https://tree-sitter.github.io/tree-sitter tree-sitter} bindings. It makes
+# it easier to configure the parsers, and work with the underlying syntax tree.
+module TreeStand
+  # Common Ancestor for all TreeStand errors.
+  class Error < StandardError; end
+  # Raised when the parsed document contains errors.
+  class InvalidDocument < Error; end
+  # Raised when performing a search on a tree where a return value is expected,
+  # but no match is found.
+  class NodeNotFound < Error; end
+
+  class << self
+    extend T::Sig
+
+    # Easy configuration of the gem.
+    #
+    # @example
+    #   TreeStand.configure do
+    #     config.parser_path = "path/to/parser/folder/"
+    #   end
+    #
+    #   sql_parser = TreeStand::Parser.new("sql")
+    #   ruby_parser = TreeStand::Parser.new("ruby")
+    sig { params(block: T.proc.void).void }
+    def configure(&block)
+      instance_eval(&block)
+    end
+
+    sig { returns(TreeStand::Config) }
+    def config
+      @config ||= Config.new
+    end
+  end
+end

data/tree_sitter.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) if !$LOAD_PATH.include?(lib)
+
+require 'tree_sitter/version'
+
+Gem::Specification.new do |spec|
+  spec.required_ruby_version = '>= 3.0'
+
+  spec.authors       = ['Firas al-Khalil', 'Derek Stride']
+  spec.email         = ['firasalkhalil@gmail.com', 'derek@stride.host']
+  spec.homepage      = 'https://www.github.com/Faveod/ruby-tree-sitter'
+  spec.license       = 'MIT'
+  spec.name          = 'ruby_tree_sitter'
+  spec.summary       = 'Ruby bindings for Tree-Sitter'
+  spec.version       = TreeSitter::VERSION
+
+  spec.metadata = {
+    'allowed_push_host' => 'https://rubygems.org',
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => spec.homepage,
+    'changelog_uri' => spec.homepage,
+    'documentation_uri' => 'https://faveod.github.io/ruby-tree-sitter/',
+  }
+
+  spec.extensions    = %(ext/tree_sitter/extconf.rb)
+  spec.files         = %w[LICENSE README.md tree_sitter.gemspec]
+  spec.files        += Dir.glob('ext/**/*.{c,h,rb}')
+  spec.files        += Dir.glob('lib/**/*.rb')
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'sorbet-runtime'
+  spec.add_dependency 'zeitwerk'
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: ruby_tree_sitter
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: arm64-darwin-22
+authors:
+- Firas al-Khalil
+- Derek Stride
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-05-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- firasalkhalil@gmail.com
+- derek@stride.host
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ext/tree_sitter/encoding.c
+- ext/tree_sitter/extconf.rb
+- ext/tree_sitter/input.c
+- ext/tree_sitter/input_edit.c
+- ext/tree_sitter/language.c
+- ext/tree_sitter/logger.c
+- ext/tree_sitter/macros.h
+- ext/tree_sitter/node.c
+- ext/tree_sitter/parser.c
+- ext/tree_sitter/point.c
+- ext/tree_sitter/quantifier.c
+- ext/tree_sitter/query.c
+- ext/tree_sitter/query_capture.c
+- ext/tree_sitter/query_cursor.c
+- ext/tree_sitter/query_error.c
+- ext/tree_sitter/query_match.c
+- ext/tree_sitter/query_predicate_step.c
+- ext/tree_sitter/range.c
+- ext/tree_sitter/repo.rb
+- ext/tree_sitter/symbol_type.c
+- ext/tree_sitter/tree.c
+- ext/tree_sitter/tree_cursor.c
+- ext/tree_sitter/tree_sitter.c
+- ext/tree_sitter/tree_sitter.h
+- lib/tree_sitter.rb
+- lib/tree_sitter/node.rb
+- lib/tree_sitter/tree_sitter.bundle
+- lib/tree_sitter/version.rb
+- lib/tree_stand.rb
+- lib/tree_stand/ast_modifier.rb
+- lib/tree_stand/breadth_first_visitor.rb
+- lib/tree_stand/config.rb
+- lib/tree_stand/node.rb
+- lib/tree_stand/parser.rb
+- lib/tree_stand/range.rb
+- lib/tree_stand/tree.rb
+- lib/tree_stand/utils/printer.rb
+- lib/tree_stand/version.rb
+- lib/tree_stand/visitor.rb
+- lib/tree_stand/visitors/tree_walker.rb
+- tree_sitter.gemspec
+homepage: https://www.github.com/Faveod/ruby-tree-sitter
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://www.github.com/Faveod/ruby-tree-sitter
+  source_code_uri: https://www.github.com/Faveod/ruby-tree-sitter
+  changelog_uri: https://www.github.com/Faveod/ruby-tree-sitter
+  documentation_uri: https://faveod.github.io/ruby-tree-sitter/
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.3.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby bindings for Tree-Sitter
+test_files: []