amka 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f2628c4521fdb7fc9d1c9a09318e9189d837ede318ac1d19ac5fc606a1b9c24
-  data.tar.gz: da07a7a6bb486d1409f26a25969fc109ec392bac6b9e8c237a88fd6d0a816650
+  metadata.gz: de5ab67f3f55def8127fdcc62f80227e3a1eac67310f5505fb0d2bd885235b5e
+  data.tar.gz: 8898093154bfa16391dbf6721204350f4f2052088db0db2be4dc0ee8cda51e38
 SHA512:
-  metadata.gz: 56db96d08effcd378cb0c7f2bd7ae18041c2ce04c2d195152d94714e1fa750b67a1230467bd15b7871ec06dcd7632e96087dd7af3a55b44cbc4e248221a67754
-  data.tar.gz: a042775a314e742322c36c7769d07ffd152ce2893147226c64bafe12d6a4da6eaa281f931dcdc43cb22e3dc9fefa25b08e0dbd311f71a17179a769490a2938d7
+  metadata.gz: 1e46d541a313fd37f7d58f98d244459110d77d22630e65d2b8941fa7c5a4a69f1d0eb8e50962acd6d7e83bec5f6b4fa227e8c1d8e3c9ef8a01c9bbd2b2589b15
+  data.tar.gz: d2b9da885d006f520a93b4a08f07561f5518b1369f16fd9c40da0a78560cee23edef7a49359e9addf8c0ec1cbeed401ebcf0159870d37325fb87ebf07a483faa

data/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2023-05-14
+
+### Added
+
+- New `validate` method that returns detailed validation errors
+- New `validate!` method that raises exceptions with descriptive messages
+- Added `safe_valid?` method to Luhn class for exception-free validation
+- Improved error handling with specific `ValidationError` class
+
+### Changed
+
+- Improved `valid?` method to never raise exceptions
+- Refactored validation logic for better maintainability
+- Better error messages for validation failures
+
+### Fixed
+
+- Rubocop compliance for method length
+
 ## [2.0.0] - 2025-04-16
 
 ### Changed

data/README.md

