string_pattern 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47172de723c22b8175a1119aa51c065056ec4eab029cfb989b4fa4c9bc20d845
-  data.tar.gz: c9e9996c3f5ec59813b157a9f818c10723fb1b9f95a1ed871ba80219d04bbe6e
+  metadata.gz: 8769f150212e86d1c798377384ec17edccc22ba4c09d4b15d75bdac5ea1772b0
+  data.tar.gz: '0249dda55facee2d54e3a9229ef3bfb5e587eeac6adc72849c6a374fa15eb9dd'
 SHA512:
-  metadata.gz: 840a84447c523a01e21657fa772c190388a1401e41d254e5340fe9bd081eb0740ba200161c0a29e06dcfa841632c26d51346da53bf2c5a8f93ad3459aa455930
-  data.tar.gz: f53b2b1ef110f8e20b95e7e5bafac00067bbc782e2817fa3292cbd4b60492454b171133b80b8808e737606c83dd8f2df59d5d57447bcc5cc225d6239c0edb7e3
+  metadata.gz: a6247d3b5b23256e06bdd1a4079197f238b856fd8f492878bfca79373abd257cf7b5b6002a6bcf363fc21ce5402222fc7c666002c0c2bb05ae429d4f9b9ce8bf
+  data.tar.gz: e72ce0732bb53fcc97b96623d43b76d73b774c2c3033c9ef4143edb53935120d734d4cbb7677e3db26cb0504047c2827576a3dbf068894f47a7092d1c9e586c2

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [2.5.0] - 2026-09-23
+
+### Added
+- Added `StringPattern.with` to apply configuration for the duration of a block, and `StringPattern.reset!` to restore defaults and clear caches.
+- Added `StringPattern::VERSION`.
+- Added full-string `Regexp` validation via `StringPattern.validate`, `StringPattern.valid?`, and `Regexp#validate` / `#val`.
+- Added `StringPattern.explain` with the failing segment index for pattern arrays.
+- Added `StringPattern.iban` / `valid_iban?` (ISO 13616) and `StringPattern.luhn` / `valid_luhn?`.
+- Added `block_list_regexp` to opt into the previous regular-expression block list.
+- `StringPattern.sample` forwards `seed:` and other generate options.
+
+### Changed
+- Generation uses its own `Random` instance. `seed:` no longer calls `srand`, so it does not change `Kernel#rand`. Sequences for a given seed may differ from 2.4.0.
+- `block_list` matches literals (case-insensitive) unless `block_list_regexp` is true.
+- Spanish word generation loads all `data/spanish/palabras*.json` files instead of one random file.
+- Invalid patterns and impossible generation honor `raise_on_error` on every failure path.
+- Required Ruby version is 3.0 or newer.
+
+## [2.4.0] - 2026-02-11
+
+### Added
+- Added `StringPattern.valid_email?` helper and centralized email format checks.
+- Added `StringPattern.valid?(text:, pattern:)` for boolean validation.
+- Added `StringPattern.sample(pattern, n)` for batch generation of distinct values.
+- Added `StringPattern.uuid` and `StringPattern.valid_uuid?`.
+- Added support for `seed:` in generation for reproducible outputs.
+- Added support for `block_list` as a `Proc`.
+- Added `StringPattern::InvalidPatternError` and `StringPattern::GenerationImpossibleError`.
+- Added `StringPattern.logger` and `StringPattern.raise_on_error` configuration.
+- Added `spec/string/pattern/analyze_spec.rb`.
+- Added GitHub Actions CI workflow.
+
+### Changed
+- Fixed email-domain comparison bug in email validation/generation paths.
+- Replaced internal direct `puts` calls with centralized logging (`StringPattern.log_message`).
+- Updated README with analyze/validation/error-handling/new-features documentation.
+- Updated CI target Ruby versions (3.0, 3.1, 3.2, 3.3).
+
+## [2.3.0] - 2025-xx-xx
+
+### Changed
+- Previous release notes not yet backfilled.

data/README.md

