ofx-parser 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2007-06-24
+
+* Initial release.
+

data/Manifest.txt

@@ -0,0 +1,12 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/class-extension.rb
+lib/ofx-parser.rb
+lib/ofx.rb
+lib/sic.rb
+test/fixtures/banking.ofx.sgml
+test/fixtures/creditcard.ofx.sgml
+test/fixtures/with_spaces.ofx.sgml
+test/test_ofx_parser.rb

data/README.txt

@@ -0,0 +1,103 @@
+== ofx-parser
+by Andrew A. Smith
+
+http://ofx-parser.rubyforge.org/
+http://rubyforge.org/projects/ofx-parser/
+
+== DESCRIPTION:
+
+ofx-parser is a ruby library to parse a realistic subset of the lengthy OFX 1.x specification.
+
+== FEATURES/PROBLEMS:
+
+* Reads OFX responses - i.e. those downloaded from financial institutions and
+  puts it into a usable object graph.
+* Supports the 3 main message sets: banking, credit card and investment
+  accounts, as well as the required 'sign on' set.
+* Knows about SIC codes - if your institution provides them.
+  See http://www.eeoc.gov/stats/jobpat/siccodes.html
+* Monetary amounts can be retrieved either as a raw string, or in pennies.
+* Supports OFX timestamps.
+
+== SYNOPSIS:
+
+Supports bank accounts:
+
+  require 'rubygems'
+  require 'ofx-parser'
+
+  ofx = OfxParser::OfxParser.parse(open("bank-statement.ofx"))
+
+  ofx.bank_account.number # => '103333333333'
+  ofx.bank_account.routing_number # => '033000033'
+  ofx.bank_account.balance # => '123.45'
+  ofx.bank_account.balance_in_pennies # => 12345
+
+  ofx.bank_account.statement.start_date # => DateTime
+  ofx.bank_account.statement.end_date # => DateTime
+
+  ofx.bank_account.statement.transactions.size # => 4
+
+  ofx.bank_account.statement.transactions.first.payee # => "FOO, INC."
+  ofx.bank_account.statement.transactions.first.type # => :DEBIT
+  ofx.bank_account.statement.transactions.first.amount # => '-11.11'
+  ofx.bank_account.statement.transactions.first.amount_in_pennies # => -1111
+
+Also supports credit cards...
+
+  ofx = OfxParser::OfxParser.parse(open("creditcard-statement.ofx"))
+
+  ofx.credit_card.remaining_credit # => '19000.0'
+  ofx.credit_card.remaining_credit_in_pennies # => '1900000'
+
+  ofx.credit_card.statement.start_date # => DateTime
+  ofx.credit_card.statement.end_date # => DateTime
+
+  ofx.credit_card.statement.transactions.size # => 10
+
+  ofx.credit_card.statement.transactions.first.type # => :DEBIT
+  ofx.credit_card.statement.transactions.first.amount # => '-19.17'
+  ofx.credit_card.statement.transactions.first.amount_in_pennies # => '-1917'
+  ofx.credit_card.statement.transactions.first.sic # => '7933'
+  ofx.credit_card.statement.transactions.first.sic_desc # => 'BOWLING CENTERS'
+  ofx.credit_card.statement.transactions.first.payee # => 'SUNSET BOWLING'
+
+Working on investment accounts...
+
+== REQUIREMENTS:
+
+* hpricot >= 0.6
+
+== INSTALL:
+
+* gem install ofx-parser
+
+== LICENSE:
+
+Copyright (c) 2007, Andrew A. Smith
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright owner nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'hoe'
+$:.unshift(File.dirname(__FILE__) + "/lib")
+require 'ofx-parser'
+
+Hoe.new('ofx-parser', OfxParser::VERSION) do |p|
+  p.author = 'Andrew A. Smith'
+  p.email = 'andy@tinnedfruit.org'
+  p.rubyforge_name = 'ofx-parser'
+  p.summary = 'ofx-parser is a ruby library for parsing OFX 1.x data.'
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = 'http://ofx-parser.rubyforge.org/'
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.remote_rdoc_dir = '' # Release to root
+  p.extra_deps << ["hpricot", ">= 0.6"]
+  p.need_zip = true
+  p.need_tar = false
+end

data/lib/class-extension.rb

