fixed_width 0.2.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.eprj
+pkg
+coverage
+doc

data/COPYING

@@ -0,0 +1,10 @@
+Copyright (c) 2010, Topspin Media Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name of the Topspin Media Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/HISTORY

@@ -0,0 +1,12 @@
+v0.1.1 (2010-05-29)
+=========================
+    * column grouping (parsing and writing)
+    * :singular section option
+    * :nil_blank column option
+    * some rdoc for FixedWidth
+    * idiomatic syntax cleanup
+
+v0.1.0 (2010-05-19)
+=========================
+    * non-release (hence untagged)
+    * Forked from ryanwood/slither, renamed.

data/README.markdown

@@ -0,0 +1,149 @@
+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

data/Rakefile

@@ -0,0 +1,44 @@
+task :default => :spec
+task :test    => :spec
+
+desc "Build a gem"
+task :gem => [ :gemspec, :build ]
+
+desc "Run specs"
+task :spec do
+  exec "spec -fn -b -c spec/"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "fixed_width"
+    gemspec.summary = "A gem that provides a DSL for parsing and writing files of fixed-width records."
+    gemspec.description = <<END
+Shamelessly forked from ryanwood/slither [http://github.com/ryanwood/slither].
+
+Renamed the gem to be a little clearer as to its purpose. Hate that 'nokogiri' nonsense.
+END
+    gemspec.email = "timon.karnezos@gmail.com"
+    gemspec.homepage = "http://github.com/timonk/fixed_width"
+    gemspec.authors = ["Timon Karnezos"]
+  end
+rescue LoadError
+  warn "Jeweler not available. Install it with:"
+  warn "gem install jeweler"
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rprince #{version}"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1,7 @@
+* Add :limit option on sections
+* Add :validation option for columns
+* Add a validate_file() method to parse a file and run all validation tests (implies validation implemented)
+* Better Documentation
+* Alternate Section Flow (other than linear), i.e. repeatable sections (think batch)
+* Add batched generation, so we don't turn into memory hogs
+* Add batched parsing, so we don't turn into memory hogs

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/examples/readme_example.rb

@@ -0,0 +1,62 @@
+require 'stringio'
+require File.join(File.dirname(__FILE__), "..", "lib", "fixed_width")
+
+# 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 header section
+  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
+
+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
+generated = FixedWidth.generate(:simple, test_data)
+
+sio = StringIO.new
+sio.write(generated)
+sio.rewind
+
+parsed = FixedWidth.parse(sio, :simple)
+
+puts parsed == test_data

data/fixed_width.gemspec

@@ -0,0 +1,74 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{fixed_width}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Timon Karnezos"]
+  s.date = %q{2010-05-31}
+  s.description = %q{Shamelessly forked from ryanwood/slither [http://github.com/ryanwood/slither].
+
+Renamed the gem to be a little clearer as to its purpose. Hate that 'nokogiri' nonsense.
+}
+  s.email = %q{timon.karnezos@gmail.com}
+  s.extra_rdoc_files = [
+    "README.markdown",
+     "TODO"
+  ]
+  s.files = [
+    ".gitignore",
+     "COPYING",
+     "HISTORY",
+     "README.markdown",
+     "Rakefile",
+     "TODO",
+     "VERSION",
+     "examples/readme_example.rb",
+     "fixed_width.gemspec",
+     "lib/fixed_width.rb",
+     "lib/fixed_width/column.rb",
+     "lib/fixed_width/core_ext/symbol.rb",
+     "lib/fixed_width/definition.rb",
+     "lib/fixed_width/fixed_width.rb",
+     "lib/fixed_width/generator.rb",
+     "lib/fixed_width/parser.rb",
+     "lib/fixed_width/section.rb",
+     "spec/column_spec.rb",
+     "spec/definition_spec.rb",
+     "spec/fixed_width_spec.rb",
+     "spec/generator_spec.rb",
+     "spec/parser_spec.rb",
+     "spec/section_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/timonk/fixed_width}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A gem that provides a DSL for parsing and writing files of fixed-width records.}
+  s.test_files = [
+    "spec/column_spec.rb",
+     "spec/definition_spec.rb",
+     "spec/fixed_width_spec.rb",
+     "spec/generator_spec.rb",
+     "spec/parser_spec.rb",
+     "spec/section_spec.rb",
+     "spec/spec_helper.rb",
+     "examples/readme_example.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/lib/fixed_width/column.rb

@@ -0,0 +1,85 @@
+class FixedWidth
+  class Column
+    DEFAULT_PADDING   = ' '
+    DEFAULT_ALIGNMENT = :right
+    DEFAULT_TRUNCATE  = false
+    DEFAULT_FORMATTER = :to_s
+
+    attr_reader :name, :length, :alignment, :padding, :truncate, :group, :unpacker
+
+    def initialize(name, length, options={})
+      assert_valid_options(options)
+      @name      = name
+      @length    = length
+      @alignment = options[:align]    || DEFAULT_ALIGNMENT
+      @padding   = options[:padding]  || DEFAULT_PADDING
+      @truncate  = options[:truncate] || DEFAULT_TRUNCATE
+
+      @group     = options[:group]
+
+      @unpacker  = "A#{@length}"
+
+      @parser    = options[:parser]
+      @parser    ||= case @alignment
+                 when :right then :lstrip
+                 when :left  then :rstrip
+                 end
+      @parser    = @parser.to_proc if @parser.is_a?(Symbol)
+
+      @formatter = options[:formatter]
+      @formatter ||= DEFAULT_FORMATTER
+      @formatter = @formatter.to_proc if @formatter.is_a?(Symbol)
+
+      @nil_blank = options[:nil_blank]
+    end
+
+    def parse(value)
+      if @nil_blank && blank?(value)
+        return nil
+      else
+        @parser.call(value)
+      end
+    rescue
+      raise ParserError.new("The value '#{value}' could not be parsed: #{$!}")
+    end
+
+    def format(value)
+      pad(
+        validate_size(
+          @formatter.call(value)
+        )
+      )
+    end
+
+    private
+    BLANK_REGEX = /^\s*$/
+    def blank?(value)
+      value =~ BLANK_REGEX
+    end
+
+    def pad(value)
+      case @alignment
+      when :left
+        value.ljust(@length, @padding)
+      when :right
+        value.rjust(@length, @padding)
+      end
+    end
+
+    def assert_valid_options(options)
+      unless options[:align].nil? || [:left, :right].include?(options[:align])
+        raise ArgumentError.new("Option :align only accepts :right (default) or :left")
+      end
+    end
+
+    def validate_size(result)
+      return result if result.length <= @length
+      raise FixedWidth::FormattedStringExceedsLengthError.new(
+        "The formatted value '#{result}' in column '#{@name}' exceeds the allowed length of #{@length} chararacters.") unless @truncate
+      case @alignment
+      when :right then result[-@length,@length]
+      when :left  then result[0,@length]
+      end
+    end
+  end
+end