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

SYNOPSIS:
=========

##Creating a definition (Quick 'n Dirty)

Hopefully this will cover 90% of use cases.

    # Create a FixedWidth::Defintion to describe a file format
    FixedWidth.define :simple do |d|
      # This is a template section that can be reused in other sections
      d.template :boundary do |t|
        t.column :record_type, 4
        t.column :company_id, 12
      end
    
      # Create a section named :header
      d.header(:align => :left) do |header|
        # The trap tells FixedWidth which lines should fall into this section
        header.trap { |line| line[0,4] == 'HEAD' }
        # Use the boundary template for the columns
        header.template :boundary
      end
    
      d.body do |body|
        body.trap { |line| line[0,4] =~ /[^(HEAD|FOOT)]/ }
        body.column :id, 10, :parser => :to_i
        body.column :first, 10, :align => :left, :group => :name
        body.column :last,  10, :align => :left, :group => :name
        body.spacer 3
        body.column :city, 20  , :group => :address
        body.column :state, 2  , :group => :address
        body.column :country, 3, :group => :address
      end
    
      d.footer do |footer|
        footer.trap { |line| line[0,4] == 'FOOT' }
        footer.template :boundary
        footer.column :record_count, 10, :parser => :to_i
      end
    end

This definition would output a parsed file something like this:

    {
        :body => [
          { :id => 12,
            :name => { :first => "Ryan", :last => "Wood" },
            :address => { :city => "Foo", :state => 'SC', :country => "USA" }
          },
          { :id => 13,
            :name => { :first => "Jo", :last => "Schmo" },
            :address => { :city => "Bar", :state => "CA", :country => "USA" }
          }
        ],
        :header => [{ :record_type => 'HEAD', :company_id => 'ABC'  }],
        :footer => [{ :record_type => 'FOOT', :company_id => 'ABC', :record_count => 2  }]
    }

##Sections
###Declaring a section

Sections can have any name, however duplicates are not allowed. (A `DuplicateSectionNameError` will be thrown.) We use the standard `method_missing` trick. So if you see any unusual behavior, that's probably the first spot to look.

    FixedWidth.define :simple do |d|
        d.a_section_name do |s|
            ...
        end
        d.another_section_name do |s|
            ...
        end
    end

### Section options:

* `:singular` (default `false`) indicates that the section will only have a single record, and that it should not be returned nested in an array.

* `:optional` (default `false`) indicates that the section is optional. (An otherwise-specified section will raise a `RequiredSectionNotFoundError` if the trap block doesn't match the row after the last one of the previous section.)

##Columns
###Declaring a column

Columns can have any name, except for `:spacer` which is reserved. Also, duplicate column names within groupings are not allowed, and a column cannot share the same name as a group. (A `DuplicateColumnNameError` will be thrown for a duplicate column name within a grouping. A `DuplicateGroupNameError` will be thrown if you try to declare a column with the same name as an existing group or vice versa.) Again, basic `method_missing` trickery here, so be warned. You can declare columns either with the `method_missing` thing or by calling `Section#column`.

    FixedWidth.define :simple do |d|
        d.a_section_name do |s|
            s.a_column_name 12
            s.column :another_column_name, 14
        end
    end

###Column Options:

* `:align` can be set to `:left` or `:right`, to indicate which side the values should be/are justified to. By default, all columns are aligned `:right`.

* `:group` can be set to a `Symbol` indicating the name of the nested hash which the value should be parsed to when reading/the name of the nested hash the value should be extracted from when writing.

* `:parser` and `:formatter` options are symbols (to be proc-ified) or procs. By default, parsing and formatting assume that we're expecting/writing right-aligned strings, padded with spaces.

* `:nil_blank` set to true will cause whitespace-only fields to be parsed to nil, regardless of `:parser`.

* `:padding` can be set to a single character that will be used to pad formatted values, when writing fixed-width files.

* `:truncate` can be set to true to truncate any value that exceeds the `length` property of a column. If unset or set to `false`, a `FixedWidth::FormattedStringExceedsLengthError` exception will be thrown.

##Writing out fixed-width records

Then either feed it a nested struct with data values to create the file in the defined format:

    test_data = {
        :body => [
          { :id => 12,
            :name => { :first => "Ryan", :last => "Wood" },
            :address => { :city => "Foo", :state => 'SC', :country => "USA" }
          },
          { :id => 13,
            :name => { :first => "Jo", :last => "Schmo" },
            :address => { :city => "Bar", :state => "CA", :country => "USA" }
          }
        ],
        :header => [{ :record_type => 'HEAD', :company_id => 'ABC'  }],
        :footer => [{ :record_type => 'FOOT', :company_id => 'ABC', :record_count => 2  }]
    }

    # Generates the file as a string
    puts FixedWidth.generate(:simple, test_data)

    # Writes the file
    FixedWidth.write(file_instance, :simple, test_data)

Or parse files already in that format into a nested hash:

    parsed_data = FixedWidth.parse(file_instance, :test).inspect

INSTALL:
========

    sudo gem install fixed_width