tree_haver 3.0.0 → 3.1.0

data/lib/tree_haver/node.rb

@@ -165,10 +165,20 @@ module TreeHaver
     def start_point
       if @inner_node.respond_to?(:start_point)
         point = @inner_node.start_point
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       elsif @inner_node.respond_to?(:start_position)
         point = @inner_node.start_position
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       else
         raise TreeHaver::Error, "Backend node does not support start_point/start_position"
       end
@@ -180,15 +190,71 @@ module TreeHaver
     def end_point
       if @inner_node.respond_to?(:end_point)
         point = @inner_node.end_point
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       elsif @inner_node.respond_to?(:end_position)
         point = @inner_node.end_position
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       else
         raise TreeHaver::Error, "Backend node does not support end_point/end_position"
       end
     end
 
+    # Get the 1-based line number where this node starts
+    #
+    # Convenience method that converts 0-based row to 1-based line number.
+    # This is useful for error messages and matching with editor line numbers.
+    #
+    # @return [Integer] 1-based line number
+    def start_line
+      start_point.row + 1
+    end
+
+    # Get the 1-based line number where this node ends
+    #
+    # Convenience method that converts 0-based row to 1-based line number.
+    #
+    # @return [Integer] 1-based line number
+    def end_line
+      end_point.row + 1
+    end
+
+    # Get position information as a hash
+    #
+    # Returns a hash with 1-based line numbers and 0-based columns.
+    # This format is compatible with *-merge gems' FileAnalysisBase.
+    #
+    # @return [Hash{Symbol => Integer}] Position hash
+    # @example
+    #   node.source_position
+    #   # => { start_line: 1, end_line: 3, start_column: 0, end_column: 10 }
+    def source_position
+      {
+        start_line: start_line,
+        end_line: end_line,
+        start_column: start_point.column,
+        end_column: end_point.column,
+      }
+    end
+
+    # Get the first child node
+    #
+    # Convenience method for iteration patterns that expect first_child.
+    #
+    # @return [Node, nil] First child node or nil if no children
+    def first_child
+      child(0)
+    end
+
     # Get the node's text content
     #
     # @return [String]
@@ -435,10 +501,10 @@ module TreeHaver
 
       # Compare by position first (start_byte, then end_byte)
       cmp = start_byte <=> other.start_byte
-      return cmp unless cmp.zero?
+      return cmp if cmp.nonzero?
 
       cmp = end_byte <=> other.end_byte
-      return cmp unless cmp.zero?
+      return cmp if cmp.nonzero?
 
       # For nodes at the same position with same span, compare by type
       type <=> other.type

data/lib/tree_haver/version.rb

@@ -10,7 +10,7 @@ module TreeHaver
     # Current version of the tree_haver gem
     #
     # @return [String] the version string (e.g., "3.0.0")
-    VERSION = "3.0.0"
+    VERSION = "3.1.0"
   end
 
   # Traditional location for VERSION constant

data/lib/tree_haver.rb

@@ -10,12 +10,17 @@ require "set"
 require_relative "tree_haver/version"
 require_relative "tree_haver/language_registry"
 
-# TreeHaver is a cross-Ruby adapter for the tree-sitter parsing library.
+# TreeHaver is a cross-Ruby adapter for code parsing with 10 backends.
 #
-# It provides a unified API for parsing source code using tree-sitter grammars,
-# working seamlessly across MRI Ruby, JRuby, and TruffleRuby.
+# Provides a unified API for parsing source code across MRI Ruby, JRuby, and TruffleRuby
+# using tree-sitter grammars or language-specific native parsers.
 #
-# @example Basic usage with TOML
+# Supports 10 backends:
+# - Tree-sitter: MRI (C), Rust, FFI, Java
+# - Native parsers: Prism (Ruby), Psych (YAML), Commonmarker (Markdown), Markly (GFM)
+# - Pure Ruby: Citrus (portable fallback)
+#
+# @example Basic usage with tree-sitter
 #   # Load a language grammar
 #   language = TreeHaver::Language.from_library(
 #     "/usr/local/lib/libtree-sitter-toml.so",
@@ -30,8 +35,28 @@ require_relative "tree_haver/language_registry"
 #   tree = parser.parse("[package]\nname = \"my-app\"")
 #   root = tree.root_node
 #