@@ -1,7 +1,7 @@
 # StringPattern
 
 [![Gem Version](https://badge.fury.io/rb/string_pattern.svg)](https://rubygems.org/gems/string_pattern)
-[![Build Status](https://travis-ci.com/MarioRuiz/string_pattern.svg?branch=master)](https://github.com/MarioRuiz/string_pattern)
+[![CI](https://github.com/MarioRuiz/string_pattern/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/MarioRuiz/string_pattern/actions/workflows/ci.yml)
 [![Coverage Status](https://coveralls.io/repos/github/MarioRuiz/string_pattern/badge.svg?branch=master)](https://coveralls.io/github/MarioRuiz/string_pattern?branch=master)
 ![Gem](https://img.shields.io/gem/dt/string_pattern)
 ![GitHub commit activity](https://img.shields.io/github/commit-activity/y/MarioRuiz/string_pattern)
@@ -503,6 +503,51 @@ StringPattern.block_list = ->(s) { s.include?("forbidden") }
 StringPattern.block_list_enabled = true
 ```
 
+Entries in `block_list` are matched as case-insensitive literals. Set `StringPattern.block_list_regexp = true` when an entry should be a regular expression, which was the behavior before 2.5.0.
+
+#### Scoped configuration
+
+`StringPattern.with` applies settings for one block and restores the previous values afterwards, including when the block raises:
+
+```ruby
+StringPattern.with(dont_repeat: true, raise_on_error: true) do
+  "6:N".gen
+end
+```
+
+`StringPattern.reset!` restores the default configuration and clears the pattern cache and the generated-value cache.
+
+#### Validate a regular expression
+
+`valid?` and `validate` accept a `Regexp` and match the whole string. The same methods are available on the regexp itself:
+
+```ruby
+StringPattern.valid?(text: "abc", pattern: /[a-z]+/)   # => true
+StringPattern.valid?(text: "abc1", pattern: /[a-z]+/)  # => false
+/[a-z]+/.validate("abc")                               # => []
+/[a-z]+/.val("abc1")                                   # => [:value]
+```
+
+#### Explain a validation
+
+```ruby
+StringPattern.explain(text: "ab", pattern: "6:N")
+# => { valid: false, errors: [:min_length, :length, :value, :string_set_not_allowed], message: "invalid: ...", index: nil }
+
+StringPattern.explain(text: "333111", pattern: ["3:n", "3:x"])
+# => { valid: false, errors: [...], message: "segment 1 does not match: ...", index: 1 }
+```
+
+#### IBAN and Luhn
+
+International checksums for test data. `iban` requires a country code and only generates countries whose length is known (ES, DE, FR, GB, PT, IT, NL, BE). The BBAN is random. `valid_iban?` accepts any well-formed IBAN. `luhn` builds a digit string with a valid Luhn check digit and does not represent a real card.
+
+```ruby
+StringPattern.iban(country: "DE")          # => "DE..."
+StringPattern.valid_iban?("DE89 3704 0044 0532 0130 00")  # => true
+StringPattern.luhn(length: 16)             # => "16 digits"
+StringPattern.valid_luhn?("79927398713")   # => true
+```
 
 ## Contributing
 

data/lib/string/pattern/add_to_ruby.rb

@@ -78,6 +78,13 @@ class Regexp
 
   alias gen generate
 
+  # Validates +string_to_validate+ against this regular expression as a full-string match.
+  def validate(string_to_validate, expected_errors: [], not_expected_errors: [], **synonyms)
+    StringPattern.validate(text: string_to_validate, pattern: self, expected_errors: expected_errors, not_expected_errors: not_expected_errors, **synonyms)
+  end
+
+  alias val validate
+
   # adds method to convert a Regexp to StringPattern
   # returns an array of string patterns or just one string pattern
   def to_sp

data/lib/string/pattern/checksum.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class StringPattern
+  # IBAN lengths we can generate. Validation accepts any well-formed IBAN.
+  IBAN_LENGTHS = {
+    "ES" => 24,
+    "DE" => 22,
+    "FR" => 27,
+    "GB" => 22,
+    "PT" => 25,
+    "IT" => 27,
+    "NL" => 18,
+    "BE" => 16
+  }.freeze
+
+  # Generates a random IBAN for +country+ (ISO 13616). The BBAN is random, not a real bank account.
+  # @param country [String, Symbol] two-letter country code
+  # @return [String]
+  # @raise [ArgumentError] when the country is not in {IBAN_LENGTHS}
+  def self.iban(country:)
+    code = country.to_s.upcase
+    length = IBAN_LENGTHS[code]
+    raise ArgumentError, "unknown IBAN country: #{country.inspect}" unless length
+
+    rng = Random.new
+    alphabet = [*("0".."9"), *("A".."Z")]
+    bban = Array.new(length - 4) { alphabet.sample(random: rng) }.join
+    "#{code}#{iban_check_digits(code, bban)}#{bban}"
+  end
+
+  # Returns true when +str+ is a well-formed IBAN (format and mod-97), ignoring spaces.
+  # @param str [String]
+  # @return [Boolean]
+  def self.valid_iban?(str)
+    return false unless str.is_a?(String)
+
+    compact = str.gsub(/\s+/, "").upcase
+    return false unless compact.match?(/\A[A-Z]{2}\d{2}[A-Z0-9]+\z/)
+    return false unless (15..34).cover?(compact.length)
+
+    rearranged = compact[4..] + compact[0, 4]
+    iban_mod97(iban_to_digits(rearranged)) == 1
+  end
+
+  # Generates a digit string of +length+ that satisfies the Luhn checksum.
+  # @param length [Integer] total number of digits, at least 2
+  # @return [String]
+  # @raise [ArgumentError] when length is below 2
+  def self.luhn(length:)
+    length = Integer(length)
+    raise ArgumentError, "length must be >= 2" if length < 2
+
+    rng = Random.new
+    digits = Array.new(length - 1) { rng.rand(10) }
+    digits << luhn_check_digit(digits)
+    digits.join
+  end
+
+  # Returns true when +str+ is a digit string with a valid Luhn checksum.
+  # @param str [String]
+  # @return [Boolean]
+  def self.valid_luhn?(str)
+    return false unless str.is_a?(String) && str.match?(/\A\d{2,}\z/)
+
+    luhn_sum(str.chars.map(&:to_i)) % 10 == 0
+  end
+
+  def self.iban_check_digits(country, bban)
+    remainder = iban_mod97(iban_to_digits("#{bban}#{country}00"))
+    format("%02d", 98 - remainder)
+  end
+
+  def self.iban_to_digits(value)
+    value.each_char.map { |char|
+      if char >= "A" && char <= "Z"
+        (char.ord - 55).to_s
+      else
+        char
+      end
+    }.join
+  end
+
+  def self.iban_mod97(digit_string)
+    remainder = 0
+    digit_string.scan(/.{1,9}/).each do |chunk|
+      remainder = "#{remainder}#{chunk}".to_i % 97
+    end
+    remainder
+  end
+
+  def self.luhn_check_digit(payload)
+    (10 - (luhn_sum(payload + [0]) % 10)) % 10
+  end
+
+  def self.luhn_sum(digits)
+    digits.reverse.each_with_index.sum do |digit, index|
+      value = digit.to_i
+      if index.odd?
+        value *= 2
+        value -= 9 if value > 9
+      end
+      value
+    end
+  end
+  private_class_method :iban_check_digits, :iban_to_digits, :iban_mod97, :luhn_check_digit, :luhn_sum
+end

data/lib/string/pattern/generate.rb

@@ -64,8 +64,11 @@ class StringPattern
   #     the generated string
   ###############################################
   def StringPattern.generate(pattern, expected_errors: [], **synonyms)
-    seed_given = synonyms.key?(:seed)
-    saved_rng = seed_given ? srand(synonyms[:seed]) : nil
+    rng = synonyms.delete(:_rng)
+    if rng.nil?
+      base = synonyms.key?(:seed) ? Random.new(synonyms[:seed]) : Random.new
+      rng = StringPattern::RandomSource.new(base)
+    end
     tries = 0
     begin
       good_result = true
@@ -81,30 +84,32 @@ class StringPattern
       if pattern.kind_of?(Array)
         pattern.each { |pat|
           if pat.kind_of?(Array) # for the case it is one of the values
-            pat = pat.sample
+            pat = pat.sample(random: rng)
           end
 
           if pat.kind_of?(Symbol)
             if pat.to_s.scan(/^!?\d+-?\d*:.+/).size > 0
-              string << StringPattern.generate(pat.to_s, expected_errors: expected_errors)
+              string << StringPattern.generate(pat.to_s, expected_errors: expected_errors, _rng: rng)
             else
               string << pat.to_s
             end
           elsif pat.kind_of?(String)
             if @optimistic and pat.to_s.scan(/^!?\d+-?\d*:.+/).size > 0
-              string << StringPattern.generate(pat.to_s, expected_errors: expected_errors)
+              string << StringPattern.generate(pat.to_s, expected_errors: expected_errors, _rng: rng)
             else
               string << pat
             end
           else
-            StringPattern.log_message("StringPattern.generate: it seems you supplied wrong array of patterns: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-            return ""
+            return StringPattern.fail_generation("StringPattern.generate: it seems you supplied wrong array of patterns: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::InvalidPatternError)
           end
         }
         return string
       elsif pattern.kind_of?(String) or pattern.kind_of?(Symbol)
         patt = StringPattern.analyze(pattern).clone
-        return "" unless patt.kind_of?(Struct)
+        unless patt.kind_of?(Struct)
+          raise StringPattern::InvalidPatternError, "pattern argument not valid on StringPattern.generate: #{pattern.inspect}" if @raise_on_error
+          return ""
+        end
 
         min_length = patt.min_length.clone
         max_length = patt.max_length.clone
@@ -122,17 +127,18 @@ class StringPattern
           }
           unless excluded_data.size == 0
             if (required_chars.flatten & excluded_data.flatten).size > 0
-              StringPattern.log_message("pattern argument not valid on StringPattern.generate, a character cannot be required and excluded at the same time: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-              return ""
+              return StringPattern.fail_generation("pattern argument not valid on StringPattern.generate, a character cannot be required and excluded at the same time: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::InvalidPatternError)
             end
           end
         end
 
         string_set_not_allowed = Array.new
       elsif pattern.kind_of?(Regexp)
-        return generate(pattern.to_sp, expected_errors: expected_errors)
+        return generate(pattern.to_sp, expected_errors: expected_errors, _rng: rng)
       else
-        StringPattern.log_message("pattern argument not valid on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
+        message = "pattern argument not valid on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
+        raise StringPattern::InvalidPatternError, message if @raise_on_error
+        StringPattern.log_message(message)
         return pattern.to_s
       end
 
@@ -141,8 +147,8 @@ class StringPattern
       if symbol_type[0..0] == "!"
         deny_pattern = true
         possible_errors = [:length, :value, :string_set_not_allowed]
-        (rand(possible_errors.size) + 1).times {
-          expected_errors << possible_errors.sample
+        (rng.rand(possible_errors.size) + 1).times {
+          expected_errors << possible_errors.sample(random: rng)
         }
         expected_errors.uniq!
         if symbol_type[1..1] == "0"
@@ -171,21 +177,18 @@ class StringPattern
 
       unless deny_pattern
         if required_data.size == 0 and expected_errors_left.include?(:required_data)
-          StringPattern.log_message("required data not supplied on pattern so it won't be possible to generate a wrong string. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-          return ""
+          return StringPattern.fail_generation("required data not supplied on pattern so it won't be possible to generate a wrong string. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::GenerationImpossibleError)
         end
 
         if excluded_data.size == 0 and expected_errors_left.include?(:excluded_data)
-          StringPattern.log_message("excluded data not supplied on pattern so it won't be possible to generate a wrong string. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-          return ""
+          return StringPattern.fail_generation("excluded data not supplied on pattern so it won't be possible to generate a wrong string. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::GenerationImpossibleError)
         end
 
         if expected_errors_left.include?(:string_set_not_allowed)
           string_set_not_allowed = all_characters_set - string_set
 
           if string_set_not_allowed.size == 0
-            StringPattern.log_message("all characters are allowed so it won't be possible to generate a wrong string. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-            return ""
+            return StringPattern.fail_generation("all characters are allowed so it won't be possible to generate a wrong string. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::GenerationImpossibleError)
           end
         end
       end
@@ -194,12 +197,12 @@ class StringPattern
          expected_errors_left.include?(:max_length) or
          expected_errors_left.include?(:length)
         if expected_errors_left.include?(:min_length) or
-           (min_length > 0 and expected_errors_left.include?(:length) and rand(2) == 0)
+           (min_length > 0 and expected_errors_left.include?(:length) and rng.rand(2) == 0)
           if min_length > 0
             if allow_empty
-              length = rand(min_length).to_i
+              length = rng.rand(min_length).to_i
             else
-              length = rand(min_length - 1).to_i + 1
+              length = rng.rand(min_length - 1).to_i + 1
             end
             if required_data.size > length and required_data.size < min_length
               length = required_data.size
@@ -207,22 +210,21 @@ class StringPattern
             expected_errors_left.delete(:length)
             expected_errors_left.delete(:min_length)
           else
-            StringPattern.log_message("min_length is 0 so it won't be possible to generate a wrong string smaller than 0 characters. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-            return ""
+            return StringPattern.fail_generation("min_length is 0 so it won't be possible to generate a wrong string smaller than 0 characters. StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::GenerationImpossibleError)
           end
         elsif expected_errors_left.include?(:max_length) or expected_errors_left.include?(:length)
-          length = max_length + 1 + rand(max_length).to_i
+          length = max_length + 1 + rng.rand(max_length).to_i
           expected_errors_left.delete(:length)
           expected_errors_left.delete(:max_length)
         end
       else
-        if allow_empty and rand(7) == 1
+        if allow_empty and rng.rand(7) == 1
           length = 0
         else
           if max_length == min_length
             length = min_length
           else
-            length = min_length + rand(max_length - min_length + 1)
+            length = min_length + rng.rand(max_length - min_length + 1)
           end
         end
       end
@@ -253,28 +255,27 @@ class StringPattern
       if symbol_type != "@" and symbol_type != "!@" and length != 0 and string_set.size != 0
         if string_set.size != 0
           1.upto(length) { |i|
-            string << string_set.sample.to_s
+            string << string_set.sample(random: rng).to_s
           }
         end
         if required_data.size > 0
           positions_to_set = (0..(string.size - 1)).to_a
           required_data.each { |rd|
             if (string.chars & rd).size > 0
-              rd_to_set = (string.chars & rd).sample
+              rd_to_set = (string.chars & rd).sample(random: rng)
             else
-              rd_to_set = rd.sample
+              rd_to_set = rd.sample(random: rng)
             end
             if ((0...string.length).find_all { |i| string[i, 1] == rd_to_set }).size == 0
               if positions_to_set.size == 0
-                StringPattern.log_message("pattern not valid on StringPattern.generate, not possible to generate a valid string: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-                return ""
+                return StringPattern.fail_generation("pattern not valid on StringPattern.generate, not possible to generate a valid string: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::GenerationImpossibleError)
               else
-                k = positions_to_set.sample
+                k = positions_to_set.sample(random: rng)
                 string[k] = rd_to_set
                 positions_to_set.delete(k)
               end
             else
-              k = ((0...string.length).find_all { |i| string[i, 1] == rd_to_set }).sample
+              k = ((0...string.length).find_all { |i| string[i, 1] == rd_to_set }).sample(random: rng)
               positions_to_set.delete(k)
             end
           }
@@ -282,7 +283,7 @@ class StringPattern
         excluded_data.each { |ed|
           if (string.chars & ed).size > 0
             (string.chars & ed).each { |s|
-              string.gsub!(s, string_set.sample)
+              string.gsub!(s, string_set.sample(random: rng))
             }
           end
         }
@@ -291,28 +292,27 @@ class StringPattern
           string_set_not_allowed = all_characters_set - string_set if string_set_not_allowed.size == 0
 
           if string_set_not_allowed.size == 0
-            StringPattern.log_message("Not possible to generate a non valid string on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
-            return ""
+            return StringPattern.fail_generation("Not possible to generate a non valid string on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::GenerationImpossibleError)
           end
-          (rand(string.size) + 1).times {
-            string[rand(string.size)] = (all_characters_set - string_set).sample
+          (rng.rand(string.size) + 1).times {
+            string[rng.rand(string.size)] = (all_characters_set - string_set).sample(random: rng)
           }
           expected_errors_left.delete(:value)
         end
 
         if expected_errors_left.include?(:required_data) and required_data.size > 0
-          (rand(required_data.size) + 1).times {
-            chars_to_remove = required_data.sample
+          (rng.rand(required_data.size) + 1).times {
+            chars_to_remove = required_data.sample(random: rng)
             chars_to_remove.each { |char_to_remove|
-              string.gsub!(char_to_remove, (string_set - chars_to_remove).sample)
+              string.gsub!(char_to_remove, (string_set - chars_to_remove).sample(random: rng))
             }
           }
           expected_errors_left.delete(:required_data)
         end
 
         if expected_errors_left.include?(:excluded_data) and excluded_data.size > 0
-          (rand(string.size) + 1).times {
-            string[rand(string.size)] = excluded_data.sample.sample
+          (rng.rand(string.size) + 1).times {
+            string[rng.rand(string.size)] = excluded_data.sample(random: rng).sample(random: rng)
           }
           expected_errors_left.delete(:excluded_data)
         end
@@ -320,67 +320,21 @@ class StringPattern
         if expected_errors_left.include?(:string_set_not_allowed)
           string_set_not_allowed = all_characters_set - string_set if string_set_not_allowed.size == 0
           if string_set_not_allowed.size > 0
-            (rand(string.size) + 1).times {
-              string[rand(string.size)] = string_set_not_allowed.sample
+            (rng.rand(string.size) + 1).times {
+              string[rng.rand(string.size)] = string_set_not_allowed.sample(random: rng)
             }
             expected_errors_left.delete(:string_set_not_allowed)
           end
         end
       elsif (symbol_type == "W" or symbol_type == "P" or symbol_type == "w" or symbol_type == "p") and length > 0
-        words = []
-        words_short = []
-        if symbol_type == "W"
-          if @words_camel.empty?
-            require "pathname"
-            require "json"
-            filename = File.join Pathname(File.dirname(__FILE__)), "../../../data", "english/nouns.json"
-            nouns = JSON.parse(File.read(filename))
-            filename = File.join Pathname(File.dirname(__FILE__)), "../../../data", "english/adjs.json"
-            adjs = JSON.parse(File.read(filename))
-            nouns = nouns.map(&:to_camel_case)
-            adjs = adjs.map(&:to_camel_case)
-            @words_camel = adjs + nouns
-            @words_camel_short = @words_camel.sample(2000)
-          end
-          words = @words_camel
-          words_short = @words_camel_short
-        elsif symbol_type == "w"
-          if @words.empty?
-            require "pathname"
-            require "json"
-            filename = File.join Pathname(File.dirname(__FILE__)), "../../../data", "english/nouns.json"
-            nouns = JSON.parse(File.read(filename))
-            filename = File.join Pathname(File.dirname(__FILE__)), "../../../data", "english/adjs.json"
-            adjs = JSON.parse(File.read(filename))
-            @words = adjs + nouns
-            @words_short = @words.sample(2000)
-          end
-          words = @words
-          words_short = @words_short
-        elsif symbol_type == "P"
-          if @palabras_camel.empty?
-            require "pathname"
-            require "json"
-            filename = File.join Pathname(File.dirname(__FILE__)), "../../../data", "spanish/palabras#{rand(12)}.json"
-            palabras = JSON.parse(File.read(filename))
-            palabras = palabras.map(&:to_camel_case)
-            @palabras_camel = palabras
-            @palabras_camel_short = @palabras_camel.sample(2000)
-          end
-          words = @palabras_camel
-          words_short = @palabras_camel_short
-        elsif symbol_type == "p"
-          if @palabras.empty?
-            require "pathname"
-            require "json"
-            filename = File.join Pathname(File.dirname(__FILE__)), "../../../data", "spanish/palabras#{rand(12)}.json"
-            palabras = JSON.parse(File.read(filename))
-            @palabras = palabras
-            @palabras_short = @palabras.sample(2000)
-          end
-          words = @palabras
-          words_short = @palabras_short
+        if symbol_type == "W" || symbol_type == "w"
+          load_english_words(camel: symbol_type == "W")
+          words = symbol_type == "W" ? @words_camel : @words
+        else
+          load_spanish_words(camel: symbol_type == "P")
+          words = symbol_type == "P" ? @palabras_camel : @palabras
         end
+        words_short = words.sample(2000, random: rng)
 
         wordr = ""
         wordr_array = []
@@ -394,16 +348,16 @@ class StringPattern
           end
           if symbol_type == "w" or symbol_type == "p"
             length = length - 1 if wordr_array.size > 0
-            res = (words_short.select { |word| word.length <= length && word.length != length - 1 && word.length != length - 2 && word.length != length - 3 }).sample.to_s
+            res = (words_short.select { |word| word.length <= length && word.length != length - 1 && word.length != length - 2 && word.length != length - 3 }).sample(random: rng).to_s
             unless res.to_s == ""
               wordr_array << res
               wordr = wordr_array.join(@word_separator)
             end
           else
-            wordr += (words_short.select { |word| word.length <= length && word.length != length - 1 && word.length != length - 2 && word.length != length - 3 }).sample.to_s
+            wordr += (words_short.select { |word| word.length <= length && word.length != length - 1 && word.length != length - 2 && word.length != length - 3 }).sample(random: rng).to_s
           end
           if (tries % 100) == 0
-            words_short = words.sample(2000)
+            words_short = words.sample(2000, random: rng)
           end
         end
         good_result = true
@@ -436,60 +390,60 @@ class StringPattern
           at_sign = "@"
 
           if expected_errors_left.include?(:value)
-            if rand(2) == 1
-              extension = (all_characters_set - ["."]).sample.dup
+            if rng.rand(2) == 1
+              extension = (all_characters_set - ["."]).sample(random: rng).dup
               expected_errors_left.delete(:value)
               expected_errors_left.delete(:required_data)
             end
 
-            if rand(2) == 1
-              1.upto(rand(7)) { |i|
-                extension << alpha_set.sample.downcase
+            if rng.rand(2) == 1
+              1.upto(rng.rand(7)) { |i|
+                extension << alpha_set.sample(random: rng).downcase
               }
 
-              (rand(extension.size) + 1).times {
-                extension[rand(extension.size)] = (string_set - alpha_set - ["."]).sample
+              (rng.rand(extension.size) + 1).times {
+                extension[rng.rand(extension.size)] = (string_set - alpha_set - ["."]).sample(random: rng)
               }
 
               expected_errors_left.delete(:value)
             else
-              1.upto(rand(3) + 2) { |i|
-                extension << alpha_set.sample.downcase
+              1.upto(rng.rand(3) + 2) { |i|
+                extension << alpha_set.sample(random: rng).downcase
               }
             end
 
-            if rand(2) == 1
-              at_sign = (string_set - ["@"]).sample.dup
+            if rng.rand(2) == 1
+              at_sign = (string_set - ["@"]).sample(random: rng).dup
               expected_errors_left.delete(:value)
               expected_errors_left.delete(:required_data)
             end
           else
             if length > 6
-              1.upto(rand(3) + 2) { |i|
-                extension << alpha_set.sample.downcase
+              1.upto(rng.rand(3) + 2) { |i|
+                extension << alpha_set.sample(random: rng).downcase
               }
             else
               1.upto(2) { |i|
-                extension << alpha_set.sample.downcase
+                extension << alpha_set.sample(random: rng).downcase
               }
             end
           end
           length_e = length - extension.size - 1
-          length1 = rand(length_e - 1) + 1
+          length1 = rng.rand(length_e - 1) + 1
           length2 = length_e - length1
-          1.upto(length1) { |i| string << string_set.sample }
+          1.upto(length1) { |i| string << string_set.sample(random: rng) }
 
           string << at_sign
 
           domain = ""
           domain_set = alpha_set + NUMBER_SET.clone + ["."] + ["-"]
           1.upto(length2) { |i|
-            domain << domain_set.sample.downcase
+            domain << domain_set.sample(random: rng).downcase
           }
 
-          if expected_errors.include?(:value) and rand(2) == 1 and domain.size > 0
-            (rand(domain.size) + 1).times {
-              domain[rand(domain.size)] = (all_characters_set - domain_set).sample
+          if expected_errors.include?(:value) and rng.rand(2) == 1 and domain.size > 0
+            (rng.rand(domain.size) + 1).times {
+              domain[rng.rand(domain.size)] = (all_characters_set - domain_set).sample(random: rng)
             }
             expected_errors_left.delete(:value)
           end
@@ -497,8 +451,8 @@ class StringPattern
           string << domain << extension
 
           if expected_errors_left.include?(:value) or expected_errors_left.include?(:string_set_not_allowed)
-            (rand(string.size) + 1).times {
-              string[rand(string.size)] = string_set_not_allowed.sample
+            (rng.rand(string.size) + 1).times {
+              string[rng.rand(string.size)] = string_set_not_allowed.sample(random: rng)
             }
             expected_errors_left.delete(:value)
             expected_errors_left.delete(:string_set_not_allowed)
@@ -529,10 +483,7 @@ class StringPattern
           end
         end until good_result or tries > 100
         unless good_result
-          msg = "Not possible to generate an email on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
-          raise StringPattern::GenerationImpossibleError, msg if @raise_on_error
-          StringPattern.log_message(msg)
-          return ""
+          return StringPattern.fail_generation("Not possible to generate an email on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}", StringPattern::GenerationImpossibleError)
         end
       end
       if @dont_repeat
@@ -563,10 +514,20 @@ class StringPattern
         if @block_list.respond_to?(:call)
           good_result = false if @block_list.call(string)
         elsif @block_list.is_a?(Array)
-          @block_list.each do |bl|
-            if string.match?(/#{bl}/i)
-              good_result = false
-              break
+          if @block_list_regexp
+            @block_list.each do |bl|
+              if string.match?(/#{bl}/i)
+                good_result = false
+                break
+              end
+            end
+          else
+            downcased = string.downcase
+            @block_list.each do |bl|
+              if downcased.include?(bl.to_s.downcase)
+                good_result = false
+                break
+              end
             end
           end
         end
@@ -575,12 +536,42 @@ class StringPattern
     unless good_result
       msg = "Not possible to generate the string on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
       msg += "\nTake in consideration if you are using StringPattern.dont_repeat=true that you don't try to generate more strings that are possible to be generated"
-      raise StringPattern::GenerationImpossibleError, msg if @raise_on_error
-      StringPattern.log_message(msg)
-      return ""
+      return StringPattern.fail_generation(msg, StringPattern::GenerationImpossibleError)
     end
     return string
-  ensure
-    srand(saved_rng) if saved_rng
+  end
+
+  def self.fail_generation(message, error_class)
+    raise error_class, message if @raise_on_error
+    log_message(message)
+    ""
+  end
+
+  def self.word_data_path(*parts)
+    File.join(__dir__, "..", "..", "..", "data", *parts)
+  end
+
+  def self.load_english_words(camel: false)
+    require "json"
+    if @words.nil? || @words.empty?
+      nouns = JSON.parse(File.read(word_data_path("english", "nouns.json")))
+      adjs = JSON.parse(File.read(word_data_path("english", "adjs.json")))
+      @words = adjs + nouns
+    end
+    if camel && (@words_camel.nil? || @words_camel.empty?)
+      @words_camel = @words.map(&:to_camel_case)
+    end
+  end
+
+  def self.load_spanish_words(camel: false)
+    require "json"
+    if @palabras.nil? || @palabras.empty?
+      @palabras = (0..11).flat_map do |i|
+        JSON.parse(File.read(word_data_path("spanish", "palabras#{i}.json")))
+      end
+    end
+    if camel && (@palabras_camel.nil? || @palabras_camel.empty?)
+      @palabras_camel = @palabras.map(&:to_camel_case)
+    end
   end
 end

data/lib/string/pattern/validate.rb

@@ -32,6 +32,11 @@ class StringPattern
     if (not_expected_errors.include?(:min_length) or not_expected_errors.include?(:max_length)) and !not_expected_errors.include?(:length)
       not_expected_errors.push(:length)
     end
+    if pattern.is_a?(Regexp)
+      return false if text_to_validate.nil?
+      detected_errors = StringPattern.regexp_full_match?(pattern, text_to_validate.to_s) ? [] : [:value]
+      return StringPattern.validation_decision(detected_errors, expected_errors, not_expected_errors)
+    end
     if pattern.kind_of?(Array) and pattern.size == 1
       pattern = pattern[0]
     elsif pattern.kind_of?(Array) and pattern.size > 1
@@ -133,7 +138,9 @@ class StringPattern
         required_chars << rd if rd.size == 1
       }
       if (required_chars.flatten & excluded_data.flatten).size > 0
-        StringPattern.log_message("pattern argument not valid on StringPattern.validate, a character cannot be required and excluded at the same time: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
+        message = "pattern argument not valid on StringPattern.validate, a character cannot be required and excluded at the same time: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
+        raise StringPattern::InvalidPatternError, message if @raise_on_error
+        StringPattern.log_message(message)
         return ""
       end
     end
@@ -190,18 +197,99 @@ class StringPattern
       end
     end
 
-    if expected_errors.size == 0 and not_expected_errors.size == 0
-      return detected_errors.uniq
+    StringPattern.validation_decision(detected_errors, expected_errors, not_expected_errors)
+  end
+
+  def self.validation_decision(detected_errors, expected_errors, not_expected_errors)
+    if expected_errors.size == 0 && not_expected_errors.size == 0
+      detected_errors.uniq
+    elsif (expected_errors & detected_errors) == expected_errors && (not_expected_errors & detected_errors).empty?
+      true
     else
-      if expected_errors & detected_errors == expected_errors
-        if (not_expected_errors & detected_errors).size > 0
-          return false
-        else
-          return true
-        end
-      else
-        return false
-      end
+      false
+    end
+  end
+
+  # True when +text+ matches the whole +regexp+, not a substring.
+  def self.regexp_full_match?(regexp, text)
+    return false unless text.is_a?(String)
+    anchored = Regexp.new("\\A(?:#{regexp.source})\\z", regexp.options)
+    anchored.match?(text)
+  rescue RegexpError
+    false
+  end
+
+  # Describes why +text+ does or does not match +pattern+.
+  # @return [Hash] :valid, :errors, :message, and :index (segment index for arrays)
+  def self.explain(text: nil, pattern: nil, **synonyms)
+    text = synonyms[:text_to_validate] if text.nil? && synonyms.key?(:text_to_validate)
+    text = synonyms[:validate] if text.nil? && synonyms.key?(:validate)
+
+    if pattern.is_a?(Array) && pattern.size > 1
+      return explain_array(text, pattern)
+    end
+
+    errors = validate(text: text, pattern: pattern)
+    if errors == true || (errors.is_a?(Array) && errors.empty?)
+      { valid: true, errors: [], message: "valid", index: nil }
+    elsif errors.is_a?(Array)
+      { valid: false, errors: errors, message: "invalid: #{errors.join(', ')}", index: nil }
+    else
+      { valid: false, errors: [:value], message: "invalid", index: nil }
+    end
+  end
+
+  def self.explain_array(text, patterns)
+    ok, index, errors = match_segments(text.to_s, patterns, 0)
+    if ok
+      { valid: true, errors: [], message: "valid", index: nil }
+    else
+      { valid: false, errors: errors, message: "segment #{index} does not match: #{errors.join(', ')}", index: index }
+    end
+  end
+
+  def self.match_segments(text, patterns, index)
+    if patterns.empty?
+      return [true, nil, []] if text.empty?
+      return [false, index, [:length]]
+    end
+
+    if patterns.size == 1
+      errors = validate(text: text, pattern: patterns[0])
+      return [true, nil, []] if errors == true || (errors.is_a?(Array) && errors.empty?)
+      errs = errors.is_a?(Array) ? errors : [:value]
+      return [false, index, errs]
+    end
+
+    info = segment_bounds(patterns[0])
+    return [false, index, [:value]] if info.nil?
+
+    best = nil
+    (info[:min]..info[:max]).each do |n|
+      next if n > text.length
+      errors = validate(text: text[0, n], pattern: patterns[0])
+      next unless errors == true || (errors.is_a?(Array) && errors.empty?)
+      ok, idx, errs = match_segments(text[n..], patterns[1..], index + 1)
+      return [true, nil, []] if ok
+      best = [idx, errs] if best.nil? || idx > best[0]
+    end
+
+    return [false, best[0], best[1]] if best
+
+    errors = validate(text: text, pattern: patterns[0])
+    errs = errors.is_a?(Array) ? errors : [:value]
+    errs = [:value] if errs.empty?
+    [false, index, errs]
+  end
+
+  def self.segment_bounds(pat)
+    pattern_like = pat.to_s.scan(/(\d+)-(\d+):(.+)/).size > 0 || pat.to_s.scan(/^!?(\d+):(.+)/).size > 0
+    if pat.is_a?(String) && (!optimistic || !pattern_like)
+      { min: pat.length, max: pat.length }
+    elsif pat.is_a?(Symbol) || pat.is_a?(String)
+      analyzed = analyze(pat, silent: true)
+      return nil unless analyzed.is_a?(Struct)
+      { min: analyzed.min_length, max: analyzed.max_length }
     end
   end
 end

data/lib/string_pattern/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class StringPattern
+  VERSION = "2.5.0"
+end

data/lib/string_pattern.rb

@@ -1,6 +1,8 @@
 SP_ADD_TO_RUBY = true if !defined?(SP_ADD_TO_RUBY)
+require_relative "string_pattern/version"
 require_relative "string/pattern/add_to_ruby" if SP_ADD_TO_RUBY
 require_relative "string/pattern/analyze"
+require_relative "string/pattern/checksum"
 require_relative "string/pattern/email"
 require_relative "string/pattern/generate"
 require_relative "string/pattern/validate"
@@ -41,13 +43,36 @@ class StringPattern
   # Raised when generation is impossible (e.g. exhausted by dont_repeat) and {raise_on_error} is true.
   GenerationImpossibleError = Class.new(StandardError)
 
+  # Wraps Random so +rand+ matches Kernel#rand for negative limits and zero.
+  # Array#sample calls +rand+ with a positive integer.
+  class RandomSource
+    def initialize(random)
+      @random = random
+    end
+
+    def rand(limit = nil)
+      return @random.rand if limit.nil?
+      if limit.is_a?(Integer) && limit.negative?
+        @random.rand(-limit)
+      elsif limit == 0
+        @random.rand
+      else
+        @random.rand(limit)
+      end
+    end
+  end
+
   class << self
     # @return [String, nil] When set, warning messages are sent here instead of +puts+.
     attr_accessor :logger
     # @return [Boolean] When true, invalid patterns or impossible generation raise instead of returning "".
     attr_accessor :raise_on_error
-    attr_accessor :national_chars, :optimistic, :dont_repeat, :cache, :cache_values, :default_infinite, :word_separator, :block_list, :block_list_enabled
+    attr_accessor :national_chars, :optimistic, :dont_repeat, :cache, :cache_values, :default_infinite, :word_separator, :block_list, :block_list_enabled, :block_list_regexp
   end
+  SCOPE_KEYS = %i[
+    dont_repeat block_list block_list_enabled block_list_regexp
+    national_chars optimistic word_separator raise_on_error logger
+  ].freeze
   @national_chars = (("a".."z").to_a + ("A".."Z").to_a).join
   @optimistic = true
   @cache = Hash.new()
@@ -59,6 +84,7 @@ class StringPattern
   @block_list = []
   @logger = nil
   @raise_on_error = false
+  @block_list_regexp = false
   NUMBER_SET = ("0".."9").to_a
   SPECIAL_SET = [" ", "~", "!", "@", "#", "$", "%", "^", "&", "*", "(", ")", "-", "_", "+", "=", "{", "}", "[", "]", "'", ";", ":", "?", ">", "<", "`", "|", "/", '"']
   ALPHA_SET_LOWER = ("a".."z").to_a
@@ -101,25 +127,78 @@ class StringPattern
   end
 
   # Generates up to +n+ distinct strings for +pattern+. Uses a temporary dont_repeat state.
+  # Keyword arguments, including +seed:+, are forwarded to {generate}. A seed advances one
+  # Random across the whole sample so successive values differ.
   # @param pattern [String, Symbol, Array, Regexp]
   # @param n [Integer]
   # @return [Array<String>]
-  def self.sample(pattern, n)
+  def self.sample(pattern, n, seed: nil, **options)
     return [] if n <= 0
+
+    rng = StringPattern::RandomSource.new(seed.nil? ? Random.new : Random.new(seed))
     old_dont = @dont_repeat
     old_cache = @cache_values.dup
+    started = true
     @dont_repeat = true
     @cache_values = {}
     results = []
     n.times do
-      s = generate(pattern)
+      s = generate(pattern, _rng: rng, **options)
       break if s.nil? || s.empty?
       results << s
     end
     results
   ensure
-    @dont_repeat = old_dont
-    @cache_values = old_cache
+    if started
+      @dont_repeat = old_dont
+      @cache_values = old_cache
+    end
+  end
+
+  # Runs +block+ with the given settings and restores the previous values afterwards.
+  # @return [Object] the block's result
+  def self.with(**options)
+    unknown = options.keys - SCOPE_KEYS
+    raise ArgumentError, "unknown option: #{unknown.join(', ')}" unless unknown.empty?
+
+    saved = {}
+    SCOPE_KEYS.each { |key| saved[key] = instance_variable_get("@#{key}") }
+    options.each do |key, value|
+      if key == :national_chars
+        self.national_chars = value
+      else
+        instance_variable_set("@#{key}", value)
+      end
+    end
+    yield
+  ensure
+    if saved
+      saved.each do |key, value|
+        if key == :national_chars
+          self.national_chars = value unless @national_chars == value
+        else
+          instance_variable_set("@#{key}", value)
+        end
+      end
+    end
+  end
+
+  # Restores configuration defaults and clears pattern and generated-value caches.
+  # @return [void]
+  def self.reset!
+    self.national_chars = (("a".."z").to_a + ("A".."Z").to_a).join
+    @optimistic = true
+    @dont_repeat = false
+    @default_infinite = 10
+    @word_separator = "_"
+    @block_list_enabled = false
+    @block_list = []
+    @block_list_regexp = false
+    @logger = nil
+    @raise_on_error = false
+    @cache = {}
+    @cache_values = {}
+    nil
   end
 
   # Generates a random UUID v4 (e.g. "550e8400-e29b-41d4-a716-446655440000").

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: string_pattern
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Mario Ruiz
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: regexp_parser
@@ -39,10 +38,12 @@ email: marioruizs@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 files:
 - ".yardopts"
+- CHANGELOG.md
 - LICENSE
 - README.md
 - data/english/adjs.json
@@ -61,15 +62,16 @@ files:
 - data/spanish/palabras9.json
 - lib/string/pattern/add_to_ruby.rb
 - lib/string/pattern/analyze.rb
+- lib/string/pattern/checksum.rb
 - lib/string/pattern/email.rb
 - lib/string/pattern/generate.rb
 - lib/string/pattern/validate.rb
 - lib/string_pattern.rb
+- lib/string_pattern/version.rb
 homepage: https://github.com/MarioRuiz/string_pattern
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -77,15 +79,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: 'Generate easily random strings following a simple pattern or regular expression.
   ''10-20:Xn/x/''.generate #>qBstvc6JN8ra. Also generate words in English or Spanish.