hippo 0.1.2 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,10 @@
+0.2.0 - 2012/01/21
+  * Updated segment definitions to differentiate between
+    Integer and Decimal.
+  * Add field level datatype conversion. Date, Time, Integer,
+    and Decimal fields will be stored internally as their
+    appropriate type and converted to a properly formatted
+    string representation when needed.
 0.1.2 - 2012/01/18
   * Add RepeatingComponent to Outputters.
   * Add HIPAA_997 to list of supported transaction sets.

data/README.md

@@ -96,6 +96,10 @@ Transaction Sets/Loops and Segments are defined with a very straight forward DSL
         field :name => 'Field4'
         field :name => 'CommonName'
         field :name => 'CommonName'
+        field :name => 'DateField',     :datatype => :date
+        field :name => 'TimeField',     :datatype => :time
+        field :name => 'IntegerField',  :datatype => :integer
+        field :name => 'DecimalField',  :datatype => :decimal
       end
 
       class TestCompoundSegment < Hippo::Segments::Base
@@ -223,8 +227,8 @@ composite field you can optionally pass the index of the field to access.
     ts.TCS do |tcs|
       tcs.Field1    = 'Foo'     # use the field name
       tcs.TCS01_01  = 'Bar'     # use shorthand notation:
-                                #   TCS01 refers to the composite field
-                                #   _01 refers to the first field within the composite
+                                #   TCS01 refers to the first field within the current segment
+                                #   _01 refers to the first field within the composite field
     end
 ```
 
@@ -235,9 +239,9 @@ but if you need to access the second instance of TSS in the transaction set you
 TSS_02 instead.
 
 ```ruby
-    ts.TCS.Field1 = 'Foo'
-    ts.TSS.Field2 = 'Bar'
-    ts.TSS_02.Field2 = 'Baz'
+    ts.TCS.Field1     = 'Foo'
+    ts.TSS.Field2     = 'Bar'
+    ts.TSS_02.Field2  = 'Baz'
 
     # ts.to_s => 'TSS*Blah*Bar~TCS*Foo**Preset Field 7~TSS*Last Segment*Baz~'
 ```
@@ -248,12 +252,12 @@ on the name provided in the TransactionSet definition.  You can either pass the
 a Regexp to search with.
 
 ```ruby
-    ts.find\_by\_name('Test Simple Segment #1') do |tss|
+    ts.find_by_name('Test Simple Segment #1') do |tss|
       tss.Field2 = 'Baz'
     end
 
     # which is essentially equivilent (because the search occurs in order of declaration)
-    ts.find\_by\_name(/Segment/) do |tss|
+    ts.find_by_name(/Segment/) do |tss|
       tss.Field2 = 'Baz'
     end
 
@@ -269,6 +273,53 @@ The same technique can be used to reference fields within a segment that have th
     # ts.to_s => 'TSS*Blah*Bar***Value1*Value2~TCS*Foo**Preset Field 7~TSS*Last Segment*Baz~'
 ```
 
+Type Conversion
+---------------
+
+As of Hippo version 0.2.0 values are stored in the native format, and coverted back to the
+appropriate string representation when required.  This means that you can set and access date,
+time, integer, and decimal fields without having to convert back and forth between strings.
+
+As part of the type conversion process we are also validating that a fields value is being set
+with a valid value for that particular data type.
+
+Just a few examples using the type conversion:
+
+```ruby
+    seg = Hippo::Segments::TSS.new    # Please review definition from above.
+
+    # Date fields:
+    seg.DateField = Date.new(2012, 01, 20)
+    seg.DateField = "20120120"
+    seg.DateField = Time.new(2012, 01, 20, 10, 15, 20)
+
+    # all of these formats result in the same internal representation
+    puts seg.DateField.inspect # => #<Date: 2012-01-20 ((2455947j,0s,0n),+0s,2299161j)>
+
+    # To set the field back to a blank/empty value simply assign it to nil
+    seg.DateField = nil
+
+    # Time fields:
+    seg.TimeField = "0120"      # => 1:20 am       (HHMM)
+    seg.TimeField = "012023"    # => 1:20:23 am    (HHMMSS)
+    seg.TimeField = "01202322"  # => 1:20:23.22 am (HHMMSSDD)
+    seg.TimeField = Time.now
+
+    # Integer fields:
+    seg.IntegerField = "10"     # => 10
+    seg.IntegerField = 10       # => 10
+    seg.IntegerField = "10blah" # => 10
+
+    # Decimal fields:
+    seg.DecimalField = "123.45"   # => #<BigDecimal:7fe83c315750,'0.12345E3',18(18)>
+    seg.DecimalField = 123.45     # => #<BigDecimal:7fe83c315750,'0.12345E3',18(18)>
+    seg.DecimalField = 123        # => #<BigDecimal:7fe83b9dd4f8,'0.123E3',9(18)>
+    seg.DecimalField = 123.0      # => #<BigDecimal:7fe83b9dd4f8,'0.123E3',9(18)>
+```
+
+__Please Note__: Due to issues with floating point representation of currency values we have
+chosen to use BigDecimal internally to store all fields with a decimal datatype.
+
 For more example please review the test suite.
 
 License

data/lib/hippo/exceptions.rb

@@ -2,8 +2,9 @@ module Hippo
   module Exceptions
     class Exception < StandardError; end
 
+    class InvalidValue    < Exception; end
     class InvalidField    < Exception; end
     class InvalidSegment  < Exception; end
-    class ParseError     < Exception; end
+    class ParseError      < Exception; end
   end
 end

data/lib/hippo/field.rb

@@ -1,6 +1,92 @@
+require 'date'
+require 'time'
+require 'bigdecimal'
+
 module Hippo
   class Field
-    attr_accessor :name, :sequence, :datatype, :options, :restrictions, :minimum, :maximum, :required, :separator, :composite, :composite_sequence
+    attr_accessor :name, :sequence, :datatype, :options,
+                  :restrictions, :minimum, :maximum, :required,
+                  :separator, :composite, :composite_sequence
+
+    def minimum
+      @minimum ||= 0
+    end
+
+    def formatted_value(value)
+      return nil if value.nil?
+
+      case datatype
+      when :binary  then value
+      when :integer then value.to_i
+      when :decimal then BigDecimal.new(value.to_s)
+      when :date    then parse_date(value)
+      when :time    then parse_time(value)
+      else value.to_s
+      end
+    end
+
+    def string_value(value)
+      return '' if value.nil? || value == ''
+
+      case datatype
+      when :binary  then value
+      when :integer then value.to_s.rjust(minimum, '0')
+      when :decimal then value.to_s('F').sub(/\.0\z/,'').rjust(minimum, '0')
+      when :date
+        if maximum == 6
+          value.strftime('%y%m%d')
+        else
+          value.strftime('%Y%m%d')
+        end
+      when :time
+        if maximum == 4 || value.sec == 0
+          value.strftime('%H%M')
+        else
+          value.strftime('%H%M%S')
+        end
+      else value.to_s.ljust(minimum)
+      end
+    end
+
+    def parse_time(value)
+      case value.class.to_s
+      when 'Time' then value
+      when 'String'
+        format =  case value
+                  when /\A\d{4}\z/ then '%H%M'
+                  when /\A\d{6}\z/ then '%H%M%S'
+                  when /\A\d{7,8}\z/ then '%H%M%S%N'
+                  else invalid!
+                  end
+
+        Time.strptime(value, format)
+      else invalid!
+      end
+    rescue
+      invalid!
+    end
+
+    def parse_date(value)
+      case value.class.to_s
+      when "Date" then value
+      when "Time" then value.to_date
+      when "String"
+        format =  case value
+                  when /\A\d{6}\z/ then '%y%m%d'
+                  when /\A\d{8}\z/ then '%Y%m%d'
+                  else invalid!
+                  end
+
+        Date.parse(value, format)
+      else
+        invalid! "Invalid datatype(#{value.class}) for date field."
+      end
+    rescue
+      invalid!
+    end
 
+    def invalid!(message = "Invalid value specified for #{self.datatype} field.")
+      raise Hippo::Exceptions::InvalidValue.new message
+    end
   end
 end

data/lib/hippo/parser/segment.rb

@@ -21,10 +21,10 @@ module Hippo
             composite_fields.each_with_index do |comp_value, comp_index|
               composite_field = field[comp_index]
 
-              self.values[composite_sequence][composite_field.sequence] = comp_value
+              self.values[composite_sequence][composite_field.sequence] = composite_field.formatted_value(comp_value)
             end
           else
-            self.values[field.sequence] = value
+            self.values[field.sequence] = field.formatted_value(value)
           end
         end
 

data/lib/hippo/segments/AK1.rb

@@ -13,8 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'GroupControlNumber',
           :sequence             => 2,
-          :datatype             => :numeric,
-          :decimal              => 0,
+          :datatype             => :integer,
           :minimum              => 1,
           :maximum              => 9,
           :required             => true,

data/lib/hippo/segments/AK3.rb

@@ -13,8 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'SegmentPositionInTransactionSet',
           :sequence             => 2,
-          :datatype             => :numeric,
-          :decimal              => 0,
+          :datatype             => :integer,
           :minimum              => 1,
           :maximum              => 10,
           :required             => true,

data/lib/hippo/segments/AK4.rb

@@ -7,8 +7,7 @@ module Hippo::Segments
 
       field :name                 => 'ElementPositionInSegment',
             :sequence             => 1,
-            :datatype             => :numeric,
-            :decimal              => 0,
+            :datatype             => :integer,
             :minimum              => 1,
             :maximum              => 2,
             :required             => true,
@@ -16,8 +15,7 @@ module Hippo::Segments
 
       field :name                 => 'ComponentDataElementPositionInComposite',
             :sequence             => 2,
-            :datatype             => :numeric,
-            :decimal              => 0,
+            :datatype             => :integer,
             :minimum              => 1,
             :maximum              => 2,
             :required             => false,
@@ -25,8 +23,7 @@ module Hippo::Segments
 
       field :name                 => 'RepeatingDataElementPosition',
             :sequence             => 3,
-            :datatype             => :numeric,
-            :decimal              => 0,
+            :datatype             => :integer,
             :minimum              => 1,
             :maximum              => 4,
             :required             => false,
@@ -36,8 +33,7 @@ module Hippo::Segments
 
     field :name                 => 'DataElementReferenceNumber',
           :sequence             => 2,
-          :datatype             => :numeric,
-          :decimal              => 0,
+          :datatype             => :integer,
           :minimum              => 1,
           :maximum              => 4,
           :required             => false,

data/lib/hippo/segments/AK9.rb

@@ -13,8 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'NumberOfTransactionSetsIncluded',
           :sequence             => 2,
-          :datatype             => :numeric,
-          :decimal              => 0,
+          :datatype             => :integer,
           :minimum              => 1,
           :maximum              => 6,
           :required             => true,
@@ -22,8 +21,7 @@ module Hippo::Segments
 
     field :name                 => 'NumberOfReceivedTransactionSets',
           :sequence             => 3,
-          :datatype             => :numeric,
-          :decimal              => 0,
+          :datatype             => :integer,
           :minimum              => 1,
           :maximum              => 6,
           :required             => true,
@@ -31,8 +29,7 @@ module Hippo::Segments
 
     field :name                 => 'NumberOfAcceptedTransactionSets',
           :sequence             => 4,
-          :datatype             => :numeric,
-          :decimal              => 0,
+          :datatype             => :integer,
           :minimum              => 1,
           :maximum              => 6,
           :required             => true,

data/lib/hippo/segments/AMT.rb

@@ -13,7 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 2,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => true,

data/lib/hippo/segments/BPR.rb

@@ -13,7 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 2,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => true,

data/lib/hippo/segments/CAS.rb

@@ -21,7 +21,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 3,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => true,
@@ -29,7 +29,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 4,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -45,7 +45,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 6,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,
@@ -53,7 +53,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 7,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -69,7 +69,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 9,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,
@@ -77,7 +77,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 10,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -93,7 +93,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 12,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,
@@ -101,7 +101,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 13,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -117,7 +117,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 15,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,
@@ -125,7 +125,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 16,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -141,7 +141,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 18,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,
@@ -149,7 +149,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 19,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,

data/lib/hippo/segments/CLM.rb

@@ -13,7 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 2,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,

data/lib/hippo/segments/CLP.rb

@@ -21,7 +21,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 3,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => true,
@@ -29,7 +29,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 4,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => true,
@@ -37,7 +37,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 5,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,
@@ -93,7 +93,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 12,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -101,7 +101,7 @@ module Hippo::Segments
 
     field :name                 => 'PercentageAsDecimal',
           :sequence             => 13,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 10,
           :required             => false,

data/lib/hippo/segments/CN1.rb

@@ -13,7 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'MonetaryAmount',
           :sequence             => 2,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 18,
           :required             => false,
@@ -21,7 +21,7 @@ module Hippo::Segments
 
     field :name                 => 'PercentDecimalFormat',
           :sequence             => 3,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 6,
           :required             => false,
@@ -37,7 +37,7 @@ module Hippo::Segments
 
     field :name                 => 'TermsDiscountPercent',
           :sequence             => 5,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 6,
           :required             => false,

data/lib/hippo/segments/CR1.rb

@@ -13,7 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'Weight',
           :sequence             => 2,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 10,
           :required             => false,
@@ -45,7 +45,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 6,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,

data/lib/hippo/segments/CR2.rb

@@ -5,8 +5,7 @@ module Hippo::Segments
 
     field :name                 => 'Count',
           :sequence             => 1,
-          :datatype             => :numeric,
-          :decimal              => 0,
+          :datatype             => :integer,
           :minimum              => 1,
           :maximum              => 9,
           :required             => false,
@@ -14,7 +13,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 2,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -46,7 +45,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 6,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,
@@ -54,7 +53,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 7,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,

data/lib/hippo/segments/CR3.rb

@@ -21,7 +21,7 @@ module Hippo::Segments
 
     field :name                 => 'Quantity',
           :sequence             => 3,
-          :datatype             => :numeric,
+          :datatype             => :decimal,
           :minimum              => 1,
           :maximum              => 15,
           :required             => false,