iso8583 0.1.0

data/lib/exception.rb

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

data/lib/field.rb

@@ -0,0 +1,178 @@
+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

@@ -0,0 +1,130 @@
+#--
+# 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/iso8583.rb

@@ -0,0 +1,9 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require "field"
+require "codec"
+require "fields"
+require "exception"
+require "bitmap"
+require "message"

data/lib/message.rb

@@ -0,0 +1,416 @@
+# 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
+