ahocorasick-rust 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 396b47e4a2166e5388e806b60370f1bbc403cd86696a612a82330a320a22d396
-  data.tar.gz: 43a7063bf08b8d320f3a431861263e923228084e98b1efd038ae324dd07cdce2
+  metadata.gz: 040bfa66b5fdcf34e1ac7c7abc0ea45fa52561e83964750c59e54213bb5dbe10
+  data.tar.gz: 3e33df04f2ae0972f696085efe98984131eecf17cece98b9ae33c9a497f8b690
 SHA512:
-  metadata.gz: 00b5689f3bd8132306f111ef7ebf102571c8cdb1a19fa072e196be6b9a24a60de105ba594a4fefe83efe1a866ca7c76efc2190fb6ad4805b15f3ae8523a30ed7
-  data.tar.gz: a3361bb6ee20744a1d649c4cb07207e8335c1f469cbfea556afdba5ac3bb292e4213f24b9c9bc8faaa36755a84e4348df05bcc36cce864e012542312357e83fb
+  metadata.gz: 58bfcb0c7c05b0b477d1e85e9c9ed7d9ab683967771d2ec512a6f2f36b5c72c6c39beb4ba4f3c0ab3e1c66e3492f53fa0ccdff2b57b0dfe62a75114105810583
+  data.tar.gz: 77839a72ffe30a4f80aa6c1626d7770d6a215954f3365c9967b739f968a4b52d88de7d350e672cd4f5feea7c7a293fbea636a7194aaeecdbe085c94410a4af18

data/README.md

@@ -19,10 +19,12 @@ Aho-Corasick is a powerful string searching algorithm that can find **multiple p
 
 **Why this gem rocks:**
 - 🦀 Powered by Rust for maximum speed
-- 💎 Easy Ruby interface
+- 💎 Clean, intuitive Ruby API with 7+ search methods
 - 🚀 Up to **67x faster** than pure Ruby implementations
 - ✨ Precompiled binaries for major platforms
-- 🌈 Works with Ruby 2.7+
+- 🎯 Multiple search modes: overlapping, positioned, existence checks
+- 🔄 Find & replace with hash or block-based logic
+- 🌈 Works with Ruby 2.7+ and UTF-8/emoji
 
 ## Installation 📦
 
@@ -44,24 +46,135 @@ Or install it yourself:
 gem install ahocorasick-rust
 ```
 
-## Usage 🎀
+## Features ✨
 
-It's super simple!
+- **Multiple search modes** - Find all matches, overlapping matches, or just check existence
+- **Position tracking** - Get byte offsets for every match
+- **Case-insensitive matching** - Optional ASCII case-insensitive search
+- **Match strategies** - Control priority when patterns overlap
+- **Find & replace** - Replace patterns with strings or dynamic logic via blocks
+- **Unicode support** - Works seamlessly with UTF-8 text and emoji
+- **Zero-copy where possible** - Efficient memory usage
+
+## Quick Start 🎀
+
+### Basic Pattern Matching
 
 ```ruby
 require 'ahocorasick-rust'
 
-# Create a new matcher with your patterns
-animals = ['cat', 'dog', 'bunny', 'fox']
-matcher = AhoCorasickRust.new(animals)
+# Create a matcher with your patterns
+matcher = AhoCorasickRust.new(['cat', 'dog', 'fox'])
 
-# Search for all patterns in your text - finds them all in one pass! ✨
-text = "The quick brown fox jumps over the lazy dog."
-matcher.lookup(text)
+# Find all matches
+matcher.lookup("The quick brown fox jumps over the lazy dog.")
 # => ["fox", "dog"]
