nice_hash 1.20.0 → 1.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 718327558f69c77e13b7d19355f990e171eaf199676e8a42ced4bda0c1063827
-  data.tar.gz: d3a086c1262af567acc060fbe6cfb18a6bfbd134b4a1df807e9ee52666f0d4d4
+  metadata.gz: ab97a22d06c02e9a17c33221c77ff01c841405e0b3a15711ecb465bbf91eb23c
+  data.tar.gz: c358cab3956cd0f4dd90020ad68da0039f42786892d71f3803a2dcbc8be87f6b
 SHA512:
-  metadata.gz: a29e7907b0feca5db0253faa574a1fba185e37ea654881b999ef3f7ea48da52c42294963ad40f19fee657f121dde0ac11f8e41881d1115a7ad89b505d19afc24
-  data.tar.gz: b1eaa9bd0c1f6baf034aaf524222bb584265495c4bb8bf014ceeb5f6404bbe6364db7ce8cf786c4cece3daf670aa2751ca65eea6986c4145930cf5091d065ae3
+  metadata.gz: a4c876a1bd17ee4bf3a845dedb57aee727e73e9173a1145a103ce2da75daeec422c768a8bc3ba82c051734221079e184925c1b432f8d6be4bc240b4e43d2854d
+  data.tar.gz: 074570bccde6d2a926286817b13f935be05e34fbc57835a761bfe745c7474be1bd5585a5fef812cfb36d03d64c03e315d08fc6dd4ca2ad65d1afb84b14c80fe3

data/README.md

@@ -96,17 +96,24 @@ 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**, **email**, **Spanish IBAN** and a **16-digit Luhn** number you can use these shorthands (string_pattern 2.4+ for `:uuid`, 2.5+ for the others):
+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, email: :email, iban: :iban, card: :luhn, doomId: :"10:N" }
-# id:   "550e8400-e29b-41d4-a716-446655440000"
+# id:    "550e8400-e29b-41d4-a716-446655440000"
 # email: a generated address
-# iban:  a Spanish IBAN (country is always ES)
+# 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
 ```
 
-`:uuid`, `:iban` and `:luhn` use their own random generator. `seed:` does not make those three fields repeat.
+`: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:
 
@@ -742,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
@@ -899,8 +913,8 @@ Valid patterns:
 - 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+): IBAN, generated as Spanish (`ES`)
-- **:luhn** (string_pattern 2.5+): 16 digits with a valid Luhn checksum
+- **: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

@@ -91,12 +91,9 @@ class NiceHash
           hashv[key] = expected_errors.empty? ? StringPattern.uuid : (StringPattern.uuid[0..-2] + "X")
         elsif value == :email
           hashv[key] = StringPattern.generate("20-40:@", **sp_opts)
-        elsif value == :iban
-          # StringPattern.iban uses its own Random, so it is not reproducible via seed:.
-          hashv[key] = expected_errors.empty? ? StringPattern.iban(country: "ES") : "ES00NOTANIBAN"
-        elsif value == :luhn
-          # StringPattern.luhn uses its own Random, so it is not reproducible via seed:.
-          hashv[key] = expected_errors.empty? ? StringPattern.luhn(length: 16) : "1234567890123456"
+        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)
@@ -139,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] = []
-              (rng.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
@@ -268,5 +267,71 @@ class NiceHash
     n.times.map { NiceHash.generate(pattern_hash, select_hash_key, expected_errors: expected_errors, _rng: rng, **synonyms) }
   end
 
-  private_class_method :generation_rng
+  # :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
@@ -87,10 +89,8 @@ class NiceHash
             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 value == :iban
-            results[key] = false unless StringPattern.valid_iban?(values[key].to_s)
-          elsif value == :luhn
-            results[key] = false unless StringPattern.valid_luhn?(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])
@@ -136,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
@@ -159,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
@@ -179,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 = []
@@ -212,6 +215,7 @@ class NiceHash
               end
             }
           end
+          explain_stored_results(results, key, value, values, same_values, explain) if explain
         end
       }
     end
@@ -219,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.20.0
+  version: 1.21.0
 platform: ruby
 authors:
 - Mario Ruiz