@@ -56,16 +56,31 @@ gem install amka
 ```ruby
 require 'amka'
 
-# To validate (takes the AMKA as a string and returns true or false)
+# Simple Validation (returns true or false)
 Amka.valid?('01011441432')
-# returns false (i did not use a valid one in this example just in case
-# it belonged to a real person!!!!)
+# returns false
 
 # You can also pass the 4 digit year of birth as a second string argument
 # This will increase the accuracy of the date part of validation to 100%.
 Amka.valid?('111098xxxxx', '1998')
 
-# To generate (returns the AMKA as a string)
+# Detailed Validation with Error Messages
+errors = Amka.validate('01AB9012345')
+if errors.empty?
+  puts "Valid AMKA!"
+else
+  puts "Invalid AMKA: #{errors.join(', ')}"
+  # => "Invalid AMKA: AMKA must contain only digits"
+end
+
+# Exception-based Validation
+begin
+  Amka.validate!('01019012345')  # Returns true if valid
+rescue Amka::ValidationError => e
+  puts "Error: #{e.message}"
+end
+
+# To generate a random AMKA (returns the AMKA as a string)
 Amka.generate
 
 # To generate with a specific date (date format: [d]d/[m]m/yyyy)

data/lib/amka/luhn.rb

@@ -50,6 +50,33 @@ module Amka
       (digits_sum % 10).zero?
     end
 
+    # Validates if a given ID follows the Luhn algorithm, without raising exceptions
+    #
+    # This is a safe version of valid? that returns false for any invalid input
+    # instead of raising exceptions. It's designed for use in validation pipelines
+    # where exceptions would need to be caught.
+    #
+    # @param luhn_id [Object] the ID to validate
+    # @return [Boolean] true if valid according to Luhn algorithm, false otherwise
+    # @example Safe validation with clean inputs
+    #   Amka::Luhn.safe_valid?('4532015112830366')  #=> true
+    # @example Safe validation with problematic inputs
+    #   Amka::Luhn.safe_valid?(nil)  #=> false
+    #   Amka::Luhn.safe_valid?(12345)  #=> false
+    #   Amka::Luhn.safe_valid?('abc-123')  #=> false
+    def self.safe_valid?(luhn_id)
+      # Return false for non-string input
+      return false unless luhn_id.is_a?(String)
+      # Return false for strings with non-digits
+      return false unless luhn_id.match(/\A\d+\Z/)
+
+      digits_sum = calculate_digits_sum(luhn_id)
+      (digits_sum % 10).zero?
+    rescue StandardError
+      # Catch any unexpected errors and return false
+      false
+    end
+
     # Generates a valid Luhn ID
     #
     # Creates a number that passes the Luhn check by:

data/lib/amka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Amka
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/lib/amka.rb

@@ -31,6 +31,9 @@ module Amka
   # Standard error class for the Amka gem
   class Error < StandardError; end
 
+  # Error raised when AMKA format or content is invalid
+  class ValidationError < Error; end
+
   # Validates whether a given string is a valid AMKA
   #
   # The validation checks three conditions:
@@ -38,7 +41,10 @@ module Amka
   # 2. The first 6 digits must form a valid date (DDMMYY format)
   # 3. The entire number must satisfy the Luhn algorithm check
   #
-  # @param amka [String] the AMKA to validate, must be a string containing only digits
+  # This method will always return a boolean and never raise exceptions,
+  # returning false for any input that doesn't meet the AMKA criteria.
+  #
+  # @param amka [Object] the AMKA to validate, should be a string containing only digits
   # @param year [String, nil] optional four-digit year to match against
   #   When provided, improves the validation by ensuring the birth year
   #   matches exactly (resolves century ambiguity in 2-digit years)
@@ -47,14 +53,120 @@ module Amka
   #   Amka.valid?('17019012345')  #=> true
   # @example Validating with explicit year
   #   Amka.valid?('17019012345', '1990')  #=> true
+  # @example Validating invalid input
+  #   Amka.valid?(nil)  #=> false
+  #   Amka.valid?(12345)  #=> false
+  #   Amka.valid?('abc123')  #=> false
   def self.valid?(amka, year = nil)
-    Utils.string_with_digits_or_fail(amka)
-
+    # Return false for non-string input
+    return false unless amka.is_a?(String)
+    # Return false for strings with non-digits
+    return false unless amka.match(/\A\d+\Z/)
+    # Check length requirement
     return false unless length_is_11?(amka)
 
-    return Luhn.valid?(amka) if Utils.valid_date?(amka, year)
+    # Check if date and Luhn algorithm are valid
+    begin
+      return false unless Utils.valid_date?(amka, year)
 
-    false
+      Luhn.safe_valid?(amka)
+    rescue ArgumentError
+      # If any validation raises an exception, the AMKA is invalid
+      false
+    end
+  end
+
+  # Validates an AMKA and returns an array of validation errors
+  #
+  # This method provides detailed feedback about why validation failed,
+  # returning an empty array for valid AMKAs or an array of error messages
+  # for invalid ones.
+  #
+  # @param amka [Object] the AMKA to validate
+  # @param year [String, nil] optional four-digit year to match against
+  # @return [Array<String>] empty array if valid, otherwise contains error messages
+  # @example Get validation errors
+  #   errors = Amka.validate(input)
+  #   if errors.empty?
+  #     puts "Valid AMKA!"
+  #   else
+  #     puts "Invalid AMKA: #{errors.join(', ')}"
+  #   end
+  def self.validate(amka, year = nil)
+    errors = []
+
+    # Check for basic format issues and return early if found
+    basic_format_errors = check_basic_format(amka)
+    return basic_format_errors unless basic_format_errors.empty?
+
+    # Check length
+    errors << 'AMKA must be exactly 11 digits long' unless length_is_11?(amka)
+
+    # Check date format
+    check_date(errors, amka, year)
+
+    # Check Luhn algorithm
+    check_luhn(errors, amka)
+
+    errors
+  end
+
+  # Helper method to validate basic format requirements
+  # @return [Array<String>] empty if valid, otherwise contains error message
+  def self.check_basic_format(amka)
+    errors = []
+
+    unless amka.is_a?(String)
+      errors << 'AMKA must be a string'
+      return errors
+    end
+
+    errors << 'AMKA must contain only digits' unless amka.match(/\A\d+\Z/)
+
+    errors
+  end
+  private_class_method :check_basic_format
+
+  # Helper method to validate date format
+  def self.check_date(errors, amka, year)
+    unless Utils.valid_date?(amka, year)
+      errors << 'First 6 digits of AMKA must form a valid date (DDMMYY)'
+    end
+  rescue ArgumentError
+    errors << 'Invalid date format in AMKA'
+  end
+  private_class_method :check_date
+
+  # Helper method to validate Luhn algorithm
+  def self.check_luhn(errors, amka)
+    errors << 'AMKA must satisfy the Luhn algorithm check' unless Luhn.safe_valid?(amka)
+  rescue StandardError
+    errors << 'Error checking Luhn algorithm'
+  end
+  private_class_method :check_luhn
+
+  # Strictly validates an AMKA and raises exceptions for invalid input
+  #
+  # Similar to valid? but raises specific exceptions when validation fails,
+  # which is useful for cases where you need detailed error information
+  # or when you prefer exceptions for control flow.
+  #
+  # @param amka [Object] the AMKA to validate
+  # @param year [String, nil] optional four-digit year to match against
+  # @return [true] if the AMKA is valid
+  # @raise [ValidationError] if the AMKA is invalid, with details about why
+  # @example Strict validation with exception handling
+  #   begin
+  #     Amka.validate!('17019012345')  #=> true (if valid)
+  #   rescue Amka::ValidationError => e
+  #     puts e.message  # Contains detailed error info
+  #   end
+  def self.validate!(amka, year = nil)
+    errors = validate(amka, year)
+
+    raise ValidationError, errors.first unless errors.empty?
+
+    true
   end
 
   # Generates a random valid AMKA

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amka
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Ioannis Angelakopoulos
@@ -35,6 +35,7 @@ metadata:
   homepage_uri: https://github.com/ioagel/amka
   source_code_uri: https://github.com/ioagel/amka
   changelog_uri: https://github.com/ioagel/amka/blob/master/CHANGELOG.md
+  documentation_uri: http://rubydoc.info/gems/amka
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []