ibandit 0.2.1 → 0.3.0

data/lib/ibandit/iban.rb

@@ -2,23 +2,25 @@ require 'yaml'
 
 module Ibandit
   class IBAN
-    attr_reader :iban
-    attr_reader :errors
-
-    def self.structures
-      @structures ||= YAML.load_file(
-        File.expand_path('../../../data/structures.yml', __FILE__)
-      )
-    end
+    attr_reader :errors, :iban,  :country_code, :check_digits, :bank_code,
+                :branch_code, :account_number
+
+    def initialize(argument)
+      if argument.is_a?(String)
+        @iban = argument.to_s.gsub(/\s+/, '').upcase
+        extract_local_details_from_iban!
+      elsif argument.is_a?(Hash)
+        build_iban_from_local_details(argument)
+      else
+        raise TypeError, 'Must pass an IBAN string or hash of local details'
+      end
 
-    def initialize(iban)
-      @iban = iban.to_s.gsub(/\s+/, '').upcase
       @errors = {}
     end
 
     def to_s(format = :compact)
       case format
-      when :compact then iban
+      when :compact   then iban.to_s
       when :formatted then formatted
       else raise ArgumentError, "invalid format '#{format}'"
       end
@@ -28,58 +30,25 @@ module Ibandit
     # Component parts #
     ###################
 
-    def country_code
-      iban[0, 2]
-    end
-
-    def check_digits
-      iban[2, 2] || ''
-    end
-
-    def bank_code
-      return '' unless structure
-
-      iban.slice(
-        structure[:bank_code_position] - 1,
-        structure[:bank_code_length]
-      ) || ''
-    end
-
-    def branch_code
-      return '' unless structure && structure[:branch_code_length] > 0
-
-      iban.slice(
-        structure[:branch_code_position] - 1,
-        structure[:branch_code_length]
-      ) || ''
-    end
-
-    def account_number
-      return '' unless structure
-
-      iban.slice(
-        structure[:account_number_position] - 1,
-        structure[:account_number_length]
-      ) || ''
-    end
-
     def iban_national_id
-      return '' unless structure
+      return unless decomposable?
 
-      national_id = branch_code.nil? ? bank_code : bank_code + branch_code
+      national_id = bank_code.to_s
+      national_id += branch_code.to_s
       national_id.slice(0, structure[:iban_national_id_length])
     end
 
     def local_check_digits
-      return '' unless structure && structure[:local_check_digit_position]
+      return unless decomposable? && structure[:local_check_digit_position]
 
-      iban.slice(structure[:local_check_digit_position] - 1,
-                 structure[:local_check_digit_length]
-      ) || ''
+      iban.slice(
+        structure[:local_check_digit_position] - 1,
+        structure[:local_check_digit_length]
+      )
     end
 
     def bban
-      iban[4..-1] || ''
+      iban[4..-1] unless iban.nil?
     end
 
     ###############
@@ -92,12 +61,18 @@ module Ibandit
         valid_characters?,
         valid_check_digits?,
         valid_length?,
-        valid_format?
+        valid_bank_code_length?,
+        valid_branch_code_length?,
+        valid_account_number_length?,
+        valid_format?,
+        valid_bank_code_format?,
+        valid_branch_code_format?,
+        valid_account_number_format?
       ].all?
     end
 
     def valid_country_code?
-      if IBAN.structures.key?(country_code)
+      if Ibandit.structures.key?(country_code)
         true
       else
         @errors[:country_code] = "'#{country_code}' is not a valid " \
@@ -107,7 +82,7 @@ module Ibandit
     end
 
     def valid_check_digits?
-      return unless valid_country_code? && valid_characters?
+      return unless decomposable? && valid_characters?
 
       expected_check_digits = CheckDigit.iban(country_code, bban)
       if check_digits == expected_check_digits
@@ -121,9 +96,9 @@ module Ibandit
     end
 
     def valid_length?
-      return unless valid_country_code?
+      return unless valid_country_code? && !iban.nil?
 
-      if iban.size == structure[:total_length]
+      if iban.length == structure[:total_length]
         true
       else
         @errors[:length] = "Length doesn't match SWIFT specification " \
@@ -133,7 +108,54 @@ module Ibandit
       end
     end
 
