tree_haver 4.0.5 → 5.0.0

data/lib/tree_haver/language.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
 module TreeHaver
-  # Represents a language grammar for parsing source code
+  # Factory module for loading language grammars
   #
   # Language is the entry point for loading and using grammars. It provides
-  # a unified interface that works across all backends (MRI, Rust, FFI, Java, Citrus).
+  # a unified interface that works across all backends (MRI, Rust, FFI, Java, Citrus, Parslet).
+  #
+  # This is a module with only module methods (factory pattern), not a class.
+  # Backend-specific Language classes (e.g., Backends::Citrus::Language,
+  # Backends::Parslet::Language) inherit from Base::Language.
   #
   # For tree-sitter backends, languages are loaded from shared library files (.so/.dylib/.dll).
-  # For pure-Ruby backends (Citrus, Prism, Psych), languages are built-in or provided by gems.
+  # For pure-Ruby backends (Citrus, Parslet, Prism, Psych), languages are built-in or provided by gems.
   #
   # == Loading Languages
   #
@@ -30,7 +34,9 @@ module TreeHaver
   # @example Register and load a language
   #   TreeHaver.register_language(:toml, path: "/path/to/grammar.so")
   #   language = TreeHaver::Language.toml
-  class Language
+  #
+  # @see Base::Language The base class that backend Language classes inherit from
+  module Language
     class << self
       # Load a language grammar from a shared library (ruby_tree_sitter compatibility)
       #
@@ -157,6 +163,8 @@ module TreeHaver
         # Determine which backend type to use
         backend_type = if current_backend == Backends::Citrus
           :citrus
+        elsif current_backend == Backends::Parslet
+          :parslet
         else
           :tree_sitter  # MRI, Rust, FFI, Java all use tree-sitter
         end
@@ -177,6 +185,19 @@ module TreeHaver
               "Registered backends: #{all_backends.keys.inspect}"
         end
 
+        # If Parslet backend is active
+        if backend_type == :parslet
+          if reg && reg[:grammar_class]
+            return Backends::Parslet::Language.new(reg[:grammar_class])
+          end
+
+          # Fall back to error if no Parslet grammar registered
+          raise NotAvailable,
+            "Parslet backend is active but no Parslet grammar registered for :#{method_name}. " \
+              "Either register a Parslet grammar or use a tree-sitter backend. " \
+              "Registered backends: #{all_backends.keys.inspect}"
+        end
+
         # For tree-sitter backends, try to load from path
         # If that fails, fall back to Citrus if available
         if reg && reg[:path]
@@ -203,15 +224,20 @@ module TreeHaver
           end
         end
 
-        # No tree-sitter path registered - check for Citrus fallback
+        # No tree-sitter path registered - check for Citrus or Parslet fallback
         # This enables auto-fallback when tree-sitter grammar is not installed
-        # but a Citrus grammar (pure Ruby) is available.
+        # but a pure Ruby grammar (Citrus or Parslet) is available.
         # Only fall back when backend is :auto - explicit native backend requests should fail.
         if TreeHaver.effective_backend == :auto
           citrus_reg = all_backends[:citrus]
           if citrus_reg && citrus_reg[:grammar_module]
             return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
           end
+
+          parslet_reg = all_backends[:parslet]
+          if parslet_reg && parslet_reg[:grammar_class]
+            return Backends::Parslet::Language.new(parslet_reg[:grammar_class])
+          end
         end
 
         # No appropriate registration found
@@ -227,27 +253,27 @@ module TreeHaver
 
       private
 
-      # Handle tree-sitter load failure with optional Citrus fallback
+      # Handle tree-sitter load failure with optional Citrus/Parslet 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 inherits from LoadError)
       # - Invalid arguments were provided (ArgumentError)
       #
-      # Fallback to Citrus ONLY happens when:
+      # Fallback to Citrus/Parslet ONLY happens when:
       # - The effective backend is :auto (user didn't explicitly request a native backend)
-      # - A Citrus grammar is registered for the language
+      # - A Citrus or Parslet grammar is registered for the language
       #
       # If the user explicitly requested a native backend (:mri, :rust, :ffi, :java),
-      # we should NOT silently fall back to Citrus - that would violate the user's intent.
+      # we should NOT silently fall back to pure Ruby - that would violate the user's intent.
       #
       # @param error [Exception] the original error
       # @param all_backends [Hash] all registered backends for the language
-      # @return [Backends::Citrus::Language] if Citrus fallback available and allowed
+      # @return [Backends::Citrus::Language, Backends::Parslet::Language] if fallback available and allowed
       # @raise [Exception] re-raises original error if no fallback or fallback not allowed
       # @api private
       def handle_tree_sitter_load_failure(error, all_backends)
-        # Only fall back to Citrus when backend is :auto
+        # Only fall back to pure Ruby when backend is :auto
         # If user explicitly requested a native backend, respect that choice
         effective = TreeHaver.effective_backend
         if effective == :auto
@@ -255,8 +281,13 @@ module TreeHaver
           if citrus_reg && citrus_reg[:grammar_module]
             return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
           end
+
+          parslet_reg = all_backends[:parslet]
+          if parslet_reg && parslet_reg[:grammar_class]
+            return Backends::Parslet::Language.new(parslet_reg[:grammar_class])
+          end
         end
-        # No Citrus fallback allowed or available, re-raise the original error
+        # No pure Ruby fallback allowed or available, re-raise the original error
         raise error
       end
     end

data/lib/tree_haver/parser.rb

@@ -1,20 +1,45 @@
 # frozen_string_literal: true
 
 module TreeHaver
-  # Represents a tree-sitter parser instance
+  # Unified Parser facade providing a consistent API across all backends
   #
-  # A Parser is used to parse source code into a syntax tree. You must
-  # set a language before parsing.
+  # This class acts as a facade/adapter that delegates to backend-specific
+  # parser implementations. It automatically selects the appropriate backend
+  # and provides a unified interface regardless of which parser is being used.
+  #
+  # == Backend Selection
+  #
+  # The parser automatically selects a backend based on:
+  # 1. Explicit `backend:` parameter in constructor
+  # 2. `TreeHaver.backend` global setting
+  # 3. `TREE_HAVER_BACKEND` environment variable
+  # 4. Auto-detection (tries available backends in order)
+  #
+  # == Supported Backends
+  #
+  # **Tree-sitter backends** (native, high-performance):
+  # - `:mri` - ruby_tree_sitter gem (C extension, MRI only)
+  # - `:rust` - tree_stump gem (Rust via magnus, MRI only)
+  # - `:ffi` - FFI bindings to libtree-sitter (MRI, JRuby)
+  # - `:java` - java-tree-sitter (JRuby only)
+  #
+  # **Pure Ruby backends** (portable, no native dependencies):
+  # - `:citrus` - Citrus PEG parser (e.g., toml-rb)
+  # - `:parslet` - Parslet PEG parser (e.g., toml gem)
+  # - `:prism` - Ruby's official parser (Ruby only)
+  # - `:psych` - YAML parser (stdlib)
   #
   # == Wrapping/Unwrapping Responsibility
   #
-  # TreeHaver::Parser is responsible for ALL object wrapping and unwrapping:
+  # TreeHaver::Parser handles ALL object wrapping and unwrapping:
   #
   # **Language objects:**
   # - Unwraps Language wrappers before passing to backend.language=
   # - MRI backend receives ::TreeSitter::Language
   # - Rust backend receives String (language name)
   # - FFI backend receives wrapped Language (needs to_ptr)
+  # - Citrus backend receives grammar module
+  # - Parslet backend receives grammar class
   #
   # **Tree objects:**
   # - parse() receives raw source, backend returns raw tree, Parser wraps it
@@ -33,16 +58,32 @@ module TreeHaver
   #   parser = TreeHaver::Parser.new
   #   parser.language = TreeHaver::Language.toml
   #   tree = parser.parse("[package]\nname = \"foo\"")
