fixed_width 0.2.0

data/lib/fixed_width/core_ext/symbol.rb

@@ -0,0 +1,17 @@
+#
+# Taken from ActiveSupport 2.3.5 lib/active_support/core_ext/symbol.rb
+#
+unless :to_proc.respond_to?(:to_proc)
+  class Symbol
+    # Turns the symbol into a simple proc, which is especially useful for enumerations. Examples:
+    #
+    #   # The same as people.collect { |p| p.name }
+    #   people.collect(&:name)
+    #
+    #   # The same as people.select { |p| p.manager? }.collect { |p| p.salary }
+    #   people.select(&:manager?).collect(&:salary)
+    def to_proc
+      Proc.new { |*args| args.shift.__send__(self, *args) }
+    end
+  end
+end

data/lib/fixed_width/definition.rb

@@ -0,0 +1,31 @@
+class FixedWidth
+  class Definition
+    attr_reader :sections, :templates, :options
+
+    def initialize(options={})
+      @sections  = []
+      @templates = {}
+      @options   = { :align => :right }.merge(options)
+    end
+
+    def section(name, options={}, &block)
+      raise DuplicateSectionNameError.new("Duplicate section name: '#{name}'") if @sections.detect{|s| s.name == name }
+
+      section = FixedWidth::Section.new(name, @options.merge(options))
+      section.definition = self
+      yield(section)
+      @sections << section
+      section
+    end
+
+    def template(name, options={}, &block)
+      section = FixedWidth::Section.new(name, @options.merge(options))
+      yield(section)
+      @templates[name] = section
+    end
+
+    def method_missing(method, *args, &block)
+      section(method, *args, &block)
+    end
+  end
+end

data/lib/fixed_width/fixed_width.rb

@@ -0,0 +1,84 @@
+#
+# =DESCRIPTION:
+# 
+# A simple, clean DSL for describing, writing, and parsing fixed-width text files.
+# 
+# =FEATURES:
+# 
+# * Easy DSL syntax
+# * Can parse and format fixed width files
+# * Templated sections for reuse
+#
+# For examples, see examples/*.rb or the README.
+#
+class FixedWidth
+  class ParserError < RuntimeError; end
+  class DuplicateColumnNameError < StandardError; end
+  class DuplicateGroupNameError < StandardError; end
+  class DuplicateSectionNameError < StandardError; end
+  class RequiredSectionNotFoundError < StandardError; end
+  class RequiredSectionEmptyError < StandardError; end
+  class FormattedStringExceedsLengthError < StandardError; end
+  class ColumnMismatchError < StandardError; end
+
+  #
+  # [name]   a symbol to reference this file definition later
+  # [option] a hash of default options for all sub-elements
+  # and a block that defines the sections of the file.
+  #
+  # returns: +Definition+ instance for this file description.
+  #
+  def self.define(name, options={}) # yields definition
+    definition = Definition.new(options)
+    yield(definition)
+    definitions[name] = definition
+    definition
+  end
+
+  #
+  # [data]            nested hash describing the contents of the sections
+  # [definition_name] symbol +name+ used in +define+
+  #
+  # returns: string of the transformed +data+ (into fixed-width records).
+  #
+  def self.generate(definition_name, data)
+    definition = definition(definition_name)
+    raise ArgumentError.new("Definition name '#{name}' was not found.") unless definition
+    generator = Generator.new(definition)
+    generator.generate(data)
+  end
+
+  #
+  # [file]            IO object to write the +generate+d data
+  # [definition_name] symbol +name+ used in +define+
+  # [data]            nested hash describing the contents of the sections
+  #
+  # writes transformed data to +file+ object as fixed-width records.
+  #
+  def self.write(file, definition_name, data)
+    file.write(generate(definition_name, data))
+  end
+
+  #
+  # [file]            IO object from which to read the fixed-width text records
+  # [definition_name] symbol +name+ used in +define+
+  #
+  # returns: parsed text records in a nested hash.
+  #
+  def self.parse(file, definition_name)
+    definition = definition(definition_name)
+    raise ArgumentError.new("Definition name '#{definition_name}' was not found.") unless definition
+    parser = Parser.new(definition, file)
+    parser.parse
+  end
+
+  private
+
+  def self.definitions
+    @@definitions ||= {}
+  end
+
+  def self.definition(name)
+    definitions[name]
+  end
+end

