iso8583 0.1.1 → 0.1.3

data/lib/8583/exception.rb

@@ -0,0 +1,4 @@
+module ISO8583
+  class ISO8583Exception < Exception; end
+  class ISO8583ParseException < ISO8583Exception; end
+end

data/lib/8583/field.rb

@@ -0,0 +1,90 @@
+module ISO8583
+
+  class Field
+    # may either be some other Field in which the length is encoded or a Fixnum for
+    # fixed length fields. Length should always be the length of the *encoded* value.
+    # A 6 digit BCD field will require a length 3, as will a 5 digit BCD field.
+    # The subclass BCDField handles this to keep things consistant.
+    attr_accessor :length
+    attr_accessor :codec
+    attr_accessor :padding
+    attr_accessor :max
+
+    attr_writer   :name
+    attr_accessor :bmp
+
+    def name
+      "BMP #{bmp}: #{@name}"
+    end
+
+    def parse(raw)
+      len, raw = case length
+                 when Fixnum
+                   [length, raw]
+                 when Field
+                   length.parse(raw)
+                 else
+                   raise ISO8583Exception.new("Cannot determine the length of '#{name}' field")
+                 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]
+      begin
+        real_value = codec.decode(raw_value)
+      rescue
+        raise ISO8583ParseException.new($!.message+" (#{name})")
+      end
+
+      [ 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.
+    # In other cases, the padding has to be implemented by the codec, such as BCD with an odd number of nibbles.
+    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} (#{name})! length=#{length}")  if encoded_value.length > length
+                  raise ISO8583Exception.new("Too short: #{value} (#{name})! length=#{length}") 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("Invalid length (#{length}) for '#{name}' field")
+                end
+
+      len_str + encoded_value
+    end
+  end
+
+  class BCDField < Field
+    # This corrects the length for BCD fields, as their encoded length is half (+ parity) of the
+    # content length. E.g. 123 (length = 3) encodes to "\x01\x23" (length 2)
+    def length
+      _length = super
+      (_length % 2) != 0 ? (_length / 2) + 1 : _length / 2
+    end
+  end
+
+end

data/lib/8583/fields.rb

@@ -0,0 +1,148 @@
+#--
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+#++
+
+module ISO8583
+
+  # 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
+  # [+LL_BCD+]       special form to de/encode variable length indicators, two BCD digits
+  # [+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.name    = "LL"
+  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.name    = "LLL"
+  LLL.length  = 3
+  LLL.codec   = ASCII_Number
+  LLL.padding = lambda {|value|
+    sprintf("%03d", value)
+  }
+
+  LL_BCD        = BCDField.new
+  LL_BCD.length = 2
+  LL_BCD.codec  = Packed_Number
+
+  # 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)
+  }
+
+  N_BCD = BCDField.new
+  N_BCD.codec = Packed_Number
+
+  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
+  MMDDhhmmss.length = 10
+
+  #Date, formatted as described in ASCII numerals
+  YYMMDDhhmmss        = Field.new
+  YYMMDDhhmmss.codec  = YYMMDDhhmmssCodec
+  YYMMDDhhmmss.length = 12
+
+  #Date, formatted as described in ASCII numerals
+  YYMM        = Field.new
+  YYMM.codec  = YYMMCodec
+  YYMM.length = 4
+
+end

data/lib/8583/message.rb

@@ -0,0 +1,419 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+module ISO8583
+
+  # 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)
+      mti_enc << _body.join
+    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
+
+
+    # METHODS starting with an underscore are meant for
+    # internal use only ...
+    
+    # Returns an array of two byte arrays:
+    # [bitmap_bytes, message_bytes]
+    def _body
+      bitmap  = Bitmap.new
+      message = ""
+      @values.keys.sort.each do |bmp_num|
+        bitmap.set(bmp_num)
+        enc_value = @values[bmp_num].encode
+        message << enc_value
+      end
+      [ bitmap.to_bytes, message ]
+    end
+
+    def _get_definition(key) #:nodoc:
+      b = self.class._definitions[key]
+      unless b
+        raise ISO8583Exception.new "no definition for field: #{key}"
+      end
+      b.dup
+    end
+
+    # return [mti_num, mti_value] for key being either
+    # mti_num or mti_value
+    def _get_mti_definition(key)
+      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
+        }
+        message
+      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
+        [@mtis_v, @mtis_n]
+      end
+      
+      # Access the field definitions of this class, this is a
+      # hash containing [bmp_number, BMP] and [bitmap_name, BMP]
+      # pairs.
+      #
+      def _definitions
+        @defs
+      end
+
+      # Returns the field definition to format the mti.
+      def _mti_format
+        @mti_format
+      end
+
+
+
+      # METHODS starting with an underscore are meant for
+      # internal use only ...
+
+      # Modifies the field definitions of the fields passed
+      # in through the `bmp` and `mti_format` class methods.
+      #
+      def _handle_opts(field, opts)
+        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
+    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
+
+end