+
+# Check if any pattern exists
+matcher.match?("I have a cat")
+# => true
 ```
 
-**Want more examples?** Check out our [example script](scripts/example.rb) with content filtering, language detection, and more! 🌈
+### Case-Insensitive Matching
+
+```ruby
+matcher = AhoCorasickRust.new(['Ruby', 'Python'], case_insensitive: true)
+
+matcher.lookup('I love RUBY and python!')
+# => ["Ruby", "Python"]
+```
+
+### Get Match Positions
+
+```ruby
+matcher = AhoCorasickRust.new(['fox', 'dog'])
+
+matcher.lookup_with_positions('The fox and dog')
+# => [
+#      { pattern: 'fox', start: 4, end: 7 },
+#      { pattern: 'dog', start: 12, end: 15 }
+#    ]
+```
+
+### Find & Replace
+
+```ruby
+matcher = AhoCorasickRust.new(['bad', 'worse', 'worst'])
+
+# Replace with hash
+matcher.replace_all('This is bad and worse', { 'bad' => 'good', 'worse' => 'better' })
+# => "This is good and better"
+
+# Replace with block
+matcher.replace_all('This is bad and worse') { |word| '*' * word.length }
+# => "This is *** and *****"
+```
+
+### Overlapping Matches
+
+```ruby
+matcher = AhoCorasickRust.new(['abc', 'bcd', 'cde'])
+
+# Regular lookup finds non-overlapping matches
+matcher.lookup('abcde')
+# => ["abc"]
+
+# Overlapping lookup finds all matches
+matcher.lookup_overlapping('abcde')
+# => ["abc", "bcd", "cde"]
+```
+
+### Advanced: Match Strategies
+
+```ruby
+# Prefer longest matches
+matcher = AhoCorasickRust.new(
+  ['test', 'testing'],
+  match_kind: :leftmost_longest
+)
+
+matcher.lookup('testing')
+# => ["testing"]  # chooses longer match over 'test'
+```
+
+### Find First (Efficient for Existence Checks)
+
+```ruby
+matcher = AhoCorasickRust.new(['foo', 'bar', 'baz'])
+
+# Get just the first match (faster than getting all matches)
+matcher.find_first('hello foo bar baz')
+# => "foo"
+
+# Or with position
+matcher.find_first_with_position('hello foo bar')
+# => { pattern: 'foo', start: 6, end: 9 }
+```
+
+## API Overview 🔍
+
+**Constructor:**
+- `AhoCorasickRust.new(patterns, case_insensitive: false, match_kind: :leftmost_first)`
+
+**Search Methods:**
+- `#lookup(text)` - Find all non-overlapping matches
+- `#lookup_overlapping(text)` - Find all matches including overlaps
+- `#lookup_with_positions(text)` - Find matches with byte positions
+- `#match?(text)` - Check if any pattern exists (returns boolean)
+- `#find_first(text)` - Get first match only
+- `#find_first_with_position(text)` - Get first match with position
+
+**Replace Methods:**
+- `#replace_all(text, hash)` - Replace with hash mapping
+- `#replace_all(text) { |match| ... }` - Replace with block
+
+## Documentation 📖
+
+- **[API Reference](docs/reference.md)** - Complete method documentation with examples
+- **[Match Kind Guide](docs/match_kind.md)** - Understanding match strategies
+- **[Example Script](scripts/example.rb)** - Real-world usage examples
+
+**Want more examples?** Check out our example script with content filtering, language detection, and more! 🌈
 
 ## Benchmark 📊
 

data/docs/match_kind.md

