tree_haver 4.0.5 → 5.0.0

data/lib/tree_haver/point.rb

@@ -7,6 +7,9 @@ module TreeHaver
   # - Hash access: point[:row], point[:column]
   # - Method access: point.row, point.column
   #
+  # TreeHaver::Point is an alias for TreeHaver::Base::Point, which is a Struct
+  # providing all the necessary functionality.
+  #
   # @example Method access
   #   point = TreeHaver::Point.new(5, 10)
   #   point.row    # => 5
@@ -18,48 +21,7 @@ module TreeHaver
   #
   # @example Converting to hash
   #   point.to_h # => {row: 5, column: 10}
-  class Point
-    attr_reader :row, :column
-
-    # Create a new Point
-    #
-    # @param row [Integer] the row (line) number, 0-indexed
-    # @param column [Integer] the column number, 0-indexed
-    def initialize(row, column)
-      @row = row
-      @column = column
-    end
-
-    # Hash-like access for compatibility
-    #
-    # @param key [Symbol, String] :row or :column
-    # @return [Integer, nil] the value or nil if key not recognized
-    def [](key)
-      case key
-      when :row, "row" then @row
-      when :column, "column" then @column
-      end
-    end
-
-    # Convert to a hash
-    #
-    # @return [Hash{Symbol => Integer}]
-    def to_h
-      {row: @row, column: @column}
-    end
-
-    # String representation
-    #
-    # @return [String]
-    def to_s
-      "(#{@row}, #{@column})"
-    end
-
-    # Inspect representation
-    #
-    # @return [String]
-    def inspect
-      "#<TreeHaver::Point row=#{@row} column=#{@column}>"
-    end
-  end
+  #
+  # @see Base::Point The underlying Struct implementation
+  Point = Base::Point
 end

data/lib/tree_haver/rspec/dependency_tags.rb

@@ -577,6 +577,16 @@ module TreeHaver
           @citrus_available = TreeHaver::BackendRegistry.available?(:citrus)
         end
 
+        # Check if Parslet backend is available
+        #
+        # This checks if the parslet gem is installed and the backend works.
+        #
+        # @return [Boolean] true if Parslet backend is available
+        def parslet_available?
+          return @parslet_available if defined?(@parslet_available)
+          @parslet_available = TreeHaver::BackendRegistry.available?(:parslet)
+        end
+
         # ============================================================
         # Ruby Engine Detection
         # ============================================================
@@ -697,11 +707,33 @@ module TreeHaver
           end
         end
 
+        # Check if toml gem is available and functional (Parslet backend for TOML)
+        #
+        # @return [Boolean] true if toml gem is available and can parse TOML
+        def toml_gem_available?
+          return @toml_gem_available if defined?(@toml_gem_available)
+          @toml_gem_available = begin
+            require "toml"
+            # Verify it can actually parse - just requiring isn't enough
+            source_toml = <<~TOML
+              # My Information
+              [machine]
+              host = "localhost"
+            TOML
+            TOML.load(source_toml)
+            true
+          rescue LoadError
+            false
+          rescue StandardError
+            false
+          end
+        end
+
         # Check if at least one TOML backend is available
         #
         # @return [Boolean] true if any TOML backend works
         def any_toml_backend_available?
-          tree_sitter_toml_available? || toml_rb_gem_available?
+          tree_sitter_toml_available? || toml_rb_gem_available? || toml_gem_available?
         end
 
         # Check if at least one markdown backend is available
@@ -795,6 +827,7 @@ module TreeHaver
             commonmarker_backend: blocked.include?(:commonmarker) ? :blocked : commonmarker_available?,
             markly_backend: blocked.include?(:markly) ? :blocked : markly_available?,
             citrus_backend: blocked.include?(:citrus) ? :blocked : citrus_available?,
+            parslet_backend: blocked.include?(:parslet) ? :blocked : parslet_available?,
             rbs_backend: blocked.include?(:rbs) ? :blocked : rbs_backend_available?,
             # Ruby engines (*_engine)
             ruby_engine: RUBY_ENGINE,
@@ -816,6 +849,7 @@ module TreeHaver
             rbs_parsing: any_rbs_backend_available?,
             # Specific libraries (*_gem)
             toml_rb_gem: toml_rb_gem_available?,
