flat 0.1.0

data/lib/flat/record.rb

@@ -0,0 +1,99 @@
+##
+# = Record
+#
+# A record abstracts on line or 'record' of a fixed width field.
+# The methods available are the keys of the hash passed to the constructor.
+# For example the call:
+#
+#  h = Hash['first_name','Andy','status','Supercool!']
+#  r = Record::Definition.new(h)
+#
+# would respond to r.first_name, and r.status yielding
+# 'Andy' and 'Supercool!' respectively.
+#
+#
+module Record
+  module ClassMethods #:nodoc:
+  end # => module ClassMethods
+
+  ##
+  # = Instance Methods
+  #
+  # Defines behavior for instances of a subclass of Flat::File regarding the
+  # creating of Records from a line of text from a flat file.
+  #
+  module InstanceMethods
+
+    ##
+    # create a record from line. The line is one line (or record) read from the
+    # text file. The resulting record is an object which. The object takes signals
+    # for each field according to the various fields defined with add_field or
+    # varients of it.
+    #
+    # line_number is an optional line number of the line in a file of records.
+    # If line is not in a series of records (lines), omit and it'll be -1 in the
+    # resulting record objects. Just make sure you realize this when reporting
+    # errors.
+    #
+    # Both a getter (field_name), and setter (field_name=) are available to the
+    # user.
+    #
+    #--
+    # NOTE: No line length checking here; consider making protected
+    #++
+    #
+    def create_record line, line_number = -1
+      attributes = {}
+      values = line.unpack pack_format # Parse the incoming line
+      fields.each_with_index do |field, index|
+        attributes[field.name] = field.filter values[index]
+      end
+      Record::Definition.new self.class, attributes, line_number
+    end
+
+  end # => module InstanceMethods
+
+  def self.included receiver #:nodoc:
+    receiver.extend         ClassMethods
+    receiver.send :include, InstanceMethods
+  end
+
+  # = Definition
+  #
+  # Defines the behavior of a Record.
+  #
+  class Definition #:nodoc:
+    attr_reader :parent, :attributes, :line_number
+
+    #
+    # Create a new Record from a Hash of attributes.
+    #
+    def initialize parent, attributes = {}, line_number = -1
+      @parent, @attributes, @line_number = parent, attributes, line_number
+
+      @attributes = parent.fields.inject({}) do |map, field|
+        map.update(field.name => attributes[field.name])
+      end
+    end
+
+    #
+    # Catches method calls and returns field values or raises an Error.
+    #
+    def method_missing method, params = nil
+      if method.to_s =~ /^(.*)=$/
+        if attributes.has_key?($1.to_sym)
+          @attributes.store($1.to_sym, params)
+        else
+          raise Errors::FlatFileError, "Unknown method: #{method}"
+        end
+      else
+        if attributes.has_key?(method)
+          @attributes.fetch(method)
+        else
+          raise Errors::FlatFileError, "Unknown method: #{method}"
+        end
+      end
+    end
+  end # => class Definition
+
+end # => module Record

data/lib/flat/version.rb

@@ -0,0 +1,3 @@
+module Flat #:nodoc:
+  VERSION = "0.1.0"
+end

data/lib/flat.rb

@@ -0,0 +1,79 @@
+require 'extlib'
+
+require 'flat/version'
+require 'flat/file'
+
+# = Flat
+#
+# Flat files are typically plain/text files containing many lines of text, or
+# data. Each line, or record, consists of one or more fields. However, unlike
+# CSV (comma spearated value) files, there are no delimiters to define where
+# values end or begin. Flat provides a mechaism of defining a file's record
+# structure, allowing users to iterate over a given file and access its data as
+# typical Ruby objects (String, Numeric, Date, Booleans, etc.).
+#
+# == Specification
+#
+# A flat file's specification is defined within the subclass of Flat::File. The
+# use of <tt>add_field</tt> and <tt>pad</tt> define and document the record
+# structure.
+#
+# Given the following
+#    # Actual plain text, flat file data, 29 bytes
+#    #
+#    #           10        20
+#    # 012345678901234567890123456789
+#    # Walt      Whitman   18190531
+#    # Linus     Torvalds  19691228
+#
+#    class People < Flat::File
+#      add_field :first_name, width: 10, filter: :trim
+#      add_field :last_name,  width: 10, filter: ->(v) { v.strip }
+#      add_field :birthday,   width: 8,  filter: BirthdayFilter
+#      pad       :autoname,   width: 2
+#    end
+#
+# You will notice the minimum required information is field name and width. The
+# special case is with <tt>pad</tt>; you can specifiy a name but the general
+# approach is to let Flat::File name it for you.
+#
+# An alternate method of specifying fields is to pass a block to the
+# <tt>add_field</tt> method. When using the block method you do not have to
+# specifiy the name first. However, you do need to set the name inside the
+# block. The value yieled to the block is an instance of Field::Definition.
+#
+#    class People < FlatFile
+#      add_field do |fd|
+#        fd.name = :first_name
+#        fd.width = 10
+#        fd.add_filter ->(v) { v.strip }
+#        fd.add_formatter ->(v) { v.strip }
+#      end
+#
+#      add_field :last_name do |fd|
+#        fd.width = 10
+#        fd.add_filter ->(v) { v.strip }
+#        fd.add_formatter ->(v) { v.strip }
+#      end
+#
+#    end
+#
+# == Reading Data
+#
+# == Writing Data
+#
+# == Filters
+#
+# == Formatters
+#
+# == Exceptions
+#
+# * +FlatFileError+ - Generic error class and superclass of all other errors raised by Flat.
+# * +LayoutConstructorError+ - The specified layout definition was not valid.
+# * +RecordLengthError+ - Generic error having to do with line lengths not meeting expectations.
+# * +ShortRecordError+ - The incoming line was shorter than expections defined.
+# * +LongRecordError+ - The incoming line was longer than expections defined.
+#
+module Flat
+  include Extlib
+end

