ach_builder 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a6370b31599af5467812e5b45be57e99c5e19a32
-  data.tar.gz: 326db2ed6596c13a95ad0deeb8b5a9881270e857
+  metadata.gz: 13b50247a53e8f32fca29c49375e6d700bd039bf
+  data.tar.gz: 84d5a95e03d5f96f1a591c47d23e748cc613c1ca
 SHA512:
-  metadata.gz: a039dc192619a516cdf9c09fdefe33dde1505655c6b67c9bdacfd7ab47301a5586b1d1b5cd01292ef244cbd1fece3aa81b7344a9c4168f40e0a68d6694ac31f5
-  data.tar.gz: 5175200c43de130adb641b6d6c3d247b860b6e186cf2ff9ecc871dae6d95f0465f189a04f9d0e8f2430c811b77c74ad6272bbdea8b8109f6d667037aafce5fff
+  metadata.gz: 6442a48f3ac4122b01339c4f95d5b4306efe21437834633211ca5bb16495cb2e07a8a08e59f8a28406a898c80101fdd05e3c8269152bb8d679876dd79c6974b4
+  data.tar.gz: 65e1c78ea5211a84b37394cfa84c2ef296cc6248291139f26d7a72bebd1c152189d3a1bce1903c5f950869832b3785a01a1adc16050594c79d08dcbef8c4d62e

data/.ruby-version

@@ -1 +1 @@
-2.0.0-p247
+2.0.0

data/Gemfile

@@ -4,10 +4,10 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in ach_builder.gemspec
 gem 'i18n'
 gemspec
-gem 'rspec'
 
 group :development, :test do
   gem 'rspec'
+  gem 'yard'
 
   gem "simplecov"          , :require => false
   gem 'simplecov-rcov-text', :require => false

data/ach_builder.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |s|
   s.name        = "ach_builder"
   s.version     = ACH::VERSION
   s.authors     = ["TMX Credit", "Artem Kuzko", "Sergey Potapov"]
-  s.email       = ["rubygems@tmxcredit.com", "AKuzko@sphereconsultinginc.com", "SPotapov@sphereconsultinginc.com"]
+  s.email       = ["rubygems@tmxcredit.com", "AKuzko@sphereconsultinginc.com", "blake131313@gmail.com"]
   s.homepage    = "https://github.com/TMXCredit/ach_builder"
   s.summary     = "Ruby tools for building ACH files"
   s.description = "Ruby tools for building ACH (Automated Clearing House) files"

data/lib/ach/batch/builder.rb

@@ -2,49 +2,66 @@ module ACH
   # Supports building a string representation of a particular instance of an
   # ACH batch. Supports building ACH lines. Included by ACH::File.
   module Batch::Builder
-    # Returns +true+ if any of internal ACH entries has 'credit' transaction code
+    # Returns +true+ if any of internal ACH entries has 'credit' transaction code.
+    #
+    # @return [Boolean]
     def has_credit?
       entries.any?(&:credit?)
     end
 
-    # Returns +true+ if any internal ACH entry has 'debit' transaction code
+    # Returns +true+ if any internal ACH entry has 'debit' transaction code.
+    #
+    # @return [Boolean]
     def has_debit?
       entries.any?(&:debit?)
     end
 
-    # Returns total amount of entry and addenda records within batch
+    # Returns total amount of entry and addenda records within batch.
+    #
+    # @return [Fixnum]
     def entry_addenda_count
       entries.size + addendas.values.flatten.size
     end
 
     # Returns 'hashed' representation of all entries within batch. See NACHA
-    # documentation for more details on entry hash
+    # documentation for more details on entry hash.
+    #
+    # @return [Fixnum]
     def entry_hash
       entries.map{ |entry| entry.routing_number.to_i / 10 }.compact.inject(&:+)
     end
 
-    # Returns total amount of all 'debit' entries within a batch
+    # Returns total amount of all 'debit' entries within a batch.
+    #
+    # @return [Fixnum]
     def total_debit_amount
       amount_sum_for(:debit?)
     end
 
-    # Returns total amount of all 'credit' entries within a batch
+    # Returns total amount of all 'credit' entries within a batch.
+    #
+    # @return [Fixnum]
     def total_credit_amount
       amount_sum_for(:credit?)
     end
 
-    # Returns ACH record objects that represent the batch
+    # Returns ACH record objects that represent the batch.
+    #
+    # @return [Array<ACH::Record::Base>]
     def to_ach
       [header] + fetch_entries + [control]
     end
 
-    # Helper method executed just before building a header record for the batch
+    # Helper method executed just before building a header record for the batch.
     def before_header
       attributes[:service_class_code] ||= (has_debit? && has_credit? ? 200 : has_debit? ? 225 : 220)
     end
     private :before_header
 
     # Helper method, returns total amount of all entries within a batch, filtered by +meth+
+    #
+    # @param [Symbol] meth
+    # @return [Fixnum]
     def amount_sum_for(meth)
       entries.select(&meth).map{ |entry| entry.amount.to_i }.compact.inject(&:+) || 0
     end
@@ -52,6 +69,8 @@ module ACH
 
     # Fetches all internal records (entries and addendas) in right order, i.e. addenda records
     # should be positioned right after corresponding entry records.
+    #
+    # @return [Array<ACH::Record::Base>]
     def fetch_entries
       entries.inject([]){ |all, entry| all << entry << addendas[entry] }.flatten.compact
     end

data/lib/ach/component.rb

@@ -19,7 +19,11 @@ module ACH
 
     # Exception raised on attempt to assign a value to nonexistent field.
     class UnknownAttributeError < ArgumentError
-      def initialize field, obj
+      # Initialize error with field and component.
+      #
+      # @param [String] field
+      # @param [ACH::Component] obj
+      def initialize(field, obj)
         super "Unrecognized attribute '#{field}' for #{obj}"
       end
     end
@@ -31,6 +35,9 @@ module ACH
 
     attr_reader :attributes
 
+    # When inherited, clone class-related properties.
+    #
+    # @param [Class] klass
     def self.inherited(klass)
       klass.default_attributes = default_attributes.dup
       klass.after_initialize_hooks = after_initialize_hooks.dup
@@ -46,6 +53,9 @@ module ACH
     # header record.
     #
     # Note that default values may be overwritten when building records.
+    #
+    # @param [Symbol] meth
+    # @param [*Object] args
     def self.method_missing(meth, *args)
       if Formatter.defined?(meth)
         default_attributes[meth] = args.first
@@ -54,16 +64,28 @@ module ACH
       end
     end
 
-    def initialize(fields = {}, &block)
-      @attributes = {}.merge(self.class.default_attributes)
+    # Initialize component with field values. If block is given, it is evaluated in context
+    # of component, allowing setting fields via method calls and declarations of nested
+    # components.
+    #
+    # @param [Hash] fields
+    # @raise [UnknownAttributeError]
+    def initialize(fields = {})
+      @attributes = self.class.default_attributes.dup
       fields.each do |name, value|
         raise UnknownAttributeError.new(name, self) unless Formatter.defined?(name)
         @attributes[name] = value
       end
       after_initialize
-      instance_eval(&block) if block
+      instance_eval(&Proc.new) if block_given?
     end
 
+    # Missing messages are treated as accessor methods for a component if their
+    # message name is defined by {ACH::Formatter}.
+    #
+    # @param [Symbol] meth
+    # @param [*Object] args
+    # @return [String]
     def method_missing(meth, *args)
       if Formatter.defined?(meth)
         args.empty? ? @attributes[meth] : (@attributes[meth] = args.first)
@@ -72,7 +94,9 @@ module ACH
       end
     end
 
-    def before_header # :nodoc:
+    # Hook that is called whenever component header record is created. To be
+    # overridden in subclasses.
+    def before_header
     end
     private :before_header
 
@@ -92,19 +116,26 @@ module ACH
     # == Example 3
     #
     #   header # => just returns a header object
-    def header(fields = {}, &block)
+    def header(fields = {})
       before_header
       merged_fields = fields_for(self.class::Header).merge(fields)
       @header ||= self.class::Header.new(merged_fields)
       @header.tap do |head|
-        head.instance_eval(&block) if block
+        head.instance_eval(&Proc.new) if block_given?
       end
     end
 
-    def build_header(str) # :nodoc:
+    # Build a component (+File+ or +Batch+) related +Header+ record from a given string.
+    #
+    # @param [String] str
+    # @return [ACH::Record::Base]
+    def build_header(str)
       @header = self.class::Header.from_s(str)
     end
 
+    # Build a component-related +Control+ record.
+    #
+    # @return [ACH::Record::Base]
     def control
       @control ||= begin
         klass  = self.class::Control
@@ -113,10 +144,19 @@ module ACH
       end
     end
 
-    def build_control(str) # :nodoc:
+    # Build a component-related +Control+ record from a given string.
+    #
+    # @param [String] str
+    # @return [ACH::Record::Base]
+    def build_control(str)
       @control = self.class::Control.from_s(str)
     end
-    
+
+    # Return a set of fields, that is a subset of +attributes+ that can be used to
+    # initialize an instance of a +klass+. +Component+ uses +attributes+ itself.
+    #
+    # @param [Class] klass
+    # @return [Hash]
     def fields_for(klass)
       if klass < Component
         attributes
@@ -126,11 +166,13 @@ module ACH
       end
     end
 
-    def after_initialize # :nodoc:
+    # Execute all +Proc+ objects contained in the +after_initialize_hooks+
+    # array in the context of the object.
+    def after_initialize
       self.class.after_initialize_hooks.each{ |hook| instance_exec(&hook) }
     end
     
-    # Creates has many association.
+    # Creates a has_many association.
     #
     # == Example
     #
@@ -147,6 +189,9 @@ module ACH
     # The example above extends File with #batches and #batch instance methods:
     # * #batch is used to add new instance of Batch.
     # * #batches is used to get an array of batches which belong to file.
+    #
+    # @param [Symbol] plural_name
+    # @param [Hash] options
     def self.has_many(plural_name, options = {})
       association = HasManyAssociation.new(plural_name, options)
 

data/lib/ach/component/has_many_association.rb

@@ -25,6 +25,10 @@ module ACH
     # created after Entry records. Each new Addenda record will be attached
     # to the latest Entry record.
     class NoLinkError < ArgumentError
+      # Initialize the error with a descriptive message.
+      #
+      # @param [String] link
+      # @param [Class] klass
       def initialize(link, klass)
         super "No #{link} was found to attach a new #{klass}"
       end
@@ -33,6 +37,10 @@ module ACH
     # Exception thrown if an association object, assigned for particular
     # owner object, is used to assign to another owner object
     class DoubleAssignmentError < StandardError
+      # Initialize the error with a descriptive message.
+      #
+      # @param [String] name
+      # @param [ACH::Component] owner
       def initialize(name, owner)
         super "Association #{name} has alredy been assigned to #{owner}"
       end
@@ -41,14 +49,23 @@ module ACH
     attr_reader :name, :linked_to, :proc_defaults
     private :linked_to, :proc_defaults
 
+    # Initialize the association with a plural name and options.
+    #
+    # @param [String] plural_name
+    # @param [Hash] options
+    # @option options [Symbol] :linked_to plural name of records to link associated ones
+    # @option options [Proc] :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 +self+ and assign +owner+ to clone. Also, for newly created
     # clone association that has owner, aliases main methods so that +owner+
     # may delegate to them.
+    #
+    # @param [ACH::Component] owner
+    # @raise [DoubleAssignmentError]
     def for(owner)
       raise DoubleAssignmentError.new(@name, @owner) if @owner
 
@@ -63,51 +80,63 @@ module ACH
       end
     end
 
-    # Returns an array of methods to be delegated by +owner+ of the association.
+    # Return 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
+    # * +items+ - that returns set of Item objects.
+    #
+    # @return [Array<String>]
     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
+    # Use <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.
+    #
+    # @param [String] str
+    # @return [Array<ACH::Record::Base>]
     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
+    # Create an associated object using common to ACH controls pattern, and push it to
+    # an 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)
+    #
+    # @param [*Object] args
+    # @return [Object] instance of a class under ACH namespace
+    def create(*args)
       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
+        component.instance_eval(&Proc.new) if block_given?
         container_for_associated << component
       end
     end
 
-    # Returns main container for association. For plain (without :linked_to option), it is
+    # Return the 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
+    # associations, and values are arrays for association's objects.
+    #
+    # @return [Hash, Array]
     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.
+    # Return an array onto which the associated object may be be pushed. 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
@@ -124,6 +153,9 @@ module ACH
     #   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'>]}
+    #
+    # @return [Array]
+    # @raise [NoLinkError]
     def container_for_associated
       return container unless linked?
 
@@ -132,21 +164,27 @@ module ACH
       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
+    # Return +true+ if the association is linked to another association (thus, its records must
+    # be preceded by other association's records). Returns +false+ otherwise.
+    #
+    # @return [Boolean]
     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
+    # Return +klass+ that corresponds to the association name. Should be defined either in
+    # ACH module, or in ACH::Record module.
+    #
+    # @return [Class]
     def klass
       @klass ||= ACH.to_const(@name.classify.to_sym)
     end
     private :klass
 
-    # Returns singular name of the association
+    # Return the singular name of the association.
+    #
+    # @return [String]
     def singular_name
       @singular_name ||= name.singularize
     end

data/lib/ach/constants.rb

@@ -1,4 +1,5 @@
 module ACH
+  # This module is a simple namespace for constants used in ACH routines.
   module Constants
     # The length of each record in characters.
     RECORD_SIZE     = 94
@@ -11,11 +12,17 @@ module ACH
     # This character must be used to delimit each row.
     ROWS_DELIMITER  = "\n"
 
+    # ACH defined value of File Header record.
     FILE_HEADER_RECORD_TYPE   = 1
+    # ACH defined value of File Control record.
     FILE_CONTROL_RECORD_TYPE  = 9
+    # ACH defined value of Batch Header record.
     BATCH_HEADER_RECORD_TYPE  = 5
+    # ACH defined value of Batch Entry record.
     BATCH_ENTRY_RECORD_TYPE   = 6
+    # ACH defined value of Batch Addenda record.
     BATCH_ADDENDA_RECORD_TYPE = 7
+    # ACH defined value of Batch Control record.
     BATCH_CONTROL_RECORD_TYPE = 8
   end
-end
+end