-#   # Traverse the AST
-#   root.each { |child| puts child.type }
+#   # Use unified Position API (works across all backends)
+#   puts root.start_line      # => 1 (1-based)
+#   puts root.source_position # => {start_line:, end_line:, start_column:, end_column:}
+#
+# @example Using language-specific backends
+#   # Parse Ruby with Prism
+#   TreeHaver.backend = :prism
+#   parser = TreeHaver::Parser.new
+#   parser.language = TreeHaver::Backends::Prism::Language.ruby
+#   tree = parser.parse("class Example; end")
+#
+#   # Parse YAML with Psych
+#   TreeHaver.backend = :psych
+#   parser = TreeHaver::Parser.new
+#   parser.language = TreeHaver::Backends::Psych::Language.yaml
+#   tree = parser.parse("key: value")
+#
+#   # Parse Markdown with Commonmarker
+#   TreeHaver.backend = :commonmarker
+#   parser = TreeHaver::Parser.new
+#   parser.language = TreeHaver::Backends::Commonmarker::Language.markdown
+#   tree = parser.parse("# Heading\nParagraph")
 #
 # @example Using language registration
 #   TreeHaver.register_language(:toml, path: "/usr/local/lib/libtree-sitter-toml.so")
@@ -43,22 +68,21 @@ require_relative "tree_haver/language_registry"
 #   finder.register! if finder.available?
 #   language = TreeHaver::Language.toml
 #
-# @example Using GrammarFinder in a *-merge gem
-#   # Each merge gem (toml-merge, json-merge, bash-merge) uses the same pattern
-#   finder = TreeHaver::GrammarFinder.new(:toml)  # or :json, :bash, etc.
-#   if finder.available?
-#     finder.register!
-#   else
-#     warn finder.not_found_message
-#   end
-#
 # @example Selecting a backend
-#   TreeHaver.backend = :ffi  # Force FFI backend
-#   TreeHaver.backend = :mri  # Force MRI backend
-#   TreeHaver.backend = :auto # Auto-select (default)
+#   TreeHaver.backend = :mri          # Force MRI (ruby_tree_sitter)
+#   TreeHaver.backend = :rust         # Force Rust (tree_stump)
+#   TreeHaver.backend = :ffi          # Force FFI
+#   TreeHaver.backend = :java         # Force Java (JRuby)
+#   TreeHaver.backend = :prism        # Force Prism (Ruby)
+#   TreeHaver.backend = :psych        # Force Psych (YAML)
+#   TreeHaver.backend = :commonmarker # Force Commonmarker (Markdown)
+#   TreeHaver.backend = :markly       # Force Markly (GFM)
+#   TreeHaver.backend = :citrus       # Force Citrus (pure Ruby)
+#   TreeHaver.backend = :auto         # Auto-select (default)
 #
 # @see https://tree-sitter.github.io/tree-sitter/ tree-sitter documentation
 # @see GrammarFinder For automatic grammar library discovery
+# @see Backends For available parsing backends
 module TreeHaver
   # Base error class for TreeHaver exceptions
   # @see https://github.com/Faveod/ruby-tree-sitter/pull/83 for inherit from Exception reasoning
@@ -115,12 +139,17 @@ module TreeHaver
   # - {Backends::FFI} - Uses Ruby FFI to call libtree-sitter directly
   # - {Backends::Java} - Uses JRuby's Java integration
   # - {Backends::Citrus} - Uses Citrus PEG parser (pure Ruby, portable)
+  # - {Backends::Prism} - Uses Ruby's built-in Prism parser (Ruby-only, stdlib in 3.4+)
   module Backends
     autoload :MRI, File.join(__dir__, "tree_haver", "backends", "mri")
     autoload :Rust, File.join(__dir__, "tree_haver", "backends", "rust")
     autoload :FFI, File.join(__dir__, "tree_haver", "backends", "ffi")
     autoload :Java, File.join(__dir__, "tree_haver", "backends", "java")
     autoload :Citrus, File.join(__dir__, "tree_haver", "backends", "citrus")
+    autoload :Prism, File.join(__dir__, "tree_haver", "backends", "prism")
+    autoload :Psych, File.join(__dir__, "tree_haver", "backends", "psych")
+    autoload :Commonmarker, File.join(__dir__, "tree_haver", "backends", "commonmarker")
+    autoload :Markly, File.join(__dir__, "tree_haver", "backends", "markly")
 
     # Known backend conflicts
     #
