tree_haver 3.1.0 → 3.1.2

data/lib/tree_haver/rspec.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# TreeHaver RSpec Integration
+#
+# This file provides RSpec helpers and configuration for testing
+# code that uses TreeHaver. Require this in your spec_helper.rb:
+#
+#   require "tree_haver/rspec"
+#
+# This will load:
+# - Dependency tags for conditional test execution
+# - (Future) Additional test helpers as needed
+#
+# @example spec_helper.rb
+#   require "tree_haver/rspec"
+#
+#   RSpec.configure do |config|
+#     # Your additional configuration...
+#   end
+#
+# @see TreeHaver::RSpec::DependencyTags
+
+require_relative "rspec/dependency_tags"

data/lib/tree_haver/tree.rb

@@ -156,7 +156,7 @@ module TreeHaver
       raise unless e.name == :edit || e.message.include?("edit")
       raise TreeHaver::NotAvailable,
         "Incremental parsing not supported by current backend. " \
-          "Use MRI (ruby_tree_sitter), Rust (tree_stump), or Java (java-tree-sitter) backend."
+          "Use MRI (ruby_tree_sitter), Rust (tree_stump), or Java (java-tree-sitter / jtreesitter) backend."
     end
 
     private

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.1.0"
+    VERSION = "3.1.2"
   end
 
   # Traditional location for VERSION constant

data/lib/tree_haver.rb

@@ -212,6 +212,9 @@ module TreeHaver
   # @see CitrusGrammarFinder
   autoload :CitrusGrammarFinder, File.join(__dir__, "tree_haver", "citrus_grammar_finder")
 
+  # Point class for position information (row, column)
+  autoload :Point, File.join(__dir__, "tree_haver", "point")
+
   # Unified Node wrapper providing consistent API across backends
   autoload :Node, File.join(__dir__, "tree_haver", "node")
 
@@ -725,6 +728,111 @@ module TreeHaver
     def registered_language(name)
       LanguageRegistry.registered(name)
     end
+
+    # Create a parser configured for a specific language
+    #
+    # This is the recommended high-level API for creating a parser. It handles:
+    # 1. Checking if the language is already registered
+    # 2. Auto-discovering tree-sitter grammar via GrammarFinder
+    # 3. Falling back to Citrus grammar if tree-sitter is unavailable
+    # 4. Creating and configuring the parser
+    #
+    # @param language_name [Symbol, String] the language to parse (e.g., :toml, :json, :bash)
+    # @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
+    # @option citrus_config [String] :gem_name gem name for the Citrus grammar
+    # @option citrus_config [String] :grammar_const fully qualified constant name for grammar module
+    # @return [TreeHaver::Parser] configured parser with language set
+    # @raise [TreeHaver::NotAvailable] if no parser backend is available for the language
+    #
+    # @example Basic usage (auto-discovers grammar)
+    #   parser = TreeHaver.parser_for(:toml)
+    #   tree = parser.parse("[package]\nname = \"my-app\"")
+    #
+    # @example With explicit library path
+    #   parser = TreeHaver.parser_for(:toml, library_path: "/custom/path/libtree-sitter-toml.so")
+    #
+    # @example With Citrus fallback configuration
+    #   parser = TreeHaver.parser_for(:toml,
+    #     citrus_config: { gem_name: "toml-rb", grammar_const: "TomlRB::Document" }
+    #   )
+    def parser_for(language_name, library_path: nil, symbol: nil, citrus_config: nil)
+      name = language_name.to_sym
+      symbol ||= "tree_sitter_#{name}"
+
+      # Step 1: Try to get the language (may already be registered)
+      language = begin
+        # Check if already registered and loadable
+        if registered_language(name)
+          Language.public_send(name, path: library_path, symbol: symbol)
+        end
+      rescue NotAvailable, ArgumentError, LoadError
+        nil
+      end
+
+      # Step 2: If not registered, try GrammarFinder for tree-sitter
+      unless language
+        # Principle of Least Surprise: If user provides an explicit path,
+        # it MUST exist. Don't silently fall back to auto-discovery.
+        if library_path && !library_path.empty?
+          unless File.exist?(library_path)
+            raise NotAvailable,
+              "Specified parser path does not exist: #{library_path}"
+          end
+          begin
+            register_language(name, path: library_path, symbol: symbol)
+            language = Language.public_send(name)
+          rescue NotAvailable, ArgumentError, LoadError => e
+            # Re-raise with more context since user explicitly provided this path
+            raise NotAvailable,
+              "Failed to load parser from specified path #{library_path}: #{e.message}"
+          end
+        else
+          # Auto-discover via GrammarFinder (no explicit path provided)
+          begin
+            finder = GrammarFinder.new(name)
+            if finder.available?
+              finder.register!
+              language = Language.public_send(name)
+            end
+          rescue NotAvailable, ArgumentError, LoadError
+            language = nil
+          end
+        end
+      end
+
+      # 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)
+          end
+        rescue NotAvailable, ArgumentError, LoadError, NameError
+          language = nil
+        end
+      end
+
+      # Step 4: Raise if nothing worked
+      unless language
+        raise NotAvailable,
+          "No parser available for #{name}. " \
+            "Install tree-sitter-#{name} or the appropriate Ruby gem. " \
+            "Set TREE_SITTER_#{name.to_s.upcase}_PATH for custom grammar location."
+      end
+
+      # Step 5: Create and configure parser
+      parser = Parser.new
+      parser.language = language
+      parser
+    end
   end
 
   # Represents a tree-sitter language grammar

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.2
 platform: ruby
 authors:
 - Peter H. Boling
@@ -133,6 +133,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: kettle-soup-cover
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
 - !ruby/object:Gem::Dependency
   name: kettle-test
   requirement: !ruby/object:Gem::Requirement
@@ -255,6 +275,9 @@ files:
 - lib/tree_haver/language_registry.rb
 - lib/tree_haver/node.rb
 - lib/tree_haver/path_validator.rb
+- lib/tree_haver/point.rb
+- lib/tree_haver/rspec.rb
+- lib/tree_haver/rspec/dependency_tags.rb
 - lib/tree_haver/tree.rb
 - lib/tree_haver/version.rb
 - sig/tree_haver.rbs
@@ -266,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.0
-  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.1.0/CHANGELOG.md
+  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
   bug_tracker_uri: https://github.com/kettle-rb/tree_haver/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.1.0
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.1.2
   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
@@ -299,7 +322,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.3
 specification_version: 4
 summary: "\U0001F334 Cross-Ruby adapter for tree-sitter parsing that works on MRI,
   JRuby, and TruffleRuby"

metadata.gz.sig

@@ -1,2 +1,3 @@
-o�&�z�5��G�&U��mo��Z~�Yu8:2ٖOF����*q�|�x| �
-�V��zwᵻ��j�^62�/
+�]��:cD1@M���S��ܖq��.8�V� ��h��p�����g�.�dn����
+K
+c�Ll 捻�r�5>���p �|sl�UԤb���zS��+"1�~㿄U��j.���F��o3��,ǥ!#�a�)��
�9��ŬЍij��tU�4��J