iso8583 0.1.1 → 0.1.3

data/lib/exception.rb

@@ -1,5 +0,0 @@
-
-class ISO8583Exception < Exception
-end
-class ISO8583ParseException < ISO8583Exception
-end

data/lib/field.rb

@@ -1,178 +0,0 @@
-class Field
-  # may either be some other Field in which the length is encoded or a Fixnum for
-  # fixed length fields.
-  attr_accessor :length
-  attr_accessor :codec
-  attr_accessor :padding
-  attr_accessor :max
-
-  attr_writer   :name
-  attr_accessor :bmp
-
-  def name
-    "BMP #{bmp}: #{@name}(#{self.class.to_s})"
-  end
-
-  def parse raw
-    len, raw = case length
-               when Fixnum
-                 [length, raw]
-               when Field
-                 length.parse(raw)
-               else
-                 raise ISO8583Exception.new("How did you manage to fuck up configuration this bad? <-")
-               end
-
-    raw_value  = raw[0,len]
-    
-    # make sure we have enough data ...
-    if raw_value.length != len
-      mes = "Field has incorrect length! field: #{raw_value} len/expected: #{raw_value.length}/#{len}"
-      raise ISO8583ParseException.new(mes)
-    end
-
-    rest       = raw[len, raw.length]
-    real_value = codec.decode(raw_value)
-    return real_value, rest
-  end
-  
-
-  # Encoding needs to consider length representation, the actual encoding (such as charset or BCD) 
-  # and padding. 
-  # The order may be important! This impl calls codec.encode and then pads, in case you need the other 
-  # special treatment, you may need to override this method alltogether.
-  def encode value
-    encoded_value = codec.encode(value) 
-    
-    
-    if padding
-      if padding.arity == 1
-        encoded_value = padding.call(encoded_value)
-      elsif padding.arity == 2
-        encoded_value = padding.call(encoded_value, length)
-      end
-    end
-
-    len_str = case length
-              when Fixnum
-                raise ISO8583Exception.new("Too long: #{value}!")  if encoded_value.length > length
-                raise ISO8583Exception.new("Too short: #{value}!") if encoded_value.length < length
-                "" 
-              when Field
-                raise ISO8583Exception.new("Max lenth exceeded: #{value}, max: #{max}") if max && encoded_value.length > max
-                length.encode(encoded_value.length)
-              else
-                raise ISO8583Exception.new("How did you manage to fuck up configuration this bad? ->")
-              end
-    return len_str + encoded_value
-    
-  end
-end
-
-#
-#class Field
-#  attr_accessor :value
-#  
-#  def initialize value=nil
-#    @value = value
-#  end
-#  
-#  def name
-#    self.class._name
-#  end
-#  
-#  def to_b
-#    self.class.to_b @value
-#  end
-#
-#  def to_s
-#    "#{name} : #{value}"
-#  end
-#
-#  class << self
-#    def name name
-#      @name = name
-#    end
-#    def _name
-#      @name
-#    end
-#    def length len
-#      @len = len
-#    end
-#
-#    def _len
-#      if (@len == nil) && (superclass.respond_to?(:_len))
-#        return superclass.send(:_len)
-#      end
-#      @len
-#    end
-#
-#    def min min
-#      @min = min
-#    end
-#
-#    def max max
-#      @max = max
-#    end
-#    #def padding pad
-#    #  @pad = pad
-#    #end 
-#    def codec codec
-#      codec ||= Codec
-#      @codec = codec
-#      @codec = codec.new if codec.is_a? Class
-#    end
-#    
-#    # tries to parse the 
-#    def parse raw
-#      l, rest = _get_len raw
-#      #puts "len #{l}"
-#      #puts "rest: #{rest}"
-#      value = rest[0,l]
-#
-#      unless value.length == l
-#        raise ISO8583ParseException.new "Wrong length for: #{value} (#{value.length}), expected #{l}" 
-#      end
-#
-#      check(value)
-#      
-#
-#      rest  = rest[l,rest.length] 
-#      real_value = @codec.decode value
-#      field = self.new real_value
-#      return field, rest
-#    end 
-#
-#    def to_b value
-#      enc_value = @codec.encode(value)
-#      enc_len   = 
-#        case _len
-#        when Fixnum
-#          enc_value
-#        when Field
-#          _len.to_b(enc_value.length)
-#
-#    end
-#
-#    def check value
-#      if @min && value.length < @min
-#        raise ISO8583ParseException.new "Wrong length for: #{value}  (#{value.length}), min length #{@min}"
-#      end
-#      
-#      if @max && value.length > @max
-#        raise ISO8583ParseException.new "Wrong length for: #{value}  (#{value.length}), max length #{@max}"
-#      end
-#    end
-#    
-#    def _get_len raw
-#      return _len, raw if _len.is_a? Fixnum
-#      puts self.ancestors
-#      puts _len
-#      len_field, rest = _len.parse(raw)
-#      return len_field.value, rest
-#    end
-#    
-#
-#  end
-#end
-#