data/spec/flat_file_helper.rb

@@ -0,0 +1,27 @@
+# This file contains Flat::File definitions that can be used to test the
+# various features and functions of Flat.
+
+class PersonFile < Flat::File
+
+  EXAMPLE_FILE = <<-EOF
+1234567890123456789012345678901234567890
+f_name    l_name              age pad---
+Captain   Stubing             4      xxx
+No        Phone               5      xxx
+Has       Phone     11111111116      xxx
+
+EOF
+
+  add_field :f_name, :width => 10
+
+  add_field :l_name, :width => 10, :aggressive => true
+
+  add_field :phone, :width => 10
+
+  add_field :age, :width => 4, :filter => proc { |v| v.to_i }, :formatter => proc { |v| v.to_f.to_s }
+
+  pad :auto_name, :width => 3
+
+  add_field :ignore, :width => 3, :padding => true
+
+end

data/spec/lib/flat/field_spec.rb

@@ -0,0 +1,126 @@
+require 'spec_helper'
+
+describe Field do
+
+  let(:flat_file) { Flat::File }
+
+  describe Field::Definition do
+    describe 'instance creation' do
+      it 'should add a new field definition given minimum required information' do
+        # Minimum required fields are not enforced, just 'nice to have'.
+        field = flat_file.add_field :name, width: 5
+        expect( field ).to be_an_instance_of( Field::Definition )
+        expect( field.parent ).to eq( flat_file )
+        expect( field.name ).to   eq( :name )
+        expect( field.width ).to  eq( 5 )
+        expect( field.padding? ).to    be false
+        expect( field.aggressive? ).to be false
+        expect( field.filters ).to    be_empty
+        expect( field.formatters ).to be_empty
+        expect( field.map_in_proc ).to be_nil
+      end
+    end
+  end # => describe Field::Definition
+
+  describe 'add_field' do
+    before do
+      flat_file.reset_file_data
+    end
+
+    it 'adds 1 field to flat file' do
+      flat_file.add_field :test, width: 20
+      expect( flat_file.fields.size ).to eq( 1 )
+      expect( flat_file.width ).to eq( 20 )
+      expect( flat_file.pack_format ).to eq( 'A20' )
+    end
+
+    it 'adds 2 fields to flat file' do
+      flat_file.add_field :test, width: 17
+      flat_file.add_field :test, width: 23
+      expect( flat_file.fields.size ).to eq( 2 )
+      expect( flat_file.width ).to eq( 40 )
+      expect( flat_file.pack_format ).to eq( 'A17A23' )
+    end
+
+    it 'adds a field via a block' do
+      # Method A: specifying field name inside the block
+      flat_file.add_field do |field|
+        field.name = :test
+        field.width = 15
+      end
+
+      # Method B: specifying field name outside the block
+      flat_file.add_field :test2 do |field|
+        field.width = 15
+      end
+
+      field = flat_file.fields.last
+      expect( field.name ).to eq( :test2 )
+
+      expect( flat_file.fields.size ).to eq( 2)
+      expect( flat_file.width ).to eq( 30 )
+      expect( flat_file.pack_format ).to eq( 'A15A15' )
+    end
+  end
+
+  describe 'pad' do
+    before do
+      flat_file.reset_file_data
+    end
+
+    it 'adds a named pad field to flat file' do
+      field = flat_file.pad :test, width: 12
+      expect( field.padding? ).to be true
+      expect( field.name ).to eq( :test )
+      expect( flat_file.fields.size ).to eq( 1 )
+      expect( flat_file.width ).to eq( 12 )
+      expect( flat_file.pack_format ).to eq( 'A12' )
+    end
+
+    it 'adds an auto named pad field to flat file' do
+      field = flat_file.pad :autoname, width: 3
+      expect( field.padding? ).to be true
+      expect( field.name ).to eq( :pad_1 )
+      expect( flat_file.fields.size ).to eq( 1 )
+      expect( flat_file.width ).to eq( 3 )
+      expect( flat_file.pack_format ).to eq( 'A3' )
+    end
+  end
+
+  describe 'filter' do
+    before do
+      flat_file.reset_file_data
+    end
+
+    it 'should not filter when none specified' do
+      field = flat_file.add_field :test
+      value = '123 '
+      filtered_value = field.filter value
+      expect( filtered_value ).to eq( '123 ' )
+    end
+
+    it 'should filter for a specified block' do
+      field = flat_file.add_field :test, filter: ->(v) { v.strip }
+      value = '123  '
+      filtered_value = field.filter value
+      expect( filtered_value ).to eq( '123' )
+    end
+
+    it 'should filter for a Filter Class' do
+      field = flat_file.add_field :test, filter: TestFilter
+      value = 'test'
+      filtered_value = field.filter value
+      expect( filtered_value ).to eq( 'TEST' )
+    end
+
+    it 'should filter for an instance of a Filter Class' do
+      test_filter = TestFilter.new
+      field = flat_file.add_field :test, filter: test_filter
+      value = 'AbCd'
+      filtered_value = field.filter value
+      expect( filtered_value ).to eq( 'dCbA' )
+    end
+
+  end
+
+end

