iso-iban 0.0.1

data/iso-iban.gemspec

@@ -0,0 +1,42 @@
+# encoding: utf-8
+
+Gem::Specification.new do |s|
+  s.name                      = "iso-iban"
+  s.version                   = "0.0.1"
+  s.authors                   = "Stefan Rusterholz"
+  s.email                     = "stefan.rusterholz@gmail.com"
+  s.homepage                  = "https://github.com/apeiros/iso-iban"
+  s.license                   = 'BSD 2-Clause'
+
+  s.description               = <<-DESCRIPTION.gsub(/^    /, '').chomp
+    ISO::IBAN implements IBAN (International Bank Account Number) specification as per ISO 13616-1.
+    It provides methods to generate valid IBAN numbers from components, or to validate a given IBAN.
+  DESCRIPTION
+  s.summary                   = <<-SUMMARY.gsub(/^    /, '').chomp
+    Utilities for International Bank Account Numbers (IBAN) as per ISO 13616-1.
+  SUMMARY
+
+  s.files                     =
+    Dir['bin/**/*'] +
+    Dir['data/**/*'] +
+    Dir['documentation/**/*'] +
+    Dir['lib/**/*'] +
+    Dir['rake/**/*'] +
+    Dir['test/**/*'] +
+    Dir['*.gemspec'] +
+    %w[
+      .yardopts
+      LICENSE.txt
+      Rakefile
+      README.markdown
+    ]
+
+  if File.directory?('bin') then
+    s.executables = Dir.chdir('bin') { Dir.glob('**/*').select { |f| File.executable?(f) } }
+  end
+
+  s.required_ruby_version     = ">= 1.9.2"
+  s.required_rubygems_version = Gem::Requirement.new("> 1.3.1")
+  s.rubygems_version          = "1.3.1"
+  s.specification_version     = 3
+end

data/lib/iso/iban.rb

