js_regex_to_ruby 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdbe70d784541cad9e2009b2306416e72349cfc5e9136cadb998faf811d5ad91
-  data.tar.gz: fee286185020e60bf68b8c36736993ed75f8056fae28a882d977498a35445b44
+  metadata.gz: 1fae9505fb2087b5f0600ae3600911debc5d9f492f74798ad25772645d9e8ce0
+  data.tar.gz: 9e316aab02a15003581d5d45cf863e4368a55dd81038fb0965de7f1f52296229
 SHA512:
-  metadata.gz: b9290e4565d2635db41c94ffbf865dbe3a085d943c413e5f5c635c74b67584ff73e09e0fe230674f662146cf170e8977e474d9aa0963b47aa84da4a3012a18ce
-  data.tar.gz: d12f32df94de6834ce18c083e0b0ba9eaadacdf1ed4c56a6e39c236e4308e1337710eb33a1ebe5f34474e52ba75db90af5654c6eadea37ecee8c2e8f90f54cd0
+  metadata.gz: 71113df052913508f1fcce6df020cce4c10de0974469e032b9d000aec4f4fd0b4081d8b07b3e9500117d01cc90c182d5aa6808cbd41325e17b66b4d4b4cdcf2a
+  data.tar.gz: dd24f145589a79e09eaf99ba7a663a4c0bde8e134de7871f70a3e467667a5769132c57b298c9ddb61e854e2ecd531bb18fc1db8f0dd6344a6ae89ba9dcae18f9

data/README.md

@@ -12,7 +12,8 @@ JavaScript and Ruby regular expressions have subtle but important differences:
 | `/s` flag (dotAll) | Makes `.` match newlines | N/A (use `/m` in Ruby) |
 | `/m` flag (multiline) | Makes `^`/`$` match line boundaries | N/A (already default behavior) |
 | `[^]` (any character) | Matches any char including `\n` | Invalid syntax (use `[\s\S]`) |
-| `/g`, `/y`, `/d`, `/u`, `/v` flags | Various features | No direct equivalents |
+| `/g`, `/y` flags | Global / sticky runtime semantics | Supported via `JsRegexToRuby::JsRegExp` (stateful `Regexp` subclass) |
+| `/d`, `/u`, `/v` flags | Various features | No direct equivalents |
 
 This gem handles these conversions automatically, emitting warnings when perfect conversion isn't possible.
 
@@ -69,6 +70,25 @@ JsRegexToRuby.try_convert("/(?invalid/")    #=> nil
 JsRegexToRuby.try_convert(nil)              #=> nil
 ```
 
+#### `literal_only` Option
+
+By default, strings without `/` delimiters are treated as raw pattern sources:
+
+```ruby
+JsRegexToRuby.try_convert("cat")  #=> /cat/ (compiled as pattern)
+```
+
+If you only want to accept JS regex literals (strings starting with `/`), use `literal_only: true`:
+
+```ruby
+# Only accept /pattern/flags format
+JsRegexToRuby.try_convert("cat", literal_only: true)   #=> nil (not a literal)
+JsRegexToRuby.try_convert("/cat/", literal_only: true) #=> /cat/
+JsRegexToRuby.try_convert("/cat/i", literal_only: true) #=> /cat/i
+```
+
+This is useful when you want to distinguish between plain strings (like keywords) and regex patterns in user input.
+
 ### Parsing JS Literal Without Converting
 
 ```ruby
@@ -83,10 +103,31 @@ flags    #=> "gi"
 result = JsRegexToRuby.convert("/test/guy")
 
 result.warnings
-#=> ["JS flag(s) not representable as Ruby Regexp options: g, u, y"]
+#=> ["JS flag(s) not representable as Ruby Regexp options: u"]
 
 result.ignored_js_flags
-#=> ["g", "u", "y"]
+#=> ["u"]
+```
+
+### Global / Sticky (`g` / `y`) Runtime Semantics
+
+When the JS flags include `g` and/or `y`, `convert` returns a `JsRegexToRuby::JsRegExp` (a `Regexp` subclass) that tracks `last_index` and provides JS-like methods:
+
+```ruby
+res = JsRegexToRuby.convert("/foo/g")
+re = res.regexp
+
+re.last_index = 2
+re.exec("foo foo")&.begin(0) #=> 4
+re.last_index               #=> 7
+```
+
+For safe global iteration (avoids empty-match infinite loops), use `match_all`:
+
+```ruby
+re = JsRegexToRuby.convert("/.*/g").regexp
+re.match_all("a").map { |m| [m[0], m.begin(0)] }
+#=> [["a", 0], ["", 1]]
 ```
 
 ### Result Object
@@ -95,7 +136,7 @@ The `Result` struct provides comprehensive information:
 
 | Method | Description |
 |--------|-------------|
-| `regexp` | The compiled `Regexp` object (or `nil` if compilation failed) |
+| `regexp` | The compiled `Regexp` object (or `JsRegexToRuby::JsRegExp` when `g`/`y` are present), or `nil` if compilation failed |
 | `success?` | Returns `true` if `regexp` is not `nil` |
 | `ruby_source` | The converted Ruby regex pattern string |
 | `ruby_options` | Integer flags (`Regexp::IGNORECASE`, `Regexp::MULTILINE`, etc.) |
@@ -125,8 +166,8 @@ result.regexp       #=> nil
 | `i` | `Regexp::IGNORECASE` | Case-insensitive matching |
 | `s` | `Regexp::MULTILINE` | JS dotAll → Ruby multiline (`.` matches `\n`) |
 | `m` | *(behavior change)* | Keeps `^`/`$` as-is instead of converting to `\A`/`\z` |
-| `g` | *(ignored)* | Global matching - handle in application code |
-| `y` | *(ignored)* | Sticky matching - no equivalent |
+| `g` | `JsRegexToRuby::JsRegExp` | JS-like `lastIndex`/`exec`/`test` behavior (not a Ruby Regexp option) |
+| `y` | `\G` + `JsRegexToRuby::JsRegExp` | Sticky matching via `\G` prefix + `lastIndex` runtime behavior |
 | `u` | *(ignored)* | Unicode mode - Ruby handles Unicode differently |
 | `v` | *(ignored)* | Unicode sets mode - no equivalent |
 | `d` | *(ignored)* | Indices for matches - no equivalent |
@@ -178,9 +219,15 @@ result.regexp.match?("axb")   #=> true
 
 Note: Negated character classes like `[^abc]` are NOT affected and work as expected.
 
+### Ruby-Only Escape Sequences
+
+JavaScript allows many "identity escapes" where `\X` means `"X"` (outside Unicode modes).
+Ruby has additional special sequences like `\A`, `\z`, `\G`, and `\Q...\E`.
+To preserve JS behavior, the converter rewrites these to literal characters where appropriate (e.g., JS `\A` becomes Ruby `A`).
+
 ## Limitations
 
-1. **No runtime flags**: JS flags like `g` (global) and `y` (sticky) affect matching behavior at runtime and have no Ruby `Regexp` equivalent. Handle these in your application logic.
+1. **Runtime flags (`g`, `y`) are stateful**: When present, `convert` returns a `JsRegexToRuby::JsRegExp` (subclass of `Regexp`) that tracks `last_index` and provides JS-like `exec`/`test`/`match` behavior. Use `match_all` for safe iteration. Note: `String#match?`, `String#scan`, and `String#=~` bypass `Regexp` method dispatch and will not update `last_index`.
 
 2. **Unicode properties**: `\p{...}` syntax exists in both JS and Ruby but with different property names and semantics. No automatic conversion is performed.
 

data/lib/js_regex_to_ruby/converter.rb

@@ -9,13 +9,19 @@ module JsRegexToRuby
   # - JS /s (dotAll) => Ruby /m (dot-all in Ruby)
   # - JS /m (multiline anchors) => Ruby has ^/$ multiline by default, so we rewrite ^/$
   #   to \A/\z when JS multiline is NOT enabled.
+  # - JS /y (sticky) => Ruby \G prefix (requires runtime lastIndex management for full fidelity)
   # - JS inline modifiers (?ims-ims:...) are supported, with mapping s->m and special handling for m.
   # - JS [^] (match any character including newline) => Ruby [\s\S]
-  # - JS /g, /y, /u, /v, /d have no direct Regexp equivalent; we report them in Result#ignored_js_flags.
+  # - JS /g and /y are supported via JsRegexToRuby::JsRegExp runtime semantics (last_index).
+  # - JS /u, /v, /d have no direct Regexp equivalent; we report them in Result#ignored_js_flags.
   class Converter
     JS_KNOWN_FLAGS = %w[d g i m s u v y].freeze
     JS_GROUP_MOD_FLAGS = %w[i m s].freeze
 
+    # Ruby has additional backslash escapes that JavaScript treats as identity escapes (i.e., \X == "X").
+    # To preserve JS behavior, we drop the backslash for these sequences during rewriting.
+    RUBY_IDENTITY_ESCAPE_CHARS = %w[A Z z G K Q E R X h H a e C M].freeze
+
     # Tracks modifier state during source rewriting (immutable).
     Context = Data.define(:js_multiline_anchors, :ruby_ignorecase, :ruby_dotall)
 
@@ -86,7 +92,10 @@ module JsRegexToRuby
       warnings << "Unknown JS RegExp flag(s): #{unknown_flags.uniq.join(', ')}" unless unknown_flags.empty?
       warnings << "Duplicate JS RegExp flag(s) ignored: #{duplicate_flags.uniq.join(', ')}" unless duplicate_flags.empty?
 
-      ignored_js_flags = (seen_flags.keys - %w[i m s]).sort
+      # Flags that remain unhandled in the conversion output.
+      handled_js_flags = %w[i m s y]
+      handled_js_flags << "g" if compile
+      ignored_js_flags = (seen_flags.keys - handled_js_flags).sort
 
       unless ignored_js_flags.empty?
         warnings << "JS flag(s) not representable as Ruby Regexp options: #{ignored_js_flags.join(', ')}"
@@ -95,6 +104,8 @@ module JsRegexToRuby
       base_js_multiline = seen_flags["m"]
       base_js_ignorecase = seen_flags["i"]
       base_js_dotall = seen_flags["s"]
+      base_js_global = seen_flags["g"]
+      base_js_sticky = seen_flags["y"]
 
       ruby_options = 0
       ruby_options |= Regexp::IGNORECASE if base_js_ignorecase
@@ -107,11 +118,17 @@ module JsRegexToRuby
       )
 
       ruby_source = rewrite_source(js_source, base_ctx, warnings)
+      ruby_source = "\\G(?:#{ruby_source})" if base_js_sticky
 
       regexp = nil
       if compile
         begin
-          regexp = Regexp.new(ruby_source, ruby_options)
+          regexp =
+            if base_js_global || base_js_sticky
+              JsRegExp.new(ruby_source, ruby_options, js_flags: js_flags)
+            else
+              Regexp.new(ruby_source, ruby_options)
+            end
         rescue RegexpError => e
           warnings << "Ruby RegexpError: #{e.message}"
           regexp = nil
@@ -178,12 +195,18 @@ module JsRegexToRuby
               next
             end
 
-            out << ch
-            if i + 1 < src.length
-              out << src[i + 1]
+            next_ch = src[i + 1]
+            if next_ch && ruby_identity_escape_char?(next_ch)
+              out << next_ch
               i += 2
             else
-              i += 1
+              out << ch
+              if next_ch
+                out << next_ch
+                i += 2
+              else
+                i += 1
+              end
             end
             next
           end
@@ -200,12 +223,18 @@ module JsRegexToRuby
             out << control_char(src[i + 2])
             i += 3
           else
-            out << ch
-            if i + 1 < src.length
-              out << src[i + 1]
+            next_ch = src[i + 1]
+            if next_ch && ruby_identity_escape_char?(next_ch)
+              out << next_ch
               i += 2
             else
-              i += 1
+              out << ch
+              if next_ch
+                out << next_ch
+                i += 2
+              else
+                i += 1
+              end
             end
           end
 
@@ -375,9 +404,13 @@ module JsRegexToRuby
       end
     end
 
+    def self.ruby_identity_escape_char?(ch)
+      RUBY_IDENTITY_ESCAPE_CHARS.include?(ch)
+    end
+
     private_class_method :looks_like_literal?, :normalize_flags,
                          :rewrite_source, :control_escape_at?, :control_char,
                          :parse_js_modifier_group, :apply_js_group_modifiers,
-                         :build_ruby_modifier_prefix
+                         :build_ruby_modifier_prefix, :ruby_identity_escape_char?
   end
 end

data/lib/js_regex_to_ruby/js_regexp.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module JsRegexToRuby
+  # A Regexp subclass that emulates JavaScript's runtime RegExp semantics for:
+  # - g (global): searches from last_index and updates it on success; resets to 0 on failure
+  # - y (sticky): requires a match at last_index (implemented via a leading \G)
+  #
+  # Note: Some Ruby String methods (e.g., String#match?, String#=~, String#scan) do not dispatch
+  # to Regexp methods and therefore cannot update last_index.
+  class JsRegExp < Regexp
+    POS_UNSET = Object.new
+    private_constant :POS_UNSET
+
+    attr_reader :js_flags
+
+    def initialize(source, options = 0, js_flags: "")
+      @js_flags = js_flags.to_s
+      @global = @js_flags.include?("g")
+      @sticky = @js_flags.include?("y")
+      @last_index = 0
+      super(source, options)
+    end
+
+    def global?
+      @global
+    end
+
+    def sticky?
+      @sticky
+    end
+
+    def last_index
+      @last_index
+    end
+
+    def last_index=(value)
+      i = value.to_i
+      @last_index = i < 0 ? 0 : i
+    end
+
+    alias lastIndex last_index
+
+    def lastIndex=(value)
+      self.last_index = value
+    end
+
+    def reset
+      @last_index = 0
+      self
+    end
+
+    # JS-like exec: returns MatchData (or nil) and updates last_index for g/y.
+    def exec(str)
+      match_internal(str, POS_UNSET)
+    end
+
+    # JS-like test: boolean wrapper around exec.
+    def test(str)
+      !exec(str).nil?
+    end
+
+    alias test? test
+
+    # Safe global iteration (similar to JS String#matchAll):
+    # - does not permanently mutate last_index
+    # - avoids infinite loops for empty-string matches by advancing 1 char
+    def match_all(str)
+      return enum_for(:match_all, str) unless block_given?
+
+      str = str.to_s
+      saved_last_index = @last_index
+
+      begin
+        @last_index = 0
+        while (m = exec(str))
+          yield m
+          if m[0].empty?
+            @last_index += 1
+            @last_index = str.length + 1 if @last_index > str.length
+          end
+        end
+      ensure
+        @last_index = saved_last_index
+      end
+    end
+
+    # If g/y and pos is omitted, behaves like #exec (uses last_index and updates it).
+    # If pos is provided, behaves like Ruby Regexp#match and does not touch last_index.
+    def match(str, pos = POS_UNSET, &block)
+      m = match_internal(str, pos)
+      return yield(m) if block && m
+      m
+    end
+
+    # If g/y and pos is omitted, behaves like #test (uses last_index and updates it).
+    # If pos is provided, behaves like Ruby Regexp#match? and does not touch last_index.
+    def match?(str, pos = POS_UNSET)
+      !!match_internal(str, pos)
+    end
+
+    # Used by `case`/`when`.
+    def ===(other)
+      !!match_internal(other, POS_UNSET)
+    end
+
+    # JS-like semantics when regexp is on the LHS.
+    def =~(other)
+      m = match_internal(other, POS_UNSET)
+      m ? m.begin(0) : nil
+    end
+
+    private
+
+    def uses_last_index?
+      @global || @sticky
+    end
+
+    def raw_match(str, pos)
+      Regexp.instance_method(:match).bind_call(self, str, pos)
+    end
+
+    def match_internal(str, pos)
+      str = str.to_s
+
+      if uses_last_index?
+        if pos == POS_UNSET
+          start = @last_index
+          if start < 0 || start > str.length
+            @last_index = 0
+            return nil
+          end
+
+          m = raw_match(str, start)
+          if m
+            @last_index = m.end(0)
+            return m
+          end
+
+          @last_index = 0
+          return nil
+        end
+
+        return raw_match(str, pos)
+      end
+
+      pos = 0 if pos == POS_UNSET
+      raw_match(str, pos)
+    end
+  end
+end

data/lib/js_regex_to_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsRegexToRuby
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/js_regex_to_ruby.rb

@@ -2,6 +2,7 @@
 
 require_relative "js_regex_to_ruby/version"
 require_relative "js_regex_to_ruby/result"
+require_relative "js_regex_to_ruby/js_regexp"
 require_relative "js_regex_to_ruby/converter"
 
 module JsRegexToRuby
@@ -17,18 +18,32 @@ module JsRegexToRuby
   # Returns the compiled Regexp on success, or nil on failure.
   # Never raises exceptions for invalid input.
   #
-  # @example
+  # @example With JS regex literal (starts with /)
   #   JsRegexToRuby.try_convert('/^foo$/i')  #=> /\Afoo\z/i
-  #   JsRegexToRuby.try_convert('not a regex')  #=> nil
-  #   JsRegexToRuby.try_convert('/invalid[/') #=> nil
+  #   JsRegexToRuby.try_convert('/invalid[/')  #=> nil (invalid regex syntax)
+  #
+  # @example With pattern source (no / delimiter) - treated as raw pattern
+  #   JsRegexToRuby.try_convert('cat')  #=> /cat/
+  #   JsRegexToRuby.try_convert('[invalid')  #=> nil (invalid regex syntax)
   #
-  # @param input [String] Either a JS literal `/.../flags` or a JS pattern source.
+  # @example With literal_only: true - only accept /.../ format
+  #   JsRegexToRuby.try_convert('cat', literal_only: true)  #=> nil (doesn't start with /)
+  #   JsRegexToRuby.try_convert('/cat/', literal_only: true)  #=> /cat/
+  #
+  # @param input [String, #to_s] Either a JS literal `/.../flags` or a JS pattern source.
   # @param flags [String, nil] JS flags if input is not a literal.
+  # @param literal_only [Boolean] If true, returns nil for inputs that don't look like
+  #   JS regex literals (i.e., don't start with "/"). Useful when you want to treat
+  #   plain strings like "cat" as non-regex values rather than pattern sources.
   # @return [Regexp, nil] The compiled Ruby Regexp, or nil if conversion/compilation failed.
-  def self.try_convert(input, flags: nil)
-    result = Converter.convert(input, flags: flags, compile: true)
-    result.regexp
-  rescue ArgumentError, RegexpError
+  def self.try_convert(input, flags: nil, literal_only: false)
+    if literal_only
+      input = input.to_s
+      return nil unless input.start_with?("/")
+    end
+
+    Converter.convert(input, flags: flags, compile: true).regexp
+  rescue
     nil
   end
 

data/sig/js_regex_to_ruby.rbs

@@ -1,3 +1,8 @@
+# Interface for objects that respond to #to_s
+interface _ToS
+  def to_s: () -> String
+end
+
 module JsRegexToRuby
   VERSION: String
 
@@ -5,7 +10,9 @@ module JsRegexToRuby
   def self.convert: (String input, ?flags: String?, ?compile: bool) -> Result
 
   # Try to convert a JS regex to Ruby Regexp, returns nil on failure
-  def self.try_convert: (String input, ?flags: String?) -> Regexp?
+  # - When literal_only: false (default), only String inputs are processed; non-strings return nil
+  # - When literal_only: true, input is converted via #to_s; returns nil if not starting with "/"
+  def self.try_convert: (String | _ToS input, ?flags: String?, ?literal_only: bool) -> Regexp?
 
   # Parse a JS regex literal into pattern and flags
   def self.parse_literal: (String literal) -> [String, String]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: js_regex_to_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - jasl
@@ -25,6 +25,7 @@ files:
 - Rakefile
 - lib/js_regex_to_ruby.rb
 - lib/js_regex_to_ruby/converter.rb
+- lib/js_regex_to_ruby/js_regexp.rb
 - lib/js_regex_to_ruby/result.rb
 - lib/js_regex_to_ruby/version.rb
 - sig/js_regex_to_ruby.rbs