ahocorasick-rust 2.2.0-aarch64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f29b41b6780293db5dec1eea569d7303b5b7aa5db21d50be29d8271226ac9e67
+  data.tar.gz: 26d85073da308cd263384679af7e6e88ac9f2e07ed8eb59c211b007bfbce6ad9
+SHA512:
+  metadata.gz: cff0104df054af9338d3b11a6fac55343906140c14d870b21137a2c794b6d74a8c533cb2b16fbb1327b64ca354ddd1519cd04658476099cd488598c6b54f8392
+  data.tar.gz: 7c2311bebb1f546b67ee35580770bfef000b0969e64f121d9f6ff0a927fde08aebff339f8199de9a205dae778be3c99451cb366311f040148d53bd7d5e5f8fb1

data/README.md

@@ -0,0 +1,255 @@
+# Aho-Corasick Rust ✨
+
+[![Gem Version](https://badge.fury.io/rb/ahocorasick-rust.svg)](https://badge.fury.io/rb/ahocorasick-rust)
+
+> **Blazing-fast multi-pattern string matching for Ruby!** (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧
+
+`ahocorasick-rust` is a Ruby wrapper for the [Aho-Corasick algorithm](https://github.com/BurntSushi/aho-corasick) implemented in Rust! 🦀💎
+
+## What is Aho-Corasick? 🤔
+
+Aho-Corasick is a powerful string searching algorithm that can find **multiple patterns simultaneously** in a single pass through your text! Unlike traditional string matching that searches for one pattern at a time, Aho-Corasick builds a finite state machine from your dictionary of patterns and matches them all at once.
+
+**Perfect for:**
+- 🔍 Content filtering & moderation
+- 📝 Finding keywords in large documents
+- 🚫 Detecting prohibited words or phrases
+- 🏷️ Multi-pattern text analysis
+- ⚡ Any scenario where you need to search for many patterns efficiently!
+
+**Why this gem rocks:**
+- 🦀 Powered by Rust for maximum speed
+- 💎 Clean, intuitive Ruby API with 7+ search methods
+- 🚀 Up to **67x faster** than pure Ruby implementations
+- ✨ Precompiled binaries for major platforms
+- 🎯 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 📦
+
+Add this gem to your `Gemfile`:
+
+```ruby
+gem 'ahocorasick-rust'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install ahocorasick-rust
+```
+
+## Features ✨
+
+- **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 matcher with your patterns
+matcher = AhoCorasickRust.new(['cat', 'dog', 'fox'])
+
+# 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
+```
+
+### 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 📊
+
+**Don't just take our word for it - check out these performance numbers!** 🎉
+
+### Test Setup 1
+- Words: 500 patterns
+- Test cases: 2,000
+- Text length: 3,154 chars (avg), 23,676 (max)
+
+```
+       user     system      total        real
+each&include  6.487059   0.185424   6.672483 (  6.791808)
+ruby_ahoc     4.178672   0.138610   4.317282 (  4.547964)
+rust_ahoc     0.157662   0.004847   0.162509 (  0.166964)
+```
+
+> 🎈 **27.2x faster** than pure Ruby implementation!
+
+### Test Setup 2
+- Words: 500 patterns
+- Test cases: 2,000
+- Text length: 49,162 chars (avg), 10,392,056 (max)
+
+```
+       user     system      total        real
+each&include 27.903179   0.237389  28.140568 ( 28.563194)
+ruby_ahoc    45.220535   0.363107  45.583642 ( 46.477702)
+rust_ahoc     0.670583   0.007192   0.677775 (  0.686904)
+```
+
+> 🎈 **67.7x faster** than pure Ruby implementation!
+
+The larger your text and the more patterns you have, the more this gem shines! ✨
+
+## Platform Support 🌍
+
+Precompiled binaries are available for:
+- 🍎 macOS (ARM64 & x86_64)
+- 🐧 Linux (ARM64 & x86_64)
+
+If a precompiled binary isn't available for your platform, the gem will automatically compile the Rust extension during installation.
+
+## Development 🛠️
+
+Want to contribute? Yay! 🎉
+
+```bash
+# Install dependencies
+bundle install
+
+# Compile the extension
+fish -c "bundle exec rake dev compile"
+
+# Run tests
+fish -c "bundle exec rake test"
+
+# Build the gem
+gem build ahocorasick-rust.gemspec
+```
+
+## References 📚
+
+- [Aho-Corasick (Rust)](https://github.com/BurntSushi/aho-corasick) - The amazing Rust implementation we wrap
+- [Aho-Corasick Algorithm](https://en.wikipedia.org/wiki/Aho%E2%80%93Corasick_algorithm) - Learn about the algorithm
+- [Original Ruby Implementation](https://github.com/ahnick/ahocorasick) - Pure Ruby version for comparison
+
+## Contributing 💝
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/jetpks/ahocorasick-rust-ruby](https://github.com/jetpks/ahocorasick-rust-ruby)!
+
+## License 📄
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+Made with 💖 and Rust 🦀 by Eric

data/Rakefile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+require 'rake/extensiontask'
+
+CROSS_PLATFORMS = %w[
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+].freeze
+
+spec = Bundler.load_gemspec('ahocorasick-rust.gemspec')
+
+Rake::ExtensionTask.new('rahocorasick', spec) do |c|
+  c.lib_dir = 'lib/rahocorasick'
+  c.source_pattern = '*.{rs,toml}'
+  c.cross_compile = true
+  c.cross_platform = CROSS_PLATFORMS
+end
+
+Rake::TestTask.new do |t|
+  t.deps << :dev << :compile
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :dev do
+  ENV['RB_SYS_CARGO_PROFILE'] = 'dev'
+end
+
+task default: :test

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.