@@ -0,0 +1,324 @@
+# encoding: utf-8
+
+require 'iso/iban/specification'
+require 'iso/iban/version'
+
+module ISO
+
+  # IBAN - ISO 13616-1
+  #
+  # General IBAN Information
+  # ========================
+  #
+  # * What is an IBAN?
+  #   IBAN stands for International Bank Account Number. It is the ISO 13616
+  #   international standard for numbering bank accounts. In 2006, the
+  #   International Organization for Standardization (ISO) designated SWIFT as
+  #   the Registration Authority for ISO 13616.
+  #
+  # * Use
+  #   The IBAN facilitates the communication and processing of cross-border
+  #   transactions. It allows exchanging account identification details in a
+  #   machine-readable form.
+  #
+  #
+  # The ISO 13616 IBAN Standard
+  # ===========================
+  #
+  # * Structure
+  #   The IBAN structure is defined in ISO 13616-1 and consists of a two-letter
+  #   ISO 3166-1 country code, followed by two check digits and up to thirty
+  #   alphanumeric characters for a BBAN (Basic Bank Account Number) which has a
+  #   fixed length per country and, included within it, a bank identifier with a
+  #   fixed position and a fixed length per country. The check digits are
+  #   calculated based on the scheme defined in ISO/IEC 7064 (MOD97-10).
+  #
+  # * Terms and definitions
+  #   Bank identifier: The identifier that uniquely identifies the financial
+  #   institution and, when appropriate, the branch of that financial institution
+  #   servicing an account
+  #   
+  #   `In this registry, the branch identifier format is shown specifically, when
+  #   present.`
+  #
+  #   *BBAN*: basic bank account number: The identifier that uniquely identifies
+  #   an individual account, at a specific financial institution, in a particular
+  #   country. The BBAN includes a bank identifier of the financial institution
+  #   servicing that account.
+  #   *IBAN*: international bank account number: The expanded version of the
+  #   basic bank account number (BBAN), intended for use internationally. The
+  #   IBAN uniquely identifies an individual account, at a specific financial
+  #   institution, in a particular country.
+  #
+  # * Submitters
+  #   Nationally-agreed, ISO13616-compliant IBAN formats are submitted to the
+  #   registration authority exclusively by the National Standards Body or the
+  #   National Central Bank of the country.
+  class IBAN
+    include Comparable
+
+    # Character code translation used to convert an IBAN into its numeric
+    # (digits-only) form
+    CharacterCodes  = Hash[('0'..'9').zip('0'..'9')+('a'..'z').zip(10..35)+('A'..'Z').zip(10..35)]
+
+    # All specifications, see ISO::IBAN::Specification
+    @specifications = nil
+
+    # Load the IBAN specifications file, which determines how the IBAN
+    # for any given country looks like.
+    #
+    # It will use the following sources in this order (first one which exists wins)
+    #
+    # * Path passed as spec_file parameter
+    # * Path provided by the env variable IBAN_SPECIFICATIONS
+    # * The file ../data/iso-iban/specs.yaml relative to the lib dir
+    # * The Gem datadir path
+    #
+    # @param [String] spec_file
+    #   Override the default specifications file path.
+    #
+    # @return [self]
+    def self.load_specifications(spec_file=nil)
+      if spec_file then
+        # do nothing
+      elsif ENV['IBAN_SPECIFICATIONS'] then
+        spec_file = ENV['IBAN_SPECIFICATIONS']
+      else
+        spec_file = File.expand_path('../../../../data/iso-iban/specs.yaml', __FILE__)
+        spec_file = Gem.datadir('iso-iban')+'/specs.yaml' if defined?(Gem) && !File.file?(spec_file)
+      end
+
+      @specifications = ISO::IBAN::Specification.load_yaml(spec_file)
+
+      self
+    end
+
+    # @return [Hash<String => ISO::IBAN::Specification>]
+    #   A hash with the country (ISO3166 2-letter) as key and the specification for that country as value
+    def self.specifications
+      @specifications || raise("No specifications have been loaded yet.")
+    end
+
+    # @param [String] a2_country_code
+    #   The country (ISO3166 2-letter), e.g. 'CH' or 'DE'.
+    #
+    # @return [ISO::IBAN::Specification]
+    #   The specification for the given country
+    def self.specification(a2_country_code, *default, &default_block)
+      specifications.fetch(a2_country_code, *default, &default_block)
+    end
+
+    # @param [String] iban
+    #   An IBAN number, either in compact or human format.
+    #
+    # @return [true, false]
+    #   Whether the IBAN is valid.
+    #   See {#validate} for details.
+    def self.valid?(iban)
+      new(iban).valid?
+    end
+
+    # @param [String] iban
+    #   An IBAN number, either in compact or human format.
+    #
+    # @return [Array<Symbol>]
+    #   An array with a code of all validation errors, empty if valid.
+    #   See {#validate} for details.
+    def self.validate(iban)
+      new(iban).validate
+    end
+
+    # @param [String] iban
+    #   The IBAN in either compact or human readable form.
+    #
+    # @return [String]
+    #   The IBAN in compact form.
+    def self.strip(iban)
+      iban.tr(' -', '')
+    end
+
+    # Generate an IBAN from country code and components, automatically filling in the checksum.
+    #
+    # @example Generate an IBAN for UBS Switzerland with account number '12345'
+    #     ISO::IBAN.generate('CH', '216', '12345') # => #<ISO::IBAN CH92 0021 6000 0000 1234 5>
+    #
+    # @param [String] country
+    #   The ISO-3166 2-letter country code.
+    #
+    def self.generate(country, *components)
+      spec      = specification(country)
+      justified = spec.component_lengths.zip(components).map { |length, component| component.rjust(length, "0") }
+      iban      = new(country+'??'+justified.join(''))
+      iban.update_checksum!
+
+      iban
+    end
+
+    # Converts a String into its digits-only form, i.e. all characters a-z are replaced with their corresponding
+    # digit sequences, according to the IBAN specification.
+    #
+    # @param [String] string
+    #   The string to convert into its numeric form.
+    #
+    # @return [String] The string in its numeric, digits-only form.
+    def self.numerify(string)
+      string.downcase.gsub(/\D/) { |char|
+        CharacterCodes.fetch(char) {
+          raise ArgumentError, "The string contains an invalid character #{char.inspect}"
+        }
+      }.to_i
+    end
+
+    # @return [String] The standard form of the IBAN for machine communication, without spaces.
+    attr_reader :compact
+
+    # @return [String] The ISO-3166 2-letter country code.
+    attr_reader :country
+
+    # @return [ISO::IBAN::Specification] The specification for this IBAN (determined by its country).
+    attr_reader :specification
+
+    # @param [String] iban
+    #   The IBAN number, either in formatted, human readable or in compact form.
+    def initialize(iban)
+      raise ArgumentError, "String expected for iban, but got #{iban.class}" unless iban.is_a?(String)
+
+      @compact       = self.class.strip(iban)
+      @country       = iban[0,2]
+      @specification = self.class.specification(@country, nil)
+    end
+
+    # @example Formatted IBAN
+    #
+    #     ISO::IBAN.new('CH')
+    #
+    # @return [String] The IBAN in its formatted form, which is more human readable than the compact form.
+    def formatted
+      @_formatted ||= @compact.gsub(/.{4}(?=.)/, '\0 ')
+    end
+
+    # @return [String]
+    #   IBAN in its numeric form, i.e. all characters a-z are replaced with their corresponding
+    #   digit sequences.
+    def numeric
+      self.class.numerify(@compact[4..-1]+@compact[0,4])
+    end
+
+    # @return [true, false]
+    #   Whether the IBAN is valid.
+    #   See {#validate} for details.
+    def valid?
+      validate.empty?
+    end
+
+    # Validation error codes:
+    #
+    # * :invalid_country
+    # * :invalid_checksum
+    # * :invalid_length
+    # * :invalid_format
+    #
+    # Invalid country means the country is unknown (char 1 & 2 in the IBAN).
+    # Invalid checksum means the two check digits (char 3 & 4 in the IBAN).
+    # Invalid length means the IBAN does not comply with the length specified for the country of that IBAN.
+    # Invalid format means the IBAN does not comply with the format specified for the country of that IBAN.
+    #
+    # @return [Array<Symbol>] An array with a code of all validation errors, empty if valid.
+    def validate
+      errors   = []
+      errors << :invalid_country  unless valid_country?
+      errors << :invalid_checksum unless valid_checksum?
+      errors << :invalid_length   unless valid_length?
+      errors << :invalid_format   unless valid_format?
+
+      errors
+    end
+
+    # @return [String] The checksum digits in the IBAN.
+    def checksum_digits
+      @compact[2,2]
+    end
+
+    # @return [String] The BBAN of the IBAN.
+    def bban
+      @compact[4..-1]
+    end
+
+    # @return [String, nil] The bank code part of the IBAN, nil if not applicable.
+    def bank_code
+      if @specification && @specification.bank_position_from && @specification.bank_position_to
+        @compact[@specification.bank_position_from..@specification.bank_position_to]
+      else
+        nil
+      end
+    end
+
+    # @return [String, nil] The branch code part of the IBAN, nil if not applicable.
+    def branch_code
+      if @specification && @specification.branch_position_from && @specification.branch_position_to
+        @compact[@specification.branch_position_from..@specification.branch_position_to]
+      else
+        nil
+      end
+    end
+
+    # @return [String] The account code part of the IBAN.
+    def account_code
+      @compact[((@specification.branch_position_to || @specification.bank_position_to || 3)+1)..-1]
+    end
+
+    # @return [true, false] Whether the country of the IBAN is valid.
+    def valid_country?
+      @specification ? true : false
+    end
+
+    # @return [true, false] Whether the format of the IBAN is valid.
+    def valid_format?
+      specification && specification.iban_regex =~ @compact ? true : false
+    end
+
+    # @return [true, false] Whether the length of the IBAN is valid.
+    def valid_length?
+      specification && @compact.size == specification.iban_length ? true : false
+    end
+
+    # @return [true, false] Whether the checksum of the IBAN is valid.
+    def valid_checksum?
+      numeric % 97 == 1
+    end
+
+    # See Object#<=>
+    #
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      other.respond_to?(:compact) ? @compact <=> other.compact : nil
+    end
+
+    # Requires that the checksum digits were left as '??', replaces them with
+    # the proper checksum.
+    #
+    # @return [self]
+    def update_checksum!
+      raise "Checksum digit placeholders missing" unless @compact[2,2] == '??'
+
+      @compact[2,2] = calculated_check_digits
+
+      self
+    end
+
+    # @return [String] The check-digits as calculated from the IBAN.
+    def calculated_check_digits
+      "%02d" % (98-(self.class.numerify(bban+@country)*100)%97)
+    end
+
+    # See Object#inspect
+    def inspect
+      sprintf "#<%p %s>", self.class, formatted
+    end
+
+    # @return [String] The compact form of the IBAN as a String.
+    def to_s
+      @compact.dup
+    end
+  end
+end

data/lib/iso/iban/autoload.rb

@@ -0,0 +1,5 @@
+# This file automatically loads all specifications. It's recommended that you require this file instead of iso/iban.
+
+require 'iso/iban'
+
+ISO::IBAN.load_specifications

data/lib/iso/iban/specification.rb

@@ -0,0 +1,128 @@
+# encoding: utf-8
+
+module ISO
+  class IBAN
+
+    # Specification of the IBAN format for one country. Every country has its
+    # own specification of the IBAN format.
+    # SWIFT is the official authority where those formats are registered.
+    class Specification
+
+      # A mapping from SWIFT structure specification to PCRE regex.
+      StructureCodes = {
+        'n' => '\d',
+        'a' => '[A-Z]',
+        'c' => '[A-Za-z0-9]',
+        'e' => ' ',
+      }
+
+      # Load the specifications YAML.
+      #
+      # @return [Hash<String => ISO::IBAN::Specification>]
+      def self.load_yaml(path)
+        Hash[YAML.load_file(path).map { |country, spec| [country, new(*spec)] }]
+      end
+
+      # Parse the SWIFT provided file (which sadly is a mess).
+      #
+      # @return [Array<ISO::IBAN::Specification>] an array with all specifications.
+      def self.parse_file(path)
+        File.read(path, encoding: Encoding::Windows_1252).encode(Encoding::UTF_8).split("\r\n").tap(&:shift).flat_map { |line|
+          country_name, country_codes, iban_structure, iban_length, bban_structure, bban_length, bank_position = line.split(/\t/).values_at(0,1,11,12,4,5,6)
+          codes = country_codes.size == 2 ? [country_codes] : country_codes.scan(/\b[A-Z]{2}\b/)
+          bank_position_from, bank_position_to, branch_position_from, branch_position_to = bank_position.match(/(?:[Pp]ositions?|) (\d+)-(\d+)(?:.*Branch identifier positions?: (\d+)-(\d+))?/).captures.map { |pos| pos && pos.to_i+3 }
+
+          codes.map { |a2_country_code|
+            new(
+              country_name.strip,
+              a2_country_code,
+              iban_structure.strip,
+              iban_length.to_i,
+              bban_structure.strip,
+              bban_length.to_i,
+              bank_position_from,
+              bank_position_to,
+              branch_position_from,
+              branch_position_to
+            )
+          }
+        }
+      end
+
+      # *n:   Digits (numeric characters 0 to 9 only)
+      # *a:   Upper case letters (alphabetic characters A-Z only)
+      # *c:   upper and lower case alphanumeric characters (A-Z, a-z and 0-9)
+      # *e:   blank space
+      # *nn!: fixed length
+      # *nn:  maximum length
+      #
+      # Example: "AL2!n8!n16!c"
+      def self.structure_regex(structure, anchored=true)
+        source = structure.scan(/([A-Z]+)|(\d+)(!?)([nac])/).map { |exact, length, fixed, code|
+          if exact
+            Regexp.escape(exact)
+          else
+            StructureCodes[code]+(fixed ? "{#{length}}" : "{,#{length}}")
+          end
+        }.join('')
+
+        anchored ? /\A#{source}\z/ : /#{source}/
+      end
+
+      attr_reader :country_name,
+                  :a2_country_code,
+                  :iban_structure,
+                  :iban_length,
+                  :bban_structure,
+                  :bban_length,
+                  :bank_position_from,
+                  :bank_position_to,
+                  :branch_position_from,
+                  :branch_position_to
+
+      def initialize(country_name, a2_country_code, iban_structure, iban_length, bban_structure, bban_length, bank_position_from, bank_position_to, branch_position_from, branch_position_to)
+        @country_name         = country_name
+        @a2_country_code      = a2_country_code
+        @iban_structure       = iban_structure
+        @iban_length          = iban_length
+        @bban_structure       = bban_structure
+        @bban_length          = bban_length
+        @bank_position_from   = bank_position_from
+        @bank_position_to     = bank_position_to
+        @branch_position_from = branch_position_from
+        @branch_position_to   = branch_position_to
+      end
+
+      # @return [Regexp] A regex to verify the structure of the IBAN.
+      def iban_regex
+        @iban_regex ||= self.class.structure_regex(@iban_structure)
+      end
+
+      # @return [Regexp] A regex to identify the structure of the IBAN, without anchors.
+      def unanchored_iban_regex
+        self.class.structure_regex(@iban_structure, false)
+      end
+
+      # @return [Array<Integer>] An array with the lengths of all components.
+      def component_lengths
+        @bban_structure.scan(/\d+/).map(&:to_i)
+      end
+
+      # @return [Array] An array with the Specification properties. Used for serialization.
+      def to_a
+        [
+          @country_name,
+          @a2_country_code,
+          @iban_structure,
+          @iban_length,
+          @bban_structure,
+          @bban_length,
+          @bank_position_from,
+          @bank_position_to,
+          @branch_position_from,
+          @branch_position_to,
+        ]
+      end
+    end
+  end
+end