@@ -0,0 +1,154 @@
+# = class_extension.rb
+#
+# == Copyright (c) 2006 Daniel Schierbeck
+#
+#   Ruby License
+#
+#   This module is free software. You may use, modify, and/or redistribute this
+#   software under the same terms as Ruby.
+#
+#   This program is distributed in the hope that it will be useful, but WITHOUT
+#   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#   FOR A PARTICULAR PURPOSE.
+#
+# == Special Thanks
+#
+# Thanks to Trans, Nobu and Ulysses for their original on this concept.
+#
+# == Authors and Contributors
+#
+# * Daniel Schierbeck
+# * Thomas Sawyer
+# * Nobu Nakada
+# * Ulysses
+
+# Author::    Daniel Schierbeck
+# Copyright:: Copyright (c) 2006 Daniel Schierbeck
+# License::   Ruby License
+
+#
+
+class Module #:nodoc: all
+
+  alias_method :append_features_without_class_extension, :append_features
+
+  # = class_extension
+  #
+  # Normally when including modules, class/module methods are not
+  # extended. To achieve this behavior requires some clever
+  # Ruby Karate. Instead class_extension provides an easy to use
+  # and clean solution. Simply place the extending class methods
+  # in a block of the special module method #class_extension.
+  #
+  #   module Mix
+  #     def inst_meth
+  #       puts 'inst_meth'
+  #     end
+  #
+  #     class_extension do
+  #       def class_meth
+  #         "Class Method!"
+  #       end
+  #     end
+  #   end
+  #
+  #   class X
+  #     include Mix
+  #   end
+  #
+  #   X.class_meth  #=> "Class Method!"
+  #
+
+  def class_extension(&block)
+    @class_extension ||= Module.new do
+      def self.append_features(mod)
+        append_features_without_class_extension(mod)
+      end
+    end
+    @class_extension.module_eval(&block) if block_given?
+    @class_extension
+  end
+
+  private :class_extension
+
+  def append_features(mod)
+    append_features_without_class_extension(mod)
+    mod.extend(class_extension)
+    if mod.instance_of? Module
+      mod.__send__(:class_extension).__send__(:include, class_extension)
+    end
+  end
+
+end
+
+class Class #:nodoc: all
+  undef_method :class_extension
+end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin test
+
+  require 'test/unit'
+
+  class TC_ClassMethods < Test::Unit::TestCase
+
+    # fixture
+
+    module N
+      class_extension do
+        def n ; 43 ; end
+        def s ; self ; end
+      end
+      extend class_extension
+    end
+
+    class X
+      include N
+      def n ; 11 ; end
+    end
+
+    module K
+      include N
+      class_extension do
+        def n ; super + 1 ; end
+      end
+    end
+
+    class Z
+      include K
+    end
+
+    # tests
+
+    def test_01
+      assert_equal( 43, N.n )
+      assert_equal(  N,  N.s )
+    end
+    def test_02
+      assert_equal( 43, X.n )
+      assert_equal(  X, X.s )
+    end
+    def test_03
+      assert_equal( 11, X.new.n )
+    end
+    def test_04
+      assert_equal( 43, K.n )  #notic the difference!
+      assert_equal(  K, K.s )
+    end
+    def test_05
+      assert_equal( 44, Z.n )
+      assert_equal(  Z, Z.s )
+    end
+
+  end
+
+=end
+

data/lib/ofx-parser.rb

@@ -0,0 +1,175 @@
+require 'hpricot'
+require 'time'
+require 'date'
+
+%w(class-extension ofx sic).each do |fn|
+  require File.dirname(__FILE__) + "/#{fn}"
+end
+
+module OfxParser
+  VERSION = '1.0.0'
+
+  class OfxParser
+
+    # Creates and returns an Ofx instance when given a well-formed OFX document,
+    # complete with the mandatory key:pair header.
+    def self.parse(ofx)
+      ofx = ofx.respond_to?(:read) ? ofx.read.to_s : ofx.to_s
+
+      return Ofx.new if ofx == ""
+
+      header, body = pre_process(ofx)
+
+      ofx_out = parse_body(body)
+      ofx_out.header = header
+      ofx_out
+    end
+
+    # Designed to make the main OFX body parsable. This means adding closing tags
+    # to the SGML to make it parsable by hpricot.
+    #
+    # Returns an array of 2 elements:
+    # * header as a hash,
+    # * body as an evily pre-processed string ready for parsing by hpricot.
+    def self.pre_process(ofx)
+      header, body = ofx.split(/\n\n/)
+
+      header = Hash[*header.split(/:|\n/)]
+
+      body.gsub!(/>\s+</m, '><')
+      body.gsub!(/\s+</m, '<')
+      body.gsub!(/>\s+/m, '>')
+      body.gsub!(/<(\w+?)>([^<]+)/m, '<\1>\2</\1>')
+
+      [header, body]
+    end
+
+    # Takes an OFX datetime string of the format:
+    # * YYYYMMDDHHMMSS.XXX[gmt offset:tz name]
+    # * YYYYMMDD
+    # * YYYYMMDDHHMMSS
+    # * YYYYMMDDHHMMSS.XXX
+    #
+    # Returns a DateTime object. Milliseconds (XXX) are ignored.
+    def self.parse_datetime(date)
+      if /\A\s*
+          (\d{4})(\d{2})(\d{2})       ?# YYYYMMDD            1,2,3
+          (?:(\d{2})(\d{2})(\d{2}))?  ?# HHMMSS  - optional  4,5,6
+          (?:\.(\d{3}))?              ?# .XXX    - optional  7
+          (?:\[(-?\d+)\:\w{3}\])?     ?# [-n:TZ] - optional  8,9
+          \s*\z/ix =~ date
+        year = $1.to_i
+        mon = $2.to_i
+        day = $3.to_i
+        hour = $4.to_i
+        min = $5.to_i
+        sec = $6.to_i
+        # DateTime does not support usecs.
+        # usec = 0
+        # usec = $7.to_f * 1000000 if $7
+        off = Rational($8.to_i, 24) # offset as a fraction of day. :|
+        DateTime.civil(year, mon, day, hour, min, sec, off)
+      end
+    end
+
+  private
+    def self.parse_body(body)
+      doc = Hpricot.XML(body)
+
+      ofx = Ofx.new
+
+      ofx.sign_on = build_signon((doc/"SIGNONMSGSRSV1/SONRS"))
+      ofx.bank_account = build_bank((doc/"BANKMSGSRSV1/STMTTRNRS")) unless (doc/"BANKMSGSRSV1").empty?
+      ofx.credit_card = build_credit((doc/"CREDITCARDMSGSRSV1/CCSTMTTRNRS")) unless (doc/"CREDITCARDMSGSRSV1").empty?
+      #build_investment((doc/"SIGNONMSGSRQV1"))
+
+      ofx
+    end
+
+    def self.build_signon(doc)
+      sign_on = SignOn.new
+      sign_on.status = build_status((doc/"STATUS"))
+      sign_on.date = parse_datetime((doc/"DTSERVER").inner_text)
+      sign_on.language = (doc/"LANGUAGE").inner_text
+
+      sign_on.institute = Institute.new
+      sign_on.institute.name = ((doc/"FI")/"ORG").inner_text
+      sign_on.institute.id = ((doc/"FI")/"FID").inner_text
+      sign_on
+    end
+
+    def self.build_bank(doc)
+      acct = BankAccount.new
+
+      acct.transaction_uid = (doc/"TRNUID").inner_text.strip
+      acct.number = (doc/"STMTRS/BANKACCTFROM/ACCTID").inner_text
+      acct.routing_number = (doc/"STMTRS/BANKACCTFROM/BANKID").inner_text
+      acct.type = (doc/"STMTRS/BANKACCTFROM/ACCTTYPE").inner_text.strip
+      acct.balance = (doc/"STMTRS/LEDGERBAL/BALAMT").inner_text
+      acct.balance_date = parse_datetime((doc/"STMTRS/LEDGERBAL/DTASOF").inner_text)
+
+      statement = Statement.new
+      statement.currency = (doc/"STMTRS/CURDEF").inner_text
+      statement.start_date = parse_datetime((doc/"STMTRS/BANKTRANLIST/DTSTART").inner_text)
+      statement.end_date = parse_datetime((doc/"STMTRS/BANKTRANLIST/DTEND").inner_text)
+      acct.statement = statement
+
+      statement.transactions = (doc/"STMTRS/BANKTRANLIST/STMTTRN").collect do |t|
+        build_transaction(t)
+      end
+
+      acct
+    end
+
+    def self.build_credit(doc)
+      acct = CreditAccount.new
+
+      acct.number = (doc/"CCSTMTRS/CCACCTFROM/ACCTID").inner_text
+      acct.transaction_uid = (doc/"TRNUID").inner_text.strip
+      acct.balance = (doc/"CCSTMTRS/LEDGERBAL/BALAMT").inner_text
+      acct.balance_date = parse_datetime((doc/"CCSTMTRS/LEDGERBAL/DTASOF").inner_text)
+      acct.remaining_credit = (doc/"CCSTMTRS/AVAILBAL/BALAMT").inner_text
+      acct.remaining_credit_date = parse_datetime((doc/"CCSTMTRS/AVAILBAL/DTASOF").inner_text)
+
+      statement = Statement.new
+      statement.currency = (doc/"CCSTMTRS/CURDEF").inner_text
+      statement.start_date = parse_datetime((doc/"CCSTMTRS/BANKTRANLIST/DTSTART").inner_text)
+      statement.end_date = parse_datetime((doc/"CCSTMTRS/BANKTRANLIST/DTEND").inner_text)
+      acct.statement = statement
+
+      statement.transactions = (doc/"CCSTMTRS/BANKTRANLIST/STMTTRN").collect do |t|
+        build_transaction(t)
+      end
+
+      acct
+    end
+
+    # for credit and bank transactions.
+    def self.build_transaction(t)
+      transaction = Transaction.new
+      transaction.type = (t/"TRNTYPE").inner_text
+      transaction.date = parse_datetime((t/"DTPOSTED").inner_text)
+      transaction.amount = (t/"TRNAMT").inner_text
+      transaction.fit_id = (t/"FITID").inner_text
+      transaction.payee = (t/"PAYEE").inner_text + (t/"NAME").inner_text
+      transaction.memo = (t/"MEMO").inner_text
+      transaction.sic = (t/"SIC").inner_text
+      transaction.check_number = (t/"CHECKNUM").inner_text if transaction.type == :CHECK
+      transaction
+    end
+
+
+    def self.build_investment(doc)
+
+    end
+
+    def self.build_status(doc)
+      status = Status.new
+      status.code = (doc/"CODE").inner_text
+      status.severity = (doc/"SEVERITY").inner_text
+      status.message = (doc/"MESSAGE").inner_text
+      status
+    end
+
+  end
+end