tree_haver 1.0.0 → 2.0.0

data/lib/tree_haver/backends/citrus.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Backends
+    # Citrus backend using pure Ruby PEG parser
+    #
+    # This backend wraps Citrus-based parsers (like toml-rb) to provide a
+    # pure Ruby alternative to tree-sitter. Citrus is a PEG (Parsing Expression
+    # Grammar) parser generator written in Ruby.
+    #
+    # Unlike tree-sitter backends which are language-agnostic runtime parsers,
+    # Citrus parsers are grammar-specific and compiled into Ruby code. Each
+    # language needs its own Citrus grammar (e.g., toml-rb for TOML).
+    #
+    # @note This backend requires a Citrus grammar for the specific language
+    # @see https://github.com/mjackson/citrus Citrus parser generator
+    # @see https://github.com/emancu/toml-rb toml-rb (TOML Citrus grammar)
+    #
+    # @example Using with toml-rb
+    #   require "toml-rb"
+    #
+    #   parser = TreeHaver::Parser.new
+    #   # For Citrus, "language" is actually a grammar module
+    #   parser.language = TomlRB::Document
+    #   tree = parser.parse(toml_source)
+    module Citrus
+      @load_attempted = false
+      @loaded = false
+
+      # Check if the Citrus backend is available
+      #
+      # Attempts to require citrus on first call and caches the result.
+      #
+      # @return [Boolean] true if citrus gem is available
+      # @example
+      #   if TreeHaver::Backends::Citrus.available?
+      #     puts "Citrus backend is ready"
+      #   end
+      class << self
+        def available?
+          return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          begin
+            require "citrus"
+
+            @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          rescue LoadError
+            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          end
+          @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
+        end
+
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+        end
+
+        # Get capabilities supported by this backend
+        #
+        # @return [Hash{Symbol => Object}] capability map
+        # @example
+        #   TreeHaver::Backends::Citrus.capabilities
+        #   # => { backend: :citrus, query: false, bytes_field: true, incremental: false }
+        def capabilities
+          return {} unless available?
+          {
+            backend: :citrus,
+            query: false,          # Citrus doesn't have a query API like tree-sitter
+            bytes_field: true,     # Citrus::Match provides offset and length
+            incremental: false,    # Citrus doesn't support incremental parsing
+            pure_ruby: true,       # Citrus is pure Ruby (portable)
+          }
+        end
+      end
+
+      # Citrus grammar wrapper
+      #
+      # Unlike tree-sitter which loads compiled .so files, Citrus uses Ruby modules
+      # that define grammars. This class wraps a Citrus grammar module.
+      #
+      # @example
+      #   # For TOML, use toml-rb's grammar
+      #   language = TreeHaver::Backends::Citrus::Language.new(TomlRB::Document)
+      class Language
+        # The Citrus grammar module
+        # @return [Module] Citrus grammar module (e.g., TomlRB::Document)
+        attr_reader :grammar_module
+
+        # @param grammar_module [Module] A Citrus grammar module with a parse method
+        def initialize(grammar_module)
+          unless grammar_module.respond_to?(:parse)
+            raise TreeHaver::NotAvailable,
+              "Grammar module must respond to :parse. " \
+                "Expected a Citrus grammar module (e.g., TomlRB::Document)."
+          end
+          @grammar_module = grammar_module
+        end
+
+        # Not applicable for Citrus (tree-sitter-specific)
+        #
+        # Citrus grammars are Ruby modules, not shared libraries.
+        # This method exists for API compatibility but will raise an error.
+        #
+        # @raise [TreeHaver::NotAvailable] always raises
+        class << self
+          def from_library(path, symbol: nil, name: nil)
+            raise TreeHaver::NotAvailable,
+              "Citrus backend doesn't use shared libraries. " \
+                "Use Citrus::Language.new(GrammarModule) instead."
+          end
+
+          alias_method :from_path, :from_library
+        end
+      end
+
+      # Citrus parser wrapper
+      #
+      # Wraps Citrus grammar modules to provide a tree-sitter-like API.
+      class Parser
+        # Create a new Citrus parser instance
+        #
+        # @raise [TreeHaver::NotAvailable] if citrus gem is not available
+        def initialize
+          raise TreeHaver::NotAvailable, "citrus gem not available" unless Citrus.available?
+          @grammar = nil
+        end
+
+        # Set the grammar for this parser
+        #
+        # @param grammar [Language, Module] Citrus grammar module or Language wrapper
+        # @return [Language, Module] the grammar that was set
+        # @example
+        #   require "toml-rb"
+        #   parser.language = TomlRB::Document  # Pass module directly
+        #   # or
+        #   parser.language = TreeHaver::Backends::Citrus::Language.new(TomlRB::Document)
+        def language=(grammar)
+          @grammar = if grammar.respond_to?(:grammar_module)
+            grammar.grammar_module
+          elsif grammar.respond_to?(:parse)
+            grammar
+          else
+            raise ArgumentError,
+              "Expected Citrus grammar module or Language wrapper, " \
+                "got #{grammar.class}"
+          end
+          grammar
+        end
+
+        # Parse source code
+        #
+        # @param source [String] the source code to parse
+        # @return [TreeHaver::Tree] wrapped tree
+        # @raise [TreeHaver::NotAvailable] if no grammar is set
+        # @raise [::Citrus::ParseError] if parsing fails
+        def parse(source)
+          raise TreeHaver::NotAvailable, "No grammar loaded" unless @grammar
+
+          begin
+            citrus_match = @grammar.parse(source)
+            inner_tree = Tree.new(citrus_match, source)
+            TreeHaver::Tree.new(inner_tree, source: source)
+          rescue ::Citrus::ParseError => e
+            # Re-raise with more context
+            raise TreeHaver::Error, "Parse error: #{e.message}"
+          end
+        end
+
+        # Parse source code (compatibility with tree-sitter API)
+        #
+        # Citrus doesn't support incremental parsing, so old_tree is ignored.
+        #
+        # @param old_tree [TreeHaver::Tree, nil] ignored (no incremental parsing support)
+        # @param source [String] the source code to parse
+        # @return [TreeHaver::Tree] wrapped tree
+        def parse_string(old_tree, source)
+          parse(source)  # Citrus doesn't support incremental parsing
+        end
+      end
+
+      # Citrus tree wrapper
+      #
+      # Wraps a Citrus::Match (which represents the parse tree) to provide
+      # tree-sitter-compatible API.
+      #
+      # @api private
+      class Tree
+        attr_reader :root_match, :source
+
+        def initialize(root_match, source)
+          @root_match = root_match
+          @source = source
+        end
+
+        def root_node
+          Node.new(@root_match, @source)
+        end
+      end
+
+      # Citrus node wrapper
+      #
+      # Wraps Citrus::Match objects to provide tree-sitter-compatible node API.
+      #
+      # Citrus::Match provides:
+      # - events[0]: rule name (Symbol) - used as type
+      # - offset: byte position
+      # - length: byte length
+      # - string: matched text
+      # - matches: child matches
+      # - captures: named groups
+      #
+      # @api private
+      class Node
+        attr_reader :match, :source
+
+        def initialize(match, source)
+          @match = match
+          @source = source
+        end
+
+        # Get node type from Citrus rule name
+        #
+        # @return [String] rule name from grammar
+        def type
+          # Citrus stores the rule name in events[0]
+          return "unknown" unless @match.respond_to?(:events)
+          return "unknown" unless @match.events.is_a?(Array)
+          return "unknown" if @match.events.empty?
+
+          first = @match.events.first
+          first.is_a?(Symbol) ? first.to_s : "unknown"
+        end
+
+        def start_byte
+          @match.offset
+        end
+
+        def end_byte
+          @match.offset + @match.length
+        end
+
+        def start_point
+          calculate_point(@match.offset)
+        end
+
+        def end_point
+          calculate_point(@match.offset + @match.length)
+        end
+
+        def text
+          @match.string
+        end
+
+        def child_count
+          @match.respond_to?(:matches) ? @match.matches.size : 0
+        end
+
+        def child(index)
+          return unless @match.respond_to?(:matches)
+          return if index >= @match.matches.size
+
+          Node.new(@match.matches[index], @source)
+        end
+
+        def children
+          return [] unless @match.respond_to?(:matches)
+          @match.matches.map { |m| Node.new(m, @source) }
+        end
+
+        def each(&block)
+          return to_enum(__method__) unless block_given?
+          children.each(&block)
+        end
+
+        def has_error?
+          false  # Citrus raises on parse error, so successful parse has no errors
+        end
+
+        def missing?
+          false  # Citrus doesn't have the concept of missing nodes
+        end
+
+        def named?
+          true  # Citrus matches are typically "named" in tree-sitter terminology
+        end
+
+        private
+
+        def calculate_point(offset)
+          lines_before = @source[0...offset].count("\n")
+          line_start = @source.rindex("\n", offset - 1) || -1
+          column = offset - line_start - 1
+          {row: lines_before, column: column}
+        end
+      end
+    end
+  end
+end