-  class Parser
+  #
+  # @example Explicit backend selection
+  #   parser = TreeHaver::Parser.new(backend: :citrus)
+  #   parser.language = TreeHaver::Language.toml
+  #   tree = parser.parse(toml_source)
+  #
+  # @see Base::Parser The base class defining the parser interface
+  # @see Backends::Citrus::Parser Citrus backend implementation
+  # @see Backends::Parslet::Parser Parslet backend implementation
+  # @see Backends::Prism::Parser Prism backend implementation
+  class Parser < Base::Parser
     # Create a new parser instance
     #
+    # The parser automatically selects the best available backend unless
+    # explicitly specified. Use the `backend:` parameter to force a specific backend.
+    #
     # @param backend [Symbol, String, nil] optional backend to use (overrides context/global)
+    #   Valid values: :auto, :mri, :rust, :ffi, :java, :citrus, :parslet, :prism, :psych
     # @raise [NotAvailable] if no backend is available or requested backend is unavailable
-    # @example Default (uses context/global)
+    # @example Default (auto-selects best available backend)
     #   parser = TreeHaver::Parser.new
     # @example Explicit backend
-    #   parser = TreeHaver::Parser.new(backend: :ffi)
+    #   parser = TreeHaver::Parser.new(backend: :citrus)
     def initialize(backend: nil)
+      super()  # Initialize @language from Base::Parser
+
       # Convert string backend names to symbols for consistency
       backend = backend.to_sym if backend.is_a?(String)
 
@@ -56,7 +97,7 @@ module TreeHaver
         end
       end
 
-      # Try to create the parser, with fallback to Citrus if tree-sitter fails
+      # Try to create the parser, with fallback to pure Ruby if tree-sitter fails
       # This enables auto-fallback when tree-sitter runtime isn't available
       begin
         @impl = mod::Parser.new
@@ -67,7 +108,7 @@ module TreeHaver
       end
     end
 
-    # Handle parser creation failure with optional Citrus fallback
+    # Handle parser creation failure with optional Citrus/Parslet fallback
     #
     # @param error [Exception] the error that caused parser creation to fail
     # @param backend [Symbol, nil] the requested backend
@@ -75,15 +116,18 @@ module TreeHaver
     # @api private
     def handle_parser_creation_failure(error, backend)
       # Tree-sitter backend failed (likely missing runtime library)
-      # Try Citrus as fallback if we weren't explicitly asked for a specific backend
+      # Try Citrus or Parslet 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
+        elsif Backends::Parslet.available?
+          @impl = Backends::Parslet::Parser.new
+          @explicit_backend = :parslet
         else
           # No fallback available, re-raise original error
           raise NotAvailable, "Tree-sitter backend failed: #{error.message}. " \
-            "Citrus fallback not available. Install tree-sitter runtime or citrus gem."
+            "Citrus/Parslet fallback not available. Install tree-sitter runtime, citrus gem, or parslet gem."
         end
       else
         # Explicit backend was requested, don't fallback
@@ -95,7 +139,7 @@ module TreeHaver
     #
     # Returns the actual backend in use, resolving :auto to the concrete backend.
     #
-    # @return [Symbol] the backend name (:mri, :rust, :ffi, :java, or :citrus)
+    # @return [Symbol] the backend name (:mri, :rust, :ffi, :java, :citrus, or :parslet)
     def backend
       if @explicit_backend && @explicit_backend != :auto
         @explicit_backend
@@ -112,6 +156,8 @@ module TreeHaver
           :java
         when /Citrus/
           :citrus
+        when /Parslet/
+          :parslet
         else
           # Fallback to effective_backend if we can't determine from class name
           TreeHaver.effective_backend
@@ -121,28 +167,27 @@ module TreeHaver
 
     # Set the language grammar for this parser
     #
+    # The language must be compatible with the parser's backend. If a mismatch
+    # is detected (e.g., Citrus language on tree-sitter parser), the parser
+    # will automatically switch to the correct backend.
+    #
     # @param lang [Language] the language to use for parsing
     # @return [Language] the language that was set
     # @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
+      # Auto-switch backend if language type doesn't match current parser
+      # This handles the case where Language.toml returns a Citrus/Parslet language
+      # but the parser was initialized with a tree-sitter backend
+      switch_backend_for_language(lang)
 
       # 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 # rubocop:disable Lint/Void (intentional return value)
+
+      # Store on base class for API compatibility
+      @language = lang
     end
 
     # Parse source code into a syntax tree
@@ -218,6 +263,51 @@ module TreeHaver
 
     private
 
+    # Switch backend if language type doesn't match current parser
+    #
+    # This is necessary because TreeHaver.parser_for may return a Language
+    # from a different backend than the Parser was initialized with.
+    # For example, Language.toml might return a Citrus::Language when
+    # tree-sitter-toml is not available, but Parser was initialized with :auto.
+    #
+    # @param lang [Object] The language object
+    # @api private
+    def switch_backend_for_language(lang)
+      return unless lang.respond_to?(:backend)
+
+      lang_backend = lang.backend
+      parser_backend = backend
+
+      # No switch needed if backends match
+      return if lang_backend == parser_backend
+
+      # Switch to matching backend parser
+      case lang_backend
+      when :citrus
+        unless @impl.is_a?(Backends::Citrus::Parser)
+          @impl = Backends::Citrus::Parser.new
+          @explicit_backend = :citrus
+        end
+      when :parslet
+        unless @impl.is_a?(Backends::Parslet::Parser)
+          @impl = Backends::Parslet::Parser.new
+          @explicit_backend = :parslet
+        end
+      when :prism
+        unless @impl.is_a?(Backends::Prism::Parser)
+          @impl = Backends::Prism::Parser.new
+          @explicit_backend = :prism
+        end
+      when :psych
+        unless @impl.is_a?(Backends::Psych::Parser)
+          @impl = Backends::Psych::Parser.new
+          @explicit_backend = :psych
+        end
+        # Tree-sitter backends (:mri, :rust, :ffi, :java) - don't auto-switch between them
+        # as that would require reloading the language from the .so file
+      end
+    end
+
     # Unwrap a language object to extract the raw backend language
     #
     # This method is smart about backend compatibility:
@@ -274,24 +364,26 @@ module TreeHaver
 
       case lang.backend
       when :mri
-        return lang.to_language if lang.respond_to?(:to_language)
-        return lang.inner_language if lang.respond_to?(:inner_language)
+        lang.to_language if lang.respond_to?(:to_language)
+        lang.inner_language if lang.respond_to?(:inner_language)
       when :rust
-        return lang.name if lang.respond_to?(:name)
+        lang.name if lang.respond_to?(:name)
       when :ffi
-        return lang  # FFI needs wrapper for to_ptr
+        lang  # FFI needs wrapper for to_ptr
       when :java
-        return lang.impl if lang.respond_to?(:impl)
+        lang.impl if lang.respond_to?(:impl)
       when :citrus
-        return lang.grammar_module if lang.respond_to?(:grammar_module)
+        lang  # Citrus backend accepts Language wrapper (handles both)
+      when :parslet
+        lang  # Parslet backend accepts Language wrapper (handles both)
       when :prism
-        return lang  # Prism backend expects the Language wrapper
+        lang  # Prism backend expects the Language wrapper
       when :psych
-        return lang  # Psych backend expects the Language wrapper
+        lang  # Psych backend expects the Language wrapper
       when :commonmarker
-        return lang  # Commonmarker backend expects the Language wrapper
+        lang  # Commonmarker backend expects the Language wrapper
       when :markly
-        return lang  # Markly backend expects the Language wrapper
+        lang  # Markly backend expects the Language wrapper
       else
         # Unknown backend (e.g., test backend)
         # Try generic unwrapping methods for flexibility in testing
@@ -299,15 +391,13 @@ module TreeHaver
         return lang.inner_language if lang.respond_to?(:inner_language)
         return lang.impl if lang.respond_to?(:impl)
         return lang.grammar_module if lang.respond_to?(:grammar_module)
+        return lang.grammar_class if lang.respond_to?(:grammar_class)
         return lang.name if lang.respond_to?(:name)
 
         # If nothing works, pass through as-is
         # This allows test languages to be passed directly
-        return lang
+        lang
       end
-
-      # Shouldn't reach here, but just in case
-      lang
     end
 
     # Try to reload a language for the current backend

data/lib/tree_haver/parslet_grammar_finder.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Utility for finding and registering Parslet grammar gems.
+  #
+  # ParsletGrammarFinder provides language-agnostic discovery of Parslet grammar
+  # gems. Given a language name and gem information, it attempts to load the
+  # grammar and register it with tree_haver.
+  #
+  # Unlike tree-sitter grammars (which are .so files), Parslet grammars are
+  # Ruby classes that inherit from Parslet::Parser. This class handles the
+  # discovery and registration of these grammars.
+  #
+  # @example Basic usage with toml gem
+  #   finder = TreeHaver::ParsletGrammarFinder.new(
+  #     language: :toml,
+  #     gem_name: "toml",
+  #     grammar_const: "TOML::Parslet"
+  #   )
+  #   finder.register! if finder.available?
+  #
+  # @example With custom require path
+  #   finder = TreeHaver::ParsletGrammarFinder.new(
+  #     language: :json,
+  #     gem_name: "json-parslet",
+  #     grammar_const: "JsonParslet::Grammar",
+  #     require_path: "json/parslet"
+  #   )
+  #
+  # @see GrammarFinder For tree-sitter grammar discovery
+  # @see CitrusGrammarFinder For Citrus grammar discovery
+  class ParsletGrammarFinder
+    # @return [Symbol] the language identifier
+    attr_reader :language_name
+
+    # @return [String] the gem name to require
+    attr_reader :gem_name
+
+    # @return [String] the constant path to the grammar class (e.g., "TOML::Parslet")
+    attr_reader :grammar_const
+
+    # @return [String, nil] custom require path (defaults to gem_name)
+    attr_reader :require_path
+
+    # Initialize a Parslet grammar finder
+    #
+    # @param language [Symbol, String] the language name (e.g., :toml, :json)
+    # @param gem_name [String] the gem name (e.g., "toml")
+    # @param grammar_const [String] constant path to grammar class (e.g., "TOML::Parslet")
+    # @param require_path [String, nil] custom require path (defaults to gem_name as-is)
+    def initialize(language:, gem_name:, grammar_const:, require_path: nil)
+      @language_name = language.to_sym
+      @gem_name = gem_name
+      @grammar_const = grammar_const
+      @require_path = require_path || gem_name
+      @load_attempted = false
+      @available = false
+      @grammar_class = nil
+    end
+
+    # Check if the Parslet grammar is available
+    #
+    # Attempts to require the gem and resolve the grammar constant.
+    # Result is cached after first call.
+    #
+    # @return [Boolean] true if grammar is available
+    def available?
+      return @available if @load_attempted
+
+      @load_attempted = true
+      debug = ENV["TREE_HAVER_DEBUG"]
+
+      # Guard against nil require_path (can happen if gem_name was nil)
+      if @require_path.nil? || @require_path.empty?
+        warn("ParsletGrammarFinder: require_path is nil or empty for #{@language_name}") if debug
+        @available = false
+        return false
+      end
+
+      begin
+        # Try to require the gem
+        require @require_path
+
+        # Try to resolve the constant
+        @grammar_class = resolve_constant(@grammar_const)
+
+        # Verify it can create a parser instance with a parse method
+        unless valid_grammar_class?(@grammar_class)
+          if debug
+            warn("ParsletGrammarFinder: #{@grammar_const} is not a valid Parslet grammar class")
+            warn("ParsletGrammarFinder: #{@grammar_const}.class = #{@grammar_class.class}")
+          end
+          @available = false
+          return false
+        end
+
+        @available = true
+      rescue LoadError => e
+        # :nocov: defensive - requires gem to not be installed
+        if debug
+          warn("ParsletGrammarFinder: Failed to load '#{@require_path}': #{e.class}: #{e.message}")
+          warn("ParsletGrammarFinder: LoadError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
+        @available = false
+        # :nocov:
+      rescue NameError => e
+        # :nocov: defensive - requires gem with missing constant
+        if debug
+          warn("ParsletGrammarFinder: Failed to resolve '#{@grammar_const}': #{e.class}: #{e.message}")
+          warn("ParsletGrammarFinder: NameError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
+        @available = false
+        # :nocov:
+      rescue TypeError => e
+        # :nocov: defensive - TruffleRuby-specific edge case
+        warn("ParsletGrammarFinder: TypeError during load of '#{@require_path}': #{e.class}: #{e.message}")
+        warn("ParsletGrammarFinder: This may be a TruffleRuby bundled_gems.rb issue")
+        if debug
+          warn("ParsletGrammarFinder: TypeError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
+        @available = false
+        # :nocov:
+      rescue => e
+        # :nocov: defensive - catch-all for unexpected errors
+        warn("ParsletGrammarFinder: Unexpected error: #{e.class}: #{e.message}")
+        if debug
+          warn("ParsletGrammarFinder: backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
+        @available = false
+        # :nocov:
+      end
+
+      @available
+    end
+
+    # Get the resolved grammar class
+    #
+    # @return [Class, nil] the grammar class if available
+    def grammar_class
+      available? # Ensure we've tried to load
+      @grammar_class
+    end
+
+    # Register this Parslet grammar with TreeHaver
+    #
+    # After registration, the language can be used via:
+    #   TreeHaver::Language.{language_name}
+    #
+    # @param raise_on_missing [Boolean] if true, raises when grammar not available
+    # @return [Boolean] true if registration succeeded
+    # @raise [NotAvailable] if grammar not available and raise_on_missing is true
+    def register!(raise_on_missing: false)
+      unless available?
+        if raise_on_missing
+          raise NotAvailable, not_found_message
+        end
+        return false
+      end
+
+      TreeHaver.register_language(
+        @language_name,
+        grammar_class: @grammar_class,
+        gem_name: @gem_name,
+      )
+      true
+    end
+
+    # Get debug information about the search
+    #
+    # @return [Hash] diagnostic information
+    def search_info
+      {
+        language: @language_name,
+        gem_name: @gem_name,
+        grammar_const: @grammar_const,
+        require_path: @require_path,
+        available: available?,
+        grammar_class: @grammar_class&.name,
+      }
+    end
+
+    # Get a human-readable error message when grammar is not found
+    #
+    # @return [String] error message with installation hints
+    def not_found_message
+      "Parslet grammar for #{@language_name} not found. " \
+        "Install #{@gem_name} gem: gem install #{@gem_name}"
+    end
+
+    private
+
+    # Resolve a constant path like "TOML::Parslet"
+    #
+    # @param const_path [String] constant path
+    # @return [Object] the constant
+    # @raise [NameError] if constant not found
+    def resolve_constant(const_path)
+      const_path.split("::").reduce(Object) do |mod, const_name|
+        mod.const_get(const_name)
+      end
+    end
+
+    # Check if the class is a valid Parslet grammar
+    #
+    # @param klass [Class] the class to check
+    # @return [Boolean] true if valid
+    def valid_grammar_class?(klass)
+      return false unless klass.respond_to?(:new)
+
+      # Check if it's a Parslet::Parser subclass
+      if defined?(::Parslet::Parser)
+        return true if klass < ::Parslet::Parser
+      end
+
+      # Fallback: check if it can create an instance that responds to parse
+      begin
+        instance = klass.new
+        instance.respond_to?(:parse)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end