@@ -0,0 +1,139 @@
+# Match Kind Strategies
+
+The `match_kind` option controls how the Aho-Corasick automaton behaves when multiple patterns could match at the same position in the text. This is important when you have overlapping patterns like `'abc'` and `'abcd'`.
+
+## Available Options
+
+### `:leftmost_first` (default)
+
+**Priority:** First pattern in the list wins
+
+When multiple patterns could match at the same position, the pattern that appears first in your pattern list takes precedence.
+
+```ruby
+matcher = AhoCorasickRust.new(['abc', 'abcd'], match_kind: :leftmost_first)
+matcher.lookup('abcd')
+# => ['abc']  # 'abc' appears first in the pattern list, so it wins
+```
+
+**Use cases:**
+- Keyword replacement where you want specific patterns to take precedence
+- Content filtering with priority rules
+- When you want explicit control over match priority by ordering your patterns
+
+---
+
+### `:leftmost_longest`
+
+**Priority:** Longest match wins
+
+When multiple patterns could match at the same position, the longest matching pattern is preferred.
+
+```ruby
+matcher = AhoCorasickRust.new(['abc', 'abcd'], match_kind: :leftmost_longest)
+matcher.lookup('abcd')
+# => ['abcd']  # 'abcd' is longer, so it wins
+```
+
+**Use cases:**
+- Tokenization where longer tokens are more meaningful
+- Entity recognition where you want the most specific match
+- Parsing structured text where longer patterns indicate more context
+
+---
+
+### `:standard`
+
+**Priority:** Standard Aho-Corasick algorithm behavior
+
+Reports matches as they're encountered in the automaton's state machine. This is the classical Aho-Corasick behavior.
+
+```ruby
+matcher = AhoCorasickRust.new(['abc', 'abcd'], match_kind: :standard)
+matcher.lookup('abcd')
+# => ['abc']  # Reports matches as the automaton finds them
+```
+
+**Use cases:**
+- When you need strict Aho-Corasick semantics
+- Potentially slightly faster for certain pattern sets
+- Academic or research purposes requiring standard algorithm behavior
+
+## Comparison Example
+
+Given patterns `['ab', 'abc', 'abcd']` and text `'abcd'`:
+
+| match_kind | Result | Reason |
+|------------|--------|--------|
+| `:leftmost_first` | `['ab']` | First pattern in list |
+| `:leftmost_longest` | `['abcd']` | Longest matching pattern |
+| `:standard` | `['ab']` | First match encountered by automaton |
+
+## Interaction with Other Features
+
+### With `#lookup_overlapping`
+
+The `match_kind` option does **not** affect `#lookup_overlapping`, which always returns all overlapping matches regardless of the strategy:
+
+```ruby
+matcher = AhoCorasickRust.new(['abc', 'bcd'], match_kind: :leftmost_first)
+
+# match_kind affects non-overlapping lookup
+matcher.lookup('abcd')
+# => ['abc']  (only one match, respects match_kind)
+
+# overlapping lookup ignores match_kind
+matcher.lookup_overlapping('abcd')
+# => ['abc', 'bcd']  (all matches, ignores match_kind)
+```
+
+### With `case_insensitive`
+
+The `match_kind` and `case_insensitive` options work together seamlessly:
+
+```ruby
+matcher = AhoCorasickRust.new(
+  ['abc', 'abcd'],
+  match_kind: :leftmost_longest,
+  case_insensitive: true
+)
+matcher.lookup('ABCD')
+# => ['abcd']  # Finds longest match, case-insensitively
+```
+
+### With `#find_first`
+
+The `match_kind` affects which match is returned by `#find_first`:
+
+```ruby
+# With leftmost_first
+matcher1 = AhoCorasickRust.new(['abc', 'abcd'], match_kind: :leftmost_first)
+matcher1.find_first('abcd')  # => 'abc'
+
+# With leftmost_longest
+matcher2 = AhoCorasickRust.new(['abc', 'abcd'], match_kind: :leftmost_longest)
+matcher2.find_first('abcd')  # => 'abcd'
+```
+
+## Choosing the Right Strategy
+
+**Use `:leftmost_first` when:**
+- You want explicit control over priority
+- Pattern order is meaningful in your domain
+- You're doing rule-based text processing
+
+**Use `:leftmost_longest` when:**
+- Longer matches are more specific/important
+- You're tokenizing or parsing
+- You want the most complete match
+
+**Use `:standard` when:**
+- You need classical Aho-Corasick semantics
+- You're comparing against other implementations
+- Performance is critical and you understand the tradeoffs
+
+## Performance Notes
+
+All three strategies use the same underlying automaton construction, so performance differences are minimal. The main difference is in the matching logic when choosing between multiple possible matches at the same position.
+
+In practice, `:leftmost_first` (the default) provides the best balance of performance, predictability, and control for most use cases.

data/docs/reference.md

