fast_regexp 0.4.0-aarch64-linux → 0.6.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e7f80619e2ffc99b8abe00ecf291d8df9f79806eef7c6a3de30e08233619c6c
-  data.tar.gz: f834be706bed41f45c93156ca97ba78876b021027ce00f5187e26a23d1641874
+  metadata.gz: '039084596a2999534c4e78c9c3fc008ddcf0712a573c93234f4191d9b8e6fd3d'
+  data.tar.gz: 8f2629a2a40c5a82c26f73ce9826954bf8de24ab879757c7e672808a3b1edf26
 SHA512:
-  metadata.gz: daea2f2211cca44de646668960d31175dc7ce26eead28da2aae6ad92ad4d1761b82227ead275f76bb5c41c6a2b87f31fd38310a633175498312b416f48b48af5
-  data.tar.gz: 27fcf044024abbb1b835afb0668dac487f5d9896e45a6840d2e2e46c90f3944a2caf39e2d08d4ecf6fb6484da75c1d09f80b170c69ddc1bdde099c8ed61aaa21
+  metadata.gz: 415c361fe5761dfcb68d734c970e120189cd2f7770dc8997af51e4572c42ba17f72fa1d04465d3b67d9f191ffc58054b8bff98498a42ff41ad25145ecad0eed1
+  data.tar.gz: 2a011e1aa4c1b1c45107fbe93ed9dffe1e5d94e61bfb429e57daa58feeeabf8dca954d85c041dee7cdb5844e5cd7df1b39be1f696fa419e2c65477036cb2a950

data/README.md

