flat 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a5de78be3005078ab631ac84a51aadf0e052925
-  data.tar.gz: 1360042ad4aa5b1179f4e5064bd9c7509c7a97d6
+  metadata.gz: ba9c2c820dfbb6f95015b50eb4d64ea957fc9ba4
+  data.tar.gz: 283cfca9ab988ae636d3d494ef0fad7dc4fb4a20
 SHA512:
-  metadata.gz: 7726ead08345447649093a88350019d001448006a82f48218ac1c9897b857533442b520b8f99bc98bf8cce2c7ee0a73f171cb3a88773f42d5f9f507f9b85b36a
-  data.tar.gz: 815db149f73d0a3f373441acd8c70b68b01b019127823ae8bf2ffc60683e8b30390b2b747f9da258f3f4a9e2fd2db84dad664ddb8cac193b4361747a118dc33e
+  metadata.gz: 148837045c6baa0812f6ba33df1736677357efa347c4c17c30f6c979774cbaa4c83fc92e6aabe14ee7a2c363e577a74d7d9570e4c4162dcb3d7a80f2b2bdbfbb
+  data.tar.gz: 09f18cfd8de97a106785fa52ad806e8e0d9578df0201fcd516ada10e6e5dfcaa4e97ed6c2dd70a6797808bbc026c9eaf1662e2b8e21be412ef7fef50ed3c58b3

data/README.md

@@ -4,7 +4,7 @@
 [![Coverage Status](https://coveralls.io/repos/juicyparts/flat/badge.png?branch=master)](https://coveralls.io/r/juicyparts/flat)
 [![Gem Version](https://badge.fury.io/rb/flat.svg)](http://badge.fury.io/rb/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.
+[Flat](https://github.com/juicyparts/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
 
@@ -42,7 +42,7 @@ people might look like this:
       pad       :autoname,   width: 2
 
       def self.trim(v)
-        v.trim
+        v.strip
       end
 
     end

data/flat.gemspec

@@ -18,8 +18,8 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  # Ruby 2.0 and above
-  spec.required_ruby_version = '>= 2.0'
+  # Ruby 1.9.3 and above
+  spec.required_ruby_version = '>= 1.9.3'
   spec.post_install_message = "Thanks for installing!"
   spec.metadata = {
     "source_code"   => 'https://github.com/juicyparts/flat',

data/lib/flat.rb

@@ -3,77 +3,6 @@ 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
+module Flat #:nodoc
   include Extlib
 end

data/lib/flat/field.rb

@@ -2,10 +2,10 @@
 # = 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:
+# Flat::File to process a particular field.  This is typically
+# added to a subclass of Flat::File like so:
 #
-#  class SomeFile < FlatFile
+#  class SomeFile < Flat::File
 #    add_field :some_field_name, :width => 35
 #  end
 #
@@ -19,13 +19,13 @@ module Field
   module ClassMethods
 
     ##
-    # Add a field to the FlatFile subclass.  Options can include
+    # Add a field to the Flat::File 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
+    #  class SomeFile < Flat::File
     #    add_field :some_field_name, :width => 35
     #  end
     #
@@ -91,7 +91,7 @@ module Field
 
     ##
     # Create a new FieldDef, having name and width. parent is a reference to the
-    # FlatFile subclass that contains this field definition.  This reference is
+    # Flat::File 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

data/lib/flat/file.rb

@@ -7,6 +7,153 @@ require 'flat/read_operations'
 
 # = Flat::File
 #
+# 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 separated value) files, there are no delimiters to define where
+# values end or begin. Flat provides a mechanism 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.
+#
+#    # 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.strip
+#      end
+#    end
+#
+# You will notice the minimum required information is field name and width. The
+# special case is with <tt>pad</tt>; you can specify 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
+# specify the name first. However, you do need to set the name inside the
+# block. The value yielded to the block is an instance of Field::Definition.
+#
+#    class People < Flat::File
+#      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
+#
+# After your Flat::File has been defined you will be able to read data from
+# an actual file. Flat::File does not manage the opening and closing of Files
+# or other IO instances (e.g. StringIO).
+#
+#    data_file = File.open('somefile.dat', 'r')
+#
+#    People.new.each_record(data_file) do |person|
+#      puts "First Name: #{person.first_name}" # => Walter
+#      puts "Last Name : #{person.last_name}"  # => White
+#      puts "Birthday  : #{person.birthday}"   # => 19590907
+#    end
+#
+#    data_file.close
+#
+# +each_record+ yields a Record::Definition and the line of text that
+# produced it. This object will respond to the field names defined by
+# +add_field+. Plus, depending on the filters defined, the resulting data
+# can be nearly any Ruby type: String, Symbol, Boolean, Date, etc. This allows
+# you to deal with the data as it was intended.
+#
+# == Writing Data
+#
+# <em>Slated for a future release.</em>
+#
+# == Filters
+#
+# When adding new fields you can specify a filter through which the incoming
+# data will be passed. In the absence of a filter the resulting values from the
+# Record::Definition will be the raw text as found in the flat file.
+#
+# You can define filters in 1 of four ways: Symbol, Proc, Class, or Object.
+#
+# Operationally they all function the same way: used when reading the raw text
+# in the file to produce a filtered value for storage in a Record::Definition.
+#
+# === Defined as a Symbol
+#
+#    add_field :first_name, width: 10, filter: :trim
+#
+# +trim+, in this case, must be defined on the Flat::File subclass.
+#
+#    def self.trim(v)
+#      v.strip
+#    end
+#
+# Use this method when more control over the filtering is required, such as
+# handling Date parsing errors.
+#
+# === Defined as a Proc
+#
+#    add_field :last_name,  width: 10, filter: ->(v) { v.strip }
+#
+# The proc is stored and later called when needed. If the filtering
+# requirements are easy and direct, this method is appropriate.
+#
+# === Defined as a Class or Object
+#
+#    add_field :birthday,   width: 8,  filter: BirthdayFilter
+#    add_field :birthday,   width: 8,  filter: BirthdayFilter.new
+#
+# The Class or Object used must respond to +filter+. This method is very
+# similar to the +Symbol+ method, expect there is only 1 method to define.
+#
+#    def self.filter(v)
+#      date = Date.parse(v) rescue $!
+#      return date unless date.is_a? ArgumentError
+#      nil
+#    end
+#
+#    def filter(v)
+#      self.class.filter(v)
+#    end
+#
+# == Formatters
+#
+# <em>Slated for a future release.</em>
+#
+# == Layouts
+#
+# <em>Slated for a future release.</em>
+#
+# == 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 expectations defined.
+# * +LongRecordError+ - The incoming line was longer than expectations defined.
+#
 class Flat::File
   include Errors
   include FileData

data/lib/flat/version.rb

@@ -1,3 +1,3 @@
 module Flat #:nodoc:
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flat
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Mel Riffe
@@ -214,7 +214,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="