tre_regex 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c397cd3765b015545e177b95c5bd349990bd93ff8bb50d93e31d6e8d1888516b
-  data.tar.gz: d149058f38eb481add948d7f44e23e6c20a49a820c95bf08cda52772313eecc1
+  metadata.gz: 71f0e9a1dae495b0c90ea158eb3ca777628ab09bff914b8e93daa1f60bae0eb7
+  data.tar.gz: a1dad85bb7991a50043691664b32515868ee0eb74a2f57c012467dadd180da72
 SHA512:
-  metadata.gz: f61f4e18c2a67b1e6136976f4558418eefbd18609bf4acb2a7a8e292aa6c6d19c675ac2008c3bc0995d6d15c071a9e4c6b58f37e5894b841632db96b55a27762
-  data.tar.gz: 5caefb33cd586c165df5f4d3c29cc879d1706b04e974a838429322d91eabe439ad4eadf7c43b6859ed02626eefa0578f8b112e3ed2591ac4c127c31224d62371
+  metadata.gz: a2f9c17fff47178e2fa7b6bdab40714593ed163229b0fec6e824b35575f7046afe8fd75fbbb208c3bf54d891268b0bcc07a93aa67c43b8966f06d5d8267bc375
+  data.tar.gz: 7fb802f25c70580d0f47488f3f43fc102a1230d2b5a5e47e092b3b6186dba97465fd3e7fd0b0f88fbdf6ff98eeca2daf9680cd86aed83f8d1e8e6939d462c0fa

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksii Vasyliev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,325 @@
+# TreRegex [![Ruby Checks](https://github.com/le0pard/tre_regex/actions/workflows/main.yml/badge.svg)](https://github.com/le0pard/tre_regex/actions/workflows/main.yml)
+
+`TreRegex` is a robust Ruby gem that provides a high-performance interface to the [TRE](https://github.com/laurikari/tre) approximate regex matching library. Powered by FFI, it allows you to perform lightning-fast fuzzy string searching while safely handling Ruby's Unicode characters.
+
+## Why?
+
+Standard regular expressions are strictly exact. If you are searching text containing typos, OCR errors, or variations in spelling, standard `Regexp` will fail.
+
+While Ruby has built-in string distance metrics (like Levenshtein distance), they usually require comparing whole strings against other whole strings. `TreRegex` solves this by allowing you to search for a pattern *within* a larger body of text while permitting a configurable number of errors (insertions, deletions, and substitutions).
+
+## Features
+
+* **Approximate Matching**: Find matches even if the target string has missing, extra, or substituted characters.
+* **Granular Control**: Set strict limits on `max_errors`, or fine-tune by specific error types (`max_insertions`, `max_deletions`, `max_substitutions`).
+* **Multi-byte Unicode Safety**: Transparently maps underlying C byte-offsets back to native Ruby character indices (e.g., emojis won't break your offsets).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tre_regex'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it directly:
+
+```bash
+$ gem install tre_regex
+```
+
+## Usage
+
+### Basic Matching
+
+Create a new `TreRegex::Regex` object and use `exec` or `test?` to search text
+
+```ruby
+require 'tre_regex'
+
+regex = TreRegex::Regex.new('apple', ignore_case: true)
+
+# Simple boolean check
+regex.test?('I ate an APPLE today')
+# => true
+
+# Get detailed match data
+result = regex.exec('I ate an apple today')
+# => {
+#      :match => "apple",
+#      :submatches => [],
+#      :index => 9,
+#      :end_index => 14,
+#      :cost => 0,
+#      :errors => {:insertions=>0, :deletions=>0, :substitutions=>0}
+#    }
+```
+
+### Fuzzy Matching
+
+You can configure fuzziness by passing options directly to the `exec` method
+
+```ruby
+regex = TreRegex::Regex.new('apple')
+
+# Allow up to 1 error of any kind
+regex.exec('I ate an aple', max_errors: 1)
+# => {match: "aple", submatches: [], index: 9, end_index: 13, cost: 1, errors: {insertions: 0, deletions: 1, substitutions: 0}}
+
+# Allow substitutions, but explicitly forbid deletions
+regex.exec('I ate an aple', max_substitutions: 1, max_deletions: 0)
+# => nil
+```
+
+### Finding All Matches
+
+Use `match_all` to find every occurrence of a pattern in a string. It can take a block or return an `Enumerator`
+
+```ruby
+regex = TreRegex::Regex.new('cat')
+
+# Returns an array of match hashes
+regex.match_all('cat, cot, cut', max_errors: 1).to_a
+# => [
+#   {match: "cat", submatches: [], index: 0, end_index: 3, cost: 0, errors: {insertions: 0, deletions: 0, substitutions: 0}},
+#  {match: "cot", submatches: [], index: 5, end_index: 8, cost: 1, errors: {insertions: 0, deletions: 0, substitutions: 1}},
+#  {match: "cut", submatches: [], index: 10, end_index: 13, cost: 1, errors: {insertions: 0, deletions: 0, substitutions: 1}}
+#    ]
+```
+
+### Capture Groups (Submatches)
+
+`TreRegex` fully supports standard POSIX capture groups using parentheses `()`. Whenever a match is found, any captured data is returned as an array of strings under the `:submatches` key in the result hash.
+
+If your pattern does not contain any capture groups, `:submatches` will simply return an empty array `[]`.
+
+```ruby
+regex = TreRegex::Regex.new('I love (ruby|python)')
+result = regex.exec('I love ruby a lot')
+
+# The captured group is extracted exactly as it was matched
+result[:submatches] # => ["ruby"]
+```
+
+#### Multiple and Optional Groups
+
+You can define multiple capture groups, and they will be returned in the array in the exact order they appear in the pattern.
+
+If you use an optional capture group `?` that does not end up matching anything in the target text, `TreRegex` will safely insert a `nil` in its place in the array to maintain the correct index order.
+
+```ruby
+# The first group (cat) is optional. The second group (dog) is required.
+regex = TreRegex::Regex.new('(cat)?(dog)')
+
+result = regex.exec('dog')
+# => {match: "dog", submatches: [nil, "dog"], index: 0, end_index: 3, cost: 0, errors: {insertions: 0, deletions: 0, substitutions: 0}}
+```
+
+#### Fuzzy Capture Groups
+
+One of the most powerful features of `TreRegex` is that capture groups respect your fuzzy matching rules! If a typo occurs *inside* a capture group, the `:submatches` array will return the actual typed text with the typo included.
+
+```ruby
+regex = TreRegex::Regex.new('I ate an (apple)')
+
+# We allow 1 error. The user typed 'aple' (1 deletion).
+result = regex.exec('I ate an aple', max_errors: 1)
+
+result[:submatches] # => ["aple"]
+```
+
+#### The 9-Group Limit
+
+For memory safety and performance during FFI allocation, `TreRegex` allocates a strict maximum of 10 slots per match. Because the first slot is always reserved for the full regex match itself, the engine will only extract a maximum of **9 capture groups** per match.
+
+If your pattern contains 10 or more capture groups `()`, the regex will still compile and match perfectly, but any captured groups beyond the 9th one will be safely ignored and omitted from the `:submatches` array.
+
+## Configuration Options
+
+`TreRegex` provides fine-grained control over how patterns are compiled and how fuzzy matching constraints are applied.
+
+### Initialization Options
+
+When creating a new `TreRegex::Regex` object, you can pass options to modify how the pattern is compiled:
+
+* **`ignore_case`** *(Boolean)*: If `true`, the regex will match characters regardless of their case (equivalent to the `/i` flag in standard Ruby regex). Default is `false`.
+
+```ruby
+# Fails because case doesn't match
+exact_regex = TreRegex::Regex.new('ruby')
+exact_regex.test?('RUBY') # => false
+
+# Succeeds using the ignore_case flag
+case_regex = TreRegex::Regex.new('ruby', ignore_case: true)
+case_regex.test?('RUBY') # => true
+```
+
+### Fuzzy Matching Options
+
+When calling `exec`, `test?`, or `match_all`, you can pass a hash of fuzzy matching options. If no options are provided, `TreRegex` forces an **exact match** (0 errors allowed).
+
+#### Error Limits
+
+These options strictly limit the number of specific operations required to transform the pattern into the matched string.
+
+* **`max_errors`** *(Integer)*: The total maximum number of combined errors (insertions + deletions + substitutions) allowed for a match.
+* **`max_insertions`** *(Integer)*: The maximum number of extra characters allowed in the searched text. *(e.g., Pattern `cat` matching `cart` is 1 insertion)*.
+* **`max_deletions`** *(Integer)*: The maximum number of missing characters in the searched text. *(e.g., Pattern `cat` matching `ct` is 1 deletion)*.
+* **`max_substitutions`** *(Integer)*: The maximum number of swapped characters. *(e.g., Pattern `cat` matching `cot` is 1 substitution)*.
+
+> **Note:** If you specify granular limits (like `max_deletions: 1`) but omit `max_errors`, the gem will automatically calculate the maximum allowed errors so you don't accidentally trigger an unlimited fuzzy search.
+
+```ruby
+regex = TreRegex::Regex.new('banana')
+
+# Allow up to 2 typos of any kind
+regex.exec('bananana', max_errors: 2) # => matches "bananana" (2 insertions)
+regex.exec('bnnna', max_errors: 2)    # => matches "bnnna" (2 deletions)
+regex.exec('bonono', max_errors: 2)   # => matches "bonono" (2 substitutions)
+
+# Another example
+regex = TreRegex::Regex.new('library')
+
+# Allow 1 deletion, but STRICTLY 0 substitutions and 0 insertions
+regex.exec('librry', max_deletions: 1, max_substitutions: 0, max_insertions: 0)
+# => matches "librry"
+
+# This fails because 'lubrary' requires a substitution, which we set to 0
+regex.exec('lubrary', max_deletions: 1, max_substitutions: 0, max_insertions: 0)
+# => nil
+```
+
+#### Cost and Weights
+
+Instead of hard limits, you can assign different "costs" to different types of errors. This is useful if you want to penalize certain typos more heavily than others.
+
+* **`max_cost`** *(Integer)*: The maximum total cost allowed for a match to be considered successful.
+* **`weight_insertion`** *(Integer)*: The cost penalty for each inserted character.
+* **`weight_deletion`** *(Integer)*: The cost penalty for each deleted character.
+* **`weight_substitution`** *(Integer)*: The cost penalty for each substituted character.
+
+```ruby
+regex = TreRegex::Regex.new('algorithm')
+
+# We allow a maximum cost of 2.
+# Missing/extra characters cost 1 point.
+# Wrong characters cost 3 points.
+options = {
+  max_cost: 2,
+  weight_deletion: 1,
+  weight_insertion: 1,
+  weight_substitution: 3
+}
+
+# 'algoritm' has 1 deletion. Cost = 1. (Passes, 1 < 2)
+regex.test?('algoritm', options) # => true
+
+# 'algorethm' has 1 substitution. Cost = 3. (Fails, 3 > 2)
+regex.test?('algorethm', options) # => false
+```
+
+## Gotchas & Best Practices
+
+### The "Empty Match" Phenomenon
+
+Because `TreRegex` relies on strict mathematical edit distances, you must be careful when setting `max_errors` to a value that is **greater than or equal to the length of your pattern**.
+
+If you allow 3 errors on a 3-letter word, the engine considers *deleting all 3 characters* to be a valid mathematical match (cost = 3). This will result in an unexpected match against an empty string (`""`).
+
+```ruby
+regex = TreRegex::Regex.new('cat')
+
+# We allow 3 errors on a 3-letter word.
+# The engine matches "cow" (2 substitutions)...
+# but it also matches "" at the end of the string (3 deletions)!
+regex.match_all('cot, cow', max_errors: 3).to_a
+# => [
+#     {match: "cot", submatches: [], index: 0, end_index: 3, cost: 1, errors: {insertions: 0, deletions: 0, substitutions: 1}},
+#     {match: "cow", submatches: [], index: 5, end_index: 8, cost: 2, errors: {insertions: 0, deletions: 0, substitutions: 2}},
+#     {match: "", submatches: [], index: 8, end_index: 8, cost: 3, errors: {insertions: 0, deletions: 3, substitutions: 0}}
+#    ]
+```
+
+**Best Practice**: if you need a high `max_errors` limit but want to prevent the engine from matching empty strings, explicitly cap the `max_deletions` option so that at least one character of your pattern must survive
+
+```ruby
+# Allow 3 total errors, but strictly forbid the engine from deleting more than 2 characters
+regex.match_all('cot, cow', max_errors: 3, max_deletions: 2).to_a
+# => [
+#     {match: "cot", submatches: [], index: 0, end_index: 3, cost: 1, errors: {insertions: 0, deletions: 0, substitutions: 1}},
+#     {match: "cow", submatches: [], index: 5, end_index: 8, cost: 2, errors: {insertions: 0, deletions: 0, substitutions: 2}}
+#    ] # The empty match is mathematically prevented
+```
+
+### POSIX vs. PCRE Syntax
+
+Ruby’s built-in `Regexp` engine uses a PCRE-like syntax (Onigmo), which supports advanced features like lookaheads `(?=...)`, lookbehinds, and backreferences.
+
+The underlying TRE C-library uses **POSIX Extended Regular Expressions (ERE)**. While it supports standard regex features (character classes `[a-z]`, quantifiers `*`, `+`, `?`, and grouping), it **does not** support Perl-specific extensions.
+
+```ruby
+# Valid TRE syntax
+TreRegex::Regex.new('(cat|dog)s?')
+
+# INVALID: Lookarounds are not supported by POSIX ERE
+TreRegex::Regex.new('cat(?=s)') # Failed to compile regex pattern: cat(?=s) (TreRegex::Error)
+```
+
+### The Performance Cost of Extreme Fuzziness
+
+Fuzzy matching is inherently more computationally expensive than exact matching. The TRE algorithm scales based on the length of the string and the number of allowed errors.
+
+If you are searching a massive block of text (like a whole book) and set `max_errors: 10`, the engine has to calculate an enormous number of branching possibilities.
+
+**Best Practice**: Keep your error limits tight and realistic. An error limit of 1 to 3 is usually perfect for catching typos. If you need to allow a massive number of errors, consider breaking the target text into smaller chunks (like sentences or words) before matching.
+
+### Unicode Character Indices vs. Byte Offsets
+
+In C, strings are just arrays of bytes. An emoji like 🍎 takes up 4 bytes, which often breaks indexing when C-libraries pass data back to Ruby.
+
+`TreRegex` handles this for you under the hood. The `:index` and `:end_index` returned in the match hash are strictly mapped to **Ruby character indices**, not raw byte offsets.
+
+**Best Practice**: You can safely use the returned indices directly with standard Ruby string slicing, even if the text is filled with emojis or multi-byte characters. Do not use them with `String#byteslice`
+
+```ruby
+regex = TreRegex::Regex.new('apple')
+target = 'I ate 🍎 and an aple'
+
+result = regex.exec(target, max_errors: 1)
+# => {match: "aple", submatches: [], index: 15, end_index: 19, cost: 1, errors: {insertions: 0, deletions: 1, substitutions: 0}}
+
+# This is 100% safe and will correctly return "aple"
+target[result[:index]...result[:end_index]]
+```
+
+### Overlapping Matches in `match_all`
+
+When using `match_all`, be aware that the engine consumes the string as it matches. By default, standard regex engines (including TRE) do not return overlapping matches.
+
+If you search for `"ana"` in `"banana"`, it will only match the first `"ana"`. Once it consumes those characters, it moves on to the remaining `"na"`.
+
+```ruby
+regex = TreRegex::Regex.new('ana')
+
+# Returns 1 match, not 2!
+regex.match_all('banana').to_a
+# => [{match: "ana", submatches: [], index: 1, end_index: 4, cost: 0, errors: {insertions: 0, deletions: 0, substitutions: 0}}]
+```
+
+If you need to find overlapping fuzzy matches, you will need to manually step through the string by advancing your starting index by 1 character after each search.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/ext/tre_regex/extconf.rb

@@ -5,10 +5,39 @@ require 'rbconfig'
 require 'open-uri'
 require 'net/http'
 require 'fileutils'
+require 'digest'
 
 is_windows = RbConfig::CONFIG['host_os'] =~ /mingw|mswin/
 is_darwin  = RbConfig::CONFIG['host_os'].include?('darwin')
 
+build_env = {
+  'CC' => RbConfig::CONFIG['CC'],
+  'CFLAGS' => RbConfig::CONFIG['CFLAGS'],
+  'CPPFLAGS' => RbConfig::CONFIG['CPPFLAGS'],
+  'LDFLAGS' => RbConfig::CONFIG['LDFLAGS']
+}
+
+# Embed standard C libraries directly into the DLL on Windows so it doesn't crash on bare machines
+if is_windows
+  # append static flags directly to CC! Libtool doesn't strip flags from the CC variable.
+  build_env['CC'] = "#{build_env['CC']} -static-libgcc -static-libstdc++"
+
+  # force MinGW to statically link the hidden winpthread dependency
+  build_env['LDFLAGS'] = "#{build_env['LDFLAGS']} -Wl,-Bstatic -lpthread -Wl,-Bdynamic"
+
+  # prevent MinGW from injecting a dependency on libssp-0.dll
+  build_env['CFLAGS'] = "#{build_env['CFLAGS']} -fno-stack-protector"
+end
+
+gnu_host = RbConfig::CONFIG['host_alias']
+gnu_host = RbConfig::CONFIG['host'] if gnu_host.nil? || gnu_host.empty?
+
+# Convert 'arm64' to 'aarch64' (Apple Silicon) and 'x64' to 'x86_64' (Windows)
+gnu_host = gnu_host.sub('arm64', 'aarch64').sub(/^x64/, 'x86_64')
+
+# Pass the translated, safe name to configure
+host_flag = "--host=#{gnu_host}"
+
 root_dir = File.expand_path(__dir__)
 root_dir = File.dirname(root_dir) until Dir.exist?(File.join(root_dir, 'lib')) || root_dir == '/'
 
@@ -16,6 +45,7 @@ root_dir = File.dirname(root_dir) until Dir.exist?(File.join(root_dir, 'lib')) |
 github_repo = 'laurikari/tre'
 version = '5ac28057f648debda76f9bf4d39dfdfa85b0df18'
 tarball_url = "https://github.com/#{github_repo}/archive/#{version}.tar.gz"
+expected_tarball_sha256 = '528a8f8a4672cd3a0e5354629323a17d0cfa98b3792a57d764b64db30e2d5e9a'
 tarball_file = File.expand_path("./tre-#{version}.tar.gz", __dir__)
 tre_src_dir = File.expand_path("./tre-#{version}", __dir__)
 dest_lib_dir = File.join(root_dir, 'lib', 'tre_regex', 'bin')
@@ -43,6 +73,18 @@ unless Dir.exist?(tre_src_dir)
   puts '========== Downloading TRE from GitHub =========='
   begin
     content = download_file(tarball_url)
+
+    actual_sha256 = Digest::SHA256.hexdigest(content)
+
+    if actual_sha256 != expected_tarball_sha256
+      abort [
+        'SECURITY ERROR:',
+        'Checksum mismatch for TRE source!',
+        "Expected: #{expected_tarball_sha256}",
+        "Actual:   #{actual_sha256}"
+      ].join("\n")
+    end
+
     File.binwrite(tarball_file, content)
   rescue StandardError => e
     abort "Error: #{e.message}"
@@ -50,33 +92,34 @@ unless Dir.exist?(tre_src_dir)
 
   puts '========== Extracting TRE Source =========='
   # Ensure we use -z for gzip
-  system("tar -xzf #{tarball_file} -C #{__dir__}") || abort('Extraction failed')
+  system('tar', '-xzf', tarball_file, '-C', __dir__) || abort('Extraction failed')
 end
 
 # Build TRE synchronously using Ruby
-host_flag = enable_config('cross-build') ? "--host=#{RbConfig::CONFIG['host']} " : ''
-RbConfig::CONFIG['SOEXT'] || RbConfig::CONFIG['DLEXT'] || (is_windows ? 'dll' : 'so')
 
 puts '========== Building TRE =========='
 Dir.chdir(tre_src_dir) do
-  system('./utils/autogen.sh') || raise('autogen.sh failed') unless File.exist?('configure')
-
-  system("./configure #{host_flag} --enable-shared --disable-static --disable-agrep") || raise('configure failed')
-  system('make') || raise('make failed')
+  system(build_env, './utils/autogen.sh') || raise('autogen.sh failed') unless File.exist?('configure')
+
+  system(
+    build_env,
+    './configure',
+    host_flag,
+    '--enable-shared',
+    '--disable-static',
+    '--disable-agrep',
+    '--disable-nls',
+    'ac_cv_header_libintl_h=no',
+    'ac_cv_lib_intl_libintl_gettext=no'
+  ) || raise('configure failed')
+  system(build_env, 'make') || raise('make failed')
 end
 
 puts '========== Staging Shared Library for FFI =========='
 FileUtils.mkdir_p(dest_lib_dir)
 
-# Find the REAL physical file, strictly ignoring symlinks and static (.a) archives
+# Find the shared library, ignoring static archives
 src_lib = Dir.glob("#{tre_src_dir}/lib/.libs/*").find do |f|
-  (f.include?('.so') || f.include?('.dylib') || f.end_with?('.dll')) &&
-    !f.end_with?('.a') &&
-    !File.symlink?(f)
-end
-
-# Fallback just in case libtool behaved differently
-src_lib ||= Dir.glob("#{tre_src_dir}/lib/.libs/*").find do |f|
   (f.include?('.so') || f.include?('.dylib') || f.end_with?('.dll')) && !f.end_with?('.a')
 end
 

data/lib/tre_regex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TreRegex
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/tre_regex.rb

@@ -5,6 +5,8 @@ require 'rbconfig'
 require_relative 'tre_regex/version'
 
 module TreRegex
+  MAX_NMATCH = 10 # 1 full match + 9 capture groups = 10 slots
+
   class Error < StandardError; end
 
   # The FFI Native Bridge
@@ -70,7 +72,7 @@ module TreRegex
 
     attach_function :tre_regcomp, %i[pointer string int], :int
     attach_function :tre_regfree, [:pointer], :void
-    attach_function :tre_regaexec, [:pointer, :string, :pointer, RegAParams.by_value, :int], :int
+    attach_function :tre_reganexec, [:pointer, :pointer, :size_t, :pointer, RegAParams.by_value, :int], :int
     attach_function :tre_regaparams_default, [:pointer], :void
   end
 
@@ -101,42 +103,62 @@ module TreRegex
       end
     end
 
-    def exec(text, options = {})
-      params = build_params(options)
-      pmatch = FFI::MemoryPointer.new(Native::RegMatch)
-      match_data = prepare_match_data(pmatch)
-
-      res = Native.tre_regaexec(@preg, text, match_data, params, 0)
-      res.zero? ? parse_result(text, match_data, pmatch) : nil
-    end
-
     def test?(text, options = {})
       !exec(text, options).nil?
     end
 
+    def exec(text, options = {})
+      ptr = FFI::MemoryPointer.from_string(text)
+      m_info = execute_match(ptr, text.bytesize, options)
+
+      m_info ? extract_match_payload(text, 0, 0, m_info).first : nil
+    end
+
     def match_all(text, options = {})
       return enum_for(:match_all, text, options) unless block_given?
 
-      offset = 0
-      while offset <= text.length
-        result = exec(text[offset..] || '', options)
-        break unless result
+      ptr = FFI::MemoryPointer.from_string(text)
+      b_off = c_off = 0
+
+      while b_off <= text.bytesize
+        m_info = execute_match(ptr + b_off, text.bytesize - b_off, options)
+        break unless m_info
+
+        payload, adv_b, adv_c = extract_match_payload(text, b_off, c_off, m_info)
+        yield payload
+
+        break if adv_b.zero? && b_off == text.bytesize
 
-        result[:index] += offset
-        result[:end_index] += offset
-        yield result
+        # Zero-width infinite loop protection
+        if adv_b.zero?
+          adv_b = text.byteslice(b_off..).chr.bytesize
+          adv_c = 1
+        end
 
-        advance = (result[:end_index] - result[:index]).clamp(1, Float::INFINITY)
-        offset = result[:index] + advance
+        b_off += adv_b
+        c_off += adv_c
       end
     end
 
     private
 
+    def execute_match(text_ptr, len, options)
+      params = build_params(options)
+
+      # Allocate a continuous block of memory for 10 RegMatch structs
+      pmatch_array = FFI::MemoryPointer.new(Native::RegMatch, MAX_NMATCH)
+      match_data = prepare_match_data(pmatch_array, MAX_NMATCH)
+
+      res = Native.tre_reganexec(@preg, text_ptr, len, match_data, params, 0)
+      return nil unless res.zero?
+
+      # Return the entire array pointer to be parsed
+      [pmatch_array, MAX_NMATCH, match_data]
+    end
+
     def build_params(opts)
       params = Native::RegAParams.new
       Native.tre_regaparams_default(params.to_ptr)
-      return params.tap { |p| p[:max_err] = 0 } if opts.empty?
 
       apply_limits(params, opts)
       apply_costs(params, opts)
@@ -163,28 +185,58 @@ module TreRegex
       params[:cost_subst] = opts[:weight_substitution] if opts.key?(:weight_substitution)
     end
 
-    def prepare_match_data(pmatch)
+    def prepare_match_data(pmatch_array, nmatch)
       Native::RegAMatch.new.tap do |m|
-        m[:nmatch] = 1
-        m[:pmatch] = pmatch
+        m[:nmatch] = nmatch # Tell TRE we have space for 10 matches
+        m[:pmatch] = pmatch_array
       end
     end
 
-    def parse_result(text, match_data, pmatch)
-      rm = Native::RegMatch.new(pmatch)
-      byte_match = text.byteslice(rm[:rm_so]...rm[:rm_eo])
-      char_start = text.byteslice(0...rm[:rm_so]).length
+    def extract_match_payload(text, byte_off, char_off, m_info)
+      pmatch_array, nmatch, match_data = m_info
 
-      {
-        match: byte_match,
-        index: char_start,
-        end_index: char_start + byte_match.length,
+      # Read the full match boundaries from index 0
+      full_rm = Native::RegMatch.new(pmatch_array)
+      rm_so = full_rm[:rm_so]
+      rm_eo = full_rm[:rm_eo]
+
+      prefix_len = (text.byteslice(byte_off, rm_so) || '').length
+      match_str = text.byteslice((byte_off + rm_so)...(byte_off + rm_eo))
+
+      payload = {
+        match: match_str,
+        submatches: extract_submatches(text, byte_off, pmatch_array, nmatch),
+        index: char_off + prefix_len,
+        end_index: char_off + prefix_len + match_str.length,
         cost: match_data[:cost],
-        errors: {
-          insertions: match_data[:num_ins],
-          deletions: match_data[:num_del],
-          substitutions: match_data[:num_subst]
-        }
+        errors: parse_errors(match_data)
+      }
+
+      [payload, rm_eo, prefix_len + match_str.length]
+    end
+
+    def extract_submatches(text, byte_off, pmatch_array, nmatch)
+      submatches = (1...nmatch).map do |i|
+        # Advance the memory pointer by the size of the struct for each index
+        rm = Native::RegMatch.new(pmatch_array + (i * Native::RegMatch.size))
+        sub_so = rm[:rm_so]
+        sub_eo = rm[:rm_eo]
+
+        # Safely extract the group, inserting nil if it was optional and unmatched
+        sub_so == -1 ? nil : text.byteslice((byte_off + sub_so)...(byte_off + sub_eo))
+      end
+
+      # Cleanup: Remove trailing nil values (unused capture groups)
+      submatches.pop while submatches.last.nil? && !submatches.empty?
+
+      submatches
+    end
+
+    def parse_errors(match_data)
+      {
+        insertions: match_data[:num_ins],
+        deletions: match_data[:num_del],
+        substitutions: match_data[:num_subst]
       }
     end
   end

data/tre_regex.gemspec

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'lib/tre_regex/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'tre_regex'
+  spec.version = TreRegex::VERSION
+  spec.authors = ['Oleksii Vasyliev']
+  spec.email = ['leopard.not.a@gmail.com']
+  spec.license = 'MIT'
+
+  spec.summary = 'A fast Ruby FFI wrapper for the TRE approximate regex matching library.'
+  spec.description = [
+    'TreRegex provides a high-performance Ruby interface to the TRE C library using FFI.',
+    'It brings robust approximate (fuzzy) regular expression matching to Ruby, featuring',
+    'multi-byte Unicode string safety, granular error limits, and precompiled cross-platform native binaries'
+  ].join(' ')
+  spec.homepage = 'https://github.com/le0pard/tre_regex'
+  spec.required_ruby_version = '>= 3.3.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/le0pard/tre_regex'
+  spec.metadata['changelog_uri'] = 'https://github.com/le0pard/tre_regex/releases'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/le0pard/tre_regex/issues'
+  spec.metadata['documentation_uri'] = 'https://github.com/le0pard/tre_regex/blob/main/README.md'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+
+  spec.files = %w[
+    lib/**/*.rb
+    ext/tre_regex/extconf.rb
+    ext/tre_regex/tre_regex.c
+    README.md
+    LICENSE
+    tre_regex.gemspec
+  ].flat_map { |p| Dir[p] }
+  spec.extensions = ['ext/tre_regex/extconf.rb']
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'ffi', '>= 1.0'
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tre_regex
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Oleksii Vasyliev
@@ -34,10 +34,13 @@ extensions:
 - ext/tre_regex/extconf.rb
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - ext/tre_regex/extconf.rb
 - ext/tre_regex/tre_regex.c
 - lib/tre_regex.rb
 - lib/tre_regex/version.rb
+- tre_regex.gemspec
 homepage: https://github.com/le0pard/tre_regex
 licenses:
 - MIT