data/lib/fixed_width/generator.rb

@@ -0,0 +1,20 @@
+class FixedWidth
+  class Generator
+
+    def initialize(definition)
+      @definition = definition
+    end
+
+    def generate(data)
+      @builder = []
+      @definition.sections.each do |section|
+        content = data[section.name]
+        arrayed_content = content.is_a?(Array) ? content : [content]
+        raise FixedWidth::RequiredSectionEmptyError.new("Required section '#{section.name}' was empty.") if (content.nil? || content.empty?) && !section.optional
+        arrayed_content.each {|row| @builder << section.format(row) }
+      end
+      @builder.join("\n")
+    end
+
+  end
+end

data/lib/fixed_width/parser.rb

@@ -0,0 +1,47 @@
+class FixedWidth
+  class Parser
+    def initialize(definition, file)
+      @definition = definition
+      @file       = file
+    end
+
+    def parse
+      @parsed = {}
+      @content = read_file
+      unless @content.empty?
+        @definition.sections.each do |section|
+          rows = fill_content(section)
+          raise FixedWidth::RequiredSectionNotFoundError.new("Required section '#{section.name}' was not found.") unless rows > 0 || section.optional
+        end
+      end
+      @parsed
+    end
+
+    private
+
+    def read_file
+      @file.readlines.map(&:chomp)
+    end
+
+    def fill_content(section)
+      matches = 0
+      loop do
+        line = @content.first
+        break unless section.match(line)
+        add_to_section(section, line)
+        matches += 1
+        @content.shift
+      end
+      matches
+    end
+
+    def add_to_section(section, line)
+      if section.singular
+        @parsed[section.name] = section.parse(line)
+      else
+        @parsed[section.name] ||= []
+        @parsed[section.name] << section.parse(line)
+      end
+    end
+  end
+end

data/lib/fixed_width/section.rb

@@ -0,0 +1,91 @@
+class FixedWidth
+  class Section
+    attr_accessor :definition, :optional, :singular
+    attr_reader :name, :columns, :options
+
+    def initialize(name, options={})
+      @name     = name
+      @options  = options
+      @columns  = []
+      @trap     = options[:trap]
+      @optional = options[:optional] || false
+      @singular = options[:singular] || false
+    end
+
+    def column(name, length, options={})
+      if column_names_by_group(options[:group]).include?(name)
+        raise FixedWidth::DuplicateColumnNameError.new("You have already defined a column named '#{name}' in the '#{options[:group].inspect}' group.")
+      end
+      if column_names_by_group(nil).include?(options[:group])
+        raise FixedWidth::DuplicateGroupNameError.new("You have already defined a column named '#{options[:group]}'; you cannot have a group and column of the same name.")
+      end
+      if group_names.include?(name)
+        raise FixedWidth::DuplicateGroupNameError.new("You have already defined a group named '#{name}'; you cannot have a group and column of the same name.")
+      end
+
+      col = Column.new(name, length, @options.merge(options))
+      @columns << col
+      col
+    end
+
+    def spacer(length, spacer=nil)
+      options           = {}
+      options[:padding] = spacer if spacer
+      column(:spacer, length, options)
+    end
+
+    def trap(&block)
+      @trap = block
+    end
+
+    def template(name)
+      template = @definition.templates[name]
+      raise ArgumentError.new("Template '#{name}' not found as a known template.") unless template
+      @columns += template.columns
+      # Section options should trump template options
+      @options = template.options.merge(@options)
+    end
+
+    def format(data)
+      @columns.map do |c|
+        hash = c.group ? data[c.group] : data
+        c.format(hash[c.name])
+      end.join
+    end
+
+    def parse(line)
+      line_data = line.unpack(unpacker)
+      row       = group_names.inject({}) {|h,g| h[g] = {}; h }
+
+      @columns.each_with_index do |c, i|
+        next if c.name == :spacer
+        assignee         = c.group ? row[c.group] : row
+        assignee[c.name] = c.parse(line_data[i])
+      end
+
+      row
+    end
+
+    def match(raw_line)
+      raw_line.nil? ? false : @trap.call(raw_line)
+    end
+
+    def method_missing(method, *args)
+      column(method, *args)
+    end
+
+    private
+
+    def column_names_by_group(group)
+      @columns.select{|c| c.group == group }.map(&:name) - [:spacer]
+    end
+
+    def group_names
+      @columns.map(&:group).compact.uniq
+    end
+
+    def unpacker
+      @unpacker ||= @columns.map(&:unpacker).join
+    end
+  end
+end

data/lib/fixed_width.rb

@@ -0,0 +1,9 @@
+$: << File.dirname(__FILE__)
+require 'ostruct'
+require 'fixed_width/core_ext/symbol'
+require 'fixed_width/fixed_width'
+require 'fixed_width/definition'
+require 'fixed_width/section'
+require 'fixed_width/column'
+require 'fixed_width/parser'
+require 'fixed_width/generator'

data/spec/column_spec.rb

@@ -0,0 +1,209 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe FixedWidth::Column do
+  before(:each) do
+    @name = :id
+    @length = 5
+    @column = FixedWidth::Column.new(@name, @length)
+  end
+
+  describe "when being created" do
+    it "should have a name" do
+      @column.name.should == @name
+    end
+
+    it "should have a length" do
+      @column.length.should == @length
+    end
+
+    it "should have a default padding" do
+      @column.padding.should == ' '
+    end
+
+    it "should have a default alignment" do
+      @column.alignment.should == :right
+    end
+
+    it "should have a default truncation" do
+      @column.truncate.should be_false
+    end
+
+    it "should build the proper unpack value for a string" do
+      @column.send(:unpacker).should == 'A5'
+    end
+  end
+
+  describe "when specifying an alignment" do
+    before(:each) do
+      @column = FixedWidth::Column.new(@name, @length, :align => :left)
+    end
+
+    it "should only accept :right or :left for an alignment" do
+      lambda{ FixedWidth::Column.new(@name, @length, :align => :bogus) }.should raise_error(ArgumentError, "Option :align only accepts :right (default) or :left")
+    end
+
+    it "should override the default alignment" do
+      @column.alignment.should == :left
+    end
+  end
+
+  describe "when specifying padding" do
+    before(:each) do
+      @column = FixedWidth::Column.new(@name, @length, :padding => '0')
+    end
+
+    it "should override the default padding" do
+      @column.padding.should == '0'
+    end
+  end
+
+  describe "when parsing a value from a file" do
+    it "should return nil for blank fields if specified" do
+      @column = FixedWidth::Column.new(@name, @length, :padding => '0', :nil_blank => true)
+      @column.parse('    name ').should == 'name '
+      @column.parse("   \t   \n").should == nil
+      @column.parse("   0  \n").should == "0  \n"
+      @column.parse('').should == nil
+    end
+    
+    it "should default to returning formatted strings if nil_blank is not set" do
+      @column = FixedWidth::Column.new(@name, @length, :padding => '0', :nil_blank => false)
+      @column.parse('    name ').should == 'name '
+      @column.parse("   \t   \n").should == ""
+      @column.parse("   0  \n").should == "0  \n"
+      @column.parse('').should == ""
+    end
+    
+    it "should default to a right-aligned string" do
+      @column.parse('    name ').should == 'name '
+      @column.parse("   \t   234").should == '234'
+      @column.parse("   000000234  \n").should == "000000234  \n"
+      @column.parse('12.34').should == '12.34'
+    end
+
+    it "should default to a left-aligned string if no parser specified, but alignment is left" do
+      @column = FixedWidth::Column.new(@name, @length, :align => :left)
+
+      @column.parse('    name ').should == '    name'
+      @column.parse("   \t   234").should == "   \t   234"
+      @column.parse("   000000234  \n").should == "   000000234"
+      @column.parse('12.34').should == '12.34'
+    end
+
+    it "should support a symbol as the parser (:to_i)" do
+      @column = FixedWidth::Column.new(:amount, 10, :parser => :to_i)
+      @column.parse('234     ').should == 234
+      @column.parse('     234').should == 234
+      @column.parse('00000234').should == 234
+      @column.parse('Ryan    ').should == 0
+      @column.parse('00023.45').should == 23
+    end
+
+    it "should support a symbol as the parser (:to_f)" do
+      @column = FixedWidth::Column.new(:amount, 10, :parser => :to_f)
+      @column.parse('  234.45').should == 234.45
+      @column.parse('234.5600').should == 234.56
+      @column.parse('     234').should == 234.0
+      @column.parse('00000234').should == 234.0
+      @column.parse('Ryan    ').should == 0
+      @column.parse('00023.45').should == 23.45
+    end
+
+    it "should support a lambda as the parser (date)" do
+      @column = FixedWidth::Column.new(:date, 10, :parser => lambda{|x| Date.strptime(x, "%m%d%Y")})
+      dt = @column.parse('08222009')
+      dt.should be_a(Date)
+      dt.to_s.should == '2009-08-22'
+    end
+  end
+
+  describe "when applying formatting options" do
+    it "should respect a right alignment" do
+      @column = FixedWidth::Column.new(@name, @length, :align => :right)
+      @column.format(25).should == '   25'
+    end
+
+    it "should respect a left alignment" do
+      @column = FixedWidth::Column.new(@name, @length, :align => :left)
+      @column.format(25).should == '25   '
+    end
+
+    it "should respect padding with spaces" do
+      @column = FixedWidth::Column.new(@name, @length, :padding => ' ')
+      @column.format(25).should == '   25'
+    end
+
+    it "should respect padding with zeros" do
+      @column = FixedWidth::Column.new(@name, @length, :padding => '0')
+      @column.format(25).should == '00025'
+    end
+
+    it "should work with non-string inputs and the default formatter" do
+      @column = FixedWidth::Column.new(@name, @length)
+      @column.format(25).should == '   25'
+    end
+  end
+
+  describe "when formatting values for a file" do
+    it "should default to a string" do
+      @column = FixedWidth::Column.new(:name, 10)
+      @column.format('Bill').should == '      Bill'
+    end
+
+    describe "whose size is too long" do
+      it "should raise an error if truncate is false" do
+        @value = "XX" * @length
+        lambda { @column.format(@value) }.should raise_error(
+          FixedWidth::FormattedStringExceedsLengthError,
+          "The formatted value '#{@value}' in column '#{@name}' exceeds the allowed length of #{@length} chararacters."
+        )
+      end
+
+      it "should truncate from the left if truncate is true and aligned left" do
+        @column = FixedWidth::Column.new(@name, @length, :truncate => true, :align => :left)
+        @column.format("This is too long").should == "This "
+      end
+
+      it "should truncate from the right if truncate is true and aligned right" do
+        @column = FixedWidth::Column.new(@name, @length, :truncate => true, :align => :right)
+        @column.format("This is too long").should == " long"
+      end
+    end
+
+    it "should support a symbol formatter (:to_s)" do
+      @column = FixedWidth::Column.new(:amount, 10, :formatter => :to_s)
+      @column.format(234).should        == '       234'
+      @column.format('234').should      == '       234'
+    end
+
+    it "should support a lambda formatter (.to_f.to_s)" do
+      @column = FixedWidth::Column.new(:amount, 10, :formatter => lambda {|x| x.to_f.to_s })
+      @column.format(234.45).should       == '    234.45'
+      @column.format('234.4500').should   == '    234.45'
+      @column.format('3').should          == '       3.0'
+    end
+
+    it "should support a lambda formatter (float with sprintf)" do
+      @column = FixedWidth::Column.new(:amount, 10, :formatter => lambda {|x| "%.3f" % x.to_f })
+      @column.format(234.45).should       == '   234.450'
+      @column.format('234.4500').should   == '   234.450'
+      @column.format('3').should          == '     3.000'
+    end
+
+    it "should support the float type with a format, alignment and padding" do
+      @column = FixedWidth::Column.new(:amount, 10, :formatter => lambda {|x| "%.2f" % x.to_f }, :align => :left, :padding => '0')
+      @column.format(234.45).should       == '234.450000'
+      @column = FixedWidth::Column.new(:amount, 10, :formatter => lambda {|x| "%.2f" % x.to_f }, :align => :right, :padding => '0')
+      @column.format('234.400').should    == '0000234.40'
+      @column = FixedWidth::Column.new(:amount, 10, :formatter => lambda {|x| "%.4f" % x.to_f }, :align => :left, :padding => ' ')
+      @column.format('3').should          == '3.0000    '
+    end
+
+    it "should support the date type with a :format" do
+      dt = Date.new(2009, 8, 22)
+      @column = FixedWidth::Column.new(:date, 8, :formatter => lambda {|x| x.strftime("%m%d%Y") } )
+      @column.format(dt).should == '08222009'
+    end
+  end
+
+end