+    def valid_bank_code_length?
+      return unless valid_country_code?
+
+      if bank_code.nil? || bank_code.length == 0
+        @errors[:bank_code] = 'is required'
+        return false
+      end
+
+      return true if bank_code.length == structure[:bank_code_length]
+
+      @errors[:bank_code] = 'is the wrong length (should be ' \
+                            "#{structure[:bank_code_length]} characters)"
+      false
+    end
+
+    def valid_branch_code_length?
+      return unless valid_country_code?
+      return true if branch_code.to_s.length == structure[:branch_code_length]
+
+      if structure[:branch_code_length] == 0
+        @errors[:branch_code] = "is not used in #{country_code}"
+      elsif branch_code.nil? || branch_code.length == 0
+        @errors[:branch_code] = 'is required'
+      else
+        @errors[:branch_code] = 'is the wrong length (should be ' \
+                                "#{structure[:branch_code_length]} characters)"
+      end
+      false
+    end
+
+    def valid_account_number_length?
+      return unless valid_country_code?
+
+      if account_number.nil?
+        @errors[:account_number] = 'is required'
+        return false
+      end
+
+      return true if account_number.length == structure[:account_number_length]
+
+      @errors[:account_number] = 'is the wrong length (should be ' \
+                                 "#{structure[:account_number_length]} " \
+                                 'characters)'
+      false
+    end
+
     def valid_characters?
+      return if iban.nil?
       if iban.scan(/[^A-Z0-9]/).any?
         @errors[:characters] = 'Non-alphanumeric characters found: ' \
                                "#{iban.scan(/[^A-Z\d]/).join(' ')}"
@@ -154,18 +176,83 @@ module Ibandit
       end
     end
 
+    def valid_bank_code_format?
+      return unless valid_bank_code_length?
+
+      if bank_code =~ Regexp.new(structure[:bank_code_format])
+        true
+      else
+        @errors[:bank_code] = 'is invalid'
+        false
+      end
+    end
+
+    def valid_branch_code_format?
+      return unless valid_branch_code_length?
+      return true unless structure[:branch_code_format]
+
+      if branch_code =~ Regexp.new(structure[:branch_code_format])
+        true
+      else
+        @errors[:branch_code] = 'is invalid'
+        false
+      end
+    end
+
+    def valid_account_number_format?
+      return unless valid_account_number_length?
+
+      if account_number =~ Regexp.new(structure[:account_number_format])
+        true
+      else
+        @errors[:account_number] = 'is invalid'
+        false
+      end
+    end
+
     ###################
     # Private methods #
     ###################
 
     private
 
+    def decomposable?
+      [iban, country_code, bank_code, account_number].none?(&:nil?)
+    end
+
+    def build_iban_from_local_details(details_hash)
+      local_details = LocalDetailsCleaner.clean(details_hash)
+
+      @country_code   = try_dup(local_details[:country_code])
+      @account_number = try_dup(local_details[:account_number])
+      @branch_code    = try_dup(local_details[:branch_code])
+      @bank_code      = try_dup(local_details[:bank_code])
+      @iban           = IBANAssembler.assemble(local_details)
+      @check_digits   = @iban.slice(2, 2) unless @iban.nil?
+    end
+
+    def extract_local_details_from_iban!
+      local_details = IBANSplitter.split(@iban)
+
+      @country_code   = local_details[:country_code]
+      @check_digits   = local_details[:check_digits]
+      @bank_code      = local_details[:bank_code]
+      @branch_code    = local_details[:branch_code]
+      @account_number = local_details[:account_number]
+    end
+
+    def try_dup(object)
+      object.dup
+    rescue TypeError
+      object
+    end
+
     def structure
-      IBAN.structures[country_code]
+      Ibandit.structures[country_code]
     end
 
     def formatted
-      iban.gsub(/(.{4})/, '\1 ').strip
+      iban.to_s.gsub(/(.{4})/, '\1 ').strip
     end
   end
 end

data/lib/ibandit/iban_assembler.rb