+            toml_gem: toml_gem_available?,
             rbs_gem: rbs_gem_available?,
           }
         end
@@ -1040,6 +1074,7 @@ RSpec.configure do |config|
     commonmarker: :commonmarker_available?,
     markly: :markly_available?,
     citrus: :citrus_available?,
+    parslet: :parslet_available?,
     rbs: :rbs_backend_available?,
   }
 
@@ -1054,6 +1089,7 @@ RSpec.configure do |config|
     commonmarker: :commonmarker_backend,
     markly: :markly_backend,
     citrus: :citrus_backend,
+    parslet: :parslet_backend,
     rbs: :rbs_backend,
   }
 
@@ -1202,10 +1238,12 @@ RSpec.configure do |config|
   # Specific Library Tags
   # ============================================================
   # Tags for specific gems/libraries (*_gem suffix)
+  #   :toml_gem - the toml gem (Parslet-based TOML parser)
   #   :toml_rb_gem - the toml-rb gem (Citrus-based TOML parser)
   #   :rbs_gem - the rbs gem (official RBS parser, MRI only)
   #   Note: :rbs_backend is also available as an alias for :rbs_gem
 
+  config.filter_run_excluding(toml_gem: true) unless deps.toml_gem_available?
   config.filter_run_excluding(toml_rb_gem: true) unless deps.toml_rb_gem_available?
   config.filter_run_excluding(rbs_gem: true) unless deps.rbs_gem_available?
 
@@ -1249,6 +1287,7 @@ RSpec.configure do |config|
   end
 
   # Specific libraries
+  config.filter_run_excluding(not_toml_gem: true) if deps.toml_gem_available?
   config.filter_run_excluding(not_toml_rb_gem: true) if deps.toml_rb_gem_available?
   config.filter_run_excluding(not_rbs_gem: true) if deps.rbs_gem_available?
 end

data/lib/tree_haver/version.rb

@@ -10,7 +10,7 @@ module TreeHaver
     # Current version of the tree_haver gem
     #
     # @return [String] the version string
-    VERSION = "4.0.5"
+    VERSION = "5.0.0"
   end
 
   # Traditional location for VERSION constant

data/lib/tree_haver.rb

@@ -175,6 +175,20 @@ module TreeHaver
     },
   }.freeze
 
+  # Default Parslet configurations for known languages
+  #
+  # These are used by {TreeHaver.parser_for} when no explicit parslet_config is provided
+  # and tree-sitter backends are not available (e.g., on TruffleRuby).
+  #
+  # @api private
+  PARSLET_DEFAULTS = {
+    toml: {
+      gem_name: "toml",
+      grammar_const: "TOML::Parslet",
+      require_path: "toml",
+    },
+  }.freeze
+
   # Namespace for backend implementations
   #
   # TreeHaver provides multiple backends to support different Ruby implementations:
@@ -183,6 +197,7 @@ 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::Parslet} - Uses Parslet PEG parser (pure Ruby, portable)
   # - {Backends::Prism} - Uses Ruby's built-in Prism parser (Ruby-only, stdlib in 3.4+)
   # - {Backends::Psych} - Uses Ruby's built-in Psych parser (YAML-only, stdlib)
   module Backends
@@ -191,6 +206,7 @@ module TreeHaver
     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 :Parslet, File.join(__dir__, "tree_haver", "backends", "parslet")
     autoload :Prism, File.join(__dir__, "tree_haver", "backends", "prism")
     autoload :Psych, File.join(__dir__, "tree_haver", "backends", "psych")
 
@@ -205,6 +221,7 @@ module TreeHaver
       ffi: [:mri],  # FFI segfaults if MRI (ruby_tree_sitter) has been loaded
       java: [],
       citrus: [],
+      parslet: [],      # Parslet has no conflicts with other backends
       prism: [],        # Prism has no conflicts with other backends
       psych: [],        # Psych has no conflicts with other backends
     }.freeze
@@ -260,6 +277,19 @@ module TreeHaver
   # @see CitrusGrammarFinder
   autoload :CitrusGrammarFinder, File.join(__dir__, "tree_haver", "citrus_grammar_finder")
 
+  # Parslet grammar finder for discovering and registering Parslet-based parsers
+  #
+  # @example Register toml gem
+  #   finder = TreeHaver::ParsletGrammarFinder.new(
+  #     language: :toml,
+  #     gem_name: "toml",
+  #     grammar_const: "TOML::Parslet"
+  #   )
+  #   finder.register! if finder.available?
+  #
+  # @see ParsletGrammarFinder
+  autoload :ParsletGrammarFinder, File.join(__dir__, "tree_haver", "parslet_grammar_finder")
+
   # Point class for position information (row, column)
   autoload :Point, File.join(__dir__, "tree_haver", "point")
 
@@ -368,7 +398,7 @@ module TreeHaver
     VALID_NATIVE_BACKENDS = %w[mri rust ffi java].freeze
 
     # Valid pure Ruby backend names (no native extensions)
-    VALID_RUBY_BACKENDS = %w[citrus prism psych commonmarker markly].freeze
+    VALID_RUBY_BACKENDS = %w[citrus parslet prism psych commonmarker markly].freeze
 
     # All valid backend names
     VALID_BACKENDS = (VALID_NATIVE_BACKENDS + VALID_RUBY_BACKENDS + %w[auto none]).freeze
@@ -734,6 +764,8 @@ module TreeHaver
         Backends::Java
       when :citrus
         Backends::Citrus
+      when :parslet
+        Backends::Parslet
       when :prism
         Backends::Prism
       when :psych
@@ -875,6 +907,8 @@ module TreeHaver
         Backends::Java
       when :citrus
         Backends::Citrus
+      when :parslet
+        Backends::Parslet
       when :prism
         Backends::Prism
       when :psych
@@ -958,6 +992,7 @@ module TreeHaver
     # @param path [String, nil] absolute path to the language shared library (for tree-sitter)
     # @param symbol [String, nil] optional exported factory symbol (e.g., "tree_sitter_toml")
     # @param grammar_module [Module, nil] Citrus grammar module that responds to .parse(source)
+    # @param grammar_class [Class, nil] Parslet grammar class that inherits from Parslet::Parser
     # @param backend_module [Module, nil] pure Ruby backend module with Language/Parser classes
     # @param backend_type [Symbol, nil] backend type for backend_module (defaults to module name)
     # @param gem_name [String, nil] optional gem name for error messages
@@ -974,6 +1009,12 @@ module TreeHaver
     #     grammar_module: TomlRB::Document,
     #     gem_name: "toml-rb"
     #   )
+    # @example Register Parslet grammar only
+    #   TreeHaver.register_language(
+    #     :toml,
+    #     grammar_class: TOML::Parslet,
+    #     gem_name: "toml"
+    #   )
     # @example Register pure Ruby backend (external gem like rbs-merge)
     #   TreeHaver.register_language(
     #     :rbs,
@@ -1001,7 +1042,7 @@ module TreeHaver
     #     gem_name: "toml-rb"
     #   )
     #   # Now TreeHaver::Language.toml works with ANY backend!
-    def register_language(name, path: nil, symbol: nil, grammar_module: nil, backend_module: nil, backend_type: nil, gem_name: nil)
+    def register_language(name, path: nil, symbol: nil, grammar_module: nil, grammar_class: nil, backend_module: nil, backend_type: nil, gem_name: nil)
       # Register tree-sitter backend if path provided
       # Note: Uses `if` not `elsif` so both backends can be registered in one call
       if path
@@ -1019,6 +1060,16 @@ module TreeHaver
         LanguageRegistry.register(name, :citrus, grammar_module: grammar_module, gem_name: gem_name)
       end
 
+      # Register Parslet backend if grammar_class provided
+      # Note: Uses `if` not `elsif` so multiple backends can be registered in one call
+      if grammar_class
+        unless grammar_class.respond_to?(:new)
+          raise ArgumentError, "Grammar class must respond to :new"
+        end
+
+        LanguageRegistry.register(name, :parslet, grammar_class: grammar_class, gem_name: gem_name)
+      end
+
       # Register pure Ruby backend if backend_module provided
       # This is used by external gems (like rbs-merge) to register their own backends
       if backend_module
@@ -1028,13 +1079,13 @@ module TreeHaver
       end
 
       # Require at least one backend to be registered
-      if path.nil? && grammar_module.nil? && backend_module.nil?
-        raise ArgumentError, "Must provide at least one of: path (tree-sitter), grammar_module (Citrus), or backend_module (pure Ruby)"
+      if path.nil? && grammar_module.nil? && grammar_class.nil? && backend_module.nil?
+        raise ArgumentError, "Must provide at least one of: path (tree-sitter), grammar_module (Citrus), grammar_class (Parslet), or backend_module (pure Ruby)"
       end
 
-      # Note: No early return! This method intentionally processes both `if` blocks
+      # Note: No early return! This method intentionally processes all `if` blocks
       # above to allow registering multiple backends for the same language.
-      # Both tree-sitter and Citrus can be registered simultaneously for maximum
+      # tree-sitter, Citrus, and Parslet can be registered simultaneously for maximum
       # flexibility. See method documentation for rationale.
       nil
     end
@@ -1075,15 +1126,17 @@ module TreeHaver
     # Respects the effective backend setting (via TREE_HAVER_BACKEND env var,
     # TreeHaver.backend=, or with_backend block).
     #
-    # Supports three types of backends:
+    # Supports four types of backends:
     # 1. Tree-sitter native backends (auto-discovered or explicit path)
     # 2. Citrus grammars (pure Ruby, via CITRUS_DEFAULTS or explicit config)
-    # 3. Pure Ruby backends (registered via backend_module, e.g., Prism, Psych, RBS)
+    # 3. Parslet grammars (pure Ruby, via PARSLET_DEFAULTS or explicit config)
+    # 4. Pure Ruby backends (registered via backend_module, e.g., Prism, Psych, RBS)
     #
     # @param language_name [Symbol, String] the language to parse (e.g., :toml, :json, :ruby, :yaml, :rbs)
     # @param library_path [String, nil] optional explicit path to tree-sitter grammar library
     # @param symbol [String, nil] optional tree-sitter symbol name (defaults to "tree_sitter_<name>")
     # @param citrus_config [Hash, nil] optional Citrus fallback configuration
+    # @param parslet_config [Hash, nil] optional Parslet fallback configuration
     # @return [TreeHaver::Parser] configured parser with language set
     # @raise [TreeHaver::NotAvailable] if no parser backend is available for the language
     #
@@ -1093,11 +1146,14 @@ module TreeHaver
     # @example Force Citrus backend
     #   TreeHaver.with_backend(:citrus) { TreeHaver.parser_for(:toml) }
     #
+    # @example Force Parslet backend
+    #   TreeHaver.with_backend(:parslet) { TreeHaver.parser_for(:toml) }
+    #
     # @example Use registered pure Ruby backend (e.g., RBS)
     #   # First, rbs-merge registers its backend:
     #   # TreeHaver.register_language(:rbs, backend_module: Rbs::Merge::RbsBackend, backend_type: :rbs)
     #   parser = TreeHaver.parser_for(:rbs)
-    def parser_for(language_name, library_path: nil, symbol: nil, citrus_config: nil)
+    def parser_for(language_name, library_path: nil, symbol: nil, citrus_config: nil, parslet_config: nil)
       # Ensure built-in pure Ruby backends are registered
       ensure_builtin_backends_registered!
 
@@ -1106,18 +1162,24 @@ module TreeHaver
       requested = effective_backend
 
       # Determine which backends to try based on effective_backend
+      # When a specific backend is requested, only try that backend
       try_tree_sitter = (requested == :auto) || NATIVE_BACKENDS.include?(requested)
       try_citrus = (requested == :auto) || (requested == :citrus)
+      try_parslet = (requested == :auto) || (requested == :parslet)
+
+      # When Citrus or Parslet is explicitly requested, don't try tree-sitter
+      if requested == :citrus || requested == :parslet
+        try_tree_sitter = false
+      end
 
       language = nil
-      parser = nil
 
       # First, check for registered pure Ruby backends
       # These take precedence when explicitly requested or when no other backend is available
       registration = registered_language(name)
-      # Find any registered backend_module (not tree_sitter or citrus)
+      # Find any registered backend_module (not tree_sitter, citrus, or parslet)
       registration&.each do |backend_type, config|
-        next if %i[tree_sitter citrus].include?(backend_type)
+        next if %i[tree_sitter citrus parslet].include?(backend_type)
         next unless config[:backend_module]
 
         backend_mod = config[:backend_module]
