flat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8dda342a45881d96ffeec6a23b57f9697d820a0
+  data.tar.gz: 2d4a6c80305e3cf117f145d45ed789671e1934c7
+SHA512:
+  metadata.gz: 70a2839490d96e0dbcc8b32376c816b5f833bbd9935aa81b97bf79ed0ce7d3e21dbe916b7e2339de5c56bb14070af71a9da4b619707af96ddeabb62985794fea
+  data.tar.gz: faec279d9e961e3de45ad854527a4d4d5107c68720500b08c56d67c1364d0f12c4f7b4c9312df98b6bb12431a2903ad3848f363b97ba472205d4705c496626da

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.ruby-gemset

@@ -0,0 +1 @@
+flat

data/.ruby-version

@@ -0,0 +1 @@
+2.1.2

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+cache: bundler
+
+rvm:
+  - 2.1.2
+
+script: 'bundle exec rake'
+
+notifications:
+  email:
+    recipients:
+      - mriffe@gmail.com
+    on_failure: change
+    on_success: never
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in flat.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec, cmd: 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Mel Riffe
+
+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,106 @@
+# Flat
+
+[![Build Status](https://travis-ci.org/juicyparts/flat.svg?branch=develop)](https://travis-ci.org/juicyparts/flat)
+[![Coverage Status](https://coveralls.io/repos/juicyparts/flat/badge.png?branch=develop)](https://coveralls.io/r/juicyparts/flat)
+
+Flat is a library to make processing Flat Flies as easy as CSV files. Easily process flat files with Flat. Specify the format in a subclass of Flat::File and read and write until the cows come home.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'flat'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install flat
+
+## Usage
+
+A simple example for a flat file class for grabbing information about
+people might look like this:
+
+    # 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
+
+      def self.trim(v)
+        v.trim
+      end
+
+    end
+
+    p = People.new
+
+    p.each_record(open('somefile.dat')) do |person|
+
+      puts "First Name: #{person.first_name}"
+      puts "Last Name : #{person.last_name}"
+      puts "Birthday : #{person.birthday}"
+
+      puts person.to_s
+    end
+
+Consult the [RDocs](http://rubydoc.info/github/juicyparts/flat) for additional examples, and information on Filters and
+Formatters.
+
+## Contributing
+
+1. Fork it ( https://github.com/juicyparts/flat/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Inspiration
+
+I had been looking for a library to handle flat files in a manner similar to
+the CSV library and stumbled upon the following:
+
+* flat_filer (http://rubygems.org/gems/flat_filer)
+* flat_filer (https://github.com/xforty/flat_filer)
+* flat_filer (https://github.com/cheapRoc/flat_filer)
+
+They all appeared to be abandoned so I decided to resurrect them with my own
+spin on the implementation.
+
+# LICENSE
+
+Copyright (c) 2014 Mel Riffe
+
+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/Rakefile

@@ -0,0 +1,18 @@
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+require 'rdoc/task'
+
+# Default directory to look in is `/specs`
+# Run with `rake spec`
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color', '--format', 'documentation']
+end
+
+task :default => :spec
+
+RDoc::Task.new(:rdoc => "doc", :clobber_rdoc => "doc:clean", :rerdoc => "doc:force") do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = 'Flat Library Documentation'
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+end

data/flat.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'flat/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "flat"
+  spec.version       = Flat::VERSION
+  spec.authors       = ["Mel Riffe"]
+  spec.email         = ["mriffe@gmail.com"]
+  spec.summary       = %q{Library to make processing Flat Flies as easy as CSV files.}
+  spec.description   = %q{Easily process flat files with Flat. Specify the format in a subclass of Flat::File and read and write until the cows come home.}
+  spec.homepage      = "http://rubydoc.info/github/juicyparts/flat"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "extlib", "~> 0.9.0"
+
+  spec.add_development_dependency "bundler", ">= 1.6.2" # was "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rdoc", "~> 4.1.0"
+
+  spec.add_development_dependency "rspec", "~> 3.1.0"
+  spec.add_development_dependency "rspec-nc", "~> 0.2.0"
+  spec.add_development_dependency "guard", "~> 2.6.0"
+  spec.add_development_dependency "guard-rspec", "~> 4.3.0"
+  spec.add_development_dependency "pry", "~> 0.10.0"
+  spec.add_development_dependency "pry-remote", "~> 0.1.0"
+  spec.add_development_dependency "pry-nav", "~> 0.2.0"
+
+  spec.add_development_dependency "coveralls", "~> 0.7.0"
+end

data/lib/flat/errors.rb

@@ -0,0 +1,33 @@
+module Errors #:nodoc:
+
+  # = FlatFileError
+  #
+  # Generic error class and superclass of all other errors raised by Flat.
+  #
+  class FlatFileError          < StandardError;     end
+
+  # = LayoutConstructorError
+  #
+  # The specified layout definition was not valid.
+  #
+  class LayoutConstructorError < FlatFileError;     end
+
+  # = RecordLengthError
+  #
+  # Generic error having to do with line lengths not meeting expectations.
+  #
+  class RecordLengthError      < FlatFileError;     end
+
+  # = ShortRecordError
+  #
+  # The incoming line was shorter than expections defined.
+  #
+  class ShortRecordError       < RecordLengthError; end
+
+  # = LongRecordError
+  #
+  # The incoming line was longer than expections defined.
+  #
+  class LongRecordError        < RecordLengthError; end
+
+end # => module Errors

data/lib/flat/field.rb

@@ -0,0 +1,171 @@
+##
+# = Field
+#
+# A field definition tracks information that's necessary for
+# FlatFile to process a particular field.  This is typically
+# added to a subclass of FlatFile like so:
+#
+#  class SomeFile < FlatFile
+#    add_field :some_field_name, :width => 35
+#  end
+#
+module Field
+  ##
+  # = Class Methods
+  #
+  # Defines behavior for subclasses of Flat::File regarding the specification
+  # of the line structure contained in a flat file.
+  #
+  module ClassMethods
+
+    ##
+    # Add a field to the FlatFile subclass.  Options can include
+    #
+    # :width - number of characters in field (default 10)
+    # :filter - callack, lambda or code block for processing during reading
+    # :formatter - callback, lambda, or code block for processing during writing
+    #
+    #  class SomeFile < FlatFile
+    #    add_field :some_field_name, :width => 35
+    #  end
+    #
+    # == Options
+    #
+    def add_field name = nil, options = {}, &block
+      fields << field_def = Field::Definition.new(name, options, self)
+
+      yield field_def if block_given?
+
+      pack_format << "A#{field_def.width}"
+      flat_file_data[:width] += field_def.width
+      # width += field_def.width # doesn't work for some reason
+
+      # TODO: Add a check here to ensure the Field has a name specified; it can be a String or Symbol
+      return field_def
+    end
+
+    ##
+    # Add a pad field. To have the name auto generated, use :autoname for
+    # the name parameter. For options see +add_field+.
+    #
+    def pad name, options = {}
+      add_field ( name == :autoname ? new_pad_name : name ), options.merge( padding: true )
+    end
+
+    private
+
+    ##
+    # Used to generate unique names for pad fields which use :autoname.
+    #
+    def new_pad_name #:nodoc:
+      "pad_#{unique_id}".to_sym
+    end
+
+    ##
+    # Increments an id counter which is used to generate unique pad names
+    #
+    def unique_id #:nodoc:
+      @unique_id = (@unique_id || 0) + 1
+    end
+
+  end # => module ClassMethods
+
+  module InstanceMethods #:nodoc:
+  end # => module InstanceMethods
+
+  def self.included receiver #:nodoc:
+    receiver.extend         ClassMethods
+    receiver.send :include, InstanceMethods
+  end
+
+  # = Definition
+  # Used in Flat::File subclasses to define how a Record is defined.
+  #
+  #  class SomeFile < Flat::File
+  #    add_field :some_field_name, :width => 35
+  #  end
+  #
+  class Definition #:nodoc:
+    attr_accessor :parent, :name, :width, :padding, :aggressive
+    attr_accessor :filters, :formatters, :map_in_proc
+
+    ##
+    # Create a new FieldDef, having name and width. parent is a reference to the
+    # FlatFile subclass that contains this field definition.  This reference is
+    # needed when calling filters if they are specified using a symbol.
+    #
+    # Options can be :padding (if present and a true value, field is marked as a
+    # pad field), :width, specify the field width, :formatter, specify a formatter,
+    # :filter, specify a filter.
+    #
+    def initialize name = null, options = {}, parent = {}
+      @parent, @name = parent, name
+
+      @width      = options.fetch(:width, 10)
+      @padding    = options.fetch(:padding, false)
+      @aggressive = options.fetch(:aggressive, false)
+
+      @filters = @formatters = Array.new
+
+      add_filter options[:filter]
+      add_formatter options[:formatter]
+
+      @map_in_proc = options[:map_in_proc]
+    end
+
+    def padding?
+      @padding
+    end
+
+    def aggressive?
+      @aggressive
+    end
+
+    ##
+    # Add a filter. Filters are used for processing field data when a flat file is
+    # being processed. For fomratting the data when writing a flat file, see
+    # add_formatter
+    #
+    def add_filter filter = nil, &block
+      @filters.push( filter ) unless filter.blank?
+      @filters.push( block ) if block_given?
+    end
+
+    ##
+    # Add a formatter. Formatters are used for formatting a field
+    # for rendering a record, or writing it to a file in the desired format.
+    #
+    def add_formatter formatter = nil, &block
+      @formatters.push( formatter ) unless formatter.blank?
+      @formatters.push( block ) if block_given?
+    end
+
+    ##
+    # Passes value through the filters defined on this Field::Definition
+    #
+    def filter value
+      @filters.each do |filter|
+        value = case filter
+            when Symbol
+              @parent.public_send filter, value
+            when Proc
+              if filter.arity == 0
+                value
+              else
+                filter.call value
+              end
+            when Class, Object
+              unless filter.respond_to? 'filter'
+                value
+              else
+                filter.filter value
+              end
+            else
+              value
+            end
+      end
+      value
+    end
+  end # => class Definition
+
+end # => module Field

data/lib/flat/file.rb

@@ -0,0 +1,18 @@
+require 'flat/errors'
+require 'flat/file_data'
+require 'flat/field'
+require 'flat/layout'
+require 'flat/record'
+require 'flat/read_operations'
+
+# = Flat::File
+#
+class Flat::File
+  include Errors
+  include FileData
+  include Layout
+  include Field
+  include Record
+  include ReadOperations
+
+end # => class Flat::File

data/lib/flat/file_data.rb

@@ -0,0 +1,123 @@
+##
+# = FileData
+#
+# Defines structures and accessors for the internal FileData required by Flat::File
+# and its successful operations.
+#
+module FileData
+  ##
+  # = Class Methods
+  #
+  # Defines behavior for subclasses of Flat::File regarding the management of
+  # its internal data structures.
+  #
+  module ClassMethods
+
+    ##
+    # Container for various points of data as defined in the Flat::File subclass.
+    #
+    # Returns a +Hash+ with the following keys:
+    # * +:width+ - The overall width, or length, of a line in the flat file.
+    # * +:pack_format+ - A format +String+ for use by String#unpack.
+    # * +:fields+ - An +Array+ of Field::Definitions
+    # * +:layouts+ - An +Array+ of Layout::Definitions
+    #
+    def flat_file_data
+      @data ||= {
+        :width       => 0,
+        :pack_format => '',
+        :fields      => [],
+        :layouts     => [],
+      }
+    end
+
+    ##
+    # Convenience method for accessing <tt>flat_file_data[:fields]</tt>
+    #
+    # Returns an +Array+ of Field::Definitions
+    #
+    def fields
+      flat_file_data[:fields]
+    end
+
+    ##
+    # Convenience method for accessing <tt>flat_file_data[:width]</tt>
+    #
+    # Returns the overall length of a line to text in the flat file.
+    #
+    def width
+      flat_file_data[:width]
+    end
+
+    #
+    # Added setter to support +=, -= constructs; also allows direct
+    # assignment.
+    #
+    def width=(value) #:nodoc:
+      flat_file_data[:width] = value
+    end
+
+    ##
+    # Convenience method for accessing <tt>flat_file_data[:pack_format]</tt>
+    #
+    # Returns a +String+ sutiable for use with String#unpack
+    #
+    def pack_format
+      flat_file_data[:pack_format]
+    end
+
+    ##
+    # Convenience method for accessing <tt>flat_file_data[:layouts]</tt>
+    #
+    # Returns an +Array+ of Layout::Definitions
+    #
+    def layouts
+      flat_file_data[:layout]
+    end
+
+    #
+    # Added for test purposes, primarily. DESTRUCTIVE!
+    #
+    def reset_file_data #:nodoc:
+      @data = nil
+    end
+
+  end # => module ClassMethods
+
+  ##
+  # = Instance Methods
+  #
+  # Defines behavior for instances of subclasses of Flat::File regarding the
+  # accessing of its internal data structures.
+  #
+  module InstanceMethods
+
+    ##
+    # Returns the +width+ of this Flat::File subclass as defined in its class
+    #
+    def width
+      self.class.width
+    end
+
+    ##
+    # Returns the +pack_format+ of this Flat::File subclass as defined in its class
+    #
+    def pack_format
+      self.class.pack_format
+    end
+
+    ##
+    # Returns the +fields+ of this Flat::File subclass as defined in its class
+    #
+    def fields
+      self.class.fields
+    end
+
+  end # => module InstanceMethods
+
+  def self.included receiver #:nodoc:
+    receiver.extend         ClassMethods
+    receiver.send :include, InstanceMethods
+  end
+
+end # => module FileData

data/lib/flat/layout.rb

@@ -0,0 +1,30 @@
+# = Layout
+# *EXPERIMENTAL*
+#
+# If a flat file contains several different record structures, defining
+# more than one Layout::Definition allows Flat::File to easily process
+# the file.
+#
+# *EXPERIMENTAL*
+#
+module Layout
+  module ClassMethods #:nodoc:
+  end # => module ClassMethods
+
+  module InstanceMethods #:nodoc:
+  end # => module InstanceMethods
+
+  def self.included receiver #:nodoc:
+    receiver.extend         ClassMethods
+    receiver.send :include, InstanceMethods
+  end
+
+  # = Definition
+  # Add the ability to have multiple layouts per flat flat.
+  #
+  # EXPERIMENTAL
+  #
+  class Definition #:nodoc:
+  end # => class Definition
+
+end # => module Layout

data/lib/flat/read_operations.rb

@@ -0,0 +1,50 @@
+##
+# = ReadOperations
+#
+# Defines functionality required for the successful reading, parsing and
+# interpreting of a line of text contained in a flat file.
+#
+module ReadOperations
+  module ClassMethods #:nodoc:
+  end # => module ClassMethods
+
+  ##
+  # = Instance Methods
+  #
+  # Defines behavior for instances of a subclass of Flat::File regarding the
+  # reading and parsing of the file contents, line by line.
+  #
+  module InstanceMethods
+
+    # Iterate through each record (each line of the data file). The passed
+    # block is passed a new Record representing the line.
+    #
+    #    s = SomeFile.new
+    #    s.each_record(open('/path/to/file')) do |r|
+    #      puts r.first_name
+    #    end
+    #--
+    # NOTE: Expects an open valid IO handle; opening and closing is out of scope
+    #++
+    #
+    def each_record io, &block
+      io.each_line do |line|
+        line.chop!
+        next if line.length.zero?
+
+        unless (self.width - line.length).zero?
+          raise Errors::RecordLengthError, "length is #{line.length} but should be #{self.width}"
+        end
+
+        yield create_record(line, io.lineno), line
+      end
+    end
+
+  end # => module InstanceMethods
+
+  def self.included receiver #:nodoc:
+    receiver.extend         ClassMethods
+    receiver.send :include, InstanceMethods
+  end
+
+end # => module ReadOperations