ach_builder 0.0.2 → 0.2.1

data/lib/ach/file/transmission_header.rb

@@ -0,0 +1,77 @@
+module ACH
+  # Hosts functionality required to append +TransmissionHeader+ to a file.
+  # +TransmissionHeader+ is optional and inherited from <tt>ACH::Record::Dynamic</tt>
+  # class, which means it may have variable number of fields with custom formatting.
+  # +TransmissionHeader+ may be defined only once per file. You may specify default
+  # value for custom fields during definition
+  #
+  # == Example
+  #
+  #   class MyFile < ACH::File
+  #     trasmission_header do
+  #       starting      '->1' => '<'
+  #       receiver_name '->10'
+  #       ending        '->1' => '>'
+  #     end
+  #     # other definitions
+  #   end
+  #   
+  #   file = MyFile.new do
+  #     receiver_name 'MY PROVIDER'
+  #   end
+  module File::TransmissionHeader
+    extend ActiveSupport::Concern
+
+    # Raised when (descendant of) ACH File tries to redeclare it's +TransmissionHeader+ 
+    class RedefinedTransmissionHeaderError < RuntimeError
+      def initialize
+        super "TransmissionHeader record may be defined only once"
+      end
+    end
+
+    # Raised when +TransmissionHeader+ is declared with no fields in it
+    class EmptyTransmissionHeaderError < RuntimeError
+      def initialize
+        super "Transmission_header should declare it's fields"
+      end
+    end
+
+    module ClassMethods
+      # Defines and declares +TransmissionHeader+ class within scope of +self+
+      def transmission_header(&block)
+        raise RedefinedTransmissionHeaderError if have_transmission_header?
+
+        klass = Class.new(Record::Dynamic, &block)
+
+        raise EmptyTransmissionHeaderError if klass.fields.nil? || klass.fields.empty?
+
+        const_set(:TransmissionHeader, klass)
+        @have_transmission_header = true
+      end
+
+      # Returns +true+ if +TransmissionHeader+ is defined within scope of the class.
+      def have_transmission_header?
+        @have_transmission_header
+      end
+    end
+
+    # Helper instance method. Returns +true+ if +TransmissionHeader+ is defined within
+    # scope of it's class
+    def have_transmission_header?
+      self.class.have_transmission_header?
+    end
+
+    # Builds +TransmissionHeader+ record for self. Yields it to +block+, if passed.
+    # Returns nil if no +TransmissionHeader+ is defined within scope of class.
+    def transmission_header(fields = {}, &block)
+      return nil unless have_transmission_header?
+
+      merged_fields = fields_for(self.class::TransmissionHeader).merge(fields)
+
+      @transmission_header ||= self.class::TransmissionHeader.new(merged_fields)
+      @transmission_header.tap do |head|
+        head.instance_eval(&block) if block
+      end
+    end
+  end
+end

data/lib/ach/formatter.rb

@@ -1,84 +1,121 @@
 module ACH
+  # Every field should be formatted with its own rule so Formatter take care about it.
+  # Rules are defined in ACH::RULES constant.
+  #
+  # == Rule Format
+  #
+  # Every rule can contain the next items:
+  # * _justification_  - "<-" or "->".
+  # * _width_          - a number of characters for a field.
+  # * _padding_        - specifying "-" will pad right-justified values with spaces instead of zeros.
+  # * _transformation_ - allows to call method on a string. Pipe must precedes a method name. Foe example: "|upcase".
+  # For real examples see RULES constants.
+  #
+  # == Usage Example
+  #
+  #    ACH::Formatter.format(:customer_name, "LINUS TORVALDS")  # => "LINUS TORVALDS        "
+  #    ACH::Formatter.format(:amount, 52)                       # => "0000000052"
+  #    ACH::Formatter.customer_acct('1234567890')               # => "1234567890     "
   module Formatter
-    extend self
-    
+    extend ActiveSupport::Autoload
+
+    autoload :Rule
+
+    # Rules for formatting each field. See module documentation for examples.
     RULES = {
-      :customer_name          => '<-22',
-      :customer_acct          => '<-15',
-      :amount                 => '->10',
-      :bank_2                 => '<-2',
-      :transaction_type       => '<-2',
-      :bank_15                => '<-15',
-      :addenda                => '<-1',
-      :trace_num              => '<-15',
-      :transaction_code       => '<-2',
-      :record_type            => '<-1',
-      :bank_account           => '<-17',
-      :routing_number         => '->9',
-      :priority_code          => '->2',
-      :immediate_dest         => '->10-',
-      :immediate_origin       => '->10-',
-      :date                   => '<-6',
-      :time                   => '<-4',
-      :file_id_modifier       => '<-1|upcase',
-      :record_size            => '->3',
-      :blocking_factor        => '->2',
-      :format_code            => '<-1',
-      :immediate_dest_name    => '<-23',
-      :immediate_origin_name  => '<-23',
-      :reference_code         => '<-8',
-      :service_class_code     => '<-3',
-      :company_name           => '<-16',
-      :company_note_data      => '<-20',
-      :company_id             => '<-10',
-      :entry_class_code       => '<-3',
-      :company_entry_descr    => '<-10',
-      :effective_date         => '<-6',
-      :settlement_date        => '<-3',
-      :origin_status_code     => '<-1',
-      :origin_dfi_id          => '<-8',
-      :batch_number           => '->7',
-      :entry_count            => '->6',
-      :entry_hash             => '->10',
-      :total_debit_amount     => '->12',
-      :total_credit_amount    => '->12',
-      :authen_code            => '<-19',
-      :bank_6                 => '<-6',
-      :batch_count            => '->6',
-      :block_count            => '->6',
-      :file_entry_count       => '->8',
-      :bank_39                => '<-39',
-      :nines                  => '<-94'
-    }.freeze
-    
-    RULE_PARSER_REGEX = /^(<-|->)(\d+)(-)?(\|\w+)?$/
-    
-    @@compiled_rules = {}
-    
-    def format field_name, value
-      compile_rule(field_name) unless @@compiled_rules.key?(field_name)
-      @@compiled_rules[field_name].call(value)
+      :customer_name            => '<-22',
+      :customer_acct            => '<-15',
+      :amount                   => '->10',
+      :bank_2                   => '<-2',
+      :transaction_type         => '<-2',
+      :bank_15                  => '<-15',
+      :addenda                  => '<-1',
+      :trace_num                => '<-15',
+      :transaction_code         => '<-2',
+      :record_type              => '<-1',
+      :bank_account             => '<-17',
+      :routing_number           => '->9',
+      :priority_code            => '->2',
+      :immediate_dest           => '->10-',
+      :immediate_origin         => '->10-',
+      :date                     => '<-6',
+      :time                     => '<-4',
+      :file_id_modifier         => '<-1|upcase',
+      :record_size              => '->3',
+      :blocking_factor          => '->2',
+      :format_code              => '<-1',
+      :immediate_dest_name      => '<-23',
+      :immediate_origin_name    => '<-23',
+      :reference_code           => '<-8',
+      :service_class_code       => '<-3',
+      :company_name             => '<-16', # aka Individual Name
+      :company_note_data        => '<-20',
+      :company_id               => '<-10',
+      :entry_class_code         => '<-3',
+      :company_entry_descr      => '<-10',
+      :effective_date           => '<-6',
+      :settlement_date          => '<-3',
+      :origin_status_code       => '<-1',
+      :origin_dfi_id            => '<-8',
+      :batch_number             => '->7',
+      :entry_addenda_count      => '->6',
+      :entry_hash               => '->10',
+      :total_debit_amount       => '->12',
+      :total_credit_amount      => '->12',
+      :authen_code              => '<-19',
+      :bank_6                   => '<-6',
+      :batch_count              => '->6',
+      :block_count              => '->6',
+      :file_entry_addenda_count => '->8',
+      :bank_39                  => '<-39',
+      :nines                    => '<-94',
+
+      # Batch header
+      :desc_date                => '<-6-', # company descriptive date
+
+      # Addenda Record
+      :addenda_type_code          => '->2',
+      :payment_related_info       => '<-80',
+      :addenda_sequence_num       => '->4',
+      :entry_details_sequence_num => '->7'
+    }
+
+    # Returns +true+ if +field_name+ is one of the keys of +RULES+
+    def self.defined?(field_name)
+      RULES.key?(field_name)
     end
-    
-    def method_missing meth, *args
-      if RULES.key? meth
-        format meth, *args
-      else
-        super
-      end
+
+    # Adds +field+ with corresponding +format+ to +RULES+
+    def self.define(field, format)
+      RULES[field] = format
     end
-    
-    def compile_rule field_name
-      just, width, pad, transf = RULES[field_name].match(RULE_PARSER_REGEX)[1..-1]
-      padmethod = just == '<-' ? :ljust : :rjust
-      length = width.to_i
-      padstr = padmethod == :ljust ? ' ' : pad == '-' ? ' ' : '0'
-      transform = transf[1..-1] if transf
-      @@compiled_rules[field_name] = lambda{ |val|
-        val = val.to_s[0..length]
-        (transform ? val.send(transform) : val).send(padmethod, length, padstr)
-      }
+
+    # If missing method name is one of the defined rules, passes its name
+    # and the rest of arguments to the +format+ method
+    def self.method_missing(meth, *args)
+      self.defined?(meth) ? format(meth, *args) : super
+    end
+
+    # Formats +value+ using the rule defined by +field_name+ format
+    def self.format(field_name, value)
+      rule_for_field(field_name).call(value)
+    end
+
+    # Returns ACH::Formatter::Rule rule, built from the corresponding format
+    # definition of a +field+
+    def self.rule_for_field(field)
+      compiled_rules[field] ||= Rule.new(RULES[field])
+    end
+
+    # Returns a hash of all rules that have been built at the moment of method call
+    def self.compiled_rules
+      @compiled_rules ||= {}
+    end
+
+    # Returns a regular expression that can be used to split string into matched parts,
+    # that will correspond to passed +fields+ parameter. Used for ACH reading purposes
+    def self.matcher_for(fields)
+      /^#{fields.map{ |f| "(.{#{rule_for_field(f).length}})" }.join}$/
     end
-    private :compile_rule
   end
 end

data/lib/ach/formatter/rule.rb

@@ -0,0 +1,27 @@
+module ACH
+  # Parses string representation of rule and builds a +Proc+ based on it
+  class Formatter::Rule
+    # Captures formatting tokens from a rule string.
+    RULE_PARSER_REGEX = /^(<-|->)(\d+)(-)?(\|\w+)?$/
+
+    delegate :call, :[], :to => :@lambda
+
+    attr_reader :length
+
+    # Initializes instance with formatting data. Parses passed string for formatting
+    # values, such as width, justification, etc. As the result, builds a Proc object
+    # that will be used to format passed string according to formatting rule.
+    def initialize(rule)
+      just, width, pad, transf = rule.match(RULE_PARSER_REGEX)[1..-1]
+      @length    = width.to_i
+      @padmethod = just == '<-' ? :ljust : :rjust
+      @padstr    = @padmethod == :ljust ? ' ' : pad == '-' ? ' ' : '0'
+      @transform = transf[1..-1] if transf
+
+      @lambda = Proc.new do |val|
+        val = val.to_s
+        (@transform ? val.send(@transform) : val).send(@padmethod, @length, @padstr)[-@length..-1]
+      end
+    end
+  end
+end

data/lib/ach/record.rb

@@ -1,66 +1,15 @@
 module ACH
-  class Record
-    include Validations
-    include Constants
-    
-    class UnknownField < ArgumentError
-      def initialize field, class_name
-        super "Unrecognized field '#{field}' in class #{class_name}"
-      end
-    end
-    
-    class EmptyField < ArgumentError
-      def initialize field
-        super "Empty field '#{field}' for #{inspect}"
-      end
-    end
-    
-    def self.fields *field_names
-      return @fields if field_names.empty?
-      @fields = field_names
-      @fields.each do |field|
-        raise UnknownField.new(field, name) unless Formatter::RULES.key?(field)
-        
-        define_method(field) do |*args|
-          args.empty? ? fields[field] : (fields[field] = args.first)
-        end
-        
-        define_method("#{field}=") do |val|
-          fields[field] = val
-        end
-      end
-    end
-    
-    def self.defaults default_values = nil
-      return @defaults if default_values.nil?
-      @defaults = default_values.freeze
-    end
-    
-    def initialize fields = {}, &block
-      defaults.each do |key, value|
-        self.fields[key] = Proc === value ? value.call : value
-      end
-      self.fields.merge!(fields)
-      instance_eval(&block) if block
-    end
-    
-    def defaults
-      self.class.defaults
-    end
-    
-    def fields
-      @fields ||= {}
-    end
-    
-    def []= name, val
-      fields[name] = val
-    end
-    
-    def to_s!
-      self.class.fields.map do |name|
-        raise EmptyField.new(name) if @fields[name].nil?
-        Formatter.format name, @fields[name]
-      end.join
-    end
+  # Responsible for record-specific functionality for most record types,
+  # handled by several subclasses. Record types handled outside this module
+  # include: ACH::File::Header, ACH::File::Control, ACH::Batch::Header,
+  # ACH::Batch::Control
+  module Record
+    extend ActiveSupport::Autoload
+
+    autoload :Addenda
+    autoload :Base
+    autoload :Dynamic
+    autoload :Entry
+    autoload :Tail
   end
-end
+end

data/lib/ach/record/addenda.rb

@@ -0,0 +1,25 @@
+module ACH
+  module Record
+    # An ACH::Record::Addenda is an ACH::Record::Base record located inside of
+    # an ACH::Batch component. An addenda record should be preceded by an
+    # ACH::Record::Entry record.
+    #
+    # == Fields
+    #
+    # * record_type
+    # * addenda_type_code
+    # * payment_related_info
+    # * addenda_sequence_num
+    # * entry_details_sequence_num
+    class Addenda < Base
+      fields :record_type,
+        :addenda_type_code,
+        :payment_related_info,
+        :addenda_sequence_num,
+        :entry_details_sequence_num
+
+      defaults :record_type => BATCH_ADDENDA_RECORD_TYPE,
+        :addenda_type_code => 5
+    end
+  end
+end

data/lib/ach/record/base.rb

@@ -0,0 +1,109 @@
+module ACH
+  module Record
+    # Base class for all record entities (e.g. +ACH::File::Header+,
+    # +ACH::File::Control+, +ACH::Record::Entry+, others). Any record
+    # being declared should specify its fields, and optional default values.
+    # Except for +ACH::Record::Dynamic+, any declared field within a record
+    # should have corresponding rule defined under +ACH::Rule::Formatter+.
+    #
+    # == Example
+    #
+    #   class Addenda < Record
+    #     fields :record_type,
+    #            :addenda_type_code,
+    #            :payment_related_info,
+    #            :addenda_sequence_num,
+    #            :entry_details_sequence_num
+    #     
+    #     defaults :record_type => 7
+    #   end
+    #   
+    #   addenda = ACH::Addenda.new(
+    #     :addenda_type_code => '05',
+    #     :payment_related_info => 'PAYMENT_RELATED_INFO',
+    #     :addenda_sequence_num => 1,
+    #     :entry_details_sequence_num => 1 )
+    #   addenda.to_s! # => "705PAYMENT_RELATED_INFO                                                            00010000001"
+    class Base
+      include Validations
+      include Constants
+      
+      # Raises when unknown field passed to ACH::Record::Base.fields method.
+      class UnknownFieldError < ArgumentError
+        def initialize(field, class_name)
+          super "Unrecognized field '#{field}' in class #{class_name}"
+        end
+      end
+      
+      # Raises when value of record's field is not specified and there is no
+      # default value.
+      class EmptyFieldError < ArgumentError
+        def initialize(field, record)
+          super "Empty field '#{field}' for #{record}"
+        end
+      end
+      
+      # Specifies fields of the record. Order is important. All fields
+      # must be declared in ACH::Formatter +RULES+. See class description
+      # for example
+      def self.fields(*field_names)
+        return @fields if field_names.empty?
+        @fields = field_names
+        @fields.each{ |field| define_field_methods(field) }
+      end
+      
+      # Sets default values for fields. See class description for example
+      def self.defaults(default_values = nil)
+        return @defaults if default_values.nil?
+        @defaults = default_values.freeze
+      end
+
+      def self.define_field_methods(field)
+        raise UnknownFieldError.new(field, name) unless Formatter::RULES.key?(field)
+        define_method(field) do |*args|
+          args.empty? ? @fields[field] : (@fields[field] = args.first)
+        end
+        define_method("#{field}=") do |val|
+          @fields[field] = val
+        end
+      end
+      private_class_method :define_field_methods
+
+      def self.from_s(string)
+        field_matcher_regexp = Formatter.matcher_for(fields)
+        new Hash[*fields.zip(string.match(field_matcher_regexp)[1..-1]).flatten]
+      end
+      
+      def initialize(fields = {}, &block)
+        defaults.each do |key, value|
+          self.fields[key] = Proc === value ? value.call : value
+        end
+        self.fields.merge!(fields)
+        instance_eval(&block) if block
+      end
+      
+      # Builds a string from record object.
+      def to_s!
+        self.class.fields.map do |name|
+          raise EmptyFieldError.new(name, self) if @fields[name].nil?
+          Formatter.format name, @fields[name]
+        end.join
+      end
+
+      # Returns a hash where key is field's name and value is field's value.
+      def fields
+        @fields ||= {}
+      end
+
+      def defaults
+        self.class.defaults
+      end
+      private :defaults
+      
+      def []=(name, val)
+        fields[name] = val
+      end
+      private :[]=
+    end
+  end
+end