@@ -3,7 +3,9 @@
 [![Gem Version](https://badge.fury.io/rb/fast_regexp.svg)](https://badge.fury.io/rb/fast_regexp)
 [![Test](https://github.com/jetpks/fast_regexp/workflows/CI/badge.svg)](https://github.com/jetpks/fast_regexp/actions)
 
-Ruby bindings for [rust/regex](https://docs.rs/regex/latest/regex/) library.
+Fast, drop-in regex for Ruby — backed by [rust/regex](https://docs.rs/regex/latest/regex/) with transparent fallback to the stdlib `::Regexp` engine for features rust/regex doesn't support (lookaround, backreferences, possessive quantifiers, etc.).
+
+You get rust/regex's speed on the common path, and a single uniform API (`Fast::Regexp`, `Fast::Regexp::MatchData`) regardless of which engine actually ran underneath.
 
 ## Installation
 
@@ -128,11 +130,50 @@ Fast::Regexp.new('(?P<n>\w+)').names        # => ["n"]
 Fast::Regexp.new('(a)(b)').captures_count   # => 2
 ```
 
+### Engine fallback
+
+rust/regex doesn't support lookaround, backreferences, or possessive
+quantifiers. Rather than make you manage two regex libraries, `Fast::Regexp`
+silently falls back to stdlib `::Regexp` when it sees something rust/regex
+can't compile. The public API (`#match`, `#sub`, `#gsub`, `#===`, `#=~`,
+`MatchData`) is identical on both paths, so callers don't have to care which
+engine ran — but you can inspect or reach the underlying object when you
+need to:
+
+```ruby
+fast = Fast::Regexp.new('\w+')
+fast.fast?       # => true
+fast.native      # => #<Fast::Regexp::Native ...>  (rust-backed)
+
+slow = Fast::Regexp.new('foo(?=bar)')   # lookahead — rust/regex rejects
+slow.stdlib?     # => true
+slow.stdlib      # => /foo(?=bar)/  (the real ::Regexp)
+slow.match?("foobar")  # => true
+```
+
+`Fast::Regexp::MatchData` exposes the same `#native?` / `#stdlib?` / `#native`
+/ `#stdlib` accessors. Replacement templates use rust/regex syntax (`$1`,
+`${name}`, `$$`) on both paths; the stdlib fallback translates them for you.
+
+You can force a specific engine via the `backend:` kwarg:
+
+```ruby
+Fast::Regexp.new('\w+', backend: :fast)     # rust/regex only; raises on unsupported
+Fast::Regexp.new(pat,   backend: :stdlib)   # skip rust/regex; use ::Regexp directly
+Fast::Regexp.new('\w+', backend: :auto)     # default — try rust, fall back on reject
+```
+
+> [!NOTE]
+> The fast path is byte-based (rust/regex's `regex::bytes`), so `#=~` returns
+> a *byte* offset. The stdlib fallback path returns the byte offset too, for
+> API consistency.
+
 > [!WARNING]
-> `rust/regex` regular expression syntax differs from Ruby's built-in
-> [`Regexp`](https://docs.ruby-lang.org/en/3.4/Regexp.html) library, see the
-> [official syntax page](https://docs.rs/regex/latest/regex/index.html#syntax) for more
-> details.
+> `rust/regex` syntax differs from Ruby's built-in
+> [`Regexp`](https://docs.ruby-lang.org/en/3.4/Regexp.html) — see the
+> [rust/regex syntax page](https://docs.rs/regex/latest/regex/index.html#syntax).
+> When fallback kicks in, your pattern is interpreted by stdlib `::Regexp`
+> instead, so Ruby's syntax applies for that compile.
 
 ### Searching simultaneously
 
@@ -176,11 +217,11 @@ It also supports parsing of strings with invalid UTF-8 characters by default. It
 In case unicode awarness of matchers should be disabled, both `Fast::Regexp` and `Fast::Regexp::Set` support `unicode: false` option:
 
 ```ruby
-Fast::Regexp.new('\w+').match('ю٤夏')
-# => ["ю٤夏"]
+Fast::Regexp.new('\w+').match('ю٤夏')[0]
+# => "ю٤夏"
 
 Fast::Regexp.new('\w+', unicode: false).match('ю٤夏')
-# => []
+# => nil
 
 Fast::Regexp::Set.new(['\w', '\d', '\s']).match("ю٤\u2000")
 # => [0, 1, 2]
@@ -189,6 +230,16 @@ Fast::Regexp::Set.new(['\w', '\d', '\s'], unicode: false).match("ю٤\u2000")
 # => []
 ```
 
+## Documentation
+
+In-depth docs live under [`docs/`](docs/README.md), organized via the
+[Diátaxis](https://diataxis.fr/) framework:
+
+- **Tutorial:** [Getting started](docs/tutorials/getting-started.md)
+- **How-to:** [Migrate from stdlib `::Regexp`](docs/how-to/migrate-from-stdlib-regexp.md), [Handle unsupported syntax](docs/how-to/handle-unsupported-syntax.md)
+- **Reference:** [`Fast::Regexp`](docs/reference/fast-regexp.md), [`MatchData`](docs/reference/fast-regexp-matchdata.md), [`Set`](docs/reference/fast-regexp-set.md)
+- **Explainers:** [Engine fallback](docs/explainers/engine-fallback.md)
+
 ## Development
 
 ```sh
@@ -209,8 +260,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/jetpks
 huge thanks for the original bindings and the clean magnus integration that
 made this work easy to extend. This fork rebrands the gem, reshapes the
 public API (`Fast::Regexp`, real `MatchData`, `sub`/`gsub`, `===`/`=~`,
-`Regexp`-constructor coercion), and releases the GVL around regex execution
-for thread/fiber-friendly matching.
+`Regexp`-constructor coercion), and adds transparent fallback to stdlib
+`::Regexp` for patterns rust/regex can't compile.
 
 ## License
 

data/lib/fast_regexp/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   class Regexp
-    VERSION = "0.4.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/fast_regexp.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
 require_relative "fast_regexp/version"
+
+module Fast
+  # Façade over rust/regex with a transparent fallback to stdlib `::Regexp`.
+  #
+  # `Fast::Regexp.new(pattern)` first tries to compile with rust/regex (fast,
+  # byte-based). If the pattern uses features rust/regex does not support
+  # (lookaround, backreferences, possessive quantifiers, etc.) we fall back
+  # to `::Regexp` so consumers don't have to juggle two libraries.
+  class Regexp
+  end
+end
+
+# Load the native extension AFTER the Fast::Regexp class shell exists — the
+# Rust init() looks up Fast::Regexp and registers Native under it.
 require_relative "fast_regexp/fast_regexp"
 
-# Ruby-side conveniences on top of the Rust extension. The native class only
-# exposes raw primitives (`_native_new`, `_native_match`, `_native_sub`,
-# `_native_gsub`); everything user-facing lives here so the API can grow
-# without touching FFI.
 module Fast
   class Regexp
     RUBY_FLAG_MAP = {
@@ -16,14 +26,21 @@ module Fast
     }.freeze
 
     class << self
-      # Accept either a pattern string or an existing `::Regexp`. When given a
-      # Regexp the flags (`/i`, `/x`, `/m`) are translated into a leading
-      # inline group so the rust/regex engine sees them. Unsupported features
-      # (lookaround, backrefs) still raise from the engine with a clear
-      # message.
+      # Compile a pattern. Accepts a String or a `::Regexp` (flags are
+      # translated into a leading `(?...)` group so rust/regex sees them).
+      # Falls back to `::Regexp` if rust/regex rejects the pattern.
       def new(pattern, **opts)
-        pattern = translate_regexp(pattern) if pattern.is_a?(::Regexp)
-        _native_new(pattern, **opts)
+        translated = pattern.is_a?(::Regexp) ? translate_regexp(pattern) : pattern
+        allocate.tap { |re| re.send(:initialize, translated, original: pattern, **opts) }
+      end
+
+      # Bulk-compile a symbol-keyed hash of patterns. Handy for defining a set
+      # of regex constants in one shot:
+      #
+      #   RE = Fast::Regexp.create_many(word: '\w+', num: '\d+').freeze
+      #   RE[:word].match("hello")
+      def create_many(**patterns)
+        patterns.transform_values { |pat| new(pat) }
       end
 
       private
@@ -36,34 +53,66 @@ module Fast
       end
     end
 
-    # Returns a `Fast::Regexp::MatchData` on hit, `nil` on miss — matching
-    # Ruby's `Regexp#match` shape so the old `[]`-truthy-but-empty trap is
-    # gone.
+    attr_reader :pattern, :backend
+
+    BACKENDS = %i[auto fast stdlib].freeze
+
+    # Internal — use `Fast::Regexp.new`. `original` is the unmodified input
+    # (String or ::Regexp) so we can build an accurate stdlib fallback.
+    # `backend:` forces a specific engine: `:auto` (default) tries rust/regex
+    # and falls back to stdlib, `:fast` raises if rust/regex rejects the
+    # pattern, `:stdlib` skips rust/regex entirely.
+    def initialize(pattern, original: pattern, backend: :auto, **opts)
+      raise ArgumentError, "backend must be one of #{BACKENDS.inspect}" unless BACKENDS.include?(backend)
+      @pattern = pattern
+      @backend = compile_backend(pattern, original, backend, opts)
+    end
+
+    def fast? = @backend.is_a?(Native)
+    def stdlib? = !fast?
+
+    # Escape hatches for callers that need the underlying object directly.
+    def native = fast? ? @backend : nil
+    def stdlib = stdlib? ? @backend : nil
+
     def match(haystack)
-      _native_match(coerce_string(haystack))
+      haystack = coerce_string(haystack)
+      raw = fast? ? @backend._native_match(haystack) : @backend.match(haystack)
+      raw && MatchData.new(raw, haystack)
+    end
+
+    def match?(haystack)
+      @backend.match?(coerce_string(haystack))
     end
 
-    # Case-equality. Enables `case/when` and RSpec's
-    # `expect(str).to match(re)`.
     def ===(other)
       return false unless other.respond_to?(:to_str)
       match?(other.to_str)
     end
 
-    # Returns the byte offset of the first match, or nil. Matches the
-    # semantics of `Regexp#=~` except positions are in **bytes** (rust/regex
-    # is byte-based).
+    # Byte offset of the first match (rust/regex is byte-based; stdlib path
+    # also returns bytes here for API consistency).
     def =~(other)
       return nil unless other.respond_to?(:to_str)
       m = match(other.to_str)
       m && m.byte_begin(0)
     end
 
-    # `sub(haystack, replacement)` or `sub(haystack) { |m| ... }`.
-    #
-    # The string form uses rust/regex's native replacement template: `$1`,
-    # `${name}`, `$$` for a literal `$`. To pass a replacement string that
-    # contains `$` literally, pass `literal: true`.
+    def scan(haystack)
+      @backend.scan(coerce_string(haystack))
+    end
+
+    def scan_matches(haystack)
+      haystack = coerce_string(haystack)
+      if fast?
+        @backend.scan_matches(haystack).map { |m| MatchData.new(m, haystack) }
+      else
+        results = []
+        haystack.scan(@backend) { results << MatchData.new(::Regexp.last_match, haystack) }
+        results
+      end
+    end
+
     def sub(haystack, replacement = nil, literal: false, &block)
       haystack = coerce_string(haystack)
       if block
@@ -73,32 +122,123 @@ module Fast
         "#{m.pre_match}#{block.call(m)}#{m.post_match}"
       else
         raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if replacement.nil?
-        _native_sub(haystack, coerce_string(replacement), literal)
+        replacement = coerce_string(replacement)
+        if fast?
+          @backend._native_sub(haystack, replacement, literal)
+        else
+          haystack.sub(@backend, stdlib_replacement(replacement, literal))
+        end
       end
     end
 
-    # `gsub(haystack, replacement)` or `gsub(haystack) { |m| ... }`. See
-    # `#sub` for the template syntax.
     def gsub(haystack, replacement = nil, literal: false, &block)
       haystack = coerce_string(haystack)
       if block
         raise ArgumentError, "wrong number of arguments (given 2, expected 1 with block)" if replacement
-        gsub_with_block(haystack, &block)
+        fast? ? fast_gsub_with_block(haystack, &block) : stdlib_gsub_with_block(haystack, &block)
       else
         raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if replacement.nil?
-        _native_gsub(haystack, coerce_string(replacement), literal)
+        replacement = coerce_string(replacement)
+        if fast?
+          @backend._native_gsub(haystack, replacement, literal)
+        else
+          haystack.gsub(@backend, stdlib_replacement(replacement, literal))
+        end
       end
     end
 
-    def inspect
-      "#<Fast::Regexp #{pattern.inspect}>"
+    # On the fast path this comes from rust/regex directly. On the stdlib
+    # fallback we walk the source counting capturing groups while honoring
+    # escapes, character classes, and non-capturing / lookaround prefixes.
+    def captures_count
+      return @backend.captures_count if fast?
+      count_stdlib_captures(@backend.source)
     end
 
+    def names
+      @backend.names
+    end
+
+    def inspect = "#<Fast::Regexp #{@pattern.inspect}#{stdlib? ? " (stdlib)" : ""}>"
     alias_method :to_s, :pattern
 
     private
 
-    def gsub_with_block(haystack)
+    def count_stdlib_captures(source)
+      count = 0
+      i = 0
+      len = source.length
+      while i < len
+        c = source[i]
+        if c == "\\"
+          i += 2
+        elsif c == "["
+          i += 1
+          i += 1 while i < len && source[i] != "]"
+          i += 1
+        elsif c == "("
+          # Capturing unless followed by (?:, (?=, (?!, (?#, (?<=, (?<!.
+          prefix = source[i + 1, 4] || ""
+          if prefix.start_with?("?:") || prefix.start_with?("?=") || prefix.start_with?("?!") ||
+              prefix.start_with?("?#") || prefix.start_with?("?<=") || prefix.start_with?("?<!")
+            i += 1
+          else
+            count += 1
+            i += 1
+          end
+        else
+          i += 1
+        end
+      end
+      count
+    end
+
+    def compile_backend(pattern, original, backend, opts)
+      return compile_stdlib(pattern, original) if backend == :stdlib
+      Native._native_new(pattern, **opts)
+    rescue ArgumentError => e
+      raise if backend == :fast
+      compile_stdlib(pattern, original, fallback_from: e)
+    end
+
+    def compile_stdlib(pattern, original, fallback_from: nil)
+      return original if original.is_a?(::Regexp)
+      ::Regexp.new(pattern)
+    rescue ::RegexpError => e
+      # Pattern is malformed in both engines (auto path) — surface the
+      # original rust/regex error since it's typically more detailed.
+      # Otherwise propagate the stdlib error as-is.
+      raise(fallback_from ? ArgumentError.new(fallback_from.message) : e)
+    end
+
+    # Maps positional capture indices to names for the stdlib backend so we
+    # can translate `$N` to `\k<name>` (Ruby's gsub ignores `\N` for named
+    # groups). Only invoked from the stdlib path.
+    def stdlib_name_by_index
+      @stdlib_name_by_index ||= @backend.named_captures.flat_map { |n, idxs| idxs.map { |i| [i, n] } }.to_h
+    end
+
+    # Translate rust/regex replacement syntax ($N, ${name}, $$) into Ruby
+    # syntax (\N, \k<name>, $) for the stdlib fallback path.
+    def stdlib_replacement(template, literal)
+      return template.gsub('\\', '\\\\\\\\') if literal
+
+      template.gsub(/\$(\$|\d+|\{[^}]+\})/) do
+        token = ::Regexp.last_match(1)
+        case token
+        when "$" then "$"
+        when /\A\d+\z/
+          name = stdlib_name_by_index[token.to_i]
+          name ? "\\k<#{name}>" : "\\#{token}"
+        else "\\k<#{token[1..-2]}>"
+        end
+      end
+    end
+
+    # Fast path: rust/regex has no native iterate-with-replace, so we scan all
+    # match positions up-front, then splice the result by byte offset in one
+    # pass. Stays UTF-8 since haystack and match slices are.
+    def fast_gsub_with_block(haystack)
       matches = scan_matches(haystack)
       return haystack.dup if matches.empty?
 
@@ -114,31 +254,64 @@ module Fast
       out
     end
 
+    # Stdlib path: String#gsub already does single-pass iterate-and-replace
+    # and sets $~ inside the block, so wrap the current ::MatchData and yield.
+    def stdlib_gsub_with_block(haystack)
+      haystack.gsub(@backend) { yield(MatchData.new(::Regexp.last_match, haystack)).to_s }
+    end
+
     def coerce_string(value)
       return value if value.is_a?(String)
       return value.to_str if value.respond_to?(:to_str)
       raise TypeError, "no implicit conversion of #{value.class} into String"
     end
 
+    # Wraps either a Fast::Regexp::Native::MatchData or a stdlib ::MatchData
+    # so callers see one type regardless of which backend ran.
     class MatchData
       include Enumerable
 
-      def each(&block)
-        to_a.each(&block)
-      end
+      attr_reader :backend, :string
 
-      def values_at(*indices)
-        indices.map { |i| self[i] }
+      def initialize(backend, haystack)
+        @backend = backend
+        @string = haystack
       end
 
+      def native? = @backend.is_a?(Fast::Regexp::Native::MatchData)
+      def stdlib? = !native?
+
+      def native = native? ? @backend : nil
+      def stdlib = stdlib? ? @backend : nil
+
+      def [](key) = @backend[key]
+      def to_a = @backend.to_a
+      def captures = @backend.captures
+      def named_captures = @backend.named_captures
+      def names = @backend.names
+      def size = @backend.size
+      alias_method :length, :size
+      def pre_match = @backend.pre_match
+      def post_match = @backend.post_match
+      def to_s = @backend.to_s
+
+      # Byte-based offsets. Both backends expose these (stdlib MatchData has
+      # `byteoffset` / `byte_begin` / `byte_end` since Ruby 3.2).
+      def byteoffset(key) = @backend.byteoffset(key)
+      def byte_begin(key) = @backend.byte_begin(key)
+      def byte_end(key) = @backend.byte_end(key)
+
+      def each(&block) = to_a.each(&block)
+      def values_at(*indices) = indices.map { |i| self[i] }
+
       def ==(other)
         other.is_a?(MatchData) && to_a == other.to_a && string == other.string
       end
       alias_method :eql?, :==
 
-      def hash
-        [to_a, string].hash
-      end
+      def hash = [to_a, string].hash
+
+      def inspect = "#<Fast::Regexp::MatchData #{to_s.inspect}>"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_regexp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: aarch64-linux
 authors:
 - Eric Jacobs