string_pattern 2.2.3 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c451e4295f5c62ea8b7c8113815a0c7a2b5c70a739826fdf651a7fb99a75be48
-  data.tar.gz: 2445e4958a2bf96b70e0ce99f4df31ab02a61183a496289a1b20b3360e2fecaf
+  metadata.gz: 47172de723c22b8175a1119aa51c065056ec4eab029cfb989b4fa4c9bc20d845
+  data.tar.gz: c9e9996c3f5ec59813b157a9f818c10723fb1b9f95a1ed871ba80219d04bbe6e
 SHA512:
-  metadata.gz: 650a16f6a2cda5c762f2f685b4fe515848135a6c4995ba08504ec80435696d4e1ab6289adaf4aae839ca0d77978338d2603411a7330fe2db0f2bede587554cfd
-  data.tar.gz: 996deb9300188c286dc0a051f744262367f928192e5c30fcd981f7f964283463f2dc606c4876163378397b767ed235f51bc749bac55e801866810aa19318da91
+  metadata.gz: 840a84447c523a01e21657fa772c190388a1401e41d254e5340fe9bd081eb0740ba200161c0a29e06dcfa841632c26d51346da53bf2c5a8f93ad3459aa455930
+  data.tar.gz: f53b2b1ef110f8e20b95e7e5bafac00067bbc782e2817fa3292cbd4b60492454b171133b80b8808e737606c83dd8f2df59d5d57447bcc5cc225d6239c0edb7e3

data/README.md