data/lib/tree_haver/backends/ffi.rb

@@ -14,7 +14,7 @@ module TreeHaver
   module Backends
     # FFI-based backend for calling libtree-sitter directly
     #
-    # This backend uses Ruby FFI (JNR-FFI on JRuby) to call the native Tree-sitter
+    # This backend uses Ruby FFI (JNR-FFI on JRuby) to call the native tree-sitter
     # C library without requiring MRI C extensions. This makes it compatible with
     # JRuby, TruffleRuby, and other Ruby implementations that support FFI.
     #
@@ -24,16 +24,16 @@ module TreeHaver
     # - Accessing node types and children
     #
     # Not yet supported:
-    # - Query API (Tree-sitter queries/patterns)
+    # - Query API (tree-sitter queries/patterns)
     #
     # @note Requires the `ffi` gem and libtree-sitter shared library to be installed
     # @see https://github.com/ffi/ffi Ruby FFI
-    # @see https://tree-sitter.github.io/tree-sitter/ Tree-sitter
+    # @see https://tree-sitter.github.io/tree-sitter/ tree-sitter
     module FFI
       # Native FFI bindings to libtree-sitter
       #
-      # This module handles loading the Tree-sitter runtime library and defining
-      # FFI function attachments for the core Tree-sitter API.
+      # This module handles loading the tree-sitter runtime library and defining
+      # FFI function attachments for the core tree-sitter API.
       #
       # @api private
       module Native
