ach_builder 0.2.1 → 0.2.2

data/lib/ach/file.rb

@@ -45,8 +45,11 @@ module ACH
 
     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.
+    # Open a +filename+ and pass its handler to the ACH::Reader object,
+    # which uses it as an enum to scan for ACH contents line by line.
+    #
+    # @param [String] filename
+    # @return [ACH::File]
     def self.read(filename)
       ::File.open(filename) do |fh|
         Reader.new(fh).to_ach

data/lib/ach/file/builder.rb

@@ -2,50 +2,70 @@ 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
+    # Return amount of +batches+ in file.
+    #
+    # @return [Fixnum]
     def batch_count
       batches.length
     end
 
-    # Returns amount of blocks, used in count. This amount is based on <tt>blocking factor</tt>,
+    # Return 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.
+    #
+    # @return [Fixnum]
     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.
+    # Return total amount of +entry+ and +addenda+ records of all batches within file.
+    #
+    # @return [Fixnum]
     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
+    # Return sum of +entry_hash+ values of all batches within self.
+    #
+    # @return [Fixnum]
     def entry_hash
       batch_sum_of(:entry_hash)
     end
 
-    # Returns sum of +total_debit_amount+ values of all batches within self
+    # Return sum of +total_debit_amount+ values of all batches within +self+.
+    #
+    # @return [Fixnum]
     def total_debit_amount
       batch_sum_of(:total_debit_amount)
     end
 
-    # Returns sum of +total_credit_amount+ values of all batches within self
+    # Return sum of +total_credit_amount+ values of all batches within +self+.
+    #
+    # @return [Fixnum]
     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>
+    # Return a complete string representation of an ACH file by converting each
+    # interval record to a string and joining the result by
+    # +ACH::Constants::ROWS_DELIMITER+.
+    #
+    # @return [String]
     def to_s!
       to_ach.map(&:to_s!).join(Constants::ROWS_DELIMITER)
     end
 
-    # Returns total amount of records hosted by a file.
+    # Return total amount of records hosted by a file.
+    #
+    # @return [Fixnum]
     def record_count
       2 + batch_count * 2 + file_entry_addenda_count
     end
 
-    # Writes string representation of self to passed +filename+
+    # Write string representation of self to passed +filename+.
+    #
+    # @param [String] filename
+    # @return [::File]
     def write(filename)
       return false unless valid?
       ::File.open(filename, 'w') do |fh|
@@ -53,29 +73,38 @@ module ACH
       end
     end
 
-    # Helper method for calculating different properties of batches within file
+    # Helper method for calculating different properties of batches within file.
+    #
+    # @param [String] meth
+    # @return [Fixnum]
     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
+    # Return well-fetched array of all ACH records in the file, appending proper
     # amount, based on number of blocks, of tail records to it.
+    #
+    # @return [Array<ACH::Record::Base>]
     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+
+    # Return array of ACH::Record::Tail records, based on +tails_count+.
+    #
+    # @return [Array<ACH::Record::Tail>]
     def tail
-      [ Record::Tail.new ] * tails_count
+      [Record::Tail.new] * tails_count
     end
 
-    # Returns amount of ACH::Record::Tail records, required to append to
+    # Return amount of ACH::Record::Tail records, required to append to
     # string representation of a file to match proper amount of blocks.
+    #
+    # @return [Fixnum]
     def tails_count
       block_count * Constants::BLOCKING_FACTOR - record_count
     end
   end
-end
+end

data/lib/ach/file/reader.rb

@@ -7,10 +7,16 @@ module ACH
   class File::Reader
     include Constants
 
+    # Initialize reader.
+    #
+    # @param [#each] enum
     def initialize(enum)
       @enum = enum
     end
 
+    # Build a {ACH::File} object using data obtained from +@enum+ source.
+    #
+    # @return [ACH::File]
     def to_ach
       header_line, batch_lines, control_line = ach_data
 
@@ -39,6 +45,9 @@ module ACH
       end
     end
 
+    # Process the source and return header batch and control records.
+    #
+    # @return [Array<ACH::Record::Base, Array>]
     def ach_data
       process! unless processed?
 
@@ -46,6 +55,10 @@ module ACH
     end
     private :ach_data
 
+    # Process each line by iterating over strings in +@enum+ source one by one and
+    # generating ACH information corresponding to record line.
+    #
+    # @return [true]
     def process!
       each_line do |record_type, line|
         case record_type
@@ -68,11 +81,16 @@ module ACH
     end
     private :process!
 
+    # Return +true+ if +@enum+ has been processed.
+    #
+    # @return [Boolean]
     def processed?
       !!@processed
     end
     private :processed?
 
+    # Iterate over +enum+ and yield first symbol of the string as
+    # record type and string itself.
     def each_line
       @enum.each do |line|
         yield line[0..0].to_i, line.chomp
@@ -80,21 +98,34 @@ module ACH
     end
     private :each_line
 
+    # Return array of batches in hash representation.
+    #
+    # @return [Array<Hash>]
     def batches
       @batches ||= []
     end
     private :batches
 
+    # Add a new hash representation of a batch to the batch list
+    # to be filled out during processing.
+    #
+    # @return [Array<Hash>]
     def initialize_batch!
       batches << {:entries => [], :addendas => {}}
     end
     private :initialize_batch!
 
+    # Current (the last one) batch to fill.
+    #
+    # @return [Hash]
     def current_batch
       batches.last
     end
     private :current_batch
 
+    # Current (the last one) entry string of the last batch that was processed.
+    #
+    # @return [String]
     def current_entry
       current_batch[:entries].last
     end

data/lib/ach/file/transmission_header.rb

@@ -22,8 +22,9 @@ module ACH
   module File::TransmissionHeader
     extend ActiveSupport::Concern
 
-    # Raised when (descendant of) ACH File tries to redeclare it's +TransmissionHeader+ 
+    # Raised when (descendant of) ACH File tries to redeclare it's +TransmissionHeader+.
     class RedefinedTransmissionHeaderError < RuntimeError
+      # Initialize error with descriptive message.
       def initialize
         super "TransmissionHeader record may be defined only once"
       end
@@ -31,13 +32,19 @@ module ACH
 
     # Raised when +TransmissionHeader+ is declared with no fields in it
     class EmptyTransmissionHeaderError < RuntimeError
+      # Initialize error with descriptive message.
       def initialize
         super "Transmission_header should declare it's fields"
       end
     end
 
+    # Class macros.
     module ClassMethods
-      # Defines and declares +TransmissionHeader+ class within scope of +self+
+      # Defines and declares +TransmissionHeader+ class within scope of +self+.
+      #
+      # @return [Boolean]
+      # @raise [RedefinedTransmissionHeaderError]
+      # @raise [EmptyTransmissionHeaderError]
       def transmission_header(&block)
         raise RedefinedTransmissionHeaderError if have_transmission_header?
 
@@ -50,27 +57,34 @@ module ACH
       end
 
       # Returns +true+ if +TransmissionHeader+ is defined within scope of the class.
+      #
+      # @return [Boolean]
       def have_transmission_header?
         @have_transmission_header
       end
     end
 
     # Helper instance method. Returns +true+ if +TransmissionHeader+ is defined within
-    # scope of it's class
+    # scope of it's class.
+    #
+    # @return [Boolean]
     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)
+    #
+    # @param [Hash] fields
+    # @return [ACH::File::TransmissionHeader]
+    def transmission_header(fields = {})
       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
+        head.instance_eval(&Proc.new) if block_given?
       end
     end
   end

data/lib/ach/formatter.rb

@@ -1,5 +1,5 @@
 module ACH
-  # Every field should be formatted with its own rule so Formatter take care about it.
+  # Ensures that every field is formatted with its own rule.
   # Rules are defined in ACH::RULES constant.
   #
   # == Rule Format
@@ -80,40 +80,62 @@ module ACH
       :entry_details_sequence_num => '->7'
     }
 
-    # Returns +true+ if +field_name+ is one of the keys of +RULES+
+    # Return +true+ if +field_name+ is one of the keys of +RULES+.
+    #
+    # @param [Symbol] field_name
+    # @return [Boolean]
     def self.defined?(field_name)
       RULES.key?(field_name)
     end
 
-    # Adds +field+ with corresponding +format+ to +RULES+
+    # Add a +field+ with corresponding +format+ to +RULES+.
+    #
+    # @param [Symbol] field
+    # @param [String] format
+    # @return [Hash]
     def self.define(field, format)
       RULES[field] = format
     end
 
-    # If missing method name is one of the defined rules, passes its name
-    # and the rest of arguments to the +format+ method
+    # If missing method name is one of the defined rules, pass its name
+    # and the rest of arguments to the +format+ method.
+    #
+    # @param [Symbol] meth
+    # @param [*Object] args
     def self.method_missing(meth, *args)
       self.defined?(meth) ? format(meth, *args) : super
     end
 
-    # Formats +value+ using the rule defined by +field_name+ format
+    # Format the +value+ using the rule defined by +field_name+ format.
+    #
+    # @param [Symbol] field_name
+    # @param [String] value
+    # @return [String]
     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+
+    # Return ACH::Formatter::Rule rule, built from the corresponding format
+    # definition of a +field+.
+    #
+    # @param [Symbol] field
+    # @return [ACH::Formatter::Rule]
     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
+    # Return a hash of all rules that have been built at the moment of method call.
+    #
+    # @return [Hash]
     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
+    # Return 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.
+    #
+    # @param [Array<Symbol>] fields
+    # @return [Regexp]
     def self.matcher_for(fields)
       /^#{fields.map{ |f| "(.{#{rule_for_field(f).length}})" }.join}$/
     end

data/lib/ach/formatter/rule.rb

@@ -8,9 +8,12 @@ module ACH
 
     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.
+    # Initialize the instance with the formatting data. Parses the given string
+    # for formatting values, such as width, justification, etc. With the result,
+    # it builds a Proc object to be used to format the given string according
+    # to the formatting rule.
+    #
+    # @param [ACH::Formatter::Rule] rule
     def initialize(rule)
       just, width, pad, transf = rule.match(RULE_PARSER_REGEX)[1..-1]
       @length    = width.to_i

data/lib/ach/record/base.rb

@@ -27,37 +27,56 @@ module ACH
     class Base
       include Validations
       include Constants
-      
+
       # Raises when unknown field passed to ACH::Record::Base.fields method.
       class UnknownFieldError < ArgumentError
+        # Initialize error with descriptive message.
+        #
+        # @param [Symbol] field
+        # @param [String] class_name
         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
+        # Initialize error with descriptive message.
+        #
+        # @param [Symbol] field
+        # @param [ACH::Record::Base] record
         def initialize(field, record)
           super "Empty field '#{field}' for #{record}"
         end
       end
-      
-      # Specifies fields of the record. Order is important. All fields
+
+      # Specify the fields of the record. Order is important. All fields
       # must be declared in ACH::Formatter +RULES+. See class description
-      # for example
+      # for example.
+      #
+      # @param [*Symbol] field_names
+      # @return [Array<Symbol>]
       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
+
+      # Set default values for fields. See class description for example.
+      #
+      # @param [Hash, nil] default_values
+      # @return [Hash]
       def self.defaults(default_values = nil)
         return @defaults if default_values.nil?
         @defaults = default_values.freeze
       end
 
+      # Define accessor methods for a given field name if it can be found
+      # in the keys of {ACH::Formatter::RULES}.
+      #
+      # @param [Symbol] field
+      # @raise [UnknownFieldError]
       def self.define_field_methods(field)
         raise UnknownFieldError.new(field, name) unless Formatter::RULES.key?(field)
         define_method(field) do |*args|
@@ -69,20 +88,31 @@ module ACH
       end
       private_class_method :define_field_methods
 
+      # Build a new instance of a record from its string representation.
+      #
+      # @param [String] string
+      # @return [ACH::Record::Base]
       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)
+
+      # Initialize object with field values. If block is given, it will be
+      # evaluated in context of isntance.
+      #
+      # @param [Hash] fields
+      def initialize(fields = {})
         defaults.each do |key, value|
           self.fields[key] = Proc === value ? value.call : value
         end
         self.fields.merge!(fields)
-        instance_eval(&block) if block
+        instance_eval(&Proc.new) if block_given?
       end
-      
-      # Builds a string from record object.
+
+      # Build a string from record object.
+      #
+      # @return [Stirng]
+      # @raise [EmptyFieldError]
       def to_s!
         self.class.fields.map do |name|
           raise EmptyFieldError.new(name, self) if @fields[name].nil?
@@ -90,16 +120,26 @@ module ACH
         end.join
       end
 
-      # Returns a hash where key is field's name and value is field's value.
+      # Return a hash where key is the field's name and value is the field's value.
+      #
+      # @return [Hash]
       def fields
         @fields ||= {}
       end
 
+      # Return field default values defined in class.
+      #
+      # @return [Hash]
       def defaults
         self.class.defaults
       end
       private :defaults
-      
+
+      # Delegate bracket-assignment to +fields+.
+      #
+      # @param [Symbol] name
+      # @param [String] val
+      # @return [String]
       def []=(name, val)
         fields[name] = val
       end