@@ -1153,9 +1215,14 @@ module TreeHaver
         language = load_citrus_language(name, citrus_config: citrus_config)
       end
 
+      # Try Parslet if applicable
+      if try_parslet && !language
+        language = load_parslet_language(name, parslet_config: parslet_config)
+      end
+
       # Raise if nothing worked
       raise NotAvailable, "No parser available for #{name}. " \
-        "Install tree-sitter-#{name} or configure a Citrus grammar." unless language
+        "Install tree-sitter-#{name} or configure a Citrus/Parslet grammar." unless language
 
       # Create and configure parser
       parser = Parser.new
@@ -1218,6 +1285,26 @@ module TreeHaver
     rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
       nil
     end
+
+    # Load a Parslet language from configuration or defaults
+    # @return [Language, nil]
+    def load_parslet_language(name, parslet_config: nil)
+      config = parslet_config || PARSLET_DEFAULTS[name] || {}
+      return unless config[:gem_name] && config[:grammar_const]
+
+      finder = ParsletGrammarFinder.new(
+        language: name,
+        gem_name: config[:gem_name],
+        grammar_const: config[:grammar_const],
+        require_path: config[:require_path],
+      )
+      return unless finder.available?
+
+      finder.register!
+      Language.public_send(name)
+    rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
+      nil
+    end
   end
 
   # Language and Parser classes have been moved to separate files:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 4.0.5
+  version: 5.0.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -227,12 +227,11 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.3
-description: "\U0001F334 TreeHaver is a cross-Ruby adapter for the tree-sitter parsing
-  library that works seamlessly across MRI Ruby, JRuby, and TruffleRuby. It provides
-  a unified API for parsing source code using tree-sitter grammars, regardless of
-  your Ruby implementation. Like Faraday for HTTP or multi_json for JSON, TreeHaver
-  lets you write once and run anywhere with automatic backend selection (MRI C extensions,
-  Rust extensions, FFI, or Java)."
+description: "\U0001F334 TreeHaver is a cross-Ruby adapter for many AST parsing libraries;
+  supporting MRI Ruby, JRuby, & TruffleRuby. Provides unified parsing API & AST when
+  using ruby_tree_sitter, parslet, citrus, ffi, tree_stump (Rust), JRuby JARs, etc.
+  As Faraday is to HTTP clients, this is for ASTs: 'Learn once & write once & run
+  anywhere'"
 email:
 - floss@galtzo.com
 executables: []
@@ -266,6 +265,7 @@ files:
 - lib/tree_haver/backends/ffi.rb
 - lib/tree_haver/backends/java.rb
 - lib/tree_haver/backends/mri.rb
+- lib/tree_haver/backends/parslet.rb
 - lib/tree_haver/backends/prism.rb
 - lib/tree_haver/backends/psych.rb
 - lib/tree_haver/backends/rust.rb
@@ -283,6 +283,7 @@ files:
 - lib/tree_haver/library_path_utils.rb
 - lib/tree_haver/node.rb
 - lib/tree_haver/parser.rb
+- lib/tree_haver/parslet_grammar_finder.rb
 - lib/tree_haver/path_validator.rb
 - lib/tree_haver/point.rb
 - lib/tree_haver/rspec.rb
@@ -298,10 +299,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://tree-haver.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v4.0.5
-  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v4.0.5/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v5.0.0
+  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v5.0.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/tree_haver/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/4.0.5
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/5.0.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
@@ -309,8 +310,8 @@ metadata:
   rubygems_mfa_required: 'true'
 rdoc_options:
 - "--title"
-- "tree_haver - \U0001F334 Cross-Ruby adapter for tree-sitter parsing that works on
-  MRI, JRuby, and TruffleRuby"
+- "tree_haver - \U0001F334 Cross-Ruby adapter for AST parsing libraries, like tree-sitter,
+  citrus, & parslet; works on MRI, JRuby, and TruffleRuby"
 - "--main"
 - README.md
 - "--exclude"
@@ -333,6 +334,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: "\U0001F334 Cross-Ruby adapter for tree-sitter parsing that works on MRI,
-  JRuby, and TruffleRuby"
+summary: "\U0001F334 Cross-Ruby adapter for AST parsing libraries, like tree-sitter,
+  citrus, & parslet; works on MRI, JRuby, and TruffleRuby"
 test_files: []