@@ -42,8 +42,8 @@ module TreeHaver
 
           # FFI struct representation of TSNode
           #
-          # Mirrors the C struct layout used by Tree-sitter. TSNode is passed
-          # by value in the Tree-sitter C API.
+          # Mirrors the C struct layout used by tree-sitter. TSNode is passed
+          # by value in the tree-sitter C API.
           #
           # @api private
           class TSNode < ::FFI::Struct
@@ -79,10 +79,10 @@ module TreeHaver
               ].compact
             end
 
-            # Load the Tree-sitter runtime library
+            # Load the tree-sitter runtime library
             #
             # Tries each candidate library name in order until one succeeds.
-            # After loading, attaches FFI function definitions for the Tree-sitter API.
+            # After loading, attaches FFI function definitions for the tree-sitter API.
             #
             # @raise [TreeHaver::NotAvailable] if no library can be loaded
             # @return [void]
@@ -189,7 +189,7 @@ module TreeHaver
         end
       end
 
-      # Represents a Tree-sitter language loaded via FFI
+      # Represents a tree-sitter language loaded via FFI
       #
       # Holds a pointer to a TSLanguage struct from a loaded shared library.
       class Language
@@ -276,7 +276,7 @@ module TreeHaver
         end
       end
 
-      # FFI-based Tree-sitter parser
+      # FFI-based tree-sitter parser
       #
       # Wraps a TSParser pointer and manages its lifecycle with a finalizer.
       class Parser
@@ -323,18 +323,19 @@ module TreeHaver
         # Parse source code into a syntax tree
         #
         # @param source [String] the source code to parse (should be UTF-8)
-        # @return [Tree] the parsed syntax tree
+        # @return [TreeHaver::Tree] wrapped tree
         # @raise [TreeHaver::NotAvailable] if parsing fails
         def parse(source)
           src = String(source)
           tree_ptr = Native.ts_parser_parse_string(@parser, ::FFI::Pointer::NULL, src, src.bytesize)
           raise TreeHaver::NotAvailable, "Parse returned NULL" if tree_ptr.null?
 
-          Tree.new(tree_ptr)
+          inner_tree = Tree.new(tree_ptr)
+          TreeHaver::Tree.new(inner_tree, source: src)
         end
       end
 
-      # FFI-based Tree-sitter tree
+      # FFI-based tree-sitter tree
       #
       # Wraps a TSTree pointer and manages its lifecycle with a finalizer.
       class Tree
@@ -369,10 +370,10 @@ module TreeHaver
         end
       end
 
-      # FFI-based Tree-sitter node
+      # FFI-based tree-sitter node
       #
       # Wraps a TSNode by-value struct. TSNode is passed by value in the
-      # Tree-sitter C API, so we store the struct value directly.
+      # tree-sitter C API, so we store the struct value directly.
       class Node
         # @api private
         # @param ts_node_value [Native::TSNode] the TSNode struct (by value)
@@ -388,6 +389,63 @@ module TreeHaver
           Native.ts_node_type(@val)
         end
 
+        # Get the number of children
+        #
+        # @return [Integer] child count
+        def child_count
+          Native.ts_node_child_count(@val)
+        end
+
+        # Get a child by index
+        #
+        # @param index [Integer] child index
+        # @return [Node, nil] child node or nil if index out of bounds
+        def child(index)
+          return if index >= child_count || index < 0
+          child_node = Native.ts_node_child(@val, index)
+          Node.new(child_node)
+        end
+
+        # Get start byte offset
+        #
+        # @return [Integer]
+        def start_byte
+          Native.ts_node_start_byte(@val)
+        end
+
+        # Get end byte offset
+        #
+        # @return [Integer]
+        def end_byte
+          Native.ts_node_end_byte(@val)
+        end
+
+        # Get start point
+        #
+        # @return [Object] with row and column
+        def start_point
+          # FFI backend would need to implement ts_node_start_point
+          # For now, return a simple struct
+          Struct.new(:row, :column).new(0, Native.ts_node_start_byte(@val))
+        end
+
+        # Get end point
+        #
+        # @return [Object] with row and column
+        def end_point
+          # FFI backend would need to implement ts_node_end_point
+          # For now, return a simple struct
+          Struct.new(:row, :column).new(0, Native.ts_node_end_byte(@val))
+        end
+
+        # Check if node has error
+        #
+        # @return [Boolean]
+        def has_error?
+          # Would need ts_node_has_error implementation
+          false
+        end
+
         # Iterate over child nodes
         #
         # @yieldparam child [Node] each child node
@@ -395,7 +453,7 @@ module TreeHaver
         def each
           return enum_for(:each) unless block_given?
 
-          count = Native.ts_node_child_count(@val)
+          count = child_count
           i = 0
           while i < count
             child = Native.ts_node_child(@val, i)

data/lib/tree_haver/backends/java.rb

@@ -7,7 +7,7 @@ module TreeHaver
     # This backend integrates with java-tree-sitter JARs on JRuby,
     # leveraging JRuby's native Java integration for optimal performance.
     #
-    # java-tree-sitter provides Java bindings to Tree-sitter and supports:
+    # java-tree-sitter provides Java bindings to tree-sitter and supports:
     # - Parsing source code into syntax trees
     # - Incremental parsing via Parser.parse(Tree, String)
     # - The Query API for pattern matching
@@ -393,10 +393,11 @@ module TreeHaver
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [Tree] the parsed syntax tree
+        # @return [TreeHaver::Tree] wrapped tree
         def parse(source)
           java_tree = @parser.parse(source)
-          Tree.new(java_tree)
+          inner_tree = Tree.new(java_tree)
+          TreeHaver::Tree.new(inner_tree, source: source)
         end
 
         # Parse source code with optional incremental parsing
@@ -404,18 +405,21 @@ module TreeHaver
         # When old_tree is provided and has been edited, tree-sitter will reuse
         # unchanged nodes for better performance.
         #
-        # @param old_tree [Tree, nil] previous tree for incremental parsing
+        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing
         # @param source [String] the source code to parse
-        # @return [Tree] the parsed syntax tree
+        # @return [TreeHaver::Tree] wrapped tree
         # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Parser.html#parse(io.github.treesitter.jtreesitter.Tree,java.lang.String)
         def parse_string(old_tree, source)
           if old_tree
-            java_old_tree = old_tree.is_a?(Tree) ? old_tree.impl : old_tree
+            # Unwrap TreeHaver::Tree to get inner tree
+            inner_old_tree = old_tree.respond_to?(:inner_tree) ? old_tree.inner_tree : old_tree
+            java_old_tree = inner_old_tree.is_a?(Tree) ? inner_old_tree.impl : inner_old_tree
             java_tree = @parser.parse(java_old_tree, source)
           else
             java_tree = @parser.parse(source)
           end
-          Tree.new(java_tree)
+          inner_tree = Tree.new(java_tree)
+          TreeHaver::Tree.new(inner_tree, source: source)
         end
       end
 

data/lib/tree_haver/backends/mri.rb