@@ -135,6 +164,10 @@ module TreeHaver
       ffi: [:mri],  # FFI segfaults if MRI (ruby_tree_sitter) has been loaded
       java: [],
       citrus: [],
+      prism: [],        # Prism has no conflicts with other backends
+      psych: [],        # Psych has no conflicts with other backends
+      commonmarker: [], # Commonmarker has no conflicts with other backends
+      markly: [],       # Markly has no conflicts with other backends
     }.freeze
   end
 
@@ -201,7 +234,10 @@ module TreeHaver
     # @return [Boolean]
     # @example Disable protection for testing
     #   TreeHaver.backend_protect = false
-    attr_writer :backend_protect
+    def backend_protect=(value)
+      @backend_protect_mutex ||= Mutex.new
+      @backend_protect_mutex.synchronize { @backend_protect = value }
+    end
 
     # Check if backend conflict protection is enabled
     #
@@ -267,6 +303,10 @@ module TreeHaver
       when "ffi" then :ffi
       when "java" then :java
       when "citrus" then :citrus
+      when "prism" then :prism
+      when "psych" then :psych
+      when "commonmarker" then :commonmarker
+      when "markly" then :markly
       else :auto
       end
     end
@@ -463,6 +503,14 @@ module TreeHaver
         Backends::Java
       when :citrus
         Backends::Citrus
+      when :prism
+        Backends::Prism
+      when :psych
+        Backends::Psych
+      when :commonmarker
+        Backends::Commonmarker
+      when :markly
+        Backends::Markly
       when :auto
         backend_module  # Fall back to normal resolution for :auto
       else
@@ -519,6 +567,14 @@ module TreeHaver
         Backends::Java
       when :citrus
         Backends::Citrus
+      when :prism
+        Backends::Prism
+      when :psych
+        Backends::Psych
+      when :commonmarker
+        Backends::Commonmarker
+      when :markly
+        Backends::Markly
       else
         # auto-select: prefer native/fast backends, fall back to pure Ruby (Citrus)
         if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby" && Backends::Java.available?
@@ -827,7 +883,8 @@ module TreeHaver
               "Registered backends: #{all_backends.keys.inspect}"
         end
 
-        # For tree-sitter backends, use the path
+        # For tree-sitter backends, try to load from path
+        # If that fails, fall back to Citrus if available
         if reg && reg[:path]
           path = kwargs[:path] || args.first || reg[:path]
           # Symbol priority: kwargs override > registration > derive from method_name
@@ -842,7 +899,30 @@ module TreeHaver
           # Using symbol-derived name ensures ruby_tree_sitter gets the correct language name
           # e.g., "toml" not "toml_both" when symbol is "tree_sitter_toml"
           name = kwargs[:name] || symbol&.sub(/\Atree_sitter_/, "")
-          return from_library(path, symbol: symbol, name: name)
+
+          begin
+            return from_library(path, symbol: symbol, name: name)
+          rescue NotAvailable, ArgumentError, LoadError, FFI::NotFoundError => _e
+            # Tree-sitter failed to load - check for Citrus fallback
+            # This handles cases where:
+            # - The .so file doesn't exist or can't be loaded (NotAvailable, LoadError)
+            # - FFI can't find required symbols like ts_parser_new (FFI::NotFoundError)
+            # - Invalid arguments were provided (ArgumentError)
+            citrus_reg = all_backends[:citrus]
+            if citrus_reg && citrus_reg[:grammar_module]
+              return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+            end
+            # No Citrus fallback available, re-raise the original error
+            raise
+          end
+        end
+
+        # No tree-sitter path registered - check for Citrus fallback
+        # This enables auto-fallback when tree-sitter grammar is not installed
+        # but a Citrus grammar (pure Ruby) is available
+        citrus_reg = all_backends[:citrus]
+        if citrus_reg && citrus_reg[:grammar_module]
+          return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
         end
 
         # No appropriate registration found
@@ -913,8 +993,28 @@ module TreeHaver
         end
       end
 