@@ -0,0 +1,117 @@
+module Ibandit
+  module IBANAssembler
+    SUPPORTED_COUNTRY_CODES = %w(AT BE CY DE EE ES FI FR GB IE IT LT LU LV MC NL
+                                 PT SI SK SM).freeze
+
+    EXCEPTION_COUNTRY_CODES = %w(IT SM BE).freeze
+
+    def self.assemble(local_details)
+      country_code = local_details[:country_code]
+
+      return unless can_assemble?(local_details)
+
+      bban =
+        if EXCEPTION_COUNTRY_CODES.include?(country_code)
+          public_send(:"assemble_#{country_code.downcase}_bban", local_details)
+        else
+          assemble_general_bban(local_details)
+        end
+
+      assemble_iban(country_code, bban)
+    end
+
+    ##############################
+    # General case BBAN creation #
+    ##############################
+
+    def self.assemble_general_bban(opts)
+      [opts[:bank_code], opts[:branch_code], opts[:account_number]].join
+    end
+
+    ##################################
+    # Country-specific BBAN creation #
+    ##################################
+
+    def self.assemble_be_bban(opts)
+      # The first three digits of Belgian account numbers are the bank_code,
+      # but the account number is not considered complete without these three
+      # numbers and the IBAN structure file includes them in its definition of
+      # the account number. As a result, this method ignores all arguments
+      # other than the account number.
+      opts[:account_number]
+    end
+
+    def self.assemble_it_bban(opts)
+      # The  Italian check digit is NOT included in the any of the other SWIFT
+      # elements, so should be passed explicitly or left blank for it to be
+      # calculated implicitly
+      partial_bban = [
+        opts[:bank_code],
+        opts[:branch_code],
+        opts[:account_number]
+      ].join
+
+      check_digit = opts[:check_digit] || CheckDigit.italian(partial_bban)
+
+      [check_digit, partial_bban].join
+    end
+
+    def self.assemble_sm_bban(opts)
+      # San Marino uses the same BBAN construction method as Italy
+      assemble_it_bban(opts)
+    end
+
+    ##################
+    # Helper methods #
+    ##################
+
+    def self.can_assemble?(local_details)
+      SUPPORTED_COUNTRY_CODES.include?(local_details[:country_code]) &&
+        valid_arguments?(local_details)
+    end
+
+    def self.valid_arguments?(local_details)
+      country_code = local_details[:country_code]
+
+      supplied = local_details.keys.select { |key| local_details[key] }
+      supplied.delete(:country_code)
+
+      allowed = allowed_fields(country_code)
+
+      required_fields(country_code).all? { |key| supplied.include?(key) } &&
+        supplied.all? { |key| allowed.include?(key) }
+    end
+
+    def self.required_fields(country_code)
+      case country_code
+      when 'AT', 'CY', 'DE', 'EE', 'FI', 'LT', 'LU', 'LV', 'NL', 'SI', 'SK'
+        %i(bank_code account_number)
+      when 'BE'
+        %i(account_number)
+      else
+        %i(bank_code branch_code account_number)
+      end
+    end
+
+    def self.allowed_fields(country_code)
+      # Some countries have additional optional fields
+      case country_code
+      when 'BE' then %i(bank_code account_number)
+      when 'CY' then %i(bank_code branch_code account_number)
+      when 'IT' then %i(bank_code branch_code account_number check_digit)
+      when 'SK' then %i(bank_code account_number account_number_prefix)
+      else required_fields(country_code)
+      end
+    end
+
+    def self.assemble_iban(country_code, bban)
+      [
+        country_code,
+        CheckDigit.iban(country_code, bban),
+        bban
+      ].join
+    rescue InvalidCharacterError
+      nil
+    end
+  end
+end

data/lib/ibandit/iban_splitter.rb

@@ -0,0 +1,66 @@
+module Ibandit
+  module IBANSplitter
+    def self.split(iban)
+      {
+        country_code:   country_code_from(iban),
+        check_digits:   check_digits_from(iban),
+        bank_code:      bank_code_from(iban),
+        branch_code:    branch_code_from(iban),
+        account_number: account_number_from(iban)
+      }
+    end
+
+    ###################
+    # Component parts #
+    ###################
+
+    def self.country_code_from(iban)
+      return if iban.nil? || iban.empty?
+
+      iban.slice(0, 2)
+    end
+
+    def self.check_digits_from(iban)
+      return unless decomposable?(iban)
+
+      iban.slice(2, 2)
+    end
+
+    def self.bank_code_from(iban)
+      return unless decomposable?(iban)
+
+      iban.slice(
+        structure(iban)[:bank_code_position] - 1,
+        structure(iban)[:bank_code_length]
+      )
+    end
+
+    def self.branch_code_from(iban)
+      unless decomposable?(iban) && structure(iban)[:branch_code_length] > 0
+        return
+      end
+
+      iban.slice(
+        structure(iban)[:branch_code_position] - 1,
+        structure(iban)[:branch_code_length]
+      )
+    end
+
+    def self.account_number_from(iban)
+      return unless decomposable?(iban)
+
+      iban.slice(
+        structure(iban)[:account_number_position] - 1,
+        structure(iban)[:account_number_length]
+      )
+    end
+
+    def self.decomposable?(iban)
+      structure(iban) && iban.length == structure(iban)[:total_length]
+    end
+
+    def self.structure(iban)
+      Ibandit.structures[country_code_from(iban)]
+    end
+  end
+end