ach_builder 0.0.2 → 0.2.1

data/lib/ach/component/has_many_association.rb

@@ -0,0 +1,155 @@
+module ACH
+  # Objects of this class host essential functionality required to create
+  # associated object from within owner objects.
+  #
+  # Newly instantiated +HasManyAssociation+ object has no owner, and should
+  # be used to assign it's copies to owners via +for+ method. This technique
+  # has following application:
+  #   class Batch < ACH::Component
+  #     association = HasManyAssociation.new(:entries)
+  #   
+  #     association.delegation_methods.each do |method_name|
+  #       delegate method_name, :to => '@batches_association'
+  #     end
+  #   
+  #     after_initialize_hooks << lambda{ instance_variable_set('@batches_association', association.for(self)) }
+  #     # All these lines of code are macrosed by <tt>ACH::Component.has_many</tt> method
+  #   end
+  #   # Now, whenever new batch is created, it will have it's own @batches_association,
+  #   # and essential methods +batches+, +batch+, +build_batch+ delegated to it
+  #   # (accordingly, to +container+, +create+, and +build+ methods)
+  class Component::HasManyAssociation
+    # If Record should be attached to (preceded by) other Record, this
+    # exception is raised on attempt to create attachment record without
+    # having preceded record. For example, Addenda records should be
+    # created after Entry records. Each new Addenda record will be attached
+    # to the latest Entry record.
+    class NoLinkError < ArgumentError
+      def initialize(link, klass)
+        super "No #{link} was found to attach a new #{klass}"
+      end
+    end
+
+    # Exception thrown if an association object, assigned for particular
+    # owner object, is used to assign to another owner object
+    class DoubleAssignmentError < StandardError
+      def initialize(name, owner)
+        super "Association #{name} has alredy been assigned to #{owner}"
+      end
+    end
+
+    attr_reader :name, :linked_to, :proc_defaults
+    private :linked_to, :proc_defaults
+
+    def initialize(plural_name, options = {})
+      @name = plural_name.to_s
+      @linked_to, @proc_defaults = options.values_at(:linked_to, :proc_defaults)
+    end
+
+    # Clones +self+ and assigns +owner+ to clone. Also, for newly created
+    # clone association that has owner, aliases main methods so that +owner+
+    # may delegate to them.
+    def for(owner)
+      raise DoubleAssignmentError.new(@name, @owner) if @owner
+
+      clone.tap do |association|
+        plural, singular = name, singular_name
+        association.instance_variable_set('@owner', owner)
+        association.singleton_class.class_eval do
+          alias_method "build_#{singular}", :build
+          alias_method singular, :create
+          alias_method plural, :container
+        end
+      end
+    end
+
+    # Returns an array of methods to be delegated by +owner+ of the association.
+    # For example, for association named :items, it will include:
+    # * +build_item+ - for instantiating Item from the string (used by parsing functionality)
+    # * +item+ - for instantiating Item during common ACH File creation
+    # * +items+ - that returns set of Item objects
+    def delegation_methods
+      ["build_#{singular_name}", singular_name, name]
+    end
+
+    # Uses <tt>klass#from_s</tt> to instantiate object from a string. Thus, +klass+ should be
+    # descendant of ACH::Record::Base. Then pushes object to appropriate container.
+    def build(str)
+      obj = klass.from_s(str)
+      container_for_associated << obj
+    end
+
+    # Creates associated object using common to ACH controls pattern, and pushes it to
+    # appropriate container. For example, for :items association, this method is
+    # aliased to +item+, so you will have:
+    #   item(:code => 'WEB') do
+    #     other_code 'BEW'
+    #     # ...
+    #   end
+    def create(*args, &block)
+      fields = args.first || {}
+
+      defaults = proc_defaults ? @owner.instance_exec(&proc_defaults) : {}
+
+      klass.new(@owner.fields_for(klass).merge(defaults).merge(fields)).tap do |component|
+        component.instance_eval(&block) if block
+        container_for_associated << component
+      end
+    end
+
+    # Returns main container for association. For plain (without :linked_to option), it is
+    # array. For linked associations, it is a hash, which keys are records from linking
+    # associations, and values are arrays for association's objects
+    def container
+      @container ||= linked? ? {} : []
+    end
+
+    # Returns array for associated object to be pushed in. For plain associations, it is
+    # equivalent to +container+. For linked associations, uses +@owner+ and linking
+    # association's name to get the latest record from linking associations. If it does
+    # not exist, +NoLinkError+ will be raised.
+    #
+    # Example:
+    #   class Batch < ACH::Component
+    #     has_many :entries
+    #     has_many :addendas, :linked_to => :entries
+    #   end
+    #   batch = Batch.new
+    #   batch.entry(:amount => 100)
+    #   batch.addenda(:text => 'Foo')
+    #   batch.entry(:amount => 200)
+    #   batch.addenda(:text => 'Bar')
+    #   batch.addenda(:text => 'Baz')
+    #   
+    #   batch.entries  # => [<Entry, amount=100>, <Entry, amount=200>]
+    #   batch.addendas # => {<Entry, amount=100> => [<Addenda, text='Foo'>],
+    #                  #     <Entry, amount=200> => [<Addenda, text='Bar'>, <Addenda, text='Baz'>]}
+    def container_for_associated
+      return container unless linked?
+
+      last_link = @owner.send(linked_to).last
+      raise NoLinkError.new(linked_to.to_s.singularize, klass.name) unless last_link
+      container[last_link] ||= []
+    end
+
+    # Returns +true+ if association is linked to another association (thus, it's records must
+    # be preceded by other association's records). Returns +false+ otherwise
+    def linked?
+      !!linked_to
+    end
+    private :linked?
+
+    # Returns +klass+ that corresponds to association name. Should be defined either in
+    # ACH module, or in ACH::Record module
+    def klass
+      @klass ||= ACH.to_const(@name.classify.to_sym)
+    end
+    private :klass
+
+    # Returns singular name of the association
+    def singular_name
+      @singular_name ||= name.singularize
+    end
+    private :singular_name
+  end
+end

data/lib/ach/constants.rb

@@ -1,7 +1,21 @@
 module ACH
   module Constants
+    # The length of each record in characters.
     RECORD_SIZE     = 94
+    # The file's total record count must be a multiple of this number. The
+    # file must be padded with blocking file control records (consisting
+    # entirely of 9s) to satisfy this condition.
     BLOCKING_FACTOR = 10
+    # Always "1".
     FORMAT_CODE     = 1
-  end  
+    # This character must be used to delimit each row.
+    ROWS_DELIMITER  = "\n"
+
+    FILE_HEADER_RECORD_TYPE   = 1
+    FILE_CONTROL_RECORD_TYPE  = 9
+    BATCH_HEADER_RECORD_TYPE  = 5
+    BATCH_ENTRY_RECORD_TYPE   = 6
+    BATCH_ADDENDA_RECORD_TYPE = 7
+    BATCH_CONTROL_RECORD_TYPE = 8
+  end
 end

data/lib/ach/file.rb

@@ -1,49 +1,55 @@
 module ACH
+  # An ACH::File instance represents an actual ACH file. Every file has an
+  # ACH::File::Header and ACH::File::Control records and a variable number of
+  # ACH::Batches. The ACH::File::TransmissionHeader is optional. (Refer to the
+  # target financial institution's documentation.)
+  #
+  # == Example
+  #
+  #   # Subclass ACH::File to set default values:
+  #   class CustomAchFile < ACH::File
+  #     immediate_dest        '123123123'
+  #     immediate_dest_name   'COMMERCE BANK'
+  #     immediate_origin      '123123123'
+  #     immediate_origin_name 'MYCOMPANY'
+  #   end
+  #
+  #   # Create a new instance:
+  #   ach_file = CustomAchFile.new do
+  #     batch(:entry_class_code => "WEB", :company_entry_descr => "TV-TELCOM") do
+  #       effective_date Time.now.strftime('%y%m%d')
+  #       desc_date      Time.now.strftime('%b %d').upcase
+  #       origin_dfi_id "00000000"
+  #       entry :customer_name  => 'JOHN SMITH',
+  #             :customer_acct  => '61242882282',
+  #             :amount         => '2501',
+  #             :routing_number => '010010101',
+  #             :bank_account   => '103030030'
+  #     end
+  #   end
+  #   
+  #   # convert to string
+  #   ach_file.to_s! # => returns string representation of file
+  #
+  #   # write to file
+  #   ach_file.write('custom_ach.txt')
   class File < Component
-    has_many :batches, lambda{ {:batch_number => batches.length + 1} }
-    
-    def batch_count
-      batches.length
-    end
-    
-    def block_count
-      (file_entry_count.to_f / BLOCKING_FACTOR).ceil
-    end
-    
-    def file_entry_count
-      batches.map{ |b| b.entries.length }.inject(&:+) || 0
-    end
-    
-    def entry_hash
-      batches.map(&:entry_hash).compact.inject(&:+)
-    end
-    
-    def total_debit_amount
-      batches.map(&:total_debit_amount).compact.inject(&:+)
-    end
-    
-    def total_credit_amount
-      batches.map(&:total_credit_amount).compact.inject(&:+)
-    end
-    
-    def to_ach
-      extra = block_count * BLOCKING_FACTOR - file_entry_count
-      tail = ([Tail.new] * extra).unshift(control)
-      [header] + batches.map(&:to_ach).flatten + tail
-    end
-    
-    def to_s!
-      to_ach.map(&:to_s!).join("\r\n") + "\r\n"
-    end
-    
-    def record_count
-      2 + batches.length * 2 + file_entry_count
-    end
-    
-    def write filename
-      return false unless valid?
-      ::File.open(filename, 'w') do |fh|
-        fh.write(to_s!)
+    autoload :Builder
+    autoload :Control
+    autoload :Header
+    autoload :TransmissionHeader
+    autoload :Reader
+
+    include Builder
+    include TransmissionHeader
+
+    has_many :batches, :proc_defaults => lambda{ {:batch_number => batches.length + 1} }
+
+    # Opens a +filename+ and passes it's handler to the ACH::Reader object, which uses it as
+    # enum to scan for ACH contents line by line.
+    def self.read(filename)
+      ::File.open(filename) do |fh|
+        Reader.new(fh).to_ach
       end
     end
   end

data/lib/ach/file/builder.rb

@@ -0,0 +1,81 @@
+module ACH
+  # This module hosts all the methods required for building string representation of an ACH file,
+  # and writing it to an actual file in the filesystem. Included by the ACH::File.
+  module File::Builder
+    # Returns amount of +batches+ in file
+    def batch_count
+      batches.length
+    end
+
+    # Returns amount of blocks, used in count. This amount is based on <tt>blocking factor</tt>,
+    # which is usually equals to 10, and on overall amount of records in a file. Return value
+    # represents the least amount of blocks taken by records in file.
+    def block_count
+      (record_count.to_f / Constants::BLOCKING_FACTOR).ceil
+    end
+
+    # Returns total amount of +entry+ and +addenda+ records of all batches within file.
+    def file_entry_addenda_count
+      batches.map{ |batch| batch.entry_addenda_count }.inject(&:+) || 0
+    end
+
+    # Returns sum of +entry_hash+ values of all batches within self
+    def entry_hash
+      batch_sum_of(:entry_hash)
+    end
+
+    # Returns sum of +total_debit_amount+ values of all batches within self
+    def total_debit_amount
+      batch_sum_of(:total_debit_amount)
+    end
+
+    # Returns sum of +total_credit_amount+ values of all batches within self
+    def total_credit_amount
+      batch_sum_of(:total_credit_amount)
+    end
+
+    # Returns complete string representation of a ACH file by converting each interval record
+    # to a string and joining the result by <tt>Constants::ROWS_DELIMITER</tt>
+    def to_s!
+      to_ach.map(&:to_s!).join(Constants::ROWS_DELIMITER)
+    end
+
+    # Returns total amount of records hosted by a file.
+    def record_count
+      2 + batch_count * 2 + file_entry_addenda_count
+    end
+
+    # Writes string representation of self to passed +filename+
+    def write(filename)
+      return false unless valid?
+      ::File.open(filename, 'w') do |fh|
+        fh.write(to_s!)
+      end
+    end
+
+    # Helper method for calculating different properties of batches within file
+    def batch_sum_of(meth)
+      batches.map(&meth).compact.inject(&:+)
+    end
+    private :batch_sum_of
+
+    # Returns well-fetched array of all ACH records in the file, appending proper
+    # amount, based on number of blocks, of tail records to it.
+    def to_ach
+      head = [ header ]
+      head.unshift(transmission_header) if have_transmission_header?
+      head + batches.map(&:to_ach).flatten + [control] + tail
+    end
+
+    # Returns array of ACH::Record::Tail records, based on +tails_count+
+    def tail
+      [ Record::Tail.new ] * tails_count
+    end
+
+    # Returns amount of ACH::Record::Tail records, required to append to
+    # string representation of a file to match proper amount of blocks.
+    def tails_count
+      block_count * Constants::BLOCKING_FACTOR - record_count
+    end
+  end
+end

data/lib/ach/file/control.rb

@@ -1,15 +1,27 @@
 module ACH
-  class File::Control < Record
+  # Every ACH::File ends with an ACH::File::Control record.
+  #
+  # == Fields:
+  #
+  # * record_type
+  # * batch_count
+  # * block_count
+  # * file_entry_addenda_count
+  # * entry_hash
+  # * total_debit_amount
+  # * total_credit_amount
+  # * bank_39
+  class File::Control < Record::Base
     fields :record_type,
       :batch_count,
       :block_count,
-      :file_entry_count,
+      :file_entry_addenda_count,
       :entry_hash,
       :total_debit_amount,
       :total_credit_amount,
       :bank_39
     
-    defaults :record_type => 9,
+    defaults :record_type => FILE_CONTROL_RECORD_TYPE,
       :bank_39            => ''
   end
 end

data/lib/ach/file/header.rb

@@ -1,5 +1,23 @@
 module ACH
-  class File::Header < Record
+  # An ACH::File::Header record is the first record of every ACH::File
+  # (in case the ACH::File::TransmissionHeader record is absent).
+  #
+  # == Fields:
+  #
+  # * record_type
+  # * priority_code
+  # * immediate_dest
+  # * immediate_origin
+  # * date
+  # * time
+  # * file_id_modifier
+  # * record_size
+  # * blocking_factor
+  # * format_code
+  # * immediate_dest_name
+  # * immediate_origin_name
+  # * reference_code
+  class File::Header < Record::Base
     fields :record_type,
       :priority_code,
       :immediate_dest,
@@ -14,9 +32,8 @@ module ACH
       :immediate_origin_name,
       :reference_code
     
-    defaults :record_type => 1,
+    defaults :record_type => FILE_HEADER_RECORD_TYPE,
       :priority_code      => 1,
-      :reference_code     => '',
       :date               => lambda{ Time.now.strftime("%y%m%d") },
       :time               => lambda{ Time.now.strftime("%H%M") },
       :file_id_modifier   => 'A',

data/lib/ach/file/reader.rb

@@ -0,0 +1,103 @@
+module ACH
+  # The +ACH::File::Reader+ class builds a corresponding +ACH::File+
+  # object from a given set of data. The constructor takes an +enum+ object
+  # representing a sequence of ACH lines (strings). This +enum+ object may be
+  # a file handler, an array, or any other object that responds to the +#each+
+  # method.
+  class File::Reader
+    include Constants
+
+    def initialize(enum)
+      @enum = enum
+    end
+
+    def to_ach
+      header_line, batch_lines, control_line = ach_data
+
+      File.new do
+        build_header header_line
+
+        batch_lines.each do |batch_data|
+          batch do
+            build_header batch_data[:header]
+
+            batch_data[:entries].each do |entry_line|
+              build_entry entry_line
+
+              if batch_data[:addendas].key?(entry_line)
+                batch_data[:addendas][entry_line].each do |addenda_line|
+                  build_addenda addenda_line
+                end
+              end
+            end
+
+            build_control batch_data[:control]
+          end
+        end
+
+        build_control control_line
+      end
+    end
+
+    def ach_data
+      process! unless processed?
+
+      return @header, batches, @control
+    end
+    private :ach_data
+
+    def process!
+      each_line do |record_type, line|
+        case record_type
+        when FILE_HEADER_RECORD_TYPE
+          @header = line
+        when BATCH_HEADER_RECORD_TYPE
+          initialize_batch!
+          current_batch[:header] = line
+        when BATCH_ENTRY_RECORD_TYPE
+          current_batch[:entries] << line
+        when BATCH_ADDENDA_RECORD_TYPE
+          (current_batch[:addendas][current_entry] ||= []) << line
+        when BATCH_CONTROL_RECORD_TYPE
+          current_batch[:control] = line
+        when FILE_CONTROL_RECORD_TYPE
+          @control = line
+        end
+      end
+      @processed = true
+    end
+    private :process!
+
+    def processed?
+      !!@processed
+    end
+    private :processed?
+
+    def each_line
+      @enum.each do |line|
+        yield line[0..0].to_i, line.chomp
+      end
+    end
+    private :each_line
+
+    def batches
+      @batches ||= []
+    end
+    private :batches
+
+    def initialize_batch!
+      batches << {:entries => [], :addendas => {}}
+    end
+    private :initialize_batch!
+
+    def current_batch
+      batches.last
+    end
+    private :current_batch
+
+    def current_entry
+      current_batch[:entries].last
+    end
+    private :current_entry
+  end
+end