tree_haver 2.0.0 → 3.1.0

data/README.md

@@ -54,20 +54,24 @@
 
 ## 🌻 Synopsis
 
-TreeHaver is a cross-Ruby adapter for the [tree-sitter](https://tree-sitter.github.io/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.
+TreeHaver is a cross-Ruby adapter for the [tree-sitter](https://tree-sitter.github.io/tree-sitter/) and [Citrus](https://github.com/mjackson/citrus) parsing libraries and other dedicated parsing tools that works seamlessly across MRI Ruby, JRuby, and TruffleRuby. It provides a unified API for parsing source code using grammars, regardless of your Ruby implementation.
 
 ### The Adapter Pattern: Like Faraday, but for Parsing
 
 If you've used [Faraday](https://github.com/lostisland/faraday), [multi_json](https://github.com/intridea/multi_json), or [multi_xml](https://github.com/sferik/multi_xml), you'll feel right at home with TreeHaver. These gems share a common philosophy:
 
-| Gem            | Unified API for     | Backend Examples                                     |
-|----------------|---------------------|------------------------------------------------------|
-| **Faraday**    | HTTP requests       | Net::HTTP, Typhoeus, Patron, Excon                   |
-| **multi_json** | JSON parsing        | Oj, Yajl, JSON gem                                   |
-| **multi_xml**  | XML parsing         | Nokogiri, LibXML, Ox                                 |
-| **TreeHaver**  | tree-sitter parsing | ruby_tree_sitter, tree_stump, FFI, Java JARs, Citrus |
+| Gem            | Unified API for     | Backend Examples                                                         |
+|----------------|---------------------|--------------------------------------------------------------------------|
+| **Faraday**    | HTTP requests       | Net::HTTP, Typhoeus, Patron, Excon                                       |
+| **multi_json** | JSON parsing        | Oj, Yajl, JSON gem                                                       |
+| **multi_xml**  | XML parsing         | Nokogiri, LibXML, Ox                                                     |
+| **TreeHaver**  | Code parsing        | MRI, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus (& Co.) |
 
-**Write once, run anywhere.** Just as Faraday lets you swap HTTP adapters without changing your code, TreeHaver lets you swap tree-sitter backends. Your parsing code remains the same whether you're running on MRI with native C extensions, JRuby with FFI, or TruffleRuby.
+**Write once, run anywhere.**
+
+**Learn once, write anywhere.**
+
+Just as Faraday lets you swap HTTP adapters without changing your code, TreeHaver lets you swap tree-sitter backends. Your parsing code remains the same whether you're running on MRI with native C extensions, JRuby with FFI, or TruffleRuby.
 
 ```ruby
 # Your code stays the same regardless of backend
@@ -76,7 +80,7 @@ parser.language = TreeHaver::Language.from_library("/path/to/grammar.so")
 tree = parser.parse(source_code)
 
 # TreeHaver automatically picks the best backend:
-# - MRI → ruby_tree_sitter (C extension)
+# - MRI → ruby_tree_sitter (C extensions)
 # - JRuby → FFI (system's libtree-sitter)
 # - TruffleRuby → FFI or MRI backend
 ```
@@ -84,18 +88,94 @@ tree = parser.parse(source_code)
 ### Key Features
 
 - **Universal Ruby Support**: Works on MRI Ruby, JRuby, and TruffleRuby
-- **Multiple Backends**:
-  - **MRI Backend**: Leverages the excellent [`ruby_tree_sitter`](https://github.com/Faveod/ruby-tree-sitter) gem (C extension)
-  - **Rust Backend**: Uses [`tree_stump`](https://github.com/anthropics/tree_stump) gem (Rust extension with precompiled binaries)
-    - **Note**: Currently requires [pboling's fork](https://github.com/pboling/tree_stump/tree/tree_haver) until PRs [#5](https://github.com/joker1007/tree_stump/pull/5), [#7](https://github.com/joker1007/tree_stump/pull/7), [#11](https://github.com/joker1007/tree_stump/pull/11), and [#13 (inclusive of the others)](https://github.com/joker1007/tree_stump/pull/13) are merged
-  - **FFI Backend**: Pure Ruby FFI bindings to `libtree-sitter` (ideal for JRuby)
-  - **Java Backend**: Support for JRuby's native Java integration, and native java-tree-sitter grammar JARs
-  - **Citrus Backend**: Pure Ruby parser using [`citrus`](https://github.com/mjackson/citrus) gem (no native dependencies, portable)
+- **10 Parsing Backends** - Choose the right backend for your needs:
+  - **Tree-sitter Backends** (high-performance, incremental parsing):
+    - **MRI Backend**: Leverages [`ruby_tree_sitter`](https://github.com/Faveod/ruby-tree-sitter) gem (C extension, fastest on MRI)
+    - **Rust Backend**: Uses [`tree_stump`](https://github.com/anthropics/tree_stump) gem (Rust with precompiled binaries)
+      - **Note**: Currently requires [pboling's fork](https://github.com/pboling/tree_stump/tree/tree_haver) until PRs [#5](https://github.com/joker1007/tree_stump/pull/5), [#7](https://github.com/joker1007/tree_stump/pull/7), [#11](https://github.com/joker1007/tree_stump/pull/11), and [#13](https://github.com/joker1007/tree_stump/pull/13) are merged
+    - **FFI Backend**: Pure Ruby FFI bindings to `libtree-sitter` (ideal for JRuby, TruffleRuby)
+    - **Java Backend**: Native Java integration for JRuby with java-tree-sitter grammar JARs
+  - **Language-Specific Backends** (native parser integration):
+    - **Prism Backend**: Ruby's official parser ([Prism](https://github.com/ruby/prism), stdlib in Ruby 3.4+)
+    - **Psych Backend**: Ruby's YAML parser ([Psych](https://github.com/ruby/psych), stdlib)
+    - **Commonmarker Backend**: Fast Markdown parser ([Commonmarker](https://github.com/gjtorikian/commonmarker), comrak Rust)
+    - **Markly Backend**: GitHub Flavored Markdown ([Markly](https://github.com/ioquatix/markly), cmark-gfm C)
+  - **Pure Ruby Fallback**:
+    - **Citrus Backend**: Pure Ruby parsing via [`citrus`](https://github.com/mjackson/citrus) (no native dependencies)
 - **Automatic Backend Selection**: Intelligently selects the best backend for your Ruby implementation
-- **Language Agnostic**: Load any tree-sitter grammar dynamically (TOML, JSON, Ruby, JavaScript, etc.)
+- **Language Agnostic**: Parse any language - Ruby, Markdown, YAML, JSON, Bash, TOML, JavaScript, etc.
 - **Grammar Discovery**: Built-in `GrammarFinder` utility for platform-aware grammar library discovery
+- **Unified Position API**: Consistent `start_line`, `end_line`, `source_position` across all backends
 - **Thread-Safe**: Built-in language registry with thread-safe caching
-- **Minimal API Surface**: Simple, focused API that covers the most common tree-sitter use cases
+- **Minimal API Surface**: Simple, focused API that covers the most common use cases
+
+### Backend Requirements
+
+TreeHaver has minimal dependencies and automatically selects the best backend for your Ruby implementation. Each backend has specific version requirements:
+
+#### MRI Backend (ruby_tree_sitter, C extensions)
+
+**Requires `ruby_tree_sitter` v2.0+**
+
+In ruby_tree_sitter v2.0, all TreeSitter exceptions were changed to inherit from `Exception` (not `StandardError`). This was an intentional breaking change made for thread-safety and signal handling reasons.
+
+**Exception Mapping**: TreeHaver catches `TreeSitter::TreeSitterError` and its subclasses, converting them to `TreeHaver::NotAvailable` while preserving the original error message. This provides a consistent exception API across all backends:
+
+| ruby_tree_sitter Exception          | TreeHaver Exception        | When It Occurs                                 |
+|-------------------------------------|----------------------------|------------------------------------------------|
+| `TreeSitter::ParserNotFoundError`   | `TreeHaver::NotAvailable`  | Parser library file cannot be loaded           |
+| `TreeSitter::LanguageLoadError`     | `TreeHaver::NotAvailable`  | Language symbol loads but returns nothing      |
+| `TreeSitter::SymbolNotFoundError`   | `TreeHaver::NotAvailable`  | Symbol not found in library                    |
+| `TreeSitter::ParserVersionError`    | `TreeHaver::NotAvailable`  | Parser version incompatible with tree-sitter   |
+| `TreeSitter::QueryCreationError`    | `TreeHaver::NotAvailable`  | Query creation fails                           |
+
+```ruby
+# Add to your Gemfile for MRI backend
+gem "ruby_tree_sitter", "~> 2.0"
+```
+
+#### Rust Backend (tree_stump)
+
+Currently requires [pboling's fork](https://github.com/pboling/tree_stump/tree/tree_haver) until upstream PRs are merged.
+
+```ruby
+# Add to your Gemfile for Rust backend
+gem "tree_stump", github: "pboling/tree_stump", branch: "tree_haver"
+```
+
+#### FFI Backend
+
+Requires the `ffi` gem and a system installation of `libtree-sitter`:
+
+```ruby
+# Add to your Gemfile for FFI backend
+gem "ffi", ">= 1.15", "< 2.0"
+```
+
+```bash
+# Install libtree-sitter on your system:
+# macOS
+brew install tree-sitter
+
+# Ubuntu/Debian
+apt-get install libtree-sitter0 libtree-sitter-dev
+
+# Fedora
+dnf install tree-sitter tree-sitter-devel
+```
+
+#### Citrus Backend
+
+Pure Ruby parser with no native dependencies:
+
+```ruby
+# Add to your Gemfile for Citrus backend
+gem "citrus", "~> 3.0"
+```
+
+#### Java Backend (JRuby only)
+
+No additional dependencies required beyond grammar JARs built for java-tree-sitter.
 
 ### Why TreeHaver?
 
@@ -132,7 +212,7 @@ TreeHaver solves these problems by providing a unified API that automatically se
 
 **Note:** Java backend works with grammar JARs built specifically for java-tree-sitter, or grammar .so files that statically link tree-sitter. This is why FFI is recommended for JRuby & TruffleRuby.
 
-**Note:** TreeHaver can use `ruby_tree_sitter` or `tree_stump` as backends, giving you TreeHaver's unified API, grammar discovery, and security features, plus full access to incremental parsing when using those backends.
+**Note:** TreeHaver can use `ruby_tree_sitter` (MRI) or `tree_stump` (MRI, JRuby?) as backends, or `jruby-tree-sitter` (JRuby), giving you TreeHaver's unified API, grammar discovery, and security features, plus full access to incremental parsing when using those backends.
 
 **Note:** `tree_stump` currently requires [pboling's fork (tree_haver branch)](https://github.com/pboling/tree_stump/tree/tree_haver) until upstream PRs [#5](https://github.com/joker1007/tree_stump/pull/5), [#7](https://github.com/joker1007/tree_stump/pull/7), [#11](https://github.com/joker1007/tree_stump/pull/11), and [#13](https://github.com/joker1007/tree_stump/pull/13) are merged.
 
@@ -281,6 +361,133 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 
 ## ⚙️ Configuration
 
+### Available Backends
+
+TreeHaver supports 10 parsing backends, each with different trade-offs. The `auto` backend automatically selects the best available option.
+
+#### Tree-sitter Backends (Universal Parsing)
+
+| Backend | Description | Performance | Portability | Examples |
+|---------|-------------|-------------|-------------|----------|
+| **Auto** | Auto-selects best backend | Varies | ✅ Universal | [JSON](examples/auto_json.rb) · [JSONC](examples/auto_jsonc.rb) · [Bash](examples/auto_bash.rb) · [TOML](examples/auto_toml.rb) |
+| **MRI** | C extension via ruby_tree_sitter | ⚡ Fastest | MRI only | [JSON](examples/mri_json.rb) · [JSONC](examples/mri_jsonc.rb) · ~~Bash~~* · [TOML](examples/mri_toml.rb) |
+| **Rust** | Precompiled via tree_stump | ⚡ Very Fast | ✅ Good | [JSON](examples/rust_json.rb) · [JSONC](examples/rust_jsonc.rb) · ~~Bash~~* · [TOML](examples/rust_toml.rb) |
+| **FFI** | Dynamic linking via FFI | 🔵 Fast | ✅ Universal | [JSON](examples/ffi_json.rb) · [JSONC](examples/ffi_jsonc.rb) · [Bash](examples/ffi_bash.rb) · [TOML](examples/ffi_toml.rb) |
+| **Java** | JNI bindings | ⚡ Very Fast | JRuby only | [JSON](examples/java_json.rb) · [JSONC](examples/java_jsonc.rb) · [Bash](examples/java_bash.rb) · [TOML](examples/java_toml.rb) |
+
+#### Language-Specific Backends (Native Parser Integration)
+
+| Backend | Description | Performance | Portability | Examples |
+|---------|-------------|-------------|-------------|----------|
+| **Prism** | Ruby's official parser | ⚡ Very Fast | ✅ Universal | [Ruby](examples/prism_ruby.rb) |
+| **Psych** | Ruby's YAML parser (stdlib) | ⚡ Very Fast | ✅ Universal | [YAML](examples/psych_yaml.rb) |
+| **Commonmarker** | Markdown via comrak (Rust) | ⚡ Very Fast | ✅ Good | [Markdown](examples/commonmarker_markdown.rb) · [Merge](examples/commonmarker_merge_example.rb) |
+| **Markly** | GFM via cmark-gfm (C) | ⚡ Very Fast | ✅ Good | [Markdown](examples/markly_markdown.rb) · [Merge](examples/markly_merge_example.rb) |
+| **Citrus** | Pure Ruby parsing | 🟡 Slower | ✅ Universal | [TOML](examples/citrus_toml.rb) · [Finitio](examples/citrus_finitio.rb) · [Dhall](examples/citrus_dhall.rb) |
+
+**Selection Priority (Auto mode):** MRI → Rust → FFI → Java → Prism → Psych → Commonmarker → Markly → Citrus
+
+**Known Issues:**
+- *MRI + Bash: ABI incompatibility (use FFI instead)
+- *Rust + Bash: Version mismatch (use FFI instead)
+
+**Backend Requirements:**
+
+```ruby
+# Tree-sitter backends
+gem "ruby_tree_sitter", "~> 2.0"  # MRI backend
+gem "tree_stump"                   # Rust backend
+gem "ffi", ">= 1.15", "< 2.0"     # FFI backend
+# Java backend: no gem required (uses JRuby's built-in JNI)
+
+# Language-specific backends
+gem "prism", "~> 1.0"              # Ruby parsing (stdlib in Ruby 3.4+)
+# Psych: no gem required (Ruby stdlib)
+gem "commonmarker", ">= 0.23"      # Markdown parsing (comrak)
+gem "markly", "~> 0.11"            # GFM parsing (cmark-gfm)
+
+# Pure Ruby fallback
+gem "citrus", "~> 3.0"             # Citrus backend
+# Plus grammar gems: toml-rb, dhall, finitio, etc.
+```
+
+**Force Specific Backend:**
+
+```ruby
+# Tree-sitter backends
+TreeHaver.backend = :mri    # Force MRI backend (ruby_tree_sitter)
+TreeHaver.backend = :rust   # Force Rust backend (tree_stump)
+TreeHaver.backend = :ffi    # Force FFI backend
+TreeHaver.backend = :java   # Force Java backend (JRuby only)
+
+# Language-specific backends
+TreeHaver.backend = :prism        # Force Prism (Ruby parsing)
+TreeHaver.backend = :psych        # Force Psych (YAML parsing)
+TreeHaver.backend = :commonmarker # Force Commonmarker (Markdown)
+TreeHaver.backend = :markly       # Force Markly (GFM Markdown)
+
+# Pure Ruby fallback
+TreeHaver.backend = :citrus # Force Citrus backend
+
+# Auto-selection (default)
+TreeHaver.backend = :auto   # Let TreeHaver choose
+```
+
+**Block-based Backend Switching:**
+
+Use `with_backend` to temporarily switch backends for a specific block of code.
+This is thread-safe and supports nesting—the previous backend is automatically
+restored when the block exits (even if an exception is raised).
+
+```ruby
+# Temporarily use a specific backend
+TreeHaver.with_backend(:mri) do
+  parser = TreeHaver::Parser.new
+  tree = parser.parse(source)
+  # All operations in this block use the MRI backend
+end
+# Backend is restored to its previous value here
+
+# Nested blocks work correctly
+TreeHaver.with_backend(:rust) do
+  # Uses :rust
+  TreeHaver.with_backend(:citrus) do
+    # Uses :citrus
+    parser = TreeHaver::Parser.new
+  end
+  # Back to :rust
+end
+# Back to original backend
+```
+
+This is particularly useful for:
+
+- **Testing**: Test the same code with different backends
+- **Performance comparison**: Benchmark different backends
+- **Fallback scenarios**: Try one backend, fall back to another
+- **Thread isolation**: Each thread can use a different backend safely
+
+```ruby
+# Example: Testing with multiple backends
+[:mri, :rust, :citrus].each do |backend_name|
+  TreeHaver.with_backend(backend_name) do
+    parser = TreeHaver::Parser.new
+    result = parser.parse(source)
+    puts "#{backend_name}: #{result.root_node.type}"
+  end
+end
+```
+
+**Check Backend Capabilities:**
+
+```ruby
+TreeHaver.backend              # => :ffi
+TreeHaver.backend_module       # => TreeHaver::Backends::FFI
+TreeHaver.capabilities         # => { backend: :ffi, parse: true, query: false, ... }
+```
+
+See [examples/](examples/) directory for **26 complete working examples** demonstrating all 10 backends with multiple languages (JSON, JSONC, Bash, TOML, Ruby, YAML, Markdown) plus markdown-merge integration examples.
+
 ### Security Considerations
 
 **⚠️ Loading shared libraries (.so/.dylib/.dll) executes arbitrary native code.**
@@ -591,16 +798,103 @@ parser = TreeSitter::Parser.new  # Actually creates TreeHaver::Parser
 
 This is safe and idempotent—if the real `TreeSitter` module is already loaded, the shim does nothing.
 
+#### ⚠️ Important: Exception Hierarchy
+
+**Both ruby_tree_sitter v2+ and TreeHaver exceptions inherit from `Exception` (not `StandardError`).**
+
+This design decision follows ruby_tree_sitter's lead for thread-safety and signal handling reasons. See [ruby_tree_sitter PR #83](https://github.com/Faveod/ruby-tree-sitter/pull/83) for the rationale.
+
+**What this means for exception handling:**
+
+```ruby
+# ⚠️ This will NOT catch TreeHaver errors
+begin
+  TreeHaver::Language.from_library("/nonexistent.so")
+rescue => e
+  puts "Caught!"  # Never reached - TreeHaver::Error inherits Exception
+end
+
+# ✅ Explicit rescue is required
+begin
+  TreeHaver::Language.from_library("/nonexistent.so")
+rescue TreeHaver::Error => e
+  puts "Caught!"  # This works
+end
+
+# ✅ Or rescue specific exceptions
+begin
+  TreeHaver::Language.from_library("/nonexistent.so")
+rescue TreeHaver::NotAvailable => e
+  puts "Grammar not available: #{e.message}"
+end
+```
+
+**TreeHaver Exception Hierarchy:**
+
+```
+Exception
+└── TreeHaver::Error              # Base error class
+    ├── TreeHaver::NotAvailable   # Backend/grammar not available
+    └── TreeHaver::BackendConflict # Backend incompatibility detected
+```
+
+**Compatibility Mode Behavior:**
+
+The compat mode (`require "tree_haver/compat"`) creates aliases but **does not change the exception hierarchy**:
+
+```ruby
+require "tree_haver/compat"
+
+# TreeSitter constants are now aliases to TreeHaver
+TreeSitter::Error       # => TreeHaver::Error (still inherits Exception)
+TreeSitter::Parser      # => TreeHaver::Parser
+TreeSitter::Language    # => TreeHaver::Language
+
+# Exception handling remains the same
+begin
+  TreeSitter::Language.load("missing", "/nonexistent.so")
+rescue TreeSitter::Error => e  # Still requires explicit rescue
+  puts "Error: #{e.message}"
+end
+```
+
+**Best Practices:**
+
+1. **Always use explicit rescue** for TreeHaver errors:
+   ```ruby
+   begin
+     finder = TreeHaver::GrammarFinder.new(:toml)
+     finder.register! if finder.available?
+     language = TreeHaver::Language.toml
+   rescue TreeHaver::NotAvailable => e
+     warn("TOML grammar not available: #{e.message}")
+     # Fallback to another backend or fail gracefully
+   end
+   `````
+
+2. **Never rely on `rescue => e`** to catch TreeHaver errors (it won't work)
+
+**Why inherit from Exception?**
+
+Following ruby_tree_sitter's reasoning:
+- **Thread safety**: Prevents accidental catching in thread cleanup code
+- **Signal handling**: Ensures parsing errors don't interfere with SIGTERM/SIGINT
+- **Intentional handling**: Forces developers to explicitly handle parsing errors
+
+See `lib/tree_haver/compat.rb` for compatibility layer documentation.
+
 ## 🔧 Basic Usage
 
 ### Quick Start
 
-Here's a complete example of parsing TOML with TreeHaver:
+TreeHaver works with any language through its 10 backends. Here are examples for different parsing needs:
+
+#### Parsing with Tree-sitter (Universal Languages)
 
 ```ruby
 require "tree_haver"
 
-# Load a language grammar
+# Load a tree-sitter grammar (works with MRI, Rust, FFI, or Java backend)
 language = TreeHaver::Language.from_library(
   "/usr/local/lib/libtree-sitter-toml.so",
   symbol: "tree_sitter_toml",
@@ -610,7 +904,7 @@ language = TreeHaver::Language.from_library(
 parser = TreeHaver::Parser.new
 parser.language = language
 
-# Parse some source code
+# Parse source code
 source = <<~TOML
   [package]
   name = "my-app"
@@ -619,16 +913,116 @@ TOML
 
 tree = parser.parse(source)
 
-# Access the root node
+# Access the unified Position API (works across all backends)
 root = tree.root_node
-puts "Root node type: #{root.type}"  # => "document"
+puts "Root type: #{root.type}"              # => "document"
+puts "Start line: #{root.start_line}"       # => 1 (1-based)
+puts "End line: #{root.end_line}"           # => 3
+puts "Position: #{root.source_position}"    # => {start_line: 1, end_line: 3, ...}
 
 # Traverse the tree
 root.each do |child|
-  puts "Child type: #{child.type}"
-  child.each do |grandchild|
-    puts "  Grandchild type: #{grandchild.type}"
+  puts "Child: #{child.type} at line #{child.start_line}"
+end
+```
+
+#### Parsing Ruby with Prism
+
+```ruby
+require "tree_haver"
+
+TreeHaver.backend = :prism
+parser = TreeHaver::Parser.new
+parser.language = TreeHaver::Backends::Prism::Language.ruby
+
+source = <<~RUBY
+  class Example
+    def hello
+      puts "Hello, world!"
+    end
   end
+RUBY
+
+tree = parser.parse(source)
+root = tree.root_node
+
+# Find all method definitions
+def find_methods(node, results = [])
+  results << node if node.type == "def_node"
+  node.children.each { |child| find_methods(child, results) }
+  results
+end
+
+methods = find_methods(root)
+methods.each do |method_node|
+  pos = method_node.source_position
+  puts "Method at lines #{pos[:start_line]}-#{pos[:end_line]}"
+end
+```
+
+#### Parsing YAML with Psych
+
+```ruby
+require "tree_haver"
+
+TreeHaver.backend = :psych
+parser = TreeHaver::Parser.new
+parser.language = TreeHaver::Backends::Psych::Language.yaml
+
+source = <<~YAML
+  database:
+    host: localhost
+    port: 5432
+YAML
+
+tree = parser.parse(source)
+root = tree.root_node
+
+# Navigate YAML structure
+def show_structure(node, indent = 0)
+  prefix = "  " * indent
+  puts "#{prefix}#{node.type} (line #{node.start_line})"
+  node.children.each { |child| show_structure(child, indent + 1) }
+end
+
+show_structure(root)
+```
+
+#### Parsing Markdown with Commonmarker or Markly
+
+```ruby
+require "tree_haver"
+
+# Choose your backend
+TreeHaver.backend = :commonmarker  # or :markly for GFM
+
+parser = TreeHaver::Parser.new
+parser.language = TreeHaver::Backends::Commonmarker::Language.markdown
+
+source = <<~MARKDOWN
+  # My Document
+
+  ## Section
+
+  - Item 1
+  - Item 2
+MARKDOWN
+
+tree = parser.parse(source)
+root = tree.root_node
+
+# Find all headings
+def find_headings(node, results = [])
+  results << node if node.type == "heading"
+  node.children.each { |child| find_headings(child, results) }
+  results
+end
+
+headings = find_headings(root)
+headings.each do |heading|
+  level = heading.header_level
+  text = heading.children.map(&:text).join
+  puts "H#{level}: #{text} (line #{heading.start_line})"
 end
 ```
 
@@ -657,6 +1051,38 @@ parser.language = toml_language
 tree = parser.parse(toml_source)
 ```
 
+#### Flexible Language Names
+
+The `name` parameter in `register_language` is an arbitrary identifier you choose—it doesn't
+need to match the actual language name. The actual grammar identity comes from the `path`
+and `symbol` parameters (for tree-sitter) or `grammar_module` (for Citrus).
+
+This flexibility is useful for:
+
+- **Aliasing**: Register the same grammar under multiple names
+- **Versioning**: Register different grammar versions (e.g., `:ruby_2`, `:ruby_3`)
+- **Testing**: Use unique names to avoid collisions between tests
+- **Context-specific naming**: Use names that make sense for your application
+
+```ruby
+# Register the same TOML grammar under different names for different purposes
+TreeHaver.register_language(
+  :config_parser,  # Custom name for your app
+  path: "/usr/local/lib/libtree-sitter-toml.so",
+  symbol: "tree_sitter_toml",
+)
+
+TreeHaver.register_language(
+  :toml_v1,  # Version-specific name
+  path: "/usr/local/lib/libtree-sitter-toml.so",
+  symbol: "tree_sitter_toml",
+)
+
+# Use your custom names
+config_lang = TreeHaver::Language.config_parser
+versioned_lang = TreeHaver::Language.toml_v1
+```
+
 ### Parsing Different Languages
 
 TreeHaver works with any tree-sitter grammar:
@@ -875,23 +1301,90 @@ TreeHaver.backend = :mri
 TreeHaver.backend = :citrus
 ```
 
-### Advanced: Testing with Multiple Backends
+### Advanced: Thread-Safe Backend Switching
+
+TreeHaver provides `with_backend` for thread-safe, temporary backend switching. This is
+essential for testing, benchmarking, and applications that need different backends in
+different contexts.
 
-If you're developing a library that uses TreeHaver, you can test against different backends:
+#### Testing with Multiple Backends
+
+Test the same code path with different backends using `with_backend`:
 
 ```ruby
 # In your test setup
 RSpec.describe("MyParser") do
-  before do
-    TreeHaver.reset_backend!(to: :ffi)
+  # Test with each available backend
+  [:mri, :rust, :citrus].each do |backend_name|
+    context "with #{backend_name} backend" do
+      it "parses correctly" do
+        TreeHaver.with_backend(backend_name) do
+          parser = TreeHaver::Parser.new
+          result = parser.parse("x = 42")
+          expect(result.root_node.type).to(eq("document"))
+        end
+        # Backend automatically restored after block
+      end
+    end
   end
+end
+```
+
+#### Thread Isolation
+
+Each thread can use a different backend safely—`with_backend` uses thread-local storage:
 
-  after do
-    TreeHaver.reset_backend!(to: :auto)
+```ruby
+threads = []
+
+threads << Thread.new do
+  TreeHaver.with_backend(:mri) do
+    # This thread uses MRI backend
+    parser = TreeHaver::Parser.new
+    100.times { parser.parse("x = 1") }
   end
+end
+
+threads << Thread.new do
+  TreeHaver.with_backend(:citrus) do
+    # This thread uses Citrus backend simultaneously
+    parser = TreeHaver::Parser.new
+    100.times { parser.parse("x = 1") }
+  end
+end
+
+threads.each(&:join)
+```
+
+#### Nested Blocks
 
-  it "parses correctly with FFI backend" do
-    # Your test code
+`with_backend` supports nesting—inner blocks override outer blocks:
+
+```ruby
+TreeHaver.with_backend(:rust) do
+  puts TreeHaver.effective_backend  # => :rust
+
+  TreeHaver.with_backend(:citrus) do
+    puts TreeHaver.effective_backend  # => :citrus
+  end
+
+  puts TreeHaver.effective_backend  # => :rust (restored)
+end
+```
+
+#### Fallback Pattern
+
+Try one backend, fall back to another on failure:
+
+```ruby
+def parse_with_fallback(source)
+  TreeHaver.with_backend(:mri) do
+    TreeHaver::Parser.new.tap { |p| p.language = load_language }.parse(source)
+  end
+rescue TreeHaver::NotAvailable
+  # Fall back to Citrus if MRI backend unavailable
+  TreeHaver.with_backend(:citrus) do
+    TreeHaver::Parser.new.tap { |p| p.language = load_language }.parse(source)
   end
 end
 ```
@@ -1292,7 +1785,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.726-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.141-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year