@@ -3,6 +3,11 @@
 [![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)
 [![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. 
-
-
-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
+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.
 
-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:
 
@@ -428,6 +430,80 @@ StringPattern.optimistic = true
 #>SAAERfixedtext988
 ```
 
+#### block_list
+
+To specify which words will be avoided from the results
+
+```ruby
+StringPattern.block_list = ['example', 'wrong', 'ugly']
+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
+```
+
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/marioruiz/string_pattern.

data/lib/string/pattern/add_to_ruby.rb

@@ -90,11 +90,14 @@ class Regexp
     pats = ""
     patg = [] # for (aa|bb|cc) group
     set = false
+    set_negate = false
+    options = []
     capture = false
 
     range = ""
     fixed_text = false
-    last_char = (regexp.to_s.gsub("?-mix:", "").length) - 2
+    options = regexp.to_s.scan(/\A\(\?([mix]*)\-[mix]*:/).join.split('')
+    last_char = (regexp.to_s.gsub(/\A\(\?[mix]*\-[mix]*:/, "").length) - 2
     Regexp::Scanner.scan regexp do |type, token, text, ts, te|
       if type == :escape
         if token == :dot
@@ -103,7 +106,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
 
@@ -126,9 +129,9 @@ class Regexp
               pata[-1] += pats.chop
             else
               if pats.size == 2
-                pata << pats.chop #jal
+                pata << pats.chop
               else
-                pata << "1:[#{pats}" #jal
+                pata << "1:[#{pats}"
               end
               if last_char == te and type == :literal and token == :literal
                 pata << text
@@ -147,7 +150,6 @@ class Regexp
         pats = ""
       end
       fixed_text = false
-
       case token
       when :open
         set = true
@@ -158,7 +160,13 @@ class Regexp
           if pats[-1] == "["
             pats.chop!
           else
-            pats += "]"
+            if set_negate
+              pats+="%]*"
+              set_negate = false
+            else
+              pats += "]"
+            end
+
           end
         elsif type == :group
           capture = false
@@ -169,6 +177,11 @@ class Regexp
             pats = ""
           end
         end
+      when :negate
+        if set and pats[-1] == '['
+          pats+="%"
+          set_negate = true
+        end
       when :capture
         capture = true if type == :group
       when :alternation
@@ -177,11 +190,11 @@ 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
       when :range
+        pats.chop! if options.include?('i')
         range = pats[-1]
         pats.chop!
       when :digit
@@ -212,28 +225,44 @@ class Regexp
             pats = text[-1]
           else
             pats += text
+            pats += text.upcase if options.include?('i')
           end
         else
           range = range + "-" + text
           if range == "a-z"
-            pats = "x" + pats
+            if options.include?('i')
+              pats = "L" + pats
+            else
+              pats = "x" + pats
+            end
           elsif range == "A-Z"
-            pats = "X" + pats
+            if options.include?('i')
+              pats = "L" + pats
+            else
+              pats = "X" + pats
+            end
           elsif range == "0-9"
             pats = "n" + pats
           else
-            pats += if set
-                      (range[0]..range[2]).to_a.join
-                    else
-                      "[" + (range[0]..range[2]).to_a.join + "]"
-                    end
+            if set
+              pats += (range[0]..range[2]).to_a.join
+              if options.include?('i')
+                pats += (range[0]..range[2]).to_a.join.upcase
+              end
+            else
+              trange = (range[0]..range[2]).to_a.join
+              if options.include?('i')
+                trange += trange.upcase
+              end
+              pats += "[" + trange + "]"
+            end
           end
           range = ""
         end
         pats = "[" + pats + "]" unless set
       when :interval
         size = text.sub(",", "-").sub("{", "").sub("}", "")
-        size.chop! if size[-1] == "-"
+        size+=(default_infinite+size.chop.to_i).to_s if size[-1] == "-"
         pats = size + ":" + pats
         if !patg.empty?
           patg << pats
@@ -269,11 +298,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)
@@ -295,7 +324,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/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

data/lib/string/pattern/generate.rb

@@ -64,6 +64,8 @@ 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
     tries = 0
     begin
       good_result = true
@@ -95,7 +97,7 @@ class StringPattern
               string << pat
             end
           else
-            puts "StringPattern.generate: it seems you supplied wrong array of patterns: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
+            StringPattern.log_message("StringPattern.generate: it seems you supplied wrong array of patterns: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
             return ""
           end
         }
@@ -120,7 +122,7 @@ class StringPattern
           }
           unless excluded_data.size == 0
             if (required_chars.flatten & excluded_data.flatten).size > 0
-              puts "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.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 ""
             end
           end
@@ -130,7 +132,7 @@ class StringPattern
       elsif pattern.kind_of?(Regexp)
         return generate(pattern.to_sp, expected_errors: expected_errors)
       else
-        puts "pattern argument not valid on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
+        StringPattern.log_message("pattern argument not valid on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
         return pattern.to_s
       end
 
@@ -169,12 +171,12 @@ class StringPattern
 
       unless deny_pattern
         if required_data.size == 0 and expected_errors_left.include?(:required_data)
-          puts "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.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 ""
         end
 
         if excluded_data.size == 0 and expected_errors_left.include?(:excluded_data)
-          puts "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.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 ""
         end
 
@@ -182,7 +184,7 @@ class StringPattern
           string_set_not_allowed = all_characters_set - string_set
 
           if string_set_not_allowed.size == 0
-            puts "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.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 ""
           end
         end
@@ -205,7 +207,7 @@ class StringPattern
             expected_errors_left.delete(:length)
             expected_errors_left.delete(:min_length)
           else
-            puts "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.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 ""
           end
         elsif expected_errors_left.include?(:max_length) or expected_errors_left.include?(:length)
@@ -264,7 +266,7 @@ class StringPattern
             end
             if ((0...string.length).find_all { |i| string[i, 1] == rd_to_set }).size == 0
               if positions_to_set.size == 0
-                puts "pattern not valid on StringPattern.generate, not possible to generate a valid string: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
+                StringPattern.log_message("pattern not valid on StringPattern.generate, not possible to generate a valid string: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
                 return ""
               else
                 k = positions_to_set.sample
@@ -289,7 +291,7 @@ 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
-            puts "Not possible to generate a non valid string on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
+            StringPattern.log_message("Not possible to generate a non valid string on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}")
             return ""
           end
           (rand(string.size) + 1).times {
@@ -502,24 +504,11 @@ class StringPattern
             expected_errors_left.delete(:string_set_not_allowed)
           end
 
-          error_regular_expression = false
+          error_regular_expression = !StringPattern.valid_email?(string)
 
           if deny_pattern and expected_errors.include?(:length)
             good_result = true #it is already with wrong length
           else
-            # I'm doing this because many times the regular expression checking hangs with these characters
-            wrong = %w(.. __ -- ._ _. .- -. _- -_ @. @_ @- .@ _@ -@ @@)
-            if !(Regexp.union(*wrong) === string) #don't include any or the wrong strings
-              if string.index("@").to_i > 0 and
-                 string[0..(string.index("@") - 1)].scan(/([a-z0-9]+([\+\._\-][a-z0-9]|)*)/i).join == string[0..(string.index("@") - 1)] and
-                 string[(string.index("@") + 1)..-1].scan(/([0-9a-z]+([\.-][a-z0-9]|)*)/i).join == string[string[(string.index("@") + 1)..-1]]
-                error_regular_expression = false
-              else
-                error_regular_expression = true
-              end
-            else
-              error_regular_expression = true
-            end
 
             if expected_errors.size == 0
               if error_regular_expression
@@ -540,7 +529,9 @@ class StringPattern
           end
         end until good_result or tries > 100
         unless good_result
-          puts "Not possible to generate an email on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
+          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 ""
         end
       end
@@ -568,12 +559,28 @@ class StringPattern
           good_result = true
         end
       end
+      if @block_list_enabled
+        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
+            end
+          end
+        end
+      end
     end until good_result or tries > 10000
     unless good_result
-      puts "Not possible to generate the string on StringPattern.generate: #{pattern.inspect}, expected_errors: #{expected_errors.inspect}"
-      puts "Take 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"
+      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 ""
     end
     return string
+  ensure
+    srand(saved_rng) if saved_rng
   end
 end

data/lib/string/pattern/validate.rb

@@ -54,7 +54,7 @@ class StringPattern
           max_length = patt.max_length.clone
           symbol_type = patt.symbol_type.clone
         else
-          puts "String pattern class not supported (#{pat.class} for #{pat})"
+          StringPattern.log_message("String pattern class not supported (#{pat.class} for #{pat})")
           return false
         end
 
@@ -133,7 +133,7 @@ class StringPattern
         required_chars << rd if rd.size == 1
       }
       if (required_chars.flatten & excluded_data.flatten).size > 0
-        puts "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}"
+        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}")
         return ""
       end
     end
@@ -183,20 +183,7 @@ class StringPattern
           end
         }
       else #symbol_type=="@"
-        string = text_to_validate
-        wrong = %w(.. __ -- ._ _. .- -. _- -_ @. @_ @- .@ _@ -@ @@)
-        if !(Regexp.union(*wrong) === string) #don't include any or the wrong strings
-          if string.index("@").to_i > 0 and
-             string[0..(string.index("@") - 1)].scan(/([a-z0-9]+([\+\._\-][a-z0-9]|)*)/i).join == string[0..(string.index("@") - 1)] and
-             string[(string.index("@") + 1)..-1].scan(/([0-9a-z]+([\.-][a-z0-9]|)*)/i).join == string[string[(string.index("@") + 1)..-1]]
-            error_regular_expression = false
-          else
-            error_regular_expression = true
-          end
-        else
-          error_regular_expression = true
-        end
-
+        error_regular_expression = !StringPattern.valid_email?(text_to_validate)
         if error_regular_expression
           detected_errors.push(:value)
         end

data/lib/string_pattern.rb

@@ -1,6 +1,7 @@
 SP_ADD_TO_RUBY = true if !defined?(SP_ADD_TO_RUBY)
 require_relative "string/pattern/add_to_ruby" if SP_ADD_TO_RUBY
 require_relative "string/pattern/analyze"
+require_relative "string/pattern/email"
 require_relative "string/pattern/generate"
 require_relative "string/pattern/validate"
 
@@ -25,9 +26,27 @@ require_relative "string/pattern/validate"
 #             In case using regular expressions the maximum when using * or + for repetitions
 # word_separator: (String, default: '_')
 #             When generating words using symbol types 'w' or 'p' the character to separate the english or spanish words.
+# block_list: (Array, default: empty)
+#             Array of words to be avoided from resultant strings.
+# block_list_enabled: (TrueFalse, default: false)
+#             If true block_list will be take in consideration
+#
+# @example Generate a string
+#   StringPattern.generate("10:N")  # => "3448910834"
+# @example Validate and get errors
+#   StringPattern.validate(text: "ab", pattern: "6:N")  # => [:min_length, :length]
 class StringPattern
+  # Raised when an invalid pattern is used and {raise_on_error} is true.
+  InvalidPatternError = Class.new(StandardError)
+  # Raised when generation is impossible (e.g. exhausted by dont_repeat) and {raise_on_error} is true.
+  GenerationImpossibleError = Class.new(StandardError)
+
   class << self
-    attr_accessor :national_chars, :optimistic, :dont_repeat, :cache, :cache_values, :default_infinite, :word_separator
+    # @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
   end
   @national_chars = (("a".."z").to_a + ("A".."Z").to_a).join
   @optimistic = true
@@ -36,6 +55,10 @@ class StringPattern
   @dont_repeat = false
   @default_infinite = 10
   @word_separator = "_"
+  @block_list_enabled = false
+  @block_list = []
+  @logger = nil
+  @raise_on_error = false
   NUMBER_SET = ("0".."9").to_a
   SPECIAL_SET = [" ", "~", "!", "@", "#", "$", "%", "^", "&", "*", "(", ")", "-", "_", "+", "=", "{", "}", "[", "]", "'", ";", ":", "?", ">", "<", "`", "|", "/", '"']
   ALPHA_SET_LOWER = ("a".."z").to_a
@@ -56,4 +79,61 @@ class StringPattern
     @cache = Hash.new()
     @national_chars = par
   end
+
+  def self.log_message(message)
+    if @logger
+      @logger.warn(message)
+    else
+      puts message
+    end
+  end
+
+  # Returns true if +text+ matches +pattern+; false otherwise. Uses validate under the hood.
+  # @param text [String] (synonyms: text_to_validate, validate)
+  # @param pattern [String, Symbol, Array]
+  # @return [Boolean]
+  def self.valid?(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)
+    return false if text.nil? || pattern.nil?
+    result = validate(text: text, pattern: pattern, **synonyms)
+    pattern.is_a?(Array) ? result == true : result.is_a?(Array) && result.empty?
+  end
+
+  # Generates up to +n+ distinct strings for +pattern+. Uses a temporary dont_repeat state.
+  # @param pattern [String, Symbol, Array, Regexp]
+  # @param n [Integer]
+  # @return [Array<String>]
+  def self.sample(pattern, n)
+    return [] if n <= 0
+    old_dont = @dont_repeat
+    old_cache = @cache_values.dup
+    @dont_repeat = true
+    @cache_values = {}
+    results = []
+    n.times do
+      s = generate(pattern)
+      break if s.nil? || s.empty?
+      results << s
+    end
+    results
+  ensure
+    @dont_repeat = old_dont
+    @cache_values = old_cache
+  end
+
+  # Generates a random UUID v4 (e.g. "550e8400-e29b-41d4-a716-446655440000").
+  # @return [String]
+  def self.uuid
+    require "securerandom"
+    SecureRandom.uuid
+  end
+
+  # Returns true if +str+ is a valid UUID v4 format (8-4-4-4-12 hex with version and variant bits).
+  # @param str [String]
+  # @return [Boolean]
+  def self.valid_uuid?(str)
+    return false unless str.is_a?(String)
+    str.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i)
+  end
 end

metadata

@@ -1,35 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: string_pattern
 version: !ruby/object:Gem::Version
-  version: 2.2.3
+  version: 2.4.0
 platform: ruby
 authors:
 - Mario Ruiz
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-14 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: regexp_parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.0
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.0
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
 description: 'Easily generate strings supplying a very simple pattern. ''10-20:Xn/x/''.generate
   #>qBstvc6JN8ra. Generate random strings using a regular expression (Regexp): /[a-z0-9]{2,5}w+/.gen
   . Also generate words in English or Spanish. Perfect to be used in test data factories.
@@ -61,6 +61,7 @@ files:
 - data/spanish/palabras9.json
 - lib/string/pattern/add_to_ruby.rb
 - lib/string/pattern/analyze.rb
+- lib/string/pattern/email.rb
 - lib/string/pattern/generate.rb
 - lib/string/pattern/validate.rb
 - lib/string_pattern.rb
@@ -68,7 +69,7 @@ homepage: https://github.com/MarioRuiz/string_pattern
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -83,8 +84,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 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.