iso8583 0.1.1 → 0.1.3

data/AUTHORS

@@ -1 +1,2 @@
 Tim Becker (tim@kuriositaet.de)
+Slava Kravchenko (cordawyn@gmail.com)

data/CHANGELOG

@@ -0,0 +1,10 @@
+0.1.3
+==========
+  bugfix, field definitions not duplicated
+  THANKS: Toni Lyytikäinen
+0.1.2
+==========
+  branched from original 0.1.1;
+  cleaned-up files;
+  put all stuff into ISO8583 namespace (module)
+  rearrange files under `lib` dir

data/README

@@ -1,5 +1,5 @@
 
-= ISO 8583 Financial Messaging for Ruby 
+= ISO 8583 Financial Messaging for Ruby
 
 This package currently contains code for coding an decoding ISO 8583
 Financial Message.
@@ -12,38 +12,16 @@ class you need to use ...
 
 == Installing
 
-You can install the +hello+ package by executing:
+You can install the +iso8583+ package by executing:
 
-	gem install iso7816 -r
-
-alternatively, you can download +.tar.gz+ or +.zip+ archives from 
-Rubyforge[http://rubyforge.org/frs/?group_id=1791].
+	gem install iso8583
 
 == Source
 
-The source is most readily available on github[http://github.com/a2800276/8583/], 
-and there should usually be a more or less current version available
-in the Rubyforge SVN repository.
-
+The source is most readily available on github[http://github.com/cordawyn/8583].
 
 == Mailing List
 
 In case you discover bugs, spelling errors, offer suggestions for
 improvements or would like to help out with the project, you can contact
-me directly (tim@kuriositaet.de).	
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-=
+me directly (tim@kuriositaet.de).

data/Rakefile

@@ -7,21 +7,21 @@ require "rubygems"
 # Some definitions that you'll need to edit in case you reuse this
 # Rakefile for your own project.
 
-SHORTNAME	='iso8583'	# this should be the rubyforge project name
-DESC		="Ruby implementation of ISO 8583 financial messaging"
-PKG_VERSION 	='0.1.1'
+SHORTNAME	= "iso8583"	# this should be the rubyforge project name
+DESC		= "Ruby implementation of ISO 8583 financial messaging"
+PKG_VERSION 	= "0.1.3"
 LONG_DESC	= <<END_DESC
-	Ruby implementation of ISO 8583 financial messaging
+Ruby implementation of ISO 8583 financial messaging
 END_DESC
-RUBYFORGE_USER	='a2800276'
+RUBYFORGE_USER	= "a2800276"
 
 # Specifies the default task to execute. This is often the "test" task
 # and we'll change things around as soon as we have some tests.
 
-task  :default => [:rdoc]
+task  :default => [:test]
 
 # The directory to generate +rdoc+ in.
-RDOC_DIR="doc/html"
+RDOC_DIR = "doc/html"
 
 # This global variable contains files that will be erased by the `clean` task.
 # The `clean` task itself is automatically generated by requiring `rake/clean`.
@@ -34,32 +34,32 @@ CLEAN << RDOC_DIR << "pkg"
 # task called `rdoc`.
 
 Rake::RDocTask.new do |rd|
-	# Options for documenation generation are specified inside of
-	# this block. For example the following line specifies that the
-	# content of the README file should be the main page of the
-	# documenation.
-	rd.main = "README" 
-	
-	# The following line specifies all the files to extract
-	# documenation from.
-	rd.rdoc_files.include(	"README", "AUTHORS", "LICENSE", "TODO",
-				"CHANGELOG", "bin/**/*", "lib/**/*.rb", 
-				"examples/**/*rb", "doc/*.rdoc")
-	# This one specifies the output directory ...
-	rd.rdoc_dir 	= "doc/html"
-
-	# Or the HTML title of the generated documentation set.
-	rd.title 	= "#{SHORTNAME}: #{DESC}"
-
-	# These are options specifiying how source code inlined in the
-	# documentation should be formatted.
-	
-	rd.options 	= ["--line-numbers", "--inline-source"]
-
-	# Check:
-	# `rdoc --help` for more rdoc options
-	# the {rdoc documenation home}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
-	# or the documentation for the +Rake::RDocTask+ task[http://rake.rubyforge.org/classes/Rake/RDocTask.html]
+  # Options for documenation generation are specified inside of
+  # this block. For example the following line specifies that the
+  # content of the README file should be the main page of the
+  # documenation.
+  rd.main = "README"
+
+  # The following line specifies all the files to extract
+  # documenation from.
+  rd.rdoc_files.include("README", "AUTHORS", "LICENSE", "TODO",
+			"CHANGELOG", "bin/**/*", "lib/**/*.rb",
+                        "examples/**/*rb", "doc/*.rdoc")
+  # This one specifies the output directory ...
+  rd.rdoc_dir 	= "doc/html"
+
+  # Or the HTML title of the generated documentation set.
+  rd.title 	= "#{SHORTNAME}: #{DESC}"
+
+  # These are options specifiying how source code inlined in the
+  # documentation should be formatted.
+
+  rd.options 	= ["--line-numbers", "--inline-source"]
+
+  # Check:
+  # `rdoc --help` for more rdoc options
+  # the {rdoc documenation home}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
+  # or the documentation for the +Rake::RDocTask+ task[http://rake.rubyforge.org/classes/Rake/RDocTask.html]
 end
 
 # The GemPackageTask facilitates getting all your files collected
@@ -68,30 +68,29 @@ end
 
 # First you'll need to assemble a gemspec
 
-PKG_FILES 	= FileList['lib/**/*.rb', 'bin/**/*', 'examples/**/*', '[A-Z]*', 'test/**/*'].to_a
+PKG_FILES 	= FileList["lib/**/*.rb", "bin/**/*", "examples/**/*", "[A-Z]*", "test/**/*"].to_a
 
 spec = Gem::Specification.new do |s|
-	s.platform = Gem::Platform::RUBY
-	s.summary = "#{SHORTNAME}: #{DESC}"
-	s.name = SHORTNAME
-	s.rubyforge_project = SHORTNAME
-	s.version = PKG_VERSION
-	s.files = PKG_FILES
-	s.requirements << "none"
-	s.require_path = 'lib'
-	s.description = LONG_DESC
-  s.has_rdoc=true
-  s.author="Tim Becker"
-  s.email="tim.becker@kuriositaet.de"
-  s.homepage="http://iso8583.rubyforge.org/"
-
+  s.platform = Gem::Platform::RUBY
+  s.summary = "#{SHORTNAME}: #{DESC}"
+  s.name = SHORTNAME 
+  s.rubyforge_project = SHORTNAME
+  s.version = PKG_VERSION
+  s.files = PKG_FILES
+  s.requirements << "none"
+  s.require_path = "lib"
+  s.description = LONG_DESC
+  s.has_rdoc = true
+  s.authors = ["Tim Becker", "Slava Kravchenko"]
+  s.email = ["tim.becker@kuriositaet.de","cordawyn@gmail.com"]
+  s.homepage = "http://github.com/a2800276/8583/"
 end
 
 # Adding a new GemPackageTask adds a task named `package`, which generates
 # packages as gems, tarball and zip archives.
 Rake::GemPackageTask.new(spec) do |pkg|
-	pkg.need_zip = true
-	pkg.need_tar_gz = true
+  pkg.need_zip = true
+  pkg.need_tar_gz = true
 end
 
 
@@ -105,7 +104,7 @@ end
 # Windows. I'm currently not aware of any pure ruby way to do scp
 # transfers.
 
-RubyForgeProject=SHORTNAME
+RubyForgeProject = SHORTNAME
 
 desc "Upload the web pages to the web."
 task :upload_pages => ["rdoc"] do
@@ -119,13 +118,10 @@ end
 # This task will run the unit tests provided in files called
 # `test/test*.rb`. The task itself can be run with a call to `rake test`
 
-Rake::TestTask.new do |t| 
-	t.libs << "test" 
-	t.libs << "lib" 
-	t.ruby_opts=["-rubygems"]
-	t.test_files = FileList['test/*.rb'] 
-	t.verbose = true 
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.ruby_opts = ["-rubygems"]
+  t.test_files = FileList["test/*.rb"]
+  t.verbose = true
 end
-
-
-

data/lib/8583.rb

@@ -0,0 +1,12 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+module ISO8583
+  require "8583/field"
+  require "8583/codec"
+  require "8583/fields"
+  require "8583/exception"
+  require "8583/bitmap"
+  require "8583/message"
+  require "8583/util"
+end

data/lib/8583/berlin.rb

@@ -0,0 +1,82 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+require 'lib/iso8583'
+
+
+# Example of a protocol specification based on:
+# http://www.berlin-group.org/documents/BG_Authorisation_3.0.pdf
+# The Berlin Groups Authorisation Interface specification.
+# No gurantees are made that this is an accurate implemenation.
+# It currently serves as an example only.
+
+module ISO8583
+
+  class BerlinMessage < Message
+    mti_format N, :length => 4
+    mti 1100, "Authorization Request Acquirer Gateway"
+    mti 1110, "Authorization Request Response Issuer Gateway"
+    mti 1420, "Reversal Advice Acquirer Gateway" 
+    mti 1421, "Reversal Advice Repeat Acquirer Gateway" 
+    mti 1430, "Reversal Advice Response Issuer Gateway" 
+    mti 1804, "Network Management Request Acquirer Gateway or Issuer Gateway"
+    mti 1814, "Network Management Request Response Issuer Gateway or Acquirer Gateway"
+
+    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
+    bmp  7,  "Date and Time, Transmission"  ,             MMDDhhmmss
+    bmp 10, "Conversion Rate, Cardholder Billing",        N,         :length =>  8
+    bmp 11, "System Trace Audit Number (STAN)",           N,         :length =>  6
+    bmp 12, "Date and Time, Local Transaction",           YYMMDDhhmmss
+    bmp 14, "Date, Expiration",                           YYMM
+    bmp 22, "POS Data Code",                              AN,        :length => 12
+    bmp 23, "Card Sequence Number",                       N,         :length =>  3
+    bmp 24, "Function Code",                              N,         :length =>  3
+    bmp 25, "Message Reason Code",                        N,         :length =>  4
+    bmp 26, "Card Acceptor Business Code",                N,         :length =>  4
+    bmp 30, "Amounts, Original",                          N,         :length => 24
+    bmp 32, "Acquiring Institution Identification Code",  LLVAR_N,   :max    => 11
+    bmp 35, "Track 2 Data",                               LLVAR_Z,   :max    => 37
+    bmp 37, "Retrieval Reference Number",                 ANP,       :length => 12
+    bmp 38, "Approval Code",                              ANP,       :length =>  6
+    bmp 39, "Action Code",                                N,         :length =>  3
+    bmp 41, "Card Acceptor Terminal Identification",      ANS,       :length =>  8
+    bmp 42, "Card Acceptor Identification Code",          ANS,       :length => 15
+    bmp 43, "Card Acceptor Name/Location",                LLVAR_ANS, :max    => 56
+    bmp 49, "Currency Code, Transaction",                 N,         :length =>  3
+    bmp 51, "Currency Code, Cardholder Billing",          N,         :length =>  3
+    bmp 52, "Personal Identification Number (PIN) Data",  B,         :length =>  8
+    bmp 53, "Security Related Control Information",       LLVAR_B,   :max    => 48
+    bmp 54, "Amounts, Additional",                        LLLVAR_ANS,:max    => 40
+
+    bmp 55, "Integrated Circuit Card (ICC) System Related Data", LLLVAR_B,   :max    => 255
+    bmp 56, "Original Data Elements",                            LLVAR_N,    :max    => 35
+    bmp 58, "Authorizing Agent Institution Identification Code", LLVAR_N,    :max    => 11
+    bmp 59, "Additional Data - Private",                         LLLVAR_ANS, :max    => 67
+    bmp 64, "Message Authentication Code (MAC) Field",           B,          :length => 8
+    
+    bmp_alias  2, :pan
+    bmp_alias  3, :proc_code
+    bmp_alias  4, :amount
+    bmp_alias 12, :exp_date
+  end
+
+end
+
+if __FILE__==$0
+  mes = ISO8583::BerlinMessage.new
+  mes.mti = 1110
+  mes[2] = 474747474747
+  mes["Processing Code"] = "123456"
+
+  pan = mes["Primary Account Number (PAN)"]
+  #mes.pan = 47474747474747
+
+  #puts mes.pan
+  puts mes.to_b
+  puts mes.to_s
+  #mes2 = BerlinMessage.parse input
+end

data/lib/8583/bitmap.rb

@@ -0,0 +1,117 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+module ISO8583
+
+  # This class constructs an object for handling bitmaps
+  # with which ISO8583 messages typically begin.
+  # Bitmaps are either 8 or 16 bytes long, an extended length
+  # bitmap is indicated by the first bit being set.
+  # In all likelyhood, you won't be using this class much, it's used
+  # transparently by the Message class.
+  class Bitmap
+
+    # create a new Bitmap object. In case an iso message
+    # is passed in, that messages bitmap will be parsed. If
+    # not, this initializes and empty bitmap.
+    def initialize(message = nil)
+      @bmp = Array.new(128, false)
+      if !message
+
+      else
+        initialize_from_message message
+      end
+    end
+    
+    # yield once with the number of each set field.
+    def each #:yields: each bit set in the bitmap.
+      @bmp.each_with_index {|set, i| yield i+1 if set}
+    end
+    
+    # Returns whether the bit is set or not.
+    def [](i)
+      @bmp[i-1]
+    end
+
+    # Set the bit to the indicated value. Only `true` sets the
+    # bit, any other value unsets it.
+    def []=(i, value)
+      if i > 128 
+        raise ISO8583Exception.new("Bits > 128 are not permitted.")
+      elsif i < 2
+        raise ISO8583Exception.new("Bits < 2 are not permitted (continutation bit is set automatically)")
+      end
+      @bmp[i-1] = (value == true)
+    end
+
+    # Sets bit #i
+    def set(i)
+      self[i] = true
+    end
+    
+    # Unsets bit #i
+    def unset(i)
+      self[i] = false
+    end
+
+    # Generate the bytes representing this bitmap.
+    def to_bytes
+      arr = [self.to_s]
+      # tricky and ugly, setting bit[1] only when generating to_s...
+      count = self[1] ? 128 : 64
+      arr.pack("B#{count}")
+    end
+    alias_method :to_b, :to_bytes
+
+    # Generate a String representation of this bitmap in the form:
+    #	01001100110000011010110110010100100110011000001101011011001010
+    def to_s
+      #check whether any `high` bits are set
+      @bmp[0] = false
+      65.upto(128) {|i|
+        if self[i]
+          # if so, set continuation bit
+          @bmp[0] = true
+          break
+        end
+      }
+      str = ""
+      1.upto(self[1] ? 128 : 64) {|i|
+        str << (self[i] ? "1" : "0")
+      }
+      str
+    end
+
+
+    private
+
+    def initialize_from_message(message)
+      bmp = message.unpack("B64")[0]
+      if bmp[0,1] == "1"
+        bmp = message.unpack("B128")[0]
+      end
+
+      0.upto(bmp.length-1) do |i|
+        @bmp[i] = (bmp[i,1] == "1")
+      end
+    end
+
+    class << self
+      # Parse the bytes in string and return the Bitmap and bytes remaining in `str`
+      # after the bitmap is taken away.
+      def parse(str)
+        bmp  = Bitmap.new(str)
+        rest = bmp[1] ? str[16, str.length] : str[8, str.length]
+        [ bmp, rest ]
+      end
+    end
+    
+  end
+end
+
+if __FILE__==$0
+  mp = ISO8583::Bitmap.new
+  20.step(128,7) {|i| mp.set(i)}
+  print mp.to_bytes
+end

data/lib/8583/codec.rb

@@ -0,0 +1,189 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+require 'date'
+
+module ISO8583
+
+  # Codec provides functionality to encode and decode values, codecs are
+  # used internally by Field instances in order to do character conversions
+  # and checking for proper values.
+  # Although they are used internally, you will probably need to write
+  # your own Codec sooner or later. The codecs used by Field instances are
+  # typically instances of Codec, it may or may not be usefull to subclass
+  # Codec.
+  # 
+  # Say, for example, a text field needs to be encoded in EBCDIC in the
+  # message, this is how a corresponding codec would be constructed:
+  #
+  #    EBCDIC_Codec = Codec.new
+  #    EBCDIC_Codec.encoder = lambda {|ascii_str|
+  #       raise ISO8583Exception.new("String (#{ascii_str})not valid!") unless =~ /someregexp/
+  #       ascii2ebcdic ascii_str  # implementing ascii_str is left as an excercise
+  #    }
+  #    EBCDIC_Codec.decode = lambda {|ebcdic_str|
+  #       # you may or may not want to raise exceptions at this point ....
+  #       # strip removes any padding...
+  #       ebcdic2ascii(ebcdic_str).strip
+  #    }
+  #
+  # This instance of Codec would then be used be the corresponding Field
+  # encoder/decoder, which may look similar to this:
+  #
+  #    EBCDIC         = Field.new
+  #    EBCDIC.codec   = EBCDIC_Codec
+  #    EBCDIC.padding = PADDING_LEFT_JUSTIFIED_SPACES
+  #
+  # Notice there is a bit of inconsistancy: the padding is added by the
+  # field, but removed by the codec. I would like to find a better
+  # solution to this...
+  #
+  # See also: Field, link:files/lib/fields_rb.html
+  #
+  # The following codecs are already implemented:
+  # [+ASCII_Number+]      encodes either a Number or String representation of 
+  #                       a number to the ASCII represenation of the number, 
+  #                       decodes ASCII  numerals to a number
+  # [+AN_Codec+]          passes through ASCII string checking they conform to [A-Za-z0-9]
+  #                       during encoding, no validity check during decoding. 
+  # [+ANP_Codec+]         passes through ASCII string checking they conform to [A-Za-z0-9 ] 
+  #                       during encoding, no validity check during decoding. 
+  # [+ANS_Codec+]         passes through ASCII string checking they conform to [\x20-\x7E]
+  #                       during encoding, no validity check during decoding.
+  # [+Null_Codec+]        passes anything along untouched.
+  # [<tt>Track2</tt>]     rudimentary check that string conforms to Track2
+  # [+MMDDhhmmssCodec+]   encodes Time, Datetime or String to the described date format, checking 
+  #                       that it is a valid date. Decodes to a DateTime instance, decoding and 
+  #                       encoding perform validity checks!
+  # [+YYMMDDhhmmssCodec+] encodes Time, Datetime or String to the described date format, checking 
+  #                       that it is a valid date. Decodes to a DateTime instance, decoding and 
+  #                       encoding perform validity checks!
+  # [+YYMMCodec+]         encodes Time, Datetime or String to the described date format (exp date), 
+  #                       checking that it is a valid date. Decodes to a DateTime instance, decoding
+  #                       and encoding perform validity checks!
+  #
+  class Codec
+    attr_accessor :encoder
+    attr_accessor :decoder
+
+    def decode(raw)
+      decoder.call(raw)
+    end
+
+    # length is either a fixnum or a lenth encoder.
+    def encode(value)
+      encoder.call(value)
+    end
+  end
+
+  # ASCII_Number
+  ASCII_Number = Codec.new
+  ASCII_Number.encoder= lambda{|num|
+    enc = num.to_s
+    raise ISO8583Exception.new("Invalid value: #{enc} must be numeric!") unless enc =~ /^[0-9]*$/
+    enc
+  }
+
+  ASCII_Number.decoder = lambda{|raw|
+    raw.to_i
+  }
+
+  PASS_THROUGH_DECODER = lambda{|str|
+    str.strip # remove padding
+  }
+
+  # Takes a number or str representation of a number and BCD encodes it, e.g.
+  # "1234" => "\x12\x34"
+  # 3456   => "\x34\x56"
+  #
+  # right justified with null ... (correct to do this? almost certainly not...)
+  Packed_Number = Codec.new
+  Packed_Number.encoder = lambda { |val|
+    val = val.to_s
+    val = val.length % 2 == 0 ? val : "0"+val
+    raise ISO8583Exception.new("Invalid value: #{val} must be numeric!") unless val =~ /^[0-9]*$/
+    [val].pack("H*")
+  }
+  Packed_Number.decoder = lambda{|encoded|
+    d = encoded.unpack("H*")[0].to_i
+  }
+
+  AN_Codec = Codec.new
+  AN_Codec.encoder = lambda{|str|
+    raise ISO8583Exception.new("Invalid value: #{str} must be [A-Za-y0-9]") unless str =~ /^[A-Za-z0-9]*$/
+    str
+  }
+  AN_Codec.decoder = PASS_THROUGH_DECODER
+
+  ANP_Codec = Codec.new
+  ANP_Codec.encoder = lambda{|str|
+    raise ISO8583Exception.new("Invalid value: #{str} must be [A-Za-y0-9 ]") unless str =~ /^[A-Za-z0-9 ]*$/
+    str
+  }
+  ANP_Codec.decoder = PASS_THROUGH_DECODER
+
+  ANS_Codec = Codec.new
+  ANS_Codec.encoder = lambda{|str|
+    raise ISO8583Exception.new("Invalid value: #{str} must be [\x20-\x7E]") unless str =~ /^[\x20-\x7E]*$/
+    str
+  }
+  ANS_Codec.decoder = PASS_THROUGH_DECODER
+
+  Null_Codec = Codec.new
+  Null_Codec.encoder = lambda {|str|
+    str
+  }
+  Null_Codec.decoder = lambda {|str|
+    str.gsub(/\000*$/, '')
+  } 
+
+  Track2 = Codec.new
+  Track2.encoder = lambda{|track2|
+    #SS | PAN | FS | Expiration Date | Service Code | Discretionary Data | ES | LRC
+    # SS = ;
+    # PAN = up to 19 digits (at least 9?)
+    # FS = '='
+    # Exp Date = YYMM
+    # SC: 3 digits or =
+    # ES = ?
+    # lrc : 1byte
+    raise ISO8583Exception.new("Invalid Track2 data: #{track2}") unless track2 =~ /^;*(\d{9,19})=(.*)\?.$/
+    track2
+  }
+  Track2.decoder = PASS_THROUGH_DECODER
+
+  def self._date_codec(fmt) 
+    c = Codec.new
+    c.encoder = lambda {|date|
+      enc = case date
+            when DateTime, Date, Time
+              date.strftime(fmt)
+            when String
+              begin
+                dt = DateTime.strptime(date, fmt)
+                dt.strftime(fmt)
+              rescue
+                raise ISO8583Exception.new("Invalid format encoding: #{date}, must be #{fmt}.")
+              end
+            else  
+              raise ISO8583Exception.new("Don't know how to encode: #{date.class} to a time.")
+            end
+      return enc
+    }
+    c.decoder = lambda {|str|
+      begin
+        DateTime.strptime(str, fmt)
+      rescue
+        raise ISO8583Exception.new("Invalid format decoding: #{str}, must be #{fmt}.")
+      end
+    }
+
+    c
+  end
+
+  MMDDhhmmssCodec   = _date_codec("%m%d%H%M%S")
+  YYMMDDhhmmssCodec = _date_codec("%y%m%d%H%M%S")
+  YYMMCodec         = _date_codec("%y%m")
+
+end