cmxl 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 099dfa2701305989d3afe020ee6fee473d75a50e
-  data.tar.gz: 74e6f6ee642e4d3680b17b977ac470ef6ed1b1a5
+  metadata.gz: 18a7814325172343b3ae6aee190378823aacd8ab
+  data.tar.gz: a87474a066345e76dc8b66a15b83a632c26a5c0b
 SHA512:
-  metadata.gz: 3635643d3f1966515e350da68bff1c46b0960508b085953338ad2f275eccb87e80fad2b8e7723ddbc526c64b4e2e036a9771e9c0343300e9fe5f613c34333364
-  data.tar.gz: 74761935463086b4464f94d64bf77a06d6ec5b5914f5def5ce1840ec491a01ee67a544643096454a15998977184ad174090fd959a1c26007dd857cfd27acb478
+  metadata.gz: 4756b37a6bf9dc970b76d258dd95fef711f86697e64ae9a28c708efc6696ee6df5b076e2d24546bcd977e9fb1481bc1f5a4058eecfe7348b7fb7d9dba2f1446f
+  data.tar.gz: 1baadae4a20e53efc0f5f9a5bdd04c4e7cd7773f7ec04c468a768d36bddb1a86f96800ddcb28c863aeeaacb06829547ee64fd700809adc0a96f2eea0758f604d

data/README.md

@@ -131,6 +131,10 @@ other parsers:
 * [betterplace/mt940_parser](https://github.com/betterplace/mt940_parser)
 * [gmitrev/mt940parser](https://github.com/gmitrev/mt940parser)
 
+## Stats
+
+[![Build Status](https://magnum.travis-ci.com/railslove/cmxl.svg?token=e6QUckhTMdWWujkwZNBD&branch=master)](https://magnum.travis-ci.com/railslove/cmxl)
+
 ------------
 
 2014 - built with love by [Railslove](http://railslove.com). We have built quite a number of FinTech products. If you need support we are happy to help. Please contact us at team@railslove.com.

data/cmxl.gemspec

@@ -13,6 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/railslove/cmxl"
   spec.license       = "MIT"
 
+  spec.post_install_message = "Thanks for using Cmxl - your friendly MT940 parser!\nWe hope we can make dealing with MT940 files a bit more fun. :) \nPlease create an issue on github if anything is not as expected.\n\n"
+
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})

data/lib/cmxl.rb

@@ -5,8 +5,20 @@ require 'cmxl/statement'
 require 'cmxl/transaction'
 Dir[File.join(File.dirname(__FILE__), 'cmxl/fields', '*.rb')].each { |f| require f; }
 module Cmxl
-
   STATEMENT_SEPARATOR = "\n-"
+
+  # Public: Parse a MT940 string
+  #
+  # data - The String containing the MT940
+  # options - Hash with encoding options. Accepts the same parameters as String#encode!
+  #     It is likely that you want to provide the encoding of your MT940 String
+  #
+  # Examples
+  #
+  # Cmxl.parse(File.read('mt940.txt'), encoding: 'ISO-8859-1')
+  # Cmxl.parse(mt940_string)
+  #
+  # Returns an array of Statement objects
   def self.parse(data, options={})
     options[:universal_newline] ||= true
     if options[:encoding]

data/lib/cmxl/field.rb

@@ -11,13 +11,21 @@ module Cmxl
     DATE = /(?<year>\d{0,2})(?<month>\d{2})(?<day>\d{2})/
     attr_accessor :source, :modifier, :match, :data, :tag
 
+    # The parser class variable is the registry of all available parser.
+    # It is a hash with the tag (MT940 field number/tag) as key and the class as value
+    # When parsing a statment line we look for a matching entry or use the Unknown class as default
     @@parsers = {}
     @@parsers.default = Unknown
     def self.parsers; @@parsers; end
 
+    # Class accessor for the parser
+    # Every sub class should have its own parser (regex to parse a MT940 field/line)
+    # The default parser matches the whole line
     class << self; attr_accessor :parser; end
-    self.parser = /(?<source>.*)/ # default parser
+    self.parser = /(?<details>.*)/ # default parser
 
+    # Class accessor for the tag every defines a MT940 tag it can parse
+    # This also adds the class to the parser registry.
     def self.tag=(tag)
       @tag = tag.to_s
       @@parsers[tag.to_s] = self
@@ -26,6 +34,15 @@ module Cmxl
       @tag
     end
 
+    # Public: Parses a statement line and initiates a matching Field class
+    #
+    # Returns an instance of the special field class for the matched line.
+    #     Raises and LineFormatError if the line is not well formatted
+    #
+    # Example:
+    #
+    # Cmxl::Field.parse(':60F:C031002PLN40000,00') #=> returns an AccountBalance instance
+    #
     def self.parse(line)
       if line.match(/^:(\d{2,2})(\w)?:(.*)$/)
         tag, modifier, content = $1, $2, $3
@@ -49,16 +66,26 @@ module Cmxl
     end
 
     def to_h
-      self.data
+      self.data.merge('tag' => self.tag)
     end
     alias :to_hash :to_h
     def to_json(*args)
       to_h.to_json(*args)
     end
 
+    # Internal: Converts a provided string into a date object
+    #     In MT940 documents the date is provided as a 6 char string (YYMMDD) or as a 4 char string (MMDD)
+    #     If a 4 char string is provided a second parameter with the year should be provided. If no year is present the current year is assumed.
+    #
+    # Example:
+    #
+    # to_date('140909')
+    # to_date('0909', 2014)
+    #
+    # Retuns a date object or the provided date value if it is not parseable.
     def to_date(date, year=nil)
       if match = date.to_s.match(DATE)
-        year ||= "20#{match['year']}"
+        year ||= "20#{match['year'] || Date.today.strftime("%y")}"
         month = match['month']
         day = match['day']
         Date.new(year.to_i, month.to_i, day.to_i)

data/lib/cmxl/fields/account_balance.rb

@@ -29,7 +29,7 @@ module Cmxl
       end
 
       def to_h
-        {
+        super.merge({
           'date' => date,
           'funds_code' => funds_code,
           'credit' => credit?,
@@ -38,7 +38,7 @@ module Cmxl
           'amount' => amount,
           'amount_in_cents' => amount_in_cents,
           'sign' => sign
-        }
+        })
       end
     end
   end

data/lib/cmxl/fields/statement_line.rb

@@ -17,11 +17,11 @@ module Cmxl
       end
 
       def amount
-        self.data['amount'].gsub(',','.').to_f * sign
+        to_amount(self.data['amount'])
       end
 
       def amount_in_cents
-        self.data['amount'].gsub(',', '').gsub('.','').to_i * sign
+        to_amount_in_cents(self.data['amount'])
       end
 
       def date
@@ -32,15 +32,20 @@ module Cmxl
       end
 
       def to_h
-        super.merge({
+        {
           'date' => date,
           'entry_date' => entry_date,
           'amount' => amount,
           'amount_in_cents' => amount_in_cents,
           'sign' => sign,
           'debit' => debit?,
-          'credit' => credit?
-        })
+          'credit' => credit?,
+          'funds_code' => funds_code,
+          'swift_code' => swift_code,
+          'reference' => reference,
+          'bank_reference' => bank_reference,
+          'currency_letter' => currency_letter
+        }
       end
     end
   end

data/lib/cmxl/statement.rb

@@ -3,6 +3,12 @@ module Cmxl
   class Statement
     attr_accessor :source, :collection, :transactions, :fields, :lines
 
+    # Public: Initiate a new Statement and parse a provided single statement string
+    # It directly parses the source and initiates file and transaction objects.
+    #
+    # Example:
+    #
+    # Cmxl::Statement.new(single_statement_string)
     def initialize(source)
       self.source = source
       self.fields = []
@@ -11,8 +17,10 @@ module Cmxl
       self.parse!
     end
 
+    # Internal: Parse a single MT940 statement and extract the line data
+    #
     def parse!
-      # first we clean uo the source and make concat wraped lines
+      # first we clean uo the source and make concat wraped lines (lines not starting with a ":")
       self.source.split("\n").each do |line|
         if line.start_with?(':') || self.lines.last.nil?
           self.lines << line.strip
@@ -20,7 +28,7 @@ module Cmxl
           self.lines.last << line.strip
         end
       end
-      # now we check each line. if it is part of a transaction we initate or update a transaction else we parse the field and add it to the fields collection
+      # Now we check each line for its content ans structure it for further use. If it is part of a transaction we initate or update a transaction else we parse the field and add it to the fields collection
       self.lines.each do |line|
         if line.match(/\A:61:/)
           self.transactions << Cmxl::Transaction.new(line)
@@ -32,6 +40,10 @@ module Cmxl
       end
     end
 
+    # Public: SHA2 of the provided source
+    # This is an experiment of trying to identify statements. The MT940 itself might not provide a unique identifier
+    #
+    # Retruns the SHA2 of the source
     def sha
      Digest::SHA2.new.update(self.source).to_s
     end
@@ -69,7 +81,8 @@ module Cmxl
         'opening_balance' => opening_balance,
         'closing_balance' => closing_balance,
         'available_balance' => available_balance,
-        'transactions' => transactions
+        'transactions' => transactions,
+        'fields' => fields
       }
     end
     alias :to_hash :to_h
@@ -77,6 +90,12 @@ module Cmxl
       to_h.to_json(*args)
     end
 
+    # Internal: Field accessor
+    # returns a field object by a given tag
+    #
+    # Example:
+    # field(20)
+    # field(61,'F')
     def field(tag, modifier=nil)
       self.fields.detect {|field| field.tag == tag.to_s && (modifier.nil? || field.modifier == modifier) }
     end

data/lib/cmxl/version.rb

@@ -1,3 +1,3 @@
 module Cmxl
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/spec/field_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 describe Cmxl::Field do
   subject { Cmxl::Field.new('D140829EUR000000000147,64') }
 
-  it { expect(Cmxl::Field.parser).to eql(/(?<source>.*)/) } # default must be set
+  it { expect(Cmxl::Field.parser).to eql(/(?<details>.*)/) } # default must be set
 
   it { expect(subject.to_amount('123.')).to eql(123.00) }
   it { expect(subject.to_amount('123.1')).to eql(123.10) }

data/spec/fields/account_balance_spec.rb

@@ -21,7 +21,8 @@ describe Cmxl::Fields::AccountBalance do
         'currency' =>"EUR",
         'amount' =>147.64,
         'amount_in_cents' =>14764,
-        'sign' =>1
+        'sign' =>1,
+        'tag' => '60'
     }) }
   end
 

data/spec/fields/reference_spec.rb

@@ -8,5 +8,5 @@ describe Cmxl::Fields::Reference do
   it { expect(subject.date).to eql(Date.new(2014,9,2)) }
   it { expect(subject.statement_identifier).to eql('D') }
   it { expect(subject.additional_number).to eql('049') }
-  it { expect(subject.to_h).to eql({"statement_identifier"=>"D", "date"=> Date.new(2014,9,2), "additional_number"=>"049", "reference"=>"D140902049"}) }
+  it { expect(subject.to_h).to eql({"tag" => '20', "statement_identifier"=>"D", "date"=> Date.new(2014,9,2), "additional_number"=>"049", "reference"=>"D140902049"}) }
 end

data/spec/fields/statment_line_spec.rb

@@ -8,8 +8,8 @@ describe Cmxl::Fields::StatementLine do
   it { expect(subject.entry_date).to eql(Date.new(2014,9,2)) }
   it { expect(subject.funds_code).to eql('D') }
   it { expect(subject.currency_letter).to eql('R') }
-  it { expect(subject.amount).to eql(-1.62) }
-  it { expect(subject.amount_in_cents).to eql(-162) }
+  it { expect(subject.amount).to eql(1.62) }
+  it { expect(subject.amount_in_cents).to eql(162) }
   it { expect(subject.swift_code).to eql('NTRF') }
   it { expect(subject.reference).to eql('0000549855700010') }
   it { expect(subject.bank_reference).to eql('025498557/000001') }

data/spec/transaction_spec.rb

@@ -9,10 +9,10 @@ describe Cmxl::Transaction do
     it { expect(subject.funds_code).to eql('D') }
     it { expect(subject.date).to eql(Date.new(2014,9,1))}
     it { expect(subject.entry_date).to eql(Date.new(2014,9,2))}
-    it { expect(subject.amount).to eql(-1.62)}
-    it { expect(subject.statement_line.amount).to eql(-1.62)}
-    it { expect(subject.amount_in_cents).to eql(-162)}
-    it { expect(subject.to_h).to eql({"date"=>Date.new(2014,9,1), "entry_date"=>Date.new(2014,9,2), "funds_code"=>"D", "currency_letter"=>"R", "amount"=>-1.62, "swift_code"=>"NTRF", "reference"=>"0000549855700010", "bank_reference"=>"025498557/000001", "amount_in_cents"=>-162, "sign"=>-1, "debit"=>true, "credit"=>false, "bic"=>"HYVEDEMMXXX", "iban"=>"HUkkbbbsssskcccccccccccccccx", "name"=>"Peter Pan", "sepa"=>{"EREF"=>"TRX-0A4A47C3-F846-4729-8A1B-5DF620F", "MREF"=>"CAC97D2144174318AC18D9BF815BD4FB", "CRED"=>"DE98ZZZ09999999999", "SVWZ"=>"FOO TRX-0A4A47C3-F846-4729-8A1B-5DF620F"}, "information"=>"EREF+TRX-0A4A47C3-F846-4729-8A1B-5DF620FMREF+CAC97D2144174318AC18D9BF815BD4FBCRED+DE98ZZZ09999999999SVWZ+FOO TRX-0A4A47C3-F846-4729-8A1B-5DF620F", "description"=>"SEPA LASTSCHRIFT KUNDE", "sub_fields"=>{"00"=>"SEPA LASTSCHRIFT KUNDE", "10"=>"281", "20"=>"EREF+TRX-0A4A47C3-F846-4729", "21"=>"-8A1B-5DF620F", "22"=>"MREF+CAC97D2144174318AC18D9", "23"=>"BF815BD4FB", "24"=>"CRED+DE98ZZZ09999999999", "25"=>"SVWZ+FOO TRX-0A4A47C3-F84", "26"=>"6-4729-8A1B-5DF620F", "30"=>"HYVEDEMMXXX", "31"=>"HUkkbbbsssskcccccccccccccccx", "32"=>"Peter Pan", "34"=>"171"}, "transaction_code"=>"171", "details"=>"?00SEPA LASTSCHRIFT KUNDE?10281?20EREF+TRX-0A4A47C3-F846-4729?21-8A1B-5DF620F?22MREF+CAC97D2144174318AC18D9?23BF815BD4FB?24CRED+DE98ZZZ09999999999?25SVWZ+FOO TRX-0A4A47C3-F84?266-4729-8A1B-5DF620F?30HYVEDEMMXXX?31HUkkbbbsssskcccccccccccccccx?32Peter Pan?34171"}) }
+    it { expect(subject.amount).to eql(1.62)}
+    it { expect(subject.statement_line.amount).to eql(1.62)}
+    it { expect(subject.amount_in_cents).to eql(162)}
+    it { expect(subject.to_h).to eql({"date"=>Date.new(2014,9,1), "entry_date"=>Date.new(2014,9,2), "funds_code"=>"D", "currency_letter"=>"R", "amount"=>1.62, "swift_code"=>"NTRF", "reference"=>"0000549855700010", "bank_reference"=>"025498557/000001", "amount_in_cents"=>162, "sign"=>-1, "debit"=>true, "credit"=>false, "bic"=>"HYVEDEMMXXX", "iban"=>"HUkkbbbsssskcccccccccccccccx", "name"=>"Peter Pan", "sepa"=>{"EREF"=>"TRX-0A4A47C3-F846-4729-8A1B-5DF620F", "MREF"=>"CAC97D2144174318AC18D9BF815BD4FB", "CRED"=>"DE98ZZZ09999999999", "SVWZ"=>"FOO TRX-0A4A47C3-F846-4729-8A1B-5DF620F"}, "information"=>"EREF+TRX-0A4A47C3-F846-4729-8A1B-5DF620FMREF+CAC97D2144174318AC18D9BF815BD4FBCRED+DE98ZZZ09999999999SVWZ+FOO TRX-0A4A47C3-F846-4729-8A1B-5DF620F", "description"=>"SEPA LASTSCHRIFT KUNDE", "sub_fields"=>{"00"=>"SEPA LASTSCHRIFT KUNDE", "10"=>"281", "20"=>"EREF+TRX-0A4A47C3-F846-4729", "21"=>"-8A1B-5DF620F", "22"=>"MREF+CAC97D2144174318AC18D9", "23"=>"BF815BD4FB", "24"=>"CRED+DE98ZZZ09999999999", "25"=>"SVWZ+FOO TRX-0A4A47C3-F84", "26"=>"6-4729-8A1B-5DF620F", "30"=>"HYVEDEMMXXX", "31"=>"HUkkbbbsssskcccccccccccccccx", "32"=>"Peter Pan", "34"=>"171"}, "transaction_code"=>"171", "details"=>"?00SEPA LASTSCHRIFT KUNDE?10281?20EREF+TRX-0A4A47C3-F846-4729?21-8A1B-5DF620F?22MREF+CAC97D2144174318AC18D9?23BF815BD4FB?24CRED+DE98ZZZ09999999999?25SVWZ+FOO TRX-0A4A47C3-F84?266-4729-8A1B-5DF620F?30HYVEDEMMXXX?31HUkkbbbsssskcccccccccccccccx?32Peter Pan?34171"}) }
   end
 
   context 'without details' do
@@ -21,8 +21,8 @@ describe Cmxl::Transaction do
     it { expect(subject).to_not be_credit }
     it { expect(subject.date).to eql(Date.new(2014,9,1))}
     it { expect(subject.entry_date).to eql(Date.new(2014,9,2))}
-    it { expect(subject.amount).to eql(-1.62)}
-    it { expect(subject.amount_in_cents).to eql(-162)}
-    it { expect(subject.to_h).to eql({"date"=>Date.new(2014,9,1), "entry_date"=>Date.new(2014,9,2), "funds_code"=>"D", "currency_letter"=>"R", "amount"=>-1.62, "swift_code"=>"NTRF", "reference"=>"0000549855700010", "bank_reference"=>"025498557/000001", "amount_in_cents"=>-162, "sign"=>-1, "debit"=>true, "credit"=>false}) }
+    it { expect(subject.amount).to eql(1.62)}
+    it { expect(subject.amount_in_cents).to eql(162)}
+    it { expect(subject.to_h).to eql({"date"=>Date.new(2014,9,1), "entry_date"=>Date.new(2014,9,2), "funds_code"=>"D", "currency_letter"=>"R", "amount"=>1.62, "swift_code"=>"NTRF", "reference"=>"0000549855700010", "bank_reference"=>"025498557/000001", "amount_in_cents"=>162, "sign"=>-1, "debit"=>true, "credit"=>false}) }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmxl
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Michael Bumann
@@ -109,7 +109,9 @@ homepage: https://github.com/railslove/cmxl
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message: "Thanks for using Cmxl - your friendly MT940 parser!\nWe hope
+  we can make dealing with MT940 files a bit more fun. :) \nPlease create an issue
+  on github if anything is not as expected.\n\n"
 rdoc_options: []
 require_paths:
 - lib