ahocorasick-rust 2.2.0-x86_64-linux-gnu

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/Cargo.lock

@@ -0,0 +1,304 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "0.7.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc936419f96fa211c1b9166887b38e5e40b19958e5b895be7c1f93adec7071ac"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.69.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "271383c67ccabffb7381723dea0672a673f292304fcb45c01cc648c7a8d58088"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "lazy_static",
+ "lazycell",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
+
+[[package]]
+name = "clang-sys"
+version = "1.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ed9a53e5d4d9c573ae844bfac6872b159cb1d1585a83b29e7a64b7eef7332a"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "glob"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2fabcfbdc87f4758337ca535fb41a6d701b65693ce38287d856d1674551ec9b"
+
+[[package]]
+name = "itertools"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba291022dbbd398a455acf126c1e341954079855bc60dfdda641363bd6922569"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646"
+
+[[package]]
+name = "lazycell"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55"
+
+[[package]]
+name = "libc"
+version = "0.2.139"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "201de327520df007757c1f0adce6e827fe8562fbc28bfd9c15571c66ca1f5f79"
+
+[[package]]
+name = "libloading"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67380fd3b2fbe7527a606e18729d21c6f3951633d0500574c4dc22d2d638b9f"
+dependencies = [
+ "cfg-if",
+ "winapi",
+]
+
+[[package]]
+name = "magnus"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
+dependencies = [
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "memchr"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2dffe52ecf27772e601905b7522cb4ef790d2cc203488bbd0e2fe85fcb74566d"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ee95bc4ef87b8d5ba32e8b7714ccc834865276eab0aed5c9958d00ec45f49e8"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rahocorasick"
+version = "0.1.0"
+dependencies = [
+ "aho-corasick 1.1.4",
+ "magnus",
+ "rb-sys",
+]
+
+[[package]]
+name = "rb-sys"
+version = "0.9.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f900d1ce4629a2ebffaf5de74bd8f9c1188d4c5ed406df02f97e22f77a006f44"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef1e9c857028f631056bcd6d88cec390c751e343ce2223ddb26d23eb4a151d59"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08f8d2924cf136a1315e2b4c7460a39f62ef11ee5d522df9b2750fab55b868b6"
+
+[[package]]
+name = "regex"
+version = "1.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48aaa5748ba571fb95cd2c85c09f629215d3a6ece942baa100950af03a34f733"
+dependencies = [
+ "aho-corasick 0.7.20",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.6.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "456c603be3e8d448b072f410900c09faf164fbce2d480456f50eea6e25f9c848"
+
+[[package]]
+name = "rustc-hash"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "shell-words"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24188a676b6ae68c3b2cb3a01be17fbf7240ce009799bb56d5b1409051e78fde"
+
+[[package]]
+name = "shlex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43b2853a4d09f215c24cc5489c992ce46052d359b5109343cbafbf26bc62f8a3"
+
+[[package]]
+name = "syn"
+version = "2.0.110"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a99801b5bd34ede4cf3fc688c5919368fea4e4814a4664359503e6015b280aea"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84a22b9f218b40614adcb3f4ff08b703773ad44fa9423e4e0d346d5db86e4ebc"
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"

data/ext/rahocorasick/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+edition = "2024"
+name = "rahocorasick"
+version = "0.1.0"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+aho-corasick = "1.1"
+magnus = "0.8"
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }