nice_hash 1.19.0 → 1.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eae7fae66c4ee14c40481157a8cd6e90ec43781b092779a3344c36a7d0d6308
-  data.tar.gz: f3071e0977d3e7e0f0e7ced9699f4823535c1daaa880cbfd7d5693d8329e9513
+  metadata.gz: ab97a22d06c02e9a17c33221c77ff01c841405e0b3a15711ecb465bbf91eb23c
+  data.tar.gz: c358cab3956cd0f4dd90020ad68da0039f42786892d71f3803a2dcbc8be87f6b
 SHA512:
-  metadata.gz: 72ced814e688ca65212c8812969947ce77f0496c2e7dbc12e2ab9ef9c396db77da473e5c079788206c6fcc24e05d92b1186c85bfe986c634e75e3b7894208b5a
-  data.tar.gz: bce43cdcaa33a6e50a06a364737e3a723156e052b34ba3423574dc4f296743f47c7b089723f72ba2ad617ece70f3ec129617dcf500fc6c5d5cddd8cf8f7bba27
+  metadata.gz: a4c876a1bd17ee4bf3a845dedb57aee727e73e9173a1145a103ce2da75daeec422c768a8bc3ba82c051734221079e184925c1b432f8d6be4bc240b4e43d2854d
+  data.tar.gz: 074570bccde6d2a926286817b13f935be05e34fbc57835a761bfe745c7474be1bd5585a5fef812cfb36d03d64c03e315d08fc6dd4ca2ad65d1afb84b14c80fe3

data/README.md

@@ -1,7 +1,7 @@
 # NiceHash
 
 [![Gem Version](https://badge.fury.io/rb/nice_hash.svg)](https://rubygems.org/gems/nice_hash)
-[![Build Status](https://travis-ci.com/MarioRuiz/nice_hash.svg?branch=master)](https://github.com/MarioRuiz/nice_hash)
+[![CI](https://github.com/MarioRuiz/nice_hash/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/MarioRuiz/nice_hash/actions/workflows/ci.yml)
 [![Coverage Status](https://coveralls.io/repos/github/MarioRuiz/nice_hash/badge.svg?branch=master)](https://coveralls.io/github/MarioRuiz/nice_hash?branch=master)
 ![Gem](https://img.shields.io/gem/dt/nice_hash)
 ![GitHub commit activity](https://img.shields.io/github/commit-activity/y/MarioRuiz/nice_hash)
@@ -79,6 +79,12 @@ Set these constants **before** `require 'nice_hash'` if you need to change defau
 
 When using **string_pattern** 2.4+, you can also set **`StringPattern.logger`** (e.g. `Logger.new($stderr)`) to redirect generation/validation messages, and **`StringPattern.raise_on_error = true`** to raise on invalid patterns or impossible generation instead of returning empty strings.
 
+**Upgrading to 1.20** (requires string_pattern 2.5):
+
+- Update assertions that pin a value produced with `seed:` in 1.19. The same seed now walks one sequence for patterns, ranges, booleans and selectors, so those strings change. Do not expect `:uuid`, `:iban` or `:luhn` to repeat from `seed:`.
+- If `StringPattern.block_list` contains regular expressions, set `StringPattern.block_list_regexp = true`. Otherwise each entry is a literal.
+- A `Regexp` pattern must match the whole value. Update fixtures that used to pass because `$` matched before a newline.
+
 Example:
 
 ```ruby
@@ -90,13 +96,25 @@ require 'nice_hash'
 
 Remember!! To generate the strings following a pattern take a look at the documentation for string_pattern gem: https://github.com/MarioRuiz/string_pattern. You can also generate Spanish or English words. We added support for generating strings from regular expressions but it is only working for the ´generate´ method, use it with caution since it is still on an early stage of development.
 
-For **UUID v4** you can use the shorthand `:uuid` (requires string_pattern 2.4+):
+For **UUID v4**, **email**, **IBAN** and a **Luhn** number you can use these shorthands (string_pattern 2.4+ for `:uuid`, 2.5+ for the others):
 
 ```ruby
-my_hash = { id: :uuid, key: "Wsdf88888", doomId: :"10:N" }
-# id will be like "550e8400-e29b-41d4-a716-446655440000"
+my_hash = { id: :uuid, email: :email, iban: :iban, card: :luhn, doomId: :"10:N" }
+# id:    "550e8400-e29b-41d4-a716-446655440000"
+# email: a generated address
+# iban:  a Spanish IBAN
+# card:  16 digits with a valid Luhn checksum
+
+my_hash = { iban: [:iban, "DE"], card: [:luhn, 15], tags: [:"3:L"] }
+# iban:  a German IBAN. Countries: ES, DE, FR, GB, PT, IT, NL, BE
+# card:  15 digits with a valid Luhn checksum
+# tags:  1 to 5 different strings from that pattern
 ```
 
+`:iban` still generates a Spanish IBAN, and validating `:iban` accepts any well-formed IBAN. `[:iban, "DE"]` generates and requires that country. `:luhn` is 16 digits; `[:luhn, 15]` sets the length.
+
+`:uuid`, `:iban` and `:luhn` use their own random generator. `seed:` does not make those three fields repeat. A one-element pattern array does follow `seed:`.
+
 Or use a Regular expression for custom formats:
 
 ```ruby
@@ -403,7 +421,7 @@ new_hash = my_hash.select_key(:correct).generate
 ```
 
 **Reproducible generation (seed)**  
-With **string_pattern** 2.4+, pass `seed:` to get the same hash every time (useful for tests):
+Pass `seed:` to get the same hash every time, including string patterns, ranges, booleans and selectors. One seed advances through the whole hash, so two fields with the same pattern get different values. `:uuid`, `:iban` and `:luhn` stay outside that sequence.
 
 ```ruby
 new_hash = my_hash.generate(:correct, seed: 42)
@@ -417,7 +435,7 @@ Use `generate_n` (alias `gen_n`) to build several different hashes in one call (
 hashes = NiceHash.generate_n(my_hash, 5, :correct)
 hashes = my_hash.generate_n(5, :correct)   # or my_hash.gen_n(5, :correct)
 # With seed: hashes = my_hash.generate_n(5, :correct, seed: 123)
-# => array of 5 hashes
+# the same seed yields the same 5 hashes, and they differ from each other
 ```
 
 In case of filtering by :correct new_hash would have a value like this for example:
@@ -731,6 +749,13 @@ The possible validation values returned:
     :excluded_data: the resultant string will include one or more characters that should be excluded. It works only if excluded data supplied on the pattern.
     :string_set_not_allowed: it will include one or more characters that are not supposed to be on the string.
 
+Pass `explain: true` to get a short description instead of `false` or the error list:
+
+```ruby
+{ name: :"6:N" }.validate({ name: "ab" }, explain: true)
+#=> { name: { valid: false, errors: [:min_length, :length, :value, :string_set_not_allowed], message: "invalid: min_length, length, value, string_set_not_allowed", index: nil } }
+```
+
 You can also supply nested pattern keys for the patterns to be more specific: `{'draws.drawId': :"4:N"}`
 
 ### Change only one value at a time and return an Array of Hashes
@@ -887,6 +912,9 @@ Valid patterns:
 - DateTime: it will verify if the value is following Time stamp string '2019-06-20T12:01:09.971Z' or if the object is a Time, Date or DateTime class
 - selectors, one of the values. Example: "uno|dos|tres"
 - **:uuid** (string_pattern 2.4+): UUID v4 format
+- **:email** (string_pattern 2.5+): email address
+- **:iban** (string_pattern 2.5+): any IBAN. `[:iban, "DE"]` requires that country
+- **:luhn** (string_pattern 2.5+): Luhn checksum. `:luhn` is 16 digits; `[:luhn, 15]` sets the length
 
 ### Other useful methods
 

data/lib/nice/hash/add_to_ruby.rb

@@ -253,16 +253,16 @@ class Hash
   # More info: NiceHash.validate
   # alias: val
   ###########################################################################
-  def validate(select_hash_key = nil, values_hash_to_validate)
-    NiceHash.validate([self, select_hash_key], values_hash_to_validate, only_patterns: false)
+  def validate(select_hash_key = nil, values_hash_to_validate, explain: false)
+    NiceHash.validate([self, select_hash_key], values_hash_to_validate, only_patterns: false, explain: explain)
   end
 
   ###########################################################################
   # Validates a given values_hash_to_validate with string patterns
   # More info: NiceHash.validate
   ###########################################################################
-  def validate_patterns(select_hash_key = nil, values_hash_to_validate)
-    NiceHash.validate([self, select_hash_key], values_hash_to_validate, only_patterns: true)
+  def validate_patterns(select_hash_key = nil, values_hash_to_validate, explain: false)
+    NiceHash.validate([self, select_hash_key], values_hash_to_validate, only_patterns: true, explain: explain)
   end
 
   ###########################################################################

data/lib/nice/hash/generate.rb

@@ -51,14 +51,26 @@ class NiceHash
   #   new_hash = my_hash.gen(:correct)
   #   new_hash = my_hash.generate(:correct, errors: [:min_length])
   ###########################################################################
+  # One RNG for the whole hash. string_pattern 2.5 no longer seeds Kernel#rand,
+  # so passing seed: on every StringPattern.generate call would restart the sequence.
+  def self.generation_rng(synonyms)
+    rng = synonyms.delete(:_rng)
+    return rng unless rng.nil?
+
+    seed = synonyms.delete(:seed)
+    base = seed.nil? ? Random.new : Random.new(seed)
+    StringPattern::RandomSource.new(base)
+  end
+
   def NiceHash.generate(pattern_hash, select_hash_key = nil, expected_errors: [], **synonyms)
     hashv = Hash.new()
     same_values = Hash.new()
-    expected_errors = synonyms[:errors] if synonyms.keys.include?(:errors)
+    expected_errors = synonyms.delete(:errors) if synonyms.key?(:errors)
     if expected_errors.kind_of?(Symbol)
       expected_errors = [expected_errors]
     end
-    sp_opts = { expected_errors: expected_errors }.merge(synonyms)
+    rng = generation_rng(synonyms)
+    sp_opts = { expected_errors: expected_errors, _rng: rng }.merge(synonyms)
 
     if pattern_hash.kind_of?(Hash) and pattern_hash.size > 0
       pattern_hash.each { |key, value|
@@ -71,16 +83,22 @@ class NiceHash
           if value.keys.include?(select_hash_key)
             value = value[select_hash_key]
           else
-            value = NiceHash.generate(value, select_hash_key, expected_errors: expected_errors, **synonyms)
+            value = NiceHash.generate(value, select_hash_key, expected_errors: expected_errors, _rng: rng, **synonyms)
           end
         end
         if value == :uuid
+          # SecureRandom is not seeded. UUID values are not reproducible via seed:.
           hashv[key] = expected_errors.empty? ? StringPattern.uuid : (StringPattern.uuid[0..-2] + "X")
+        elsif value == :email
+          hashv[key] = StringPattern.generate("20-40:@", **sp_opts)
+        elsif (spec = checksum_spec(value))
+          # StringPattern.iban and StringPattern.luhn use their own Random, so they are not reproducible via seed:.
+          hashv[key] = generated_checksum(spec, expected_errors)
         elsif value.kind_of?(String) or value.kind_of?(Symbol)
           if ((StringPattern.optimistic and value.kind_of?(String)) or value.kind_of?(Symbol)) and value.to_s.scan(/^!?\d+-?\d*:.+/).size > 0
             hashv[key] = StringPattern.generate(value, **sp_opts)
           elsif ((StringPattern.optimistic and value.kind_of?(String)) or value.kind_of?(Symbol)) and value.to_s.scan(/^([\w\s\-]+\|)+[\w\s\-]+$/).size > 0
-            if expected_errors.include?(:min_length) or (expected_errors.include?(:length) and rand.round == 0)
+            if expected_errors.include?(:min_length) or (expected_errors.include?(:length) and rng.rand.round == 0)
               min = value.to_s.split("|").min { |a, b| a.size <=> b.size }
               hashv[key] = min[0..-2] unless min == ""
             end
@@ -94,7 +112,7 @@ class NiceHash
               if hashv.keys.include?(key)
                 v = hashv[key]
               else
-                v = value.to_s.split("|").sample
+                v = value.to_s.split("|").sample(random: rng)
               end
               unless expected_errors.include?(:string_set_not_allowed)
                 v = StringPattern.generate(:"#{v.size}:[#{value.to_s.split("|").join.split(//).uniq.join}]", **sp_opts)
@@ -102,13 +120,13 @@ class NiceHash
               end
               unless hashv.keys.include?(key)
                 # Need a valid 1-char not in the allowed set (do not pass expected_errors)
-                one_wrong_letter = StringPattern.generate(:"1:LN$[%#{value.to_s.split("|").join.split(//).uniq.join}%]")
-                v[rand(v.size)] = one_wrong_letter
+                one_wrong_letter = StringPattern.generate(:"1:LN$[%#{value.to_s.split("|").join.split(//).uniq.join}%]", _rng: rng)
+                v[rng.rand(v.size)] = one_wrong_letter
                 hashv[key] = v unless value.to_s.split("|").include?(v)
               end
             end
             unless hashv.keys.include?(key)
-              hashv[key] = value.to_s.split("|").sample
+              hashv[key] = value.to_s.split("|").sample(random: rng)
             end
           else
             hashv[key] = value
@@ -118,9 +136,11 @@ class NiceHash
           if value.size == 1
             v = value[0]
             if (v.kind_of?(String) or v.kind_of?(Symbol)) and StringPattern.analyze(v, silent: true).kind_of?(StringPattern::Pattern)
-              hashv[key] = []
-              (rand(5)+1).times do
-                hashv[key]<<StringPattern.generate(v, **sp_opts)
+              count = rng.rand(5) + 1
+              hashv[key] = if expected_errors.empty?
+                distinct_strings(v, count, sp_opts)
+              else
+                count.times.map { StringPattern.generate(v, **sp_opts) }
               end
               array_pattern = true
             end
@@ -137,9 +157,9 @@ class NiceHash
             value_ret = Array.new
             value.each { |v|
               if v.is_a?(Hash)
-                ret = NiceHash.generate(v, select_hash_key, expected_errors: expected_errors, **synonyms)
+                ret = NiceHash.generate(v, select_hash_key, expected_errors: expected_errors, _rng: rng, **synonyms)
               else
-                ret = NiceHash.generate({ doit: v }, select_hash_key, expected_errors: expected_errors, **synonyms)
+                ret = NiceHash.generate({ doit: v }, select_hash_key, expected_errors: expected_errors, _rng: rng, **synonyms)
                 ret = ret[:doit] if ret.is_a?(Hash) and ret.key?(:doit)
               end
               ret = v if ret.kind_of?(Hash) and ret.size == 0
@@ -152,28 +172,28 @@ class NiceHash
             if value.size == Float::INFINITY
               value = (value.min..2**64)
             end
-            hashv[key] = rand(value)
+            hashv[key] = rng.rand(value)
           else
             if value.size == Float::INFINITY
               infinite = true
               value = (value.min..2**64)
             else
               infinite = false
-              hashv[key] = rand(value)
+              hashv[key] = rng.rand(value)
             end
             expected_errors.each do |er|
               if er == :min_length
-                hashv[key] = rand((value.first - value.last)..value.first - 1)
+                hashv[key] = rng.rand((value.first - value.last)..value.first - 1)
               elsif er == :max_length and !infinite
-                hashv[key] = rand((value.last + 1)..(value.last * 2))
+                hashv[key] = rng.rand((value.last + 1)..(value.last * 2))
               elsif er == :length
-                if rand.round == 1 or infinite
-                  hashv[key] = rand((value.first - value.last)..value.first - 1)
+                if rng.rand.round == 1 or infinite
+                  hashv[key] = rng.rand((value.first - value.last)..value.first - 1)
                 else
-                  hashv[key] = rand((value.last + 1)..(value.last * 2))
+                  hashv[key] = rng.rand((value.last + 1)..(value.last * 2))
                 end
               elsif er == :value
-                hashv[key] = :"1-10:N/L/".gen
+                hashv[key] = StringPattern.generate(:"1-10:N/L/", _rng: rng)
               end
             end
           end
@@ -188,24 +208,24 @@ class NiceHash
               elsif er == :max_length
                 hashv[key] = hashv[key] + "Z"
               elsif er == :length
-                if rand.round == 1
+                if rng.rand.round == 1
                   hashv[key] = hashv[key].chop
                 else
                   hashv[key] = hashv[key] + "Z"
                 end
               elsif er == :value
-                hashv[key][rand(hashv[key].size - 1)] = "1:L".gen
+                hashv[key][rng.rand(hashv[key].size - 1)] = StringPattern.generate("1:L", _rng: rng)
               end
             end
           end
         elsif value.kind_of?(Module) and value == Boolean
           if expected_errors.empty?
-            hashv[key] = (rand.round == 0)
+            hashv[key] = (rng.rand.round == 0)
           else
-            hashv[key] = (rand.round == 0)
+            hashv[key] = (rng.rand.round == 0)
             expected_errors.each do |er|
               if er == :value
-                hashv[key] = "1-10:L".gen
+                hashv[key] = StringPattern.generate("1-10:L", _rng: rng)
               end
             end
           end
@@ -243,6 +263,75 @@ class NiceHash
   #   hashes = my_hash.generate_n(5, :correct)
   ###########################################################################
   def NiceHash.generate_n(pattern_hash, n, select_hash_key = nil, expected_errors: [], **synonyms)
-    n.times.map { NiceHash.generate(pattern_hash, select_hash_key, expected_errors: expected_errors, **synonyms) }
+    rng = generation_rng(synonyms)
+    n.times.map { NiceHash.generate(pattern_hash, select_hash_key, expected_errors: expected_errors, _rng: rng, **synonyms) }
+  end
+
+  # :iban and :luhn, or [:iban, country] and [:luhn, length].
+  # Country nil means "generate ES, accept any IBAN on validate".
+  def self.checksum_spec(value)
+    case value
+    when :iban
+      [:iban, nil]
+    when :luhn
+      [:luhn, 16]
+    when Array
+      return nil unless (1..2).cover?(value.size)
+
+      case value[0]
+      when :iban
+        return [:iban, nil] if value[1].nil?
+
+        country = value[1].to_s.strip.upcase
+        raise ArgumentError, "unknown IBAN country: #{country.inspect}" unless StringPattern::IBAN_LENGTHS.key?(country)
+
+        [:iban, country]
+      when :luhn
+        length = value[1].nil? ? 16 : Integer(value[1])
+        raise ArgumentError, "Luhn length must be >= 2" if length < 2
+
+        [:luhn, length]
+      end
+    end
   end
+
+  def self.generated_checksum(spec, expected_errors)
+    kind, arg = spec
+    if kind == :iban
+      country = arg || "ES"
+      return StringPattern.iban(country: country) if expected_errors.empty?
+
+      "#{country}00NOTANIBAN"
+    elsif expected_errors.empty?
+      StringPattern.luhn(length: arg)
+    else
+      invalid_luhn(arg)
+    end
+  end
+
+  def self.invalid_luhn(length)
+    good = StringPattern.luhn(length: length)
+    digit = good[-1] == "0" ? "1" : "0"
+    good[0..-2] + digit
+  end
+
+  # Distinct values from one pattern, drawing from the shared RNG.
+  # Stops once the pattern cannot yield another new string.
+  def self.distinct_strings(pattern, count, sp_opts)
+    results = []
+    seen = {}
+    attempts = 0
+    while results.size < count && attempts < count * 20
+      attempts += 1
+      generated = StringPattern.generate(pattern, **sp_opts)
+      break if generated.nil? || generated.empty?
+      next if seen[generated]
+
+      seen[generated] = true
+      results << generated
+    end
+    results
+  end
+
+  private_class_method :generation_rng, :checksum_spec, :generated_checksum, :invalid_luhn, :distinct_strings
 end

data/lib/nice/hash/validate.rb

@@ -45,8 +45,10 @@ class NiceHash
   #
   #   results = my_hash.validate_patterns(:correct, values_to_validate)
   #   results = my_hash.validate(:correct, values_to_validate)
+  #   results = my_hash.validate(values_to_validate, explain: true)
+  # explain: true replaces false or an error list with { valid:, errors:, message:, index: }.
   ###########################################################################
-  def NiceHash.validate(patterns_hash, values_hash_to_validate, only_patterns: true)
+  def NiceHash.validate(patterns_hash, values_hash_to_validate, only_patterns: true, explain: false)
     if patterns_hash.kind_of?(Array)
       pattern_hash = patterns_hash[0]
       select_hash_key = patterns_hash[1]
@@ -76,7 +78,7 @@ class NiceHash
           if !select_hash_key.nil? and value.keys.include?(select_hash_key)
             value = value[select_hash_key]
           elsif values.keys.include?(key) and values[key].kind_of?(Hash)
-            res = NiceHash.validate([value, select_hash_key], values[key], only_patterns: only_patterns)
+            res = NiceHash.validate([value, select_hash_key], values[key], only_patterns: only_patterns, explain: explain)
             results[key] = res if res.size > 0
             next
           end
@@ -85,6 +87,10 @@ class NiceHash
         if values.keys.include?(key)
           if value == :uuid
             results[key] = false unless StringPattern.valid_uuid?(values[key].to_s)
+          elsif value == :email
+            results[key] = false unless StringPattern.valid_email?(values[key].to_s)
+          elsif (spec = checksum_spec(value))
+            results[key] = false if checksum_problem(spec, values[key])
           elsif value.kind_of?(String) or value.kind_of?(Symbol)
             if ((StringPattern.optimistic and value.kind_of?(String)) or value.kind_of?(Symbol)) and value.to_s.scan(/^!?\d+-?\d*:.+/).size > 0
               res = StringPattern.validate(pattern: value, text: values[key])
@@ -119,10 +125,8 @@ class NiceHash
           elsif value.kind_of?(Module) and value == Boolean
             results[key] = false unless values[key].is_a?(Boolean)
           elsif value.kind_of?(Regexp)
-            rex = Regexp.new("^#{value}$")
-            unless values[key].to_s.match?(rex)
-              results[key] = false
-            end
+            res = StringPattern.validate(text: values[key].to_s, pattern: value)
+            results[key] = false unless res == true || (res.is_a?(Array) && res.empty?)
           elsif value.kind_of?(Array)
             array_pattern = false
             complex_data = false
@@ -132,6 +136,9 @@ class NiceHash
                   results[key] ||= []
                   values[key].each do |vk|
                     res = StringPattern.validate(pattern: value[0], text: vk)
+                    if explain && res.is_a?(Array) && !res.empty?
+                      res = described_failure(value[0], vk, res, true)
+                    end
                     results[key] << res
                   end
                   if results[key].flatten.size == 0
@@ -155,10 +162,10 @@ class NiceHash
                 if values[key].class == value.class
                   values[key].each do |v|
                     if value[0].is_a?(Hash)
-                      res = NiceHash.validate([value[0], select_hash_key], v, only_patterns: only_patterns)
+                      res = NiceHash.validate([value[0], select_hash_key], v, only_patterns: only_patterns, explain: explain)
                     else
                       # for the case {cars: ['Ford|Newton|Seat']}
-                      res = NiceHash.validate([{ key => value[0] }, select_hash_key], { key => v }, only_patterns: only_patterns)
+                      res = NiceHash.validate([{ key => value[0] }, select_hash_key], { key => v }, only_patterns: only_patterns, explain: explain)
                       #res = {key => res[:doit]} if res.is_a?(Hash) and res.key?(:doit)
                       array_pattern = true
                     end
@@ -175,10 +182,10 @@ class NiceHash
                 i = 0
                 value.each { |v|
                   if v.is_a?(Hash)
-                    res = NiceHash.validate([v, select_hash_key], values[key][i], only_patterns: only_patterns)
+                    res = NiceHash.validate([v, select_hash_key], values[key][i], only_patterns: only_patterns, explain: explain)
                   elsif v.is_a?(Array)
                     # for the case {cars: ['Ford|Newton|Seat']}
-                    res = NiceHash.validate([{ key => v }, select_hash_key], { key => values[key][i] }, only_patterns: only_patterns)
+                    res = NiceHash.validate([{ key => v }, select_hash_key], { key => values[key][i] }, only_patterns: only_patterns, explain: explain)
                     array_pattern = true
                   else
                     res = []
@@ -208,6 +215,7 @@ class NiceHash
               end
             }
           end
+          explain_stored_results(results, key, value, values, same_values, explain) if explain
         end
       }
     end
@@ -215,5 +223,81 @@ class NiceHash
     return results
   end
 
+  def self.checksum_problem(spec, text)
+    kind, arg = spec
+    raw = text.to_s
+    if kind == :iban
+      compact = raw.gsub(/\s+/, "").upcase
+      return [[:value], "invalid IBAN"] unless StringPattern.valid_iban?(raw)
+      return nil if arg.nil? || compact.start_with?(arg)
+
+      [[:value], "IBAN country is not #{arg}"]
+    else
+      return [[:value], "invalid Luhn number"] unless StringPattern.valid_luhn?(raw)
+      return nil if raw.size == arg
+
+      [[:length], "expected #{arg} digits"]
+    end
+  end
+
+  def self.explain_stored_results(results, key, pattern, values, same_values, _explain)
+    keys = [key]
+    keys.concat(same_values[key]) if same_values.include?(key)
+    keys.each do |result_key|
+      payload = results[result_key]
+      next if payload.nil?
+
+      if payload == false || (payload.is_a?(Array) && !payload.empty? && payload.all? { |item| item.is_a?(Symbol) })
+        results[result_key] = explained_result(pattern, values[result_key], payload)
+      elsif payload.is_a?(String)
+        results[result_key] = { valid: false, errors: [:value], message: payload, index: nil }
+      end
+    end
+  end
+
+  def self.explained_result(pattern, text, plain)
+    spec = checksum_spec(pattern)
+    if spec && (problem = checksum_problem(spec, text))
+      errors, message = problem
+      return { valid: false, errors: errors, message: message, index: nil }
+    end
+
+    described_failure(pattern, text, plain, true)
+  end
+
+  def self.described_failure(pattern, text, plain, explain)
+    return plain unless explain
+    return StringPattern.explain(text: text, pattern: pattern) if explainable_pattern?(pattern)
+    return { valid: false, errors: [:value], message: plain, index: nil } if plain.is_a?(String)
+
+    errors = plain.is_a?(Array) ? plain : [:value]
+    { valid: false, errors: errors, message: failure_message(pattern, errors), index: nil }
+  end
+
+  def self.explainable_pattern?(pattern)
+    return true if pattern.is_a?(Regexp)
+    if pattern.is_a?(String) || pattern.is_a?(Symbol)
+      return StringPattern.analyze(pattern, silent: true).is_a?(StringPattern::Pattern)
+    end
+    return false unless pattern.is_a?(Array) && pattern.size > 1
+
+    pattern.all? { |part|
+      part.is_a?(Regexp) || (
+        (part.is_a?(String) || part.is_a?(Symbol)) &&
+        StringPattern.analyze(part, silent: true).is_a?(StringPattern::Pattern)
+      )
+    }
+  end
+
+  def self.failure_message(pattern, errors)
+    case pattern
+    when :uuid then "invalid UUID"
+    when :email then "invalid email"
+    else
+      errors == [:value] ? "invalid" : "invalid: #{errors.join(", ")}"
+    end
+  end
 
+  private_class_method :checksum_problem, :explain_stored_results, :explained_result,
+    :described_failure, :explainable_pattern?, :failure_message
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nice_hash
 version: !ruby/object:Gem::Version
-  version: 1.19.0
+  version: 1.21.0
 platform: ruby
 authors:
 - Mario Ruiz
@@ -15,20 +15,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: 2.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: 2.5.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement