tree_haver 3.1.2 → 3.2.0

data/lib/tree_haver.rb

@@ -15,11 +15,33 @@ require_relative "tree_haver/language_registry"
 # Provides a unified API for parsing source code across MRI Ruby, JRuby, and TruffleRuby
 # using tree-sitter grammars or language-specific native parsers.
 #
+# == Backends
+#
 # 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)
 #
+# == Platform Compatibility
+#
+# Not all backends work on all Ruby platforms:
+#
+#   | Backend      | MRI | JRuby | TruffleRuby |
+#   |--------------|-----|-------|-------------|
+#   | MRI (C ext)  | ✓   | ✗     | ✗           |
+#   | Rust         | ✓   | ✗     | ✗           |
+#   | FFI          | ✓   | ✓     | ✗           |
+#   | Java         | ✗   | ✓     | ✗           |
+#   | Prism        | ✓   | ✓     | ✓           |
+#   | Psych        | ✓   | ✓     | ✓           |
+#   | Citrus       | ✓   | ✓     | ✓           |
+#   | Commonmarker | ✓   | ✗     | ?           |
+#   | Markly       | ✓   | ✗     | ?           |
+#
+# - JRuby: Cannot load native C/Rust extensions; use FFI, Java, or pure Ruby backends
+# - TruffleRuby: FFI doesn't support STRUCT_BY_VALUE; magnus/rb-sys incompatible with C API;
+#   use Prism, Psych, Citrus, or potentially Commonmarker/Markly
+#
 # @example Basic usage with tree-sitter
 #   # Load a language grammar
 #   language = TreeHaver::Language.from_library(
@@ -131,6 +153,20 @@ module TreeHaver
   #   # Now you can test backend conflicts (at risk of segfaults)
   class BackendConflict < Error; end
 
+  # Default Citrus configurations for known languages
+  #
+  # These are used by {TreeHaver.parser_for} when no explicit citrus_config is provided
+  # and tree-sitter backends are not available (e.g., on TruffleRuby).
+  #
+  # @api private
+  CITRUS_DEFAULTS = {
+    toml: {
+      gem_name: "toml-rb",
+      grammar_const: "TomlRB::Document",
+      require_path: "toml-rb",
+    },
+  }.freeze
+
   # Namespace for backend implementations
   #
   # TreeHaver provides multiple backends to support different Ruby implementations:
@@ -545,6 +581,66 @@ module TreeHaver
       mod
     end
 
+    # Native tree-sitter backends that support loading shared libraries (.so files)
+    # These backends wrap the tree-sitter C library via various bindings.
+    # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are excluded.
+    NATIVE_BACKENDS = %i[mri rust ffi java].freeze
+
+    # Resolve a native tree-sitter backend module (for from_library)
+    #
+    # This method is similar to resolve_backend_module but ONLY considers
+    # backends that support loading shared libraries (.so files):
+    # - MRI (ruby_tree_sitter C extension)
+    # - Rust (tree_stump)
+    # - FFI (ffi gem with libtree-sitter)
+    # - Java (jtreesitter on JRuby)
+    #
+    # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are NOT
+    # considered because they don't support from_library.
+    #
+    # @param explicit_backend [Symbol, String, nil] explicitly requested backend
+    # @return [Module, nil] the backend module or nil if none available
+    # @raise [BackendConflict] if the backend conflicts with previously used backends
+    def resolve_native_backend_module(explicit_backend = nil)
+      # Short-circuit on TruffleRuby: no native backends work
+      # - MRI: C extension, MRI only
+      # - Rust: magnus requires MRI's C API
+      # - FFI: STRUCT_BY_VALUE not supported
+      # - Java: requires JRuby's Java interop
+      if defined?(RUBY_ENGINE) && RUBY_ENGINE == "truffleruby"
+        return unless explicit_backend # Auto-select: no backends available
+        # If explicit backend requested, let it fail with proper error below
+      end
+
+      # Get the effective backend (considers thread-local and global settings)
+      requested = resolve_effective_backend(explicit_backend)
+
+      # If the effective backend is a native backend, use it
+      if NATIVE_BACKENDS.include?(requested)
+        return resolve_backend_module(requested)
+      end
+
+      # If a specific non-native backend was explicitly requested, return nil
+      # (from_library only works with native backends that load .so files)
+      return if explicit_backend
+
+      # If effective backend is :auto, auto-select from native backends in priority order
+      # Note: non-native backends set via with_backend are NOT used here because
+      # from_library only works with native backends
+      native_priority = if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby"
+        %i[java ffi] # JRuby: Java first, then FFI
+      else
+        %i[mri rust ffi] # MRI: MRI first, then Rust, then FFI
+      end
+
+      native_priority.each do |backend|
+        mod = resolve_backend_module(backend)
+        return mod if mod
+      end
+
+      nil # No native backend available
+    end
+
     # Determine the concrete backend module to use
     #
     # This method performs backend auto-selection when backend is :auto.
@@ -804,19 +900,25 @@ module TreeHaver
 
       # Step 3: Try Citrus fallback if tree-sitter failed
       unless language
-        citrus_config ||= {}
-        begin
-          citrus_finder = CitrusGrammarFinder.new(
-            language: name,
-            gem_name: citrus_config[:gem_name],
-            grammar_const: citrus_config[:grammar_const],
-          )
-          if citrus_finder.available?
-            citrus_finder.register!
-            language = Language.public_send(name)
+        # Use explicit config, or fall back to built-in defaults for known languages
+        citrus_config ||= CITRUS_DEFAULTS[name] || {}
+
+        # Only attempt if we have the required configuration
+        if citrus_config[:gem_name] && citrus_config[:grammar_const]
+          begin
+            citrus_finder = CitrusGrammarFinder.new(
+              language: name,
+              gem_name: citrus_config[:gem_name],
+              grammar_const: citrus_config[:grammar_const],
+              require_path: citrus_config[:require_path],
+            )
+            if citrus_finder.available?
+              citrus_finder.register!
+              language = Language.public_send(name)
+            end
+          rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
+            language = nil
           end
-        rescue NotAvailable, ArgumentError, LoadError, NameError
-          language = nil
         end
       end
 
@@ -912,13 +1014,18 @@ module TreeHaver
           end
         end
 
-        mod = TreeHaver.resolve_backend_module(backend)
+        # from_library only works with tree-sitter backends that support .so files
+        # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) don't support from_library
+        mod = TreeHaver.resolve_native_backend_module(backend)
 
         if mod.nil?
           if backend
-            raise NotAvailable, "Requested backend #{backend.inspect} is not available"
+            raise NotAvailable, "Requested backend #{backend.inspect} is not available or does not support shared libraries"
           else
-            raise NotAvailable, "No TreeHaver backend is available"
+            raise NotAvailable,
+              "No native tree-sitter backend is available for loading shared libraries. " \
+                "Available native backends (MRI, Rust, FFI, Java) require platform-specific setup. " \
+                "For pure-Ruby parsing, use backend-specific Language classes directly (e.g., Prism, Psych, Citrus)."
           end
         end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 3.1.2
+  version: 3.2.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -289,10 +289,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://tree-haver.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.1.2
-  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.1.2/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.2.0
+  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.2.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/tree_haver/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.1.2
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.2.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