@@ -0,0 +1,396 @@
+# API Reference
+
+Complete reference for all methods and options in the `ahocorasick-rust` gem.
+
+## Table of Contents
+
+- [Constructor](#constructor)
+- [Search Methods](#search-methods)
+- [Replace Methods](#replace-methods)
+
+---
+
+## Constructor
+
+### `AhoCorasickRust.new(patterns, **options)`
+
+Creates a new Aho-Corasick matcher from an array of pattern strings.
+
+**Parameters:**
+- `patterns` (Array<String>) - Array of pattern strings to search for
+- `options` (Hash) - Optional configuration
+
+**Options:**
+- `case_insensitive` (Boolean) - Enable ASCII case-insensitive matching (default: `false`)
+- `match_kind` (Symbol) - Strategy for handling overlapping patterns (default: `:leftmost_first`)
+  - `:leftmost_first` - First pattern in list wins
+  - `:leftmost_longest` - Longest pattern wins
+  - `:standard` - Standard Aho-Corasick behavior
+
+**Examples:**
+
+```ruby
+# Basic usage
+matcher = AhoCorasickRust.new(['foo', 'bar', 'baz'])
+
+# Case-insensitive matching
+matcher = AhoCorasickRust.new(['Ruby', 'Python'], case_insensitive: true)
+
+# Control match priority
+matcher = AhoCorasickRust.new(['abc', 'abcd'], match_kind: :leftmost_longest)
+
+# Combine options
+matcher = AhoCorasickRust.new(
+  ['test', 'testing'],
+  case_insensitive: true,
+  match_kind: :leftmost_longest
+)
+```
+
+**Raises:**
+- `TypeError` - If patterns is not an array or contains non-strings
+- `ArgumentError` - If match_kind is invalid
+- `RuntimeError` - If automaton construction fails
+
+---
+
+## Search Methods
+
+### `#lookup(haystack)`
+
+Finds all non-overlapping pattern matches in the haystack.
+
+**Parameters:**
+- `haystack` (String) - The text to search
+
+**Returns:** Array<String> - Array of matched patterns
+
+**Examples:**
+
+```ruby
+matcher = AhoCorasickRust.new(['foo', 'bar'])
+
+matcher.lookup('foo and bar')
+# => ['foo', 'bar']
+
+matcher.lookup('hello world')
+# => []
+
+# Non-overlapping: finds 'abc' and stops
+matcher = AhoCorasickRust.new(['abc', 'bcd'])
+matcher.lookup('abcd')
+# => ['abc']
+```
+
+---
+
+### `#lookup_overlapping(haystack)`
+
+Finds all pattern matches, including overlapping ones.
+
+**Parameters:**
+- `haystack` (String) - The text to search
+
+**Returns:** Array<String> - Array of all matched patterns, including overlaps
+
+**Examples:**
+
+```ruby
+matcher = AhoCorasickRust.new(['abc', 'bcd', 'cde'])
+
+matcher.lookup_overlapping('abcde')
+# => ['abc', 'bcd', 'cde']
+
+# Compare with non-overlapping
+matcher.lookup('abcde')
+# => ['abc']
+
+# Finds multiple occurrences of same pattern at different positions
+matcher = AhoCorasickRust.new(['a', 'ab'])
+matcher.lookup_overlapping('aab')
+# => ['a', 'a', 'ab']
+```
+
+---
+
+### `#lookup_with_positions(haystack)`
+
+Finds all non-overlapping matches with their byte positions.
+
+**Parameters:**
+- `haystack` (String) - The text to search
+
+**Returns:** Array<Hash> - Array of hashes with `:pattern`, `:start`, `:end` keys
+
+**Examples:**
+
+```ruby
+matcher = AhoCorasickRust.new(['fox', 'dog'])
+
+matcher.lookup_with_positions('The quick brown fox jumps over the lazy dog.')
+# => [
+#      { pattern: 'fox', start: 16, end: 19 },
+#      { pattern: 'dog', start: 40, end: 43 }
+#    ]
+
+matcher.lookup_with_positions('hello world')
+# => []
+
+# Positions are byte offsets, not character offsets
+matcher = AhoCorasickRust.new(['数据'])
+matcher.lookup_with_positions('金数据工具')
+# => [{ pattern: '数据', start: 3, end: 9 }]  # byte positions
+```
+
+---
+
+### `#match?(haystack)`
+
+Checks if any pattern matches in the haystack (predicate method).
+
+**Parameters:**
+- `haystack` (String) - The text to search
+
+**Returns:** Boolean - `true` if any pattern matches, `false` otherwise
+
+**Examples:**
+
+```ruby
+matcher = AhoCorasickRust.new(['foo', 'bar'])
+
+matcher.match?('hello foo world')
+# => true
+
+matcher.match?('hello world')
+# => false
+
+# Works with case-insensitive
+matcher = AhoCorasickRust.new(['Ruby'], case_insensitive: true)
+matcher.match?('I love ruby')
+# => true
+```
+
+---
+
+### `#find_first(haystack)`
+
+Returns the first pattern match found, or `nil` if no match.
+
+**Parameters:**
+- `haystack` (String) - The text to search
+
+**Returns:** String or nil - First matched pattern, or `nil` if no match
+
+**Examples:**
+
+```ruby
+matcher = AhoCorasickRust.new(['foo', 'bar', 'baz'])
+
+matcher.find_first('hello foo bar baz')
+# => 'foo'
+
+matcher.find_first('hello world')
+# => nil
+
+# Stops after first match (more efficient than #lookup)
+matcher = AhoCorasickRust.new(['cat', 'dog', 'bird'])
+matcher.find_first('The cat and dog are friends')
+# => 'cat'  (stops, doesn't find 'dog')
+```
+
+---
+
+### `#find_first_with_position(haystack)`
+
+Returns the first pattern match with its position, or `nil` if no match.
+
+**Parameters:**
+- `haystack` (String) - The text to search
+
+**Returns:** Hash or nil - Hash with `:pattern`, `:start`, `:end` keys, or `nil` if no match
+
+**Examples:**
+
+```ruby
+matcher = AhoCorasickRust.new(['foo', 'bar'])
+
+matcher.find_first_with_position('hello foo world')
+# => { pattern: 'foo', start: 6, end: 9 }
+
+matcher.find_first_with_position('hello world')
+# => nil
+
+# Finds earliest match in text, not first in pattern list
+matcher = AhoCorasickRust.new(['bar', 'foo'])
+matcher.find_first_with_position('foo bar baz')
+# => { pattern: 'foo', start: 0, end: 3 }  # 'foo' appears first in text
+```
+
+---
+
+## Replace Methods
+
+### `#replace_all(haystack, replacements)`
+
+Replaces all pattern matches with their corresponding replacements.
+
+**Parameters:**
+- `haystack` (String) - The text to search
+- `replacements` (Hash or Block) - Replacement mapping or block
+
+**Returns:** String - New string with replacements applied
+
+**Hash-based replacement:**
+
+Maps pattern strings to their replacements. Patterns not in the hash remain unchanged.
+
+```ruby
+matcher = AhoCorasickRust.new(['foo', 'bar', 'baz'])
+
+matcher.replace_all('foo and bar', { 'foo' => 'FOO', 'bar' => 'BAR' })
+# => 'FOO and BAR'
+
+# Partial replacement - 'baz' not in hash, stays unchanged
+matcher.replace_all('foo bar baz', { 'foo' => 'hello' })
+# => 'hello bar baz'
+
+# Empty hash - no replacements
+matcher.replace_all('foo and bar', {})
+# => 'foo and bar'
+```
+
+**Block-based replacement:**
+
+Passes each matched pattern to the block, uses return value as replacement.
+
+```ruby
+matcher = AhoCorasickRust.new(['foo', 'bar'])
+
+matcher.replace_all('foo and bar') { |match| match.upcase }
+# => 'FOO and BAR'
+
+# Dynamic replacement logic
+matcher = AhoCorasickRust.new(['apple', 'banana', 'cherry'])
+text = 'I like apple, banana, and cherry'
+result = matcher.replace_all(text) do |fruit|
+  { 'apple' => '🍎', 'banana' => '🍌', 'cherry' => '🍒' }[fruit]
+end
+# => 'I like 🍎, 🍌, and 🍒'
+
+# Replacement length can differ from match
+matcher = AhoCorasickRust.new(['a', 'bb'])
+matcher.replace_all('a bb a bb') { |m| m.length.to_s }
+# => '1 2 1 2'
+```
+
+**Raises:**
+- `ArgumentError` - If replacements is neither a Hash nor a block given
+
+---
+
+## Usage Patterns
+
+### Content Filtering
+
+```ruby
+# Filter profanity with asterisks
+bad_words = ['bad', 'worse', 'worst']
+filter = AhoCorasickRust.new(bad_words, case_insensitive: true)
+
+filter.replace_all('This is bad and worse') { |word| '*' * word.length }
+# => 'This is *** and *****'
+```
+
+### Keyword Highlighting
+
+```ruby
+keywords = ['Ruby', 'Python', 'JavaScript']
+matcher = AhoCorasickRust.new(keywords)
+
+positions = matcher.lookup_with_positions('I love Ruby and Python')
+# Use positions to add HTML tags, syntax highlighting, etc.
+```
+
+### Quick Existence Check
+
+```ruby
+# Check if any banned word appears
+banned = ['spam', 'scam', 'fraud']
+checker = AhoCorasickRust.new(banned, case_insensitive: true)
+
+if checker.match?(user_input)
+  reject_message
+end
+```
+
+### DNA Sequence Analysis
+
+```ruby
+# Find all overlapping genetic markers
+markers = ['ATCG', 'TCGA', 'CGAT']
+analyzer = AhoCorasickRust.new(markers)
+
+sequence = 'ATCGAT'
+analyzer.lookup_overlapping(sequence)
+# => ['ATCG', 'TCGA', 'CGAT']  # all overlapping matches
+```
+
+### Tokenization
+
+```ruby
+# Prefer longest matches for tokens
+keywords = ['if', 'iffy', 'then', 'end', 'endif']
+tokenizer = AhoCorasickRust.new(keywords, match_kind: :leftmost_longest)
+
+tokenizer.lookup('iffy then endif')
+# => ['iffy', 'then', 'endif']  # chooses longer 'iffy' over 'if'
+```
+
+---
+
+## Type Compatibility
+
+### Accepted Types
+
+- **Patterns:** Array of String objects
+- **Haystack:** String objects
+- **Options:** Symbol keys (`:case_insensitive`, `:match_kind`)
+- **Replacements:** Hash with String keys/values, or Block returning String
+
+### Unicode Support
+
+All methods support UTF-8 encoded strings:
+
+```ruby
+matcher = AhoCorasickRust.new(['こんにちは', '世界'])
+matcher.lookup('こんにちは世界')
+# => ['こんにちは', '世界']
+
+# Emoji support
+matcher = AhoCorasickRust.new(['😊', '🎉'])
+matcher.lookup('I am 😊 today 🎉')
+# => ['😊', '🎉']
+```
+
+**Note:** Position values in `#lookup_with_positions` and `#find_first_with_position` are byte offsets, not character offsets. For multi-byte UTF-8 characters, byte positions will differ from character positions.
+
+---
+
+## Error Handling
+
+```ruby
+# TypeError: patterns must be array of strings
+AhoCorasickRust.new('not an array')
+# TypeError: wrong argument type String (expected Array)
+
+AhoCorasickRust.new(['foo', 123])
+# TypeError: wrong argument type Integer (expected String)
+
+# ArgumentError: invalid match_kind
+AhoCorasickRust.new(['foo'], match_kind: :invalid)
+# ArgumentError: Invalid match_kind: 'invalid'...
+
+# TypeError: haystack must be string
+matcher.lookup(123)
+# TypeError: wrong argument type Integer (expected String)
+```

data/ext/rahocorasick/src/lib.rs

@@ -1,5 +1,5 @@
-use aho_corasick::AhoCorasick;
-use magnus::{method, function, prelude::*, Error, Ruby};
+use aho_corasick::{AhoCorasick, AhoCorasickBuilder, MatchKind};
+use magnus::{method, function, prelude::*, Error, Ruby, RHash, RArray, Value, Symbol};
 
 #[magnus::wrap(class = "AhoCorasickRust")]
 pub struct AhoCorasickRust {
@@ -8,12 +8,56 @@ pub struct AhoCorasickRust {
 }
 
 impl AhoCorasickRust {
-    fn new(ruby: &Ruby, words: Vec<String>) -> Result<Self, Error> {
-        let ac = AhoCorasick::new(&words)
+    fn new_impl(ruby: &Ruby, words: Vec<String>, kwargs: Option<RHash>) -> Result<Self, Error> {
+        let mut builder = AhoCorasickBuilder::new();
+
+        // Check for options if kwargs provided
+        if let Some(kwargs) = kwargs {
+            // case_insensitive option
+            if let Some(val) = kwargs.get(ruby.to_symbol("case_insensitive")) {
+                if let Ok(case_insensitive) = bool::try_convert(val) {
+                    if case_insensitive {
+                        builder.ascii_case_insensitive(true);
+                    }
+                }
+            }
+
+            // match_kind option
+            if let Some(val) = kwargs.get(ruby.to_symbol("match_kind")) {
+                if let Some(sym) = Symbol::from_value(val) {
+                    let kind_str = sym.name()?.to_string();
+                    let match_kind = match kind_str.as_ref() {
+                        "standard" => MatchKind::Standard,
+                        "leftmost_first" => MatchKind::LeftmostFirst,
+                        "leftmost_longest" => MatchKind::LeftmostLongest,
+                        _ => {
+                            return Err(Error::new(
+                                ruby.exception_arg_error(),
+                                format!("Invalid match_kind: '{}'. Valid values are :standard, :leftmost_first, :leftmost_longest", kind_str)
+                            ));
+                        }
+                    };
+                    builder.match_kind(match_kind);
+                }
+            }
+        }
+
+        let ac = builder.build(&words)
             .map_err(|e| Error::new(ruby.exception_runtime_error(), format!("Failed to build automaton: {}", e)))?;
         Ok(Self { words, ac })
     }
 
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = magnus::scan_args::scan_args::<(Vec<String>,), (), (), (), RHash, ()>(args)?;
+        let (words,) = args.required;
+        let kwargs = args.keywords;
+
+        // Only pass kwargs if non-empty
+        let kwargs_opt = if kwargs.len() > 0 { Some(kwargs) } else { None };
+
+        Self::new_impl(ruby, words, kwargs_opt)
+    }
+
     fn lookup(&self, haystack: String) -> Vec<String> {
         let mut matches = vec![];
         for mat in self.ac.find_iter(&haystack) {
@@ -21,12 +65,127 @@ impl AhoCorasickRust {
         }
         matches
     }
+
+    fn is_match(&self, haystack: String) -> bool {
+        self.ac.is_match(&haystack)
+    }
+
+    fn lookup_overlapping(&self, haystack: String) -> Vec<String> {
+        let mut matches = vec![];
+        for mat in self.ac.find_overlapping_iter(&haystack) {
+            matches.push(self.words[mat.pattern()].clone());
+        }
+        matches
+    }
+
+    fn find_first(&self, haystack: String) -> Option<String> {
+        self.ac.find(&haystack).map(|mat| self.words[mat.pattern()].clone())
+    }
+
+    fn find_first_with_position(&self, haystack: String) -> Result<Option<RHash>, Error> {
+        let ruby = Ruby::get().unwrap();
+        if let Some(mat) = self.ac.find(&haystack) {
+            let hash = ruby.hash_new();
+            hash.aset(ruby.to_symbol("pattern"), self.words[mat.pattern()].clone())?;
+            hash.aset(ruby.to_symbol("start"), mat.start())?;
+            hash.aset(ruby.to_symbol("end"), mat.end())?;
+            Ok(Some(hash))
+        } else {
+            Ok(None)
+        }
+    }
+
+    fn lookup_with_positions(&self, haystack: String) -> Result<RArray, Error> {
+        let ruby = Ruby::get().unwrap();
+        let matches = ruby.ary_new();
+        for mat in self.ac.find_iter(&haystack) {
+            let hash = ruby.hash_new();
+            hash.aset(ruby.to_symbol("pattern"), self.words[mat.pattern()].clone())?;
+            hash.aset(ruby.to_symbol("start"), mat.start())?;
+            hash.aset(ruby.to_symbol("end"), mat.end())?;
+            matches.push(hash)?;
+        }
+        Ok(matches)
+    }
+
+    fn replace_all(&self, args: &[Value]) -> Result<String, Error> {
+        let ruby = Ruby::get().unwrap();
+
+        // Parse arguments: haystack (required), replacements (optional if block given)
+        let haystack: String = if args.is_empty() {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "wrong number of arguments (given 0, expected 1..2)"
+            ));
+        } else {
+            String::try_convert(args[0])?
+        };
+
+        // Check if a block was given
+        match ruby.block_proc() {
+            Ok(proc) => {
+                // Block-based replacement
+                let mut result = haystack.clone();
+                let mut offset: isize = 0;
+
+                for mat in self.ac.find_iter(&haystack) {
+                    let pattern = &self.words[mat.pattern()];
+                    let replacement: String = proc.call((pattern.clone(),))?;
+
+                    let start = (mat.start() as isize + offset) as usize;
+                    let end = (mat.end() as isize + offset) as usize;
+
+                    result.replace_range(start..end, &replacement);
+                    offset += replacement.len() as isize - (mat.end() - mat.start()) as isize;
+                }
+
+                Ok(result)
+            }
+            Err(_) if args.len() >= 2 => {
+                // Hash-based replacement
+                if let Some(hash) = RHash::from_value(args[1]) {
+                    let mut replace_with: Vec<String> = Vec::with_capacity(self.words.len());
+
+                    for word in &self.words {
+                        if let Some(val) = hash.get(word.clone()) {
+                            if let Ok(replacement) = String::try_convert(val) {
+                                replace_with.push(replacement);
+                            } else {
+                                replace_with.push(word.clone());
+                            }
+                        } else {
+                            replace_with.push(word.clone());
+                        }
+                    }
+
+                    Ok(self.ac.replace_all(&haystack, &replace_with))
+                } else {
+                    Err(Error::new(
+                        ruby.exception_arg_error(),
+                        "replace_all requires a Hash or block"
+                    ))
+                }
+            }
+            Err(_) => {
+                Err(Error::new(
+                    ruby.exception_arg_error(),
+                    "replace_all requires a Hash or block"
+                ))
+            }
+        }
+    }
 }
 
 #[magnus::init]
 fn main(ruby: &Ruby) -> Result<(), Error> {
     let class = ruby.define_class("AhoCorasickRust", ruby.class_object())?;
-    class.define_singleton_method("new", function!(AhoCorasickRust::new, 1))?;
+    class.define_singleton_method("new", function!(AhoCorasickRust::new, -1))?;
     class.define_method("lookup", method!(AhoCorasickRust::lookup, 1))?;
+    class.define_method("match?", method!(AhoCorasickRust::is_match, 1))?;
+    class.define_method("lookup_overlapping", method!(AhoCorasickRust::lookup_overlapping, 1))?;
+    class.define_method("find_first", method!(AhoCorasickRust::find_first, 1))?;
+    class.define_method("find_first_with_position", method!(AhoCorasickRust::find_first_with_position, 1))?;
+    class.define_method("lookup_with_positions", method!(AhoCorasickRust::lookup_with_positions, 1))?;
+    class.define_method("replace_all", method!(AhoCorasickRust::replace_all, -1))?;
     Ok(())
 }

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ahocorasick-rust
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Eric
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -26,8 +25,9 @@ dependencies:
         version: 0.9.117
 description: A Ruby gem wrapping the legendary Rust Aho-Corasick algorithm! Aho-Corasick
   is a powerful string searching algorithm that finds multiple patterns simultaneously
-  in a text. Perfect for matching dictionaries, filtering words, and other multi-pattern
-  search tasks at lightning speed! (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧
+  in a text. Features include overlapping matches, case-insensitive search, find &
+  replace, match positions, and configurable match strategies. Perfect for content
+  filtering, tokenization, and multi-pattern search at lightning speed! (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧
 email:
 - eric@ebj.dev
 executables: []
@@ -37,6 +37,8 @@ extra_rdoc_files: []
 files:
 - README.md
 - Rakefile
+- docs/match_kind.md
+- docs/reference.md
 - ext/rahocorasick/Cargo.lock
 - ext/rahocorasick/Cargo.toml
 - ext/rahocorasick/extconf.rb
@@ -46,7 +48,6 @@ homepage: https://github.com/jetpks/ahocorasick-rust-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -61,8 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Blazing-fast ✨ Ruby wrapper for the Rust Aho-Corasick string matching algorithm!
 test_files: []