-      @impl = mod::Parser.new
-      @explicit_backend = backend  # Remember for introspection (always a Symbol or nil)
+      # Try to create the parser, with fallback to Citrus if tree-sitter fails
+      # This enables auto-fallback when tree-sitter runtime isn't available
+      begin
+        @impl = mod::Parser.new
+        @explicit_backend = backend  # Remember for introspection (always a Symbol or nil)
+      rescue NoMethodError, FFI::NotFoundError, LoadError => e
+        # Tree-sitter backend failed (likely missing runtime library)
+        # Try Citrus as fallback if we weren't explicitly asked for a specific backend
+        if backend.nil? || backend == :auto
+          if Backends::Citrus.available?
+            @impl = Backends::Citrus::Parser.new
+            @explicit_backend = :citrus
+          else
+            # No fallback available, re-raise original error
+            raise NotAvailable, "Tree-sitter backend failed: #{e.message}. " \
+              "Citrus fallback not available. Install tree-sitter runtime or citrus gem."
+          end
+        else
+          # Explicit backend was requested, don't fallback
+          raise
+        end
+      end
     end
 
     # Get the backend this parser is using (for introspection)
@@ -952,12 +1052,23 @@ module TreeHaver
     # @example
     #   parser.language = TreeHaver::Language.from_library("/path/to/grammar.so")
     def language=(lang)
+      # Check if this is a Citrus language - if so, we need a Citrus parser
+      # This enables automatic backend switching when tree-sitter fails and
+      # falls back to Citrus
+      if lang.is_a?(Backends::Citrus::Language)
+        unless @impl.is_a?(Backends::Citrus::Parser)
+          # Switch to Citrus parser to match the Citrus language
+          @impl = Backends::Citrus::Parser.new
+          @explicit_backend = :citrus
+        end
+      end
+
       # Unwrap the language before passing to backend
       # Backends receive raw language objects, never TreeHaver wrappers
       inner_lang = unwrap_language(lang)
       @impl.language = inner_lang
       # Return the original (possibly wrapped) language for consistency
-      lang
+      lang # rubocop:disable Lint/Void (intentional return value)
     end
 
     private
@@ -1028,6 +1139,14 @@ module TreeHaver
         return lang.impl if lang.respond_to?(:impl)
       when :citrus
         return lang.grammar_module if lang.respond_to?(:grammar_module)
+      when :prism
+        return lang  # Prism backend expects the Language wrapper
+      when :psych
+        return lang  # Psych backend expects the Language wrapper
+      when :commonmarker
+        return lang  # Commonmarker backend expects the Language wrapper
+      when :markly
+        return lang  # Markly backend expects the Language wrapper
       else
         # Unknown backend (e.g., test backend)
         # Try generic unwrapping methods for flexibility in testing

data/sig/tree_haver.rbs

@@ -1,6 +1,9 @@
 # Type definitions for TreeHaver
 #
-# TreeHaver is a cross-Ruby adapter for the tree-sitter parsing library
+# TreeHaver is a cross-Ruby adapter for code parsing with 10 backends:
+# - Tree-sitter: MRI, Rust, FFI, Java
+# - Native parsers: Prism (Ruby), Psych (YAML), Commonmarker (Markdown), Markly (GFM)
+# - Pure Ruby: Citrus
 
 module TreeHaver
   VERSION: String
@@ -134,6 +137,20 @@ module TreeHaver
     # Get the end point (row, column)
     def end_point: () -> Point
 
+    # Position API - consistent across all backends
+    # Get 1-based line number where node starts
+    def start_line: () -> Integer
+
+    # Get 1-based line number where node ends
+    def end_line: () -> Integer
+
+    # Get complete position information as hash
+    # Returns {start_line:, end_line:, start_column:, end_column:}
+    def source_position: () -> Hash[Symbol, Integer]
+
+    # Get first child node (convenience method)
+    def first_child: () -> Node?
+
     # Get the number of child nodes
     def child_count: () -> Integer
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -241,9 +241,13 @@ files:
 - SECURITY.md
 - lib/tree_haver.rb
 - lib/tree_haver/backends/citrus.rb
+- lib/tree_haver/backends/commonmarker.rb
 - lib/tree_haver/backends/ffi.rb
 - lib/tree_haver/backends/java.rb
+- lib/tree_haver/backends/markly.rb
 - lib/tree_haver/backends/mri.rb
+- lib/tree_haver/backends/prism.rb
+- lib/tree_haver/backends/psych.rb
 - lib/tree_haver/backends/rust.rb
 - lib/tree_haver/citrus_grammar_finder.rb
 - lib/tree_haver/compat.rb
@@ -262,10 +266,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://tree-haver.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.0.0
-  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.0.0/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.1.0
+  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.1.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/tree_haver/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.0.0
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.1.0
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/tree_haver/wiki
   news_uri: https://www.railsbling.com/tags/tree_haver