norma43_parser 1.0.1

data/lib/norma43/line_handlers.rb

@@ -0,0 +1,54 @@
+require "norma43/line_parsers/line_parsers"
+require "norma43/line_processors"
+
+module Norma43
+  module LineHandlers
+    def self.mapping
+      {
+        "00" => self.document_start,
+        "88" => self.document_end,
+        "11" => self.account_start,
+        "33" => self.account_end,
+        "22" => self.transaction,
+        "23" => self.additional_item,
+        "24" => self.additional_currency
+      }
+    end
+
+    def self.document_start
+      Handler.new LineParsers::DocumentStart, LineProcessors::DocumentStart
+    end
+
+    def self.document_end
+      Handler.new LineParsers::DocumentEnd, LineProcessors::DocumentEnd
+    end
+
+    def self.account_start
+      Handler.new LineParsers::AccountStart, LineProcessors::AccountStart
+    end
+
+    def self.account_end
+      Handler.new LineParsers::AccountEnd, LineProcessors::AccountEnd
+    end
+
+    def self.transaction
+      Handler.new LineParsers::Transaction, LineProcessors::Transaction
+    end
+
+    def self.additional_item
+      Handler.new LineParsers::AdditionalItem, LineProcessors::AdditionalItem
+    end
+
+    def self.additional_currency
+      Handler.new LineParsers::AdditionalCurrency, LineProcessors::AdditionalCurrency
+    end
+
+    Handler = Struct.new :parser, :processor do
+      def process line, contexts
+        line_parser = self.parser.new(line)
+
+        processor.call line_parser, contexts
+      end
+    end
+  end
+end

data/lib/norma43/line_parsers/file_format_validator.rb

@@ -0,0 +1,19 @@
+require "norma43/line_parsers/line_parser"
+module Norma43
+  class FileFormatValidator < LineParser
+    field :record_type, 0..1, :raw
+    field :file_type, 36..38
+
+    def has_document?; file_type=="00" end
+
+    def valid?
+      errors.empty?
+    end
+
+    def errors
+      errors = []
+      %w(11 00).include? record_type or errors << "Must start with 00 (was ”#{record_type}”)"
+      errors
+    end
+  end
+end

data/lib/norma43/line_parsers/line_parser.rb

@@ -0,0 +1,42 @@
+require "norma43/utils/typecaster"
+
+module Norma43
+  class LineParser
+    attr_reader :line
+    def initialize line
+      @line = line
+    end
+
+    def attributes
+      self.class.field_names.each_with_object({}) do |field, attrs|
+        attrs[field] = self.public_send(field)
+      end
+    end
+
+    def self.field name, range, type = :string
+      self.field_names.push name
+
+      define_method name do
+        if range.is_a?(Array) # let multivalued attribute
+          range.map { |r| value_at_position(r, type) }.compact
+        else
+          value_at_position range, type
+        end
+      end
+    end
+
+    private
+
+    def self.field_names
+      @field_names ||= []
+    end
+
+    def value_at_position range, type
+      typecast line[range].to_s.strip, type
+    end
+
+    def typecast value, type
+      Typecaster.cast value, type
+    end
+  end
+end

data/lib/norma43/line_parsers/line_parsers.rb

@@ -0,0 +1,69 @@
+require "norma43/line_parsers/line_parser"
+
+module Norma43
+  module LineParsers
+    class DocumentStart < LineParser
+      field :id, 2..13
+      field :created_at, 14..33, :time
+      field :delivery_number, 34..35, :integer
+      field :file_type, 36..38
+      field :name, 39..48
+    end
+
+    class DocumentEnd < LineParser
+      field :record_number, 20..25, :integer
+    end
+
+    class AccountStart < LineParser
+      field :bank_code, 2..5, :integer
+      field :branch_code, 6..9, :integer
+      field :account_number, 10..19, :integer
+      field :start_date, 20..25, :date
+      field :end_date, 26..31, :date
+      field :balance_code, 32, :integer
+      field :balance_amount, 33..46, :integer
+      field :currency_code, 47..49, :integer
+      field :information_mode_code, 50, :integer
+      field :abbreviated_name, 51..76
+    end
+
+    class AccountEnd < LineParser
+      field :bank_code, 2..5, :integer
+      field :branch_code, 6..9, :integer
+      field :account_number, 10..19, :integer
+      field :debit_entries, 20..24, :integer
+      field :debit_amount, 25..38, :integer
+      field :credit_entries, 39..43, :integer
+      field :credit_amount, 44..57, :integer
+      field :balance_code, 58, :integer
+      field :balance_amount, 59..72, :integer
+      field :currency_code, 73..75, :integer
+    end
+
+    class Transaction < LineParser
+      field :origin_branch_code, 6..9, :integer
+      field :transaction_date, 10..15, :date
+      field :value_date, 16..21, :date
+      field :shared_item, 22..23, :integer
+      field :own_item, 24..26, :integer
+      field :amount_code, 27, :integer
+      field :amount, 28..41, :integer
+      field :document_number, 42..51, :integer
+      field :reference_1, 52..63, :integer
+      field :reference_2, 64..79
+    end
+
+    class AdditionalItem < LineParser
+      field :data_code, 2..3, :integer
+      field :item_1, 4..41
+      field :item_2, 42..79
+    end
+
+    class AdditionalCurrency < LineParser
+      field :data_code, 2..3, :integer
+      field :currency_code, 4..6, :integer
+      field :amount, 7..20, :integer
+      field :free, 21..79
+    end
+  end
+end

data/lib/norma43/line_processors.rb

@@ -0,0 +1,60 @@
+require "norma43/models"
+module Norma43
+  module LineProcessors
+    DocumentStart = ->(line, contexts) {
+      document = Models::Document.new line.attributes
+
+      contexts.add document
+
+      contexts
+    }
+
+    DocumentEnd = ->(line, contexts) {
+      contexts.move_to Models::Document
+      contexts.current.number_of_lines = line.record_number
+      contexts
+    }
+
+    AccountStart = ->(line, contexts) {
+      contexts.move_to Models::Document
+      account = Models::Account.new line.attributes
+      contexts.current.accounts << account
+      contexts.add account
+
+      contexts
+    }
+
+    AccountEnd = ->(line, contexts) {
+      contexts.move_to Models::Account
+      contexts.current.attributes = line.attributes
+      contexts
+    }
+
+    Transaction = ->(line, contexts) {
+      contexts.move_to Models::Account
+
+      transaction = Models::Transaction.new line.attributes
+
+      contexts.current.transactions << transaction
+
+      contexts.add transaction
+
+      contexts
+    }
+
+    AdditionalItem = ->(line, contexts) {
+      contexts.move_to Models::Transaction
+      additional_item = Models::AdditionalItem.new line.attributes
+      contexts.current.additional_items << additional_item
+      contexts
+    }
+
+    AdditionalCurrency = ->(line, contexts) {
+      contexts.move_to Models::Transaction
+      additional_currency = Models::AdditionalCurrency.new line.attributes
+      contexts.current.additional_currency = additional_currency
+      contexts
+    }
+
+  end
+end

data/lib/norma43/models.rb

@@ -0,0 +1,85 @@
+require "norma43/utils/string_helpers"
+require 'virtus'
+
+module Norma43
+  module Models
+    #forward declarations
+    class Account; end
+    class Transaction; end
+    class AdditionalItem; end
+    class AdditionalCurrency; end
+    DEBIT_CODE = 1
+    CREDIT_CODE = 2
+
+    class Document
+      include Virtus.model
+
+      attribute :id
+      attribute :created_at
+      attribute :delivery_number
+      attribute :file_type
+      attribute :name
+      attribute :number_of_lines
+      attribute :accounts, Array[Account]
+
+      def transaction_date
+        accounts.map(&:date).compact.first
+      end
+    end
+
+    class Account
+      include Virtus.model
+
+      attribute :bank_code
+      attribute :branch_code
+      attribute :account_number
+      attribute :start_date
+      attribute :end_date
+      attribute :balance_code
+      attribute :balance_amount
+      attribute :currency_code
+      attribute :information_mode_code
+      attribute :abbreviated_name
+      attribute :debit_entries
+      attribute :debit_amount
+      attribute :credit_entries
+      attribute :credit_amount
+      attribute :transactions, Array[Transaction]
+    end
+
+    class Transaction
+      include Virtus.model
+
+      attribute :origin_branch_code
+      attribute :transaction_date
+      attribute :value_date
+      attribute :shared_item
+      attribute :own_item
+      attribute :amount_code
+      attribute :amount
+      attribute :document_number
+      attribute :reference_1
+      attribute :reference_2
+      attribute :additional_items, Array[AdditionalItem]
+      attribute :additional_currency, AdditionalCurrency
+      def debit?; self.amount_code==DEBIT_CODE end
+    end
+
+    class AdditionalItem
+      include Virtus.model
+
+      attribute :data_code
+      attribute :item_1
+      attribute :item_2
+    end
+
+    class AdditionalCurrency
+      include Virtus.model
+
+      attribute :data_code
+      attribute :currency_code
+      attribute :amount
+      attribute :free
+    end
+  end
+end

data/lib/norma43/parser.rb

@@ -0,0 +1,79 @@
+require "norma43/line_parsers/file_format_validator"
+require "norma43/line_handlers"
+require "norma43/utils/contexts"
+
+module Norma43
+  class InvalidFileFormatError < ArgumentError; end;
+
+  class Parser
+    attr_reader :file
+
+    # Parser.new accepts a File instance or a String
+    # A InvalidFileFormatError will be raised if file isn't in the Norma43 format
+    def initialize file
+      @file = file
+      validator = validate_file_format
+      @contexts = if validator.has_document?
+        Contexts.new
+      else
+        # in theory Norma43 says that files should start with DocumentStart but
+        # practically doesn't happen, so that we create one artificially
+        # to avoid corner cases in the processors
+        Contexts.new().tap { |ctx| ctx.add Models::Document.new }
+      end
+    end
+
+    def result
+      parse_lines(@contexts).result
+    end
+
+    protected
+
+    def lines
+      @lines ||= file.each_line
+    end
+
+    private
+
+    def validate_file_format
+      validator = FileFormatValidator.new first_line
+      raise InvalidFileFormatError.new(validator.errors.join(", ")) unless validator.valid?
+      validator
+    end
+
+    def parse_lines contexts
+      parse_lines parse_line(self.lines.next, contexts)
+
+    rescue StopIteration# because lines is an enumerator raises StopIteration on end
+      self.lines.rewind # Ensure we do not bomb out when calling result multiple times
+      contexts
+    end
+
+    # Look up a matching handler for the line and process it
+    # The process method on a handler always returns a Contexts object
+    def parse_line line, contexts
+      line = line.encode Encoding::UTF_8 if encode_lines?
+
+      handler = handler_for_line line
+
+      handler.process line, contexts
+    end
+
+    def handler_for_line line
+      LineHandlers.mapping.fetch line[0..1]
+    end
+
+    def encode_lines?
+      first_line.encoding != Encoding::UTF_8
+    end
+
+    def first_line
+      @first_line ||= begin
+        line = self.lines.peek
+        self.lines.rewind # peek seems to move the pointer when file is an actual File object
+
+        line
+      end
+    end
+  end
+end

data/lib/norma43/utils/contexts.rb

@@ -0,0 +1,54 @@
+module Norma43
+  class Contexts
+    def initialize containers = nil
+      Array(containers).compact.each do |container|
+        add container
+      end
+    end
+
+    def result
+      contexts.first
+    end
+
+    def current
+      contexts.last
+    end
+
+    def add container
+      contexts.push container
+    end
+
+    def move_up
+      contexts.pop
+    end
+
+    def move_to container_class
+      until current.is_a?(container_class) or current.nil?
+        move_up
+      end if contexts.any?
+    end
+
+    def move_to_or_add_to_parent container_class, parent_container_class
+      return self if current.is_a?(container_class)
+
+      until current.kind_of?(parent_container_class)
+        move_up
+      end
+
+      entity = container_class.new
+
+      setter_name = StringHelpers.underscore container_class.name.split("::").last
+      current.public_send "#{setter_name}=", entity
+
+      add entity
+
+      self
+    end
+
+    private
+
+    def contexts
+      @contexts ||= []
+    end
+  end
+end

data/lib/norma43/utils/string_helpers.rb

@@ -0,0 +1,10 @@
+module Norma43
+  module StringHelpers
+    def self.underscore word
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      word.tr!("-", "_")
+      word.downcase
+    end
+  end
+end

data/lib/norma43/utils/typecaster.rb

@@ -0,0 +1,19 @@
+require "time"
+
+module Norma43
+  module Typecaster
+    def self.cast value, type
+      casters.fetch(type).call(value) unless value == ""
+    end
+
+    def self.casters
+      {
+        integer: ->(value) { value.to_i },
+        time: ->(value) { Time.strptime(value, "%Y%m%d%H%M%S%N") },
+        date: ->(value) { Date.strptime(value, "%y%m%d") },
+        string: ->(value) { value unless value.match(/\A0+\Z/) },
+        raw: ->(value) { value }
+      }
+    end
+  end
+end

data/lib/norma43/version.rb

@@ -0,0 +1,3 @@
+module Norma43
+  VERSION = "1.0.1"
+end

data/lib/norma43.rb

@@ -0,0 +1,8 @@
+require "norma43/version"
+require "norma43/parser"
+
+module Norma43
+  def self.parse text
+    Parser.new(text).result
+  end
+end

data/norma43_parser.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "norma43/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "norma43_parser"
+  spec.version       = Norma43::VERSION
+  spec.authors       = ["Sequra engineering"]
+  spec.email         = ["dev@sequra.es"]
+  spec.summary       = %q{Parses banks transactions files specified in rule 43}
+  spec.homepage      = "https://github.com/sequra/norma43_parser"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = "~> 2.0"
+
+  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)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "rspec"
+  spec.add_runtime_dependency "virtus"
+end

data/spec/example1_parse_spec.rb

@@ -0,0 +1,91 @@
+require "norma43"
+
+RSpec.describe Norma43 do
+  describe "parse" do
+
+    let(:document) do
+      file = File.open( File.join(__dir__, "fixtures/example1.n43"),
+                        encoding: "iso-8859-1")
+      Norma43.parse file
+    end
+
+    it "finds one account" do
+      expect(document.accounts.size).to eq 1
+    end
+
+    describe "first account" do
+      let(:account) { document.accounts.first }
+
+      it "stores expected attributes from AccountStart parser" do
+        expect(account).to have_attributes({
+          "bank_code"             => 9999,
+          "branch_code"           => 1111,
+          "account_number"        => 123456789,
+          "start_date"            => Date.parse("2004-08-04"),
+          "end_date"              => Date.parse("2004-09-05"),
+          "currency_code"         => 1,
+          "information_mode_code" => 3,
+          "abbreviated_name"      => "MY ACCOUNT"
+        })
+      end
+
+      it "stores expected attributes from AccountEnd parser" do
+        expect(account).to have_attributes({
+          "balance_code"   => 2,
+          "balance_amount" => 78889999999999,
+          "debit_entries"  => 4,
+          "debit_amount"   => 4936,
+          "credit_entries" => 2,
+          "credit_amount"  => 999999,
+        })
+      end
+
+      describe "transactions" do
+        it "finds all transactions" do
+          expect(account.transactions.size).to eq 4
+        end
+
+        describe "first transaction" do
+          let(:transaction) { account.transactions[0] }
+          it "stores expected attributes" do
+            expect(transaction).to have_attributes({
+              "origin_branch_code" => 6700,
+              "transaction_date"   => Date.parse("2004-04-08"),
+              "value_date"         => Date.parse("2004-04-08"),
+              "shared_item"        => 4,
+              "own_item"           => 7,
+              "amount_code"        => 2,
+              "amount"             => 1234,
+              "document_number"    => 0,
+              "reference_1"        => 0,
+              "reference_2"        => nil,
+            })
+          end
+        end
+
+        it "each transaction has 5 additional_items as a maximum" do
+          account.transactions.each do |transaction|
+            expect(transaction.additional_items.size).to be <= 5
+          end
+        end
+
+        describe "first additional item" do
+          let(:additional_item) { account.transactions[0].additional_items[0]}
+          it "stores expected attributes" do
+            expect(additional_item).to have_attributes({
+              "data_code" => 1,
+              "item_1"    => "XXXXXXXXX",
+              "item_2"    => nil
+            })
+          end
+        end
+
+        describe "first additional currency" do
+          xit "stores expected attributes" do
+            # We don't have exaples to write test write when have
+          end
+        end
+      end
+    end
+  end
+end

data/spec/fixtures/example1.n43

@@ -0,0 +1,10 @@
+119999111101234567890408040409052000000001234569783MY ACCOUNT
+2212346700040408040408040072000000000012340000000000000000000000                
+2301XXXXXXXXX                                                                   
+2212346700040408040408040072000000000012340000000000000000000000                
+2301A28152585
+2256781128040405040405040072000000000012340000000000000000000000                
+2301XXXXXXXXX                                                                   
+2256781127040805040805020092000000000012340000000000000000000000                
+2301REF XXXXXXXXX                                                               
+3399991111012345678900004000000000049360000200000000999999278889999999999001

data/spec/norma43/line_parsers/account_end_spec.rb

@@ -0,0 +1,51 @@
+require "norma43/line_parsers/line_parsers"
+
+module Norma43
+  module LineParsers
+    RSpec.describe AccountEnd do
+      let :account_end do
+        AccountEnd.new "3399991111012345678900004000000000049360000200000000999999278889999999999001    "
+      end
+
+      it "parses the bank code" do
+        expect(account_end.bank_code).to eq 9999
+      end
+
+      it "parses the branch code" do
+        expect(account_end.branch_code).to eq 1111
+      end
+
+      it "parses the account number" do
+        expect(account_end.account_number).to eq 123456789
+      end
+
+      it "parses the number of debit entries" do
+        expect(account_end.debit_entries).to eq 4
+      end
+
+      it "parses the total of debit amounts" do
+        expect(account_end.debit_amount).to eq 4936
+      end
+
+      it "parses the number of credit entries" do
+        expect(account_end.credit_entries).to eq 2
+      end
+
+      it "parses the total of credit amounts" do
+        expect(account_end.credit_amount).to eq 999999
+      end
+
+      it "parses the final balance code" do
+        expect(account_end.balance_code).to eq 2
+      end
+
+      it "parses the final balance amount" do
+        expect(account_end.balance_amount).to eq 78889999999999
+      end
+
+      it "parses the currency code" do
+        expect(account_end.currency_code).to eq 1
+      end
+    end
+  end
+end