string_pattern 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b9ea7310d3fb561b37d8b0753360ddd5742188a2f71b68560a121d716d65083
-  data.tar.gz: a0504e61ff66a749d7c0b0fcc36ad629474d793abd78bc0456bdd6a9ddeae7f7
+  metadata.gz: 8769f150212e86d1c798377384ec17edccc22ba4c09d4b15d75bdac5ea1772b0
+  data.tar.gz: '0249dda55facee2d54e3a9229ef3bfb5e587eeac6adc72849c6a374fa15eb9dd'
 SHA512:
-  metadata.gz: 3ade8ead8f7434fb1893f62e44523245fb52776a24ffc9f9f548a16f790ec035f2411d223203886571decd7c7455b6f56cf41a7e62c491910762c210754e11f7
-  data.tar.gz: bbb68322396f6017f6f6f1b6190b1e14cc0a3cea804efa66f6527f892be032fe5cebc321e39ea399e0af9f69ee6f5e4ef1c7a9241ac97541cf6d4aac3191c658
+  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,8 +1,13 @@
 # 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)
+![GitHub last commit](https://img.shields.io/github/last-commit/MarioRuiz/string_pattern)
+![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/MarioRuiz/string_pattern)
+
 
 With this gem, you can easily generate strings supplying a very simple pattern. Even generate random words in English or Spanish.
 Also, you can validate if a text fulfills a specific pattern or even generate a string following a pattern and returning the wrong length, value... for testing your applications. Perfect to be used in test data factories.
@@ -313,12 +318,9 @@ Examples:
 
 If you need to validate if a specific text is fulfilling the pattern you can use the validate method.
 
-If a string pattern supplied and no other parameters supplied the output will be an array with the errors detected. 
-
+When you supply a single pattern and do **not** supply `expected_errors` or `not_expected_errors`, the method returns an **array of error symbols**: an empty array `[]` when the text is valid, or one or more of `:min_length`, `:max_length`, `:length`, `:value`, `:string_set_not_allowed`, `:required_data`, `:excluded_data` when invalid.
 
-Possible output values, empty array (validation without errors detected) or one or more of: :min_length, :max_length, :length, :value, :string_set_not_allowed, :required_data, :excluded_data
-
-In case an array of patterns supplied it will return only true or false
+When an array of patterns is supplied, the method returns only `true` or `false`.
 
 Examples:
 
@@ -438,6 +440,114 @@ StringPattern.block_list_enabled = true
 "2-20:Tn".gen #>AAñ34Ef99éNOP
 ```
 
+#### StringPattern.analyze
+
+To inspect how a pattern is parsed without generating or validating:
+
+```ruby
+p = StringPattern.analyze("10-20:LN/x/")
+# => #<Struct min_length=10, max_length=20, symbol_type="LN/x/", required_data=..., string_set=..., unique=false>
+p.min_length   # => 10
+p.max_length   # => 20
+p.symbol_type  # => "LN/x/"
+```
+
+Useful for debugging or building tools on top of the pattern DSL. Invalid patterns return the pattern string; use `silent: true` to avoid logging.
+
+#### Error handling and logging
+
+By default, when generation is impossible (e.g. invalid pattern or `dont_repeat` exhausted), `generate` returns an empty string `""` and a message is printed. You can:
+
+- Set `StringPattern.logger = Logger.new($stderr)` to send messages to a logger instead of `puts`.
+- Set `StringPattern.raise_on_error = true` to raise `StringPattern::GenerationImpossibleError` or `StringPattern::InvalidPatternError` instead of returning `""`.
+
+#### Reproducible generation (seed)
+
+Pass `seed:` to get the same string for the same pattern in tests:
+
+```ruby
+"10:N".gen(seed: 42)  # => same result every time
+```
+
+#### Batch generation (sample)
+
+Generate up to `n` distinct strings without mutating the global dont_repeat cache:
+
+```ruby
+StringPattern.sample("4:N", 10)  # => array of 10 distinct 4-digit strings
+```
+
+#### Boolean validation (valid?)
+
+Check if text matches a pattern without building the full error list:
+
+```ruby
+StringPattern.valid?(text: "user@domain.com", pattern: "14-40:@")  # => true
+```
+
+#### UUID
+
+Generate a random UUID v4 or validate one:
+
+```ruby
+StringPattern.uuid                    # => "550e8400-e29b-41d4-a716-446655440000"
+StringPattern.valid_uuid?(some_str)   # => true or false
+```
+
+#### block_list as Proc
+
+You can set `block_list` to a Proc for custom blocking:
+
+```ruby
+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
@@ -106,7 +113,7 @@ class Regexp
         elsif token == :literal and text.size == 2
           text = text[1]
         else
-          puts "Report token not controlled: type: #{type}, token: #{token}, text: '#{text}' [#{ts}..#{te}]"
+          StringPattern.log_message("Report token not controlled: type: #{type}, token: #{token}, text: '#{text}' [#{ts}..#{te}]")
         end
       end
 
@@ -165,7 +172,7 @@ class Regexp
               set_negate = false
             else
               pats += "]"
-            end    
+            end
 
           end
         elsif type == :group
@@ -190,7 +197,6 @@ class Regexp
             patg << pats
             pats = ""
           elsif patg.empty?
-            # for the case the first element was not added to patg and was on pata fex: (a+|b|c)
             patg << pata.pop
           end
         end
@@ -299,11 +305,11 @@ class Regexp
     end
     if pats != ""
       if pata.empty?
-        if pats[0] == "[" and pats[-1] == "]" #fex: /[12ab]/
+        if pats[0] == "[" and pats[-1] == "]"
           pata = ["1:#{pats}"]
         end
       else
-        pata[-1] += pats[1] #fex: /allo/
+        pata[-1] += pats[1]
       end
     end
     if pata.size == 1 and pata[0].kind_of?(String)
@@ -325,7 +331,7 @@ module Kernel
     if pattern.is_a?(String) || pattern.is_a?(Array) || pattern.is_a?(Symbol) || pattern.is_a?(Regexp)
       StringPattern.generate(pattern, expected_errors: expected_errors, **synonyms)
     else
-      puts " Kernel generate method: class not recognized:#{pattern.class}"
+      StringPattern.log_message(" Kernel generate method: class not recognized:#{pattern.class}")
     end
   end
 

data/lib/string/pattern/analyze.rb

@@ -1,8 +1,8 @@
 class StringPattern
-  ###############################################
-  # Analyze the pattern supplied and returns an object of Pattern structure including:
-  # min_length, max_length, symbol_type, required_data, excluded_data, data_provided, string_set, all_characters_set
-  ###############################################
+  # Analyzes a pattern string and returns a Pattern struct.
+  # @param pattern [String, Symbol] Pattern in format "length:type" or "min-max:type" (e.g. "10:N", "5-15:L")
+  # @param silent [Boolean] If true, invalid patterns do not log a message.
+  # @return [Struct, String] Pattern struct with min_length, max_length, symbol_type, required_data, excluded_data, data_provided, string_set, all_characters_set, unique; or the pattern string if invalid.
   def StringPattern.analyze(pattern, silent: false)
     #unless @cache[pattern.to_s].nil?
     #  return Pattern.new(@cache[pattern.to_s].min_length.clone, @cache[pattern.to_s].max_length.clone,
@@ -16,7 +16,7 @@ class StringPattern
       min_length, symbol_type = pattern.to_s.scan(/^!?(\d+):(.+)/)[0]
       max_length = min_length
       if min_length.nil?
-        puts "pattern argument not valid on StringPattern.generate: #{pattern.inspect}" unless silent
+        StringPattern.log_message("pattern argument not valid on StringPattern.generate: #{pattern.inspect}") unless silent
         return pattern.to_s
       end
     end

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/email.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class StringPattern
+  # Validates email format using the same rules as pattern type @:
+  # - Forbids consecutive/adjacent invalid sequences (.. __ -- etc.)
+  # - Local part: [a-z0-9]+([\+\._\-][a-z0-9])*
+  # - Domain part: [0-9a-z]+([\.-][a-z0-9])*
+  def self.valid_email?(string)
+    return false if string.nil? || !string.is_a?(String)
+    return false if string.index("@").to_i <= 0
+
+    wrong = %w(.. __ -- ._ _. .- -. _- -_ @. @_ @- .@ _@ -@ @@)
+    return false if Regexp.union(*wrong) === string
+
+    local = string[0..(string.index("@") - 1)]
+    domain = string[(string.index("@") + 1)..-1]
+    local_ok = local.scan(/([a-z0-9]+([\+\._\-][a-z0-9]|)*)/i).join == local
+    domain_ok = domain.scan(/([0-9a-z]+([\.-][a-z0-9]|)*)/i).join == domain
+    local_ok && domain_ok
+  end
+end