@@ -5,7 +5,7 @@ module TreeHaver
     # MRI backend using the ruby_tree_sitter gem
     #
     # This backend wraps the ruby_tree_sitter gem, which is a native C extension
-    # for MRI Ruby. It provides the most feature-complete Tree-sitter integration
+    # for MRI Ruby. It provides the most feature-complete tree-sitter integration
     # on MRI, including support for the Query API.
     #
     # @note This backend only works on MRI Ruby, not JRuby or TruffleRuby
@@ -96,34 +96,24 @@ module TreeHaver
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [::TreeSitter::Tree] the parsed syntax tree
+        # @return [TreeHaver::Tree] wrapped tree
         def parse(source)
-          @parser.parse(source)
+          tree = @parser.parse(source)
+          TreeHaver::Tree.new(tree, source: source)
         end
 
         # Parse source code with optional incremental parsing
         #
-        # @param old_tree [::TreeSitter::Tree, nil] previous tree for incremental parsing
+        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing
         # @param source [String] the source code to parse
-        # @return [::TreeSitter::Tree] the parsed syntax tree
+        # @return [TreeHaver::Tree] wrapped tree
         def parse_string(old_tree, source)
-          @parser.parse_string(old_tree, source)
+          # Unwrap if TreeHaver::Tree to get inner tree for incremental parsing
+          inner_old_tree = old_tree.respond_to?(:inner_tree) ? old_tree.inner_tree : old_tree
+          tree = @parser.parse_string(inner_old_tree, source)
+          TreeHaver::Tree.new(tree, source: source)
         end
       end
-
-      # Wrapper for ruby_tree_sitter Tree
-      #
-      # Not used directly; TreeHaver passes through ::TreeSitter::Tree objects.
-      class Tree
-        # Not used directly; we pass through ruby_tree_sitter::Tree
-      end
-
-      # Wrapper for ruby_tree_sitter Node
-      #
-      # Not used directly; TreeHaver passes through ::TreeSitter::Node objects.
-      class Node
-        # Not used directly; we pass through ruby_tree_sitter::Node
-      end
     end
   end
 end

data/lib/tree_haver/backends/rust.rb

@@ -5,7 +5,7 @@ module TreeHaver
     # Rust backend using the tree_stump gem
     #
     # This backend wraps the tree_stump gem, which provides Ruby bindings to
-    # Tree-sitter written in Rust. It offers native performance with Rust's
+    # tree-sitter written in Rust. It offers native performance with Rust's
     # safety guarantees and includes precompiled binaries for common platforms.
     #
     # tree_stump supports incremental parsing and the Query API, making it
@@ -140,36 +140,24 @@ module TreeHaver
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [Object] the parsed syntax tree
+        # @return [TreeHaver::Tree] wrapped tree
         def parse(source)
-          @parser.parse(source)
+          tree = @parser.parse(source)
+          TreeHaver::Tree.new(tree, source: source)
         end
 
         # Parse source code with optional incremental parsing
         #
-        # @param old_tree [Object, nil] previous tree for incremental parsing
+        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing
         # @param source [String] the source code to parse
-        # @return [Object] the parsed syntax tree
+        # @return [TreeHaver::Tree] wrapped tree
         def parse_string(old_tree, source)
           # tree_stump doesn't have parse_string, use parse instead
           # TODO: Check if tree_stump supports incremental parsing
-          @parser.parse(source)
+          tree = @parser.parse(source)
+          TreeHaver::Tree.new(tree, source: source)
         end
       end
-
-      # Wrapper for tree_stump Tree
-      #
-      # Not used directly; TreeHaver passes through tree_stump Tree objects.
-      class Tree
-        # Not used directly; we pass through tree_stump::Tree
-      end
-
-      # Wrapper for tree_stump Node
-      #
-      # Not used directly; TreeHaver passes through tree_stump::Node objects.
-      class Node
-        # Not used directly; we pass through tree_stump::Node
-      end
     end
   end
 end

data/lib/tree_haver/grammar_finder.rb

@@ -221,7 +221,7 @@ module TreeHaver
     #
     # @return [String] error message with installation hints
     def not_found_message
-      "Tree-sitter #{@language_name} grammar not found. " \
+      "tree-sitter #{@language_name} grammar not found. " \
         "Searched: #{search_paths.join(", ")}. " \
         "Install tree-sitter-#{@language_name} or set #{env_var_name}."
     end