data/lib/fields.rb

@@ -1,130 +0,0 @@
-#--
-# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
-# MIT License, for details, see the LICENSE file accompaning
-# this distribution
-#++
-# This file contains a number of preinstantiated Field definitions. You
-# will probably need to create own fields in your implementation, please
-# see Field and Codec for further discussion on how to do this.
-# The fields currently available are those necessary to implement the 
-# Berlin Groups Authorization Spec.
-#
-# The following fields are available:
-#
-# [+LL+]           special form to de/encode variable length indicators, two bytes ASCII numerals
-# [+LLL+]          special form to de/encode variable length indicators, two bytes ASCII numerals
-# [+LLVAR_N+]      two byte variable length ASCII numeral, payload ASCII numerals
-# [+LLLVAR_N+]     three byte variable length ASCII numeral, payload ASCII numerals
-# [+LLVAR_Z+]      two byte variable length ASCII numeral, payload Track2 data 
-# [+LLVAR_ANS+]    two byte variable length ASCII numeral, payload ASCII+special
-# [+LLLVAR_ANS+]   three byte variable length ASCII numeral, payload ASCII+special
-# [+LLVAR_B+]      Two byte variable length binary payload
-# [+LLLVAR_B+]     Three byte variable length binary payload
-# [+N+]            fixed lengh numerals, repesented in ASCII, padding right justified using zeros
-# [+AN+]          fixed lengh ASCII [A-Za-z0-9], padding left justified using spaces.
-# [+ANP+]          fixed lengh ASCII [A-Za-z0-9] and space, padding left, spaces
-# [+ANS+]          fixed length ASCII  [\x20-\x7E], padding left, spaces
-# [+B+]            binary data, padding left using nulls (0x00)
-# [+MMDDhhmmss+]   Date, formatted as described in ASCII numerals
-# [+YYMMDDhhmmss+] Date, formatted as named in ASCII numerals
-# [+YYMM+]         Expiration Date, formatted as named in ASCII numerals
-
-
-# Special form to de/encode variable length indicators, two bytes ASCII numerals 
-LL         = Field.new
-LL.length  = 2
-LL.codec   = ASCII_Number
-LL.padding = lambda { |value|
-  sprintf("%02d", value)
-}
-# Special form to de/encode variable length indicators, three bytes ASCII numerals
-LLL         = Field.new
-LLL.length  = 3
-LLL.codec   = ASCII_Number
-LLL.padding = lambda { |value|
-  sprintf("%03d", value)
-}
-
-# Two byte variable length ASCII numeral, payload ASCII numerals
-LLVAR_N        = Field.new
-LLVAR_N.length = LL
-LLVAR_N.codec  = ASCII_Number
-
-# Three byte variable length ASCII numeral, payload ASCII numerals
-LLLVAR_N        = Field.new
-LLLVAR_N.length = LLL
-LLLVAR_N.codec  = ASCII_Number
-
-# Two byte variable length ASCII numeral, payload Track2 data
-LLVAR_Z         = Field.new
-LLVAR_Z.length  = LL
-LLVAR_Z.codec   = Track2
-
-# Two byte variable length ASCII numeral, payload ASCII+special
-LLVAR_ANS       = Field.new
-LLVAR_ANS.length= LL
-LLVAR_ANS.codec = ANS_Codec
-
-# Three byte variable length ASCII numeral, payload ASCII+special
-LLLVAR_ANS       = Field.new
-LLLVAR_ANS.length= LLL
-LLLVAR_ANS.codec = ANS_Codec
-
-# Two byte variable length binary payload
-LLVAR_B       = Field.new
-LLVAR_B.length= LL
-LLVAR_B.codec = Null_Codec
-
-
-# Three byte variable length binary payload
-LLLVAR_B       = Field.new
-LLLVAR_B.length= LLL
-LLLVAR_B.codec = Null_Codec
-
-# Fixed lengh numerals, repesented in ASCII, padding right justified using zeros
-N = Field.new
-N.codec = ASCII_Number
-N.padding = lambda {|val, len|
-  sprintf("%0#{len}d", val)
-}
-
-PADDING_LEFT_JUSTIFIED_SPACES = lambda {|val, len|
-  sprintf "%-#{len}s", val
-}
-
-# Fixed lengh ASCII [A-Za-z0-9], padding left justified using spaces.
-AN = Field.new
-AN.codec = AN_Codec
-AN.padding = PADDING_LEFT_JUSTIFIED_SPACES
-
-# Fixed lengh ASCII [A-Za-z0-9] and space, padding left, spaces
-ANP = Field.new
-ANP.codec = ANP_Codec
-ANP.padding = PADDING_LEFT_JUSTIFIED_SPACES
-
-# Fixed length ASCII  [\x20-\x7E], padding left, spaces
-ANS = Field.new
-ANS.codec = ANS_Codec
-ANS.padding = PADDING_LEFT_JUSTIFIED_SPACES
-
-# Binary data, padding left using nulls (0x00)
-B = Field.new
-B.codec = Null_Codec
-B.padding = lambda {|val, len|
-  while val.length < len
-    val = val + "\000"
-  end
-  val
-}
-
-# Date, formatted as described in ASCII numerals
-MMDDhhmmss = Field.new
-MMDDhhmmss.codec = MMDDhhmmssCodec
-
-#Date, formatted as described in ASCII numerals
-YYMMDDhhmmss = Field.new
-YYMMDDhhmmss.codec = YYMMDDhhmmssCodec
-
-#Date, formatted as described in ASCII numerals
-YYMM = Field.new
-YYMM.codec = YYMMCodec

data/lib/message.rb

@@ -1,416 +0,0 @@
-# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
-# MIT License, for details, see the LICENSE file accompaning
-# this distribution
-
-# The class `Message` defines functionality to describe classes
-# representing different type of messages, or message families.
-# A message family consists of a number of possible message types that
-# are allowed, and a way of naming and encoding the bitmaps allowed in
-# the messages.
-#
-# To create your own message, start by subclassing Message:
-#
-#    class MyMessage < Message
-#       (...)
-#    end
-#
-# the subtyped message should be told how the MTI is encoded:
-#
-#    class MyMessage < Message
-#       mti_format N, :length => 4
-#       (...)
-#    end
-#
-# `N` above is an instance of Field which encodes numbers into their
-# ASCII representations in  a fixed length field. The option `length=>4`
-# indicates the length of the fixed field.
-#
-# Next, the allowed message types are specified:
-#
-#    class MyMessage < Message
-#       (...)
-#       mti 1100, "Authorization Request Acquirer Gateway"
-#       mti 1110, "Authorization Request Response Issuer Gateway"
-#       (...)
-#    end
-#
-# This basically defines to message types, 1100 and 1110 which may
-# be accessed later either via their name or value:
-#
-#    mes = MyMessage.new 1100
-# 
-# or
-#    mes = MyMessage.new "Authorization Request Acquirer Gateway"
-#
-# or
-#    mes = MyMessage.new
-#    mes.mti = 1110 # or Auth. Req. Acq. Gateway ...
-#
-# Finally the allowed bitmaps, their names and the encoding rules are
-# specified:
-#
-#    class MyMessage < Message
-#       (...)
-#       bmp  2, "Primary Account Number (PAN)",               LLVAR_N,   :max    => 19
-#       bmp  3,  "Processing Code",                           N,         :length =>  6
-#       bmp  4,  "Amount (Transaction)",                      N,         :length => 12
-#       bmp  6,  "Amount, Cardholder Billing" ,               N,         :length => 12
-#       (...)
-#    end
-#
-# The example above defines four bitmaps (2,3,4 and 6), and provides
-# their bitmap number and description. The PAN field is variable length
-# encoded (LL length indicator, ASCII, contents numeric, ASCII) and the
-# maximum length of the field is limited to 19 using options.
-#
-# The other fields are fixed length numeric ASCII fields (the length of the fields is
-# indicated by the `:length` options.)
-#
-# This message may be used as follows in order to interpret a received message.:
-#
-#    mes = MyMessage.parse inputData
-#    puts mes[2] # prints the PAN from the message.
-#
-# Constructing own messages works as follows:
-#
-#     mes = MyMessage.new 1100 
-#     mes[2]= 474747474747
-#     # Alternatively
-#     mes["Primary Account Number (PAN)"]= 4747474747
-#     mes[3] = 1234 # padding is added by the Field en/decoder
-#     mes["Amount (Transaction)"] = 100
-#     mes[6] = 200
-#
-# the convenience method bmp_alias may be used in defining the class in
-# order to provide direct access to fields using methods:
-#
-#    class MyMessage < Message
-#       (...)
-#       bmp  2, "Primary Account Number (PAN)",               LLVAR_N,   :max    => 19
-#       (...)
-#       bmp_alias 2, :pan
-#    end
-#
-# this allows accessing fields in the following manner:
-#
-#     mes = MyMessage.new 1100
-#     mes.pan = 474747474747
-#     puts mes.pan
-#     # Identical functionality to:
-#     mes[2]= 474747474747
-#     # or:
-#     mes["Primary Account Number (PAN)"]= 4747474747
-#
-# Most of the work in implementing a new set of message type lays in
-# figuring out the correct fields to use defining the Message class via
-# bmp.
-#    
-
-
-class Message 
-  
-  # The value of the MTI (Message Type Indicator) of this message.
-  attr_reader :mti 
-
-  # Instantiate a new instance of this type of Message
-  # optionally specifying an mti. 
-  def initialize mti=nil
-    # values is an internal field used to collect all the
-    # bmp number | bmp name | field en/decoders | values
-    # which are set in this message.
-    @values = {}
-    self.mti= mti if mti
-  end
-
-  # Set the mti of the Message using either the actual value
-  # or the name of the message type that was defined using
-  # Message.mti
-  #
-  # === Example
-  #    class MyMessage < Message
-  #      (...)
-  #      mti 1100, "Authorization Request Acquirer Gateway"
-  #    end
-  #
-  #    mes = MyMessage.new
-  #    mes.mti = 1100 # or mes.mti = "Authorization Request Acquirer Gateway"
-
-  def mti= value
-    num, name = _get_mti_definition(value)
-    @mti = num
-  end
-  
-  # Set a field in this message, `key` is either the
-  # bmp number or it's name.
-  # ===Example
-  #
-  #    mes = BlaBlaMessage.new
-  #    mes[2]=47474747                          # bmp 2 is generally the PAN
-  #    mes["Primary Account Number"]=47474747   # if thats what you called the field in Message.bmp.
-  def []= key, value
-    bmp_def              = _get_definition key
-    bmp_def.value        = value
-    @values[bmp_def.bmp] = bmp_def 
-  end
-
-  # Retrieve the decoded value of the contents of a bitmap
-  # described either by the bitmap number or name.
-  #
-  # ===Example
-  #
-  #    mes = BlaBlaMessage.parse someMessageBytes
-  #    mes[2] # bmp 2 is generally the PAN
-  #    mes["Primary Account Number"] # if thats what you called the field in Message.bmp.
-  def [] key
-    bmp_def = _get_definition key
-    bmp     = @values[bmp_def.bmp]
-    bmp ? bmp.value : nil
-  end
-  
-  # Retrieve the byte representation of the bitmap.
-  def to_b
-    raise ISO8583Exception.new "no MTI set!" unless mti
-    mti_enc = self.class._mti_format.encode(mti)
-    bitmap  = Bitmap.new
-    message = ""
-    @values.keys.sort.each{|bmp_num|
-      bitmap.set(bmp_num)
-      enc_value = @values[bmp_num].encode
-      message << enc_value
-    }
-    mti_enc+bitmap.to_bytes + message
-  end
-  
-  # Returns a nicely formatted representation of this
-  # message.
-  def to_s
-    _mti_name = _get_mti_definition(mti)[1]
-    str = "MTI:#{mti} (#{_mti_name})\n\n"
-    _max = @values.values.max {|a,b|
-      a.name.length <=> b.name.length
-    }
-    _max_name = _max.name.length
-    
-    @values.keys.sort.each{|bmp_num|
-      _bmp = @values[bmp_num]
-      str += ("%03d %#{_max_name}s : %s\n" % [bmp_num, _bmp.name, _bmp.value])
-    }
-    str
-  end
-
-  def _get_definition key #:nodoc:
-    b = self.class._definitions[key]
-    unless b
-      raise ISO8583Exception.new "no definition for field: #{key}"
-    end
-    b
-  end
-
-  # return [mti_num, mti_value] for key being either
-  # mti_num or mti_value
-  def _get_mti_definition key #:nodoc:
-    num_hash,name_hash = self.class._mti_definitions
-    if    num_hash[key]
-      [key, num_hash[key]]
-    elsif name_hash[key]
-      [name_hash[key], key]
-    else
-      raise ISO8583Exception.new("MTI: #{key} not allowed!")
-    end
-    
-  end
-
-  class << self
-    
-    # Defines how the message type indicator is encoded into bytes. 
-    # ===Params:
-    # * field    : the decoder/encoder for the MTI
-    # * opts     : the options to pass to this field
-    #
-    # === Example
-    #     class MyMessage < Message
-    #       mti_format N, :length =>4
-    #       (...)
-    #     end
-    #
-    # encodes the mti of this message using the `N` field (fixed
-    # length, plain ASCII) and sets the fixed lengh to 4 bytes.
-    #
-    # See also: mti
-    def mti_format field, opts 
-      f = field.dup
-      _handle_opts(f, opts)
-      @mti_format = f
-    end
-    
-    # Defines the message types allowed for this type of message and
-    # gives them names
-    # 
-    # === Example
-    #    class MyMessage < Message
-    #      (...)
-    #      mti 1100, "Authorization Request Acquirer Gateway"
-    #    end
-    #
-    #    mes = MyMessage.new
-    #    mes.mti = 1100 # or mes.mti = "Authorization Request Acquirer Gateway"
-    #
-    # See Also: mti_format
-
-    def mti value, name
-      @mtis_v ||= {}
-      @mtis_n ||= {}
-      @mtis_v[value] = name
-      @mtis_n[name]  = value
-    end
-
-    #
-    # Define a bitmap in the message
-    # ===Params:
-    # * bmp   : bitmap number
-    # * name  : human readable form
-    # * field : field for encoding/decoding
-    # * opts  : options to pass to the field, e.g. length for fxed len fields.
-    #
-    # ===Example
-    #
-    #    class MyMessage < Message
-    #      bmp 2, "PAN", LLVAR_N, :max =>19
-    #      (...)
-    #    end
-    #
-    # creates a class MyMessage that allows for a bitmap 2 which 
-    # is named "PAN" and encoded by an LLVAR_N Field. The maximum 
-    # length of the value is 19. This class may be used as follows:
-    #
-    #    mes = MyMessage.new
-    #    mes[2] = 474747474747 # or mes["PAN"] = 4747474747
-    #
-    #
-    def bmp bmp, name, field, opts=nil
-      @defs ||= {}
-
-      field = field.dup
-      field.name = name
-      field.bmp  = bmp
-      _handle_opts(field, opts) if opts
-      
-      bmp_def = BMP.new bmp, name, field
-
-      @defs[bmp]  = bmp_def
-      @defs[name] = bmp_def
-    end
-    
-    # Create an alias to access bitmaps directly using a method.
-    # Example:
-    #     class MyMessage < Message
-    #         (...)
-    #         bmp 2, "PAN", LLVAR_N
-    #         (...)
-    #         bmp_alias 2, :pan
-    #     end #class
-    #
-    # would allow you to access the PAN like this:
-    #
-    #    mes.pan = 1234
-    #    puts mes.pan
-    #
-    # instead of:
-    #
-    #    mes[2] = 1234
-    #
-    def bmp_alias bmp, aliaz
-      define_method (aliaz) {
-        bmp_ = @values[bmp]
-        bmp_ ? bmp_.value : nil
-      }
-
-      define_method ("#{aliaz}=") { |value|
-        self[bmp]=value
-        #bmp_def = _get_definition(bmp)
-        #bmp_def.value= value
-        #@values[bmp] = bmp_def
-      }
-    end
-    
-    # Parse the bytes `str` returning a message of the defined type.
-    def parse str
-      message = self.new
-      message.mti, rest = _mti_format.parse str
-      bmp,rest = Bitmap.parse(rest)
-      bmp.each {|bit|
-        bmp_def     = _definitions[bit]
-        value, rest = bmp_def.field.parse(rest)
-        message[bit] = value
-      }
-      return message
-    end
-   
-
-    # METHODS starting with an underscore are meant for
-    # internal use only ...
-
-    #
-    # Access the field definitions of this class, this is a
-    # hash containing [bmp_number, BMP] and [bitmap_name, BMP]
-    # pairs.
-    #
-    def _definitions #:nodoc:
-      @defs
-    end
-
-    #
-    # access the mti definitions applicable to the Message
-    #
-    # returns a pair of hashes containing:
-    #
-    # mti_value => mti_name
-    #
-    # mti_name => mti_value
-    #
-    def _mti_definitions #:nodoc:
-      [@mtis_v, @mtis_n]
-    end
-    
-    
-    # Returns the field definition to format the mti.
-    def _mti_format #:nodoc:
-      @mti_format
-    end
-    
-    #
-    # Modifies the field definitions of the fields passed
-    # in through the `bmp` and `mti_format` class methods.
-    #
-    def _handle_opts field, opts #:nodoc:
-      opts.each_pair {|key, value|
-        key = (key.to_s+"=").to_sym
-        if field.respond_to? key
-          field.send(key, value)
-        else
-          warn "unknown option #{key} for #{field.name}"
-        end
-      }
-    end
-  end
-end
-
-# Internal class used to tie together name, bitmap number, field en/decoder
-# and the value of the corresponding field
-class BMP #:nodoc:
-  
-  attr_accessor :bmp
-  attr_accessor :name
-  attr_accessor :field
-  attr_accessor :value
-
-  def initialize bmp, name, field
-    @bmp   = bmp
-    @name  = name
-    @field = field
-  end
-  def encode
-    field.encode(value)
-  end
-end
-