fencer 0.4.2

data/.rspec

@@ -0,0 +1 @@
+ --color --format documentation

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Dan Cheail
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# Fencer
+Fencer is designed to process rows of fixed-length and delimited text 
+data, splitting at designated termination points, converting field values
+where required and making fields available through named object accessors.
+
+Row formats are defined by subclassing Fencer::Base and using the DSL
+provided.
+
+## Example
+    class EmployeeRecord < Fencer::Base
+     field :department, 50, :string
+     field :name, 20, -> s { s.split }
+     space 2
+     field :age, 4, :integer
+    end
+    
+`field` takes 3 arguments: a field name, the field length and an (optional)
+converter.
+
+## Field Conversion
+`Fencer::Base::Converters` is a `Hash<` defines some commonly-used converters. 
+It's left un-frozen, so it can be extended as required.
+
+Short-cut methods for the default field types are also available:
+
+   class EmployeeRecord < Fencer::Base
+     string  :department, 20      => String
+     integer :age, 2              => Integer
+     decimal :salary, 10          => BigDecimal
+   end
+
+Additionally, custom conversions can be defined by passing a `lambda`
+as the final argument.
+
+## Usage
+
+Records are extracted on initialisation:
+
+    raw_string = "EXAMPLE FORMAT      10   300.04"
+    fields     = EmployeeRecord.new(raw_string)
+
+And are directly accessible thereafter:
+    
+    fields.department # => "EXAMPLE FORMAT"
+    fields.age        # => 2
+    fields.salary     # => BigDecimal("300.04")
+
+In the case of importing delimiter-separated data, passing the delimiting
+character as the second argument to `new` will yield the desired result 
+without any change of layout:
+
+    raw_string = "EXAMPLE FORMAT|10|300.04"
+    fields     = EmployeeRecord.new(raw_string, "|")
+    
+    fields.department # => "EXAMPLE FORMAT"
+    fields.age        # => 2
+    fields.salary     # => BigDecimal("300.04")
+
+
+## Known Deficiencies
+
+Currently, Fencer works with Ruby 1.9 only. Sorry. I wanted Hashes that
+preserve field-order. P;us, the newer syntax is pretty.
+
+Fencer is also blissfully unaware of any sort of encoding. This is a planned  
+feature for the 1.0 release.

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/fencer.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/fencer/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Dan Cheail"]
+  gem.email         = ["dan@undumb.com"]
+  gem.description   = %q{Fixed-length/delimited record parser DSL}
+  gem.summary       = %q{Fencer makes working with fixed-length and delimited
+                       text-based records simpler by providing a flexible DSL
+                       for defining field lengths and transformations}
+
+  gem.homepage      = "https://github.com/undumb/fencer"
+  gem.files         = `git ls-files`.split($\) - %w(Gemfile .gitignore)
+  # gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "fencer"
+  gem.require_paths = ["lib"]
+  gem.version       = Fencer::VERSION
+  
+  gem.add_development_dependency "rspec", "~> 2.10"
+  gem.add_development_dependency "rake"
+end

data/lib/fencer.rb

@@ -0,0 +1,89 @@
+require "bigdecimal"
+require "fencer/version"
+
+module Fencer
+  
+  class Base
+    Converters = {
+      string:  -> s { s.strip },
+      integer: -> s { s.to_i },
+      decimal: -> s { BigDecimal(s) },
+    }
+
+    class << self
+      attr_reader :fields
+      
+      def inherited(subclass)      
+        subclass.instance_variable_set(:@fields, {})
+      end
+      
+      def field(name, size, convert = nil)
+        # error handling, ahoy!
+        raise "#{name} already defined as a field on #{self.name}" if fields.has_key?(name)
+        
+        unless convert.nil? || Converters.has_key?(convert) || convert.is_a?(Proc)
+          raise "Invalid converter"
+        end
+
+        fields[name] = { size: size, convert: convert }
+        
+        # create our attr method
+        define_method(name) { @values[name] }        
+      end
+      
+      def space(size)
+        fields[:"_#{fields.length.succ}"] = { size: size, space: true }
+      end
+      
+      def string(name, size)
+        field(name, size, :string)
+      end
+
+      def integer(name, size)
+        field(name, size, :integer)
+      end
+      
+      def decimal(name, size)
+        field(name, size, :decimal)
+      end      
+    end
+    
+    def initialize(str, delimiter = nil)
+      @values    = {}
+      @delimiter = delimiter
+      @str       = str
+
+      parse!
+    end
+    
+    def to_hash
+      @values
+    end
+    
+    private
+    
+    def parse!      
+      if @delimiter
+        raw_values = @str.split(@delimiter)
+      else
+        unpack_phrase = self.class.fields.values.map { |s| "A#{s[:size]}" }.join
+        raw_values = @str.unpack(unpack_phrase)
+      end
+
+      _index = 0      
+      self.class.fields.each do |name, opts|        
+        unless opts[:space]          
+          _conversion_proc = case opts[:convert]
+            when Symbol then Converters[opts[:convert]]
+            when Proc   then opts[:convert]
+            else nil
+          end 
+          
+          @values[name] = _conversion_proc ? _conversion_proc.call(raw_values[_index]) : raw_values[_index]
+        end
+        
+        _index += 1 unless opts[:space] && @delimiter
+      end      
+    end    
+  end
+end

data/lib/fencer/version.rb

@@ -0,0 +1,3 @@
+module Fencer
+  VERSION = "0.4.2"
+end

data/spec/fencer_spec.rb

@@ -0,0 +1,142 @@
+# require 'rubygems'
+
+Bundler.require(:default, :development)
+
+require 'rspec'
+require 'fencer'
+
+describe Fencer do
+
+  class EmployeeRecord < Fencer::Base
+    string :name, 20
+    string :department, 20
+    space 2
+    field :employment_date, 8, -> s { dasherise_ymd(s) }
+    integer :id_number, 6
+    decimal :leave_accrued, 11
+
+    class << self
+      def dasherise_ymd(str)
+        str.gsub(/([0-9]{4})([0-9]{2})([0-9]{2})/) { "#{$1}-#{$2}-#{$3}" }
+      end
+    end
+  end
+
+  let(:name)            { "Ford Prefect" }
+  let(:department)      { "Publication" }
+  let(:employment_date) { "20120525" }
+  let(:id_number)       { "42" }
+  let(:leave_accrued)   { "1484.33" }
+
+  it "has many wonderful features" do
+
+    compiled_record = name.ljust(20)
+    compiled_record << department.ljust(20)
+    compiled_record <<  "  "
+    compiled_record << employment_date
+    compiled_record << id_number.rjust(6, '0')
+    compiled_record << leave_accrued.rjust(11, '0')
+
+    # auto parsing
+    values = EmployeeRecord.new(compiled_record)
+
+    # individual accessors for each field
+    values.name.should eq(name)
+    values.department.should eq(department)
+    values.employment_date.should eq("2012-05-25")
+    values.id_number.should eq(id_number.to_i)
+    values.leave_accrued.should eq(BigDecimal(leave_accrued))
+
+    # export our values to a hash
+    values.to_hash.should eq({
+      name: name,
+      department: department,
+      employment_date: "2012-05-25",
+      id_number: id_number.to_i,
+      leave_accrued: BigDecimal(leave_accrued),
+    })
+  end
+
+  it "also works when parsing arbitrarily delimited fields!" do
+    compiled_record = [
+      name, department, employment_date, id_number, leave_accrued
+    ].join("|")
+    
+    values = EmployeeRecord.new(compiled_record, "|")
+    
+    values.name.should eq(name)
+    values.department.should eq(department)
+    values.employment_date.should eq("2012-05-25")
+    values.id_number.should eq(id_number.to_i)
+    values.leave_accrued.should eq(BigDecimal(leave_accrued))    
+  end
+end
+
+
+class FencerBaseTest < Fencer::Base
+  class << self      
+    def reset_fields!
+      @fields = {}
+    end
+  end
+end
+
+describe Fencer::Base do
+  before(:each) do
+    subject.reset_fields!
+  end
+
+  subject { FencerBaseTest }
+
+  it "#field adds fields to the internal register" do
+    subject.field(:derp, 1)
+    subject.fields.should have_key(:derp)
+  end
+
+  it "#field adds an instance access method" do
+    subject.field(:derp, 1)
+
+    instance = subject.new("")
+    instance.should respond_to(:derp)
+    instance.should_not respond_to(:herp)
+  end
+
+  it "raises an error when the size attribute is omitted" do
+    expect { subject.field(:derp) }.to raise_error
+  end
+
+  it "raises an error when duplicate keys are defined" do
+    subject.field(:derp, 1)
+    expect { subject.field(:derp, 1) }.to raise_error
+  end
+
+  context "when using shortcut methods" do
+    it "has a shortcut for string fields" do
+      subject.string(:derp, 1)
+      subject.fields.should have_key(:derp)
+      subject.fields[:derp][:convert].should be :string
+    end
+
+    it "has a shortcut for integer fields" do
+      subject.integer(:derp, 1)
+      subject.fields.should have_key(:derp)
+      subject.fields[:derp][:convert].should be :integer
+    end
+
+    it "has a shortcut for decimal fields" do
+      subject.decimal(:derp, 1)
+      subject.fields.should have_key(:derp)
+      subject.fields[:derp][:convert].should be :decimal
+    end
+  end
+
+  context "when setting an invalid conversion argument" do
+    it "raises an error if the symbol is not registered" do
+      expect { subject.field(:derp, 1, :to_date) }.to raise_error
+    end
+
+    it "raises an error if the argument is not a lambda" do
+      expect { subject.field(:derp, 1, "") }.to raise_error
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: fencer
+version: !ruby/object:Gem::Version
+  version: 0.4.2
+  prerelease: 
+platform: ruby
+authors:
+- Dan Cheail
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70270773693060 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :development
+  prerelease: false
+  version_requirements: *70270773693060
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70270773692560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70270773692560
+description: Fixed-length/delimited record parser DSL
+email:
+- dan@undumb.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .rspec
+- LICENSE
+- README.md
+- Rakefile
+- fencer.gemspec
+- lib/fencer.rb
+- lib/fencer/version.rb
+- spec/fencer_spec.rb
+homepage: https://github.com/undumb/fencer
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1981968692186319614
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1981968692186319614
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Fencer makes working with fixed-length and delimited text-based records simpler
+  by providing a flexible DSL for defining field lengths and transformations
+test_files:
+- spec/fencer_spec.rb