data/spec/lib/flat/file_data_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+
+describe FileData do
+
+  let(:flat_file) { Flat::File }
+
+  describe 'flat_file_data' do
+    it 'should be a Hash' do
+      expect( flat_file.flat_file_data ).to be_an_instance_of( Hash )
+    end
+
+    it 'should have 4 keys' do
+      keys = flat_file.flat_file_data.keys
+      expect( keys.size ).to eq( 4 )
+      expect( keys ).to include( :width )
+      expect( keys ).to include( :pack_format )
+      expect( keys ).to include( :fields )
+    end
+  end
+
+  describe 'width' do
+    before do
+      flat_file.reset_file_data
+    end
+
+    it 'has a convenience accessor' do
+      expect( flat_file.flat_file_data[:width] ).to eq( flat_file.width )
+    end
+
+    it 'defaults to 0' do
+      expect( flat_file.width ).to eq( 0 )
+    end
+
+    it 'can be changed' do
+      flat_file.width += 1
+      expect( flat_file.width ).to eq( 1 )
+
+      flat_file.width -= 2
+      expect( flat_file.width ).to eq( -1 )
+
+      flat_file.width = 12
+      expect( flat_file.width ).to eq( 12 )
+    end
+  end
+
+end

data/spec/lib/flat/file_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe Flat::File do
+
+end

data/spec/lib/flat/record_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+
+describe Record do
+
+  let(:flat_file) { Flat::File }
+
+  describe Record::Definition do
+    before do
+      flat_file.reset_file_data
+    end
+
+    it 'creates a new instance' do
+      record = Record::Definition.new flat_file, {}, 12
+      expect( record.line_number ).to eq( 12 )
+      expect( record.attributes ).to be_empty
+    end
+
+    it 'has a getter per defined field' do
+      flat_file.add_field :field, width: 25
+      record = Record::Definition.new flat_file, {field: 'Field'}
+      expect( record.field ).to eq( 'Field' )
+    end
+
+    it 'has a setter per defined field' do
+      flat_file.add_field :field, width: 25
+      record = Record::Definition.new flat_file, {field: 'Field'}
+      record.field = record.field.upcase
+      expect( record.field ).to eq( 'FIELD' )
+    end
+
+    it 'throws an error for an unknown attribute' do
+      skip 'not capturing raised error correctly'
+
+      record = Record::Definition.new flat_file, {}, 12
+      expect( record.field ).to raise_error( Errors::FlatFileError )
+    end
+
+  end # => describe Record::Definition
+
+end

data/spec/lib/flat_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+require 'flat_file_helper'
+
+describe Flat do
+
+  describe 'Version' do
+    it 'should verify current gem version' do
+      expect(Flat::VERSION).to eq('0.1.0')
+    end
+  end
+
+  describe 'Operations' do
+    let(:person_file) { PersonFile.new }
+    let(:data)        { PersonFile::EXAMPLE_FILE }
+    let(:lines)       { data.split("\n") }
+    let(:stream)      { StringIO.new(data) }
+
+    it 'reads data from a flat file' do
+      count = 0
+      person_file.each_record( stream ) do |x, y|
+        count += 1
+      end
+      expect( count ).to eq( lines.size )
+    end
+
+  end # => describe 'Operations'
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# Setup the RSpec testing environment for Flat:
+#
+require 'coveralls'
+Coveralls.wear!
+
+require 'pry'
+require 'flat'
+
+class TestFilter
+  def self.filter(value)
+    value.upcase
+  end
+
+  def filter(value)
+    value.reverse
+  end
+end