pikelet 2.0.0.beta.7 → 2.0.0.beta.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4e3adcc8650568a13523518174d2723b61ddf4ba
-  data.tar.gz: d79cc1a300a4d0356ada007222b6759f98e86c6d
+  metadata.gz: 3c813b4fc0de2c84af10d6e1be5ef863df7dfd89
+  data.tar.gz: a638197dd405056da0024b5f6e9352159e8ba72b
 SHA512:
-  metadata.gz: 6fb05cf2c716cd1cee499cbe4abe9fe4fd6d4bf99b55c0d9bf471a5749dc17d122514f2aebd8d52e671c3dadf5633e69e1183a10ee16275fdbe46897dd0f5546
-  data.tar.gz: d4b1012c93182ce8d00364ed9d47ccd9ba5003e224c122ccf78d4f33111f08fdf3b3208501a2054fa9aba06b5e75172a7803d57ea6c51a33be97ac7df167d3e3
+  metadata.gz: 9c6c7eddcdc7e5b6453e0364e1f2fd3cc8b7a327a3ad8c4c9c09a5c624c3ae4e9d6b81cdae35b55ca3220f19e9fe4d17e294b714e5c04876fd898f9e2fa647b0
+  data.tar.gz: 54cce0eef113dd276d2a7971f5b7c5789c53648e0a53e316f145222a99d95627e37f6f98356ba5d2e2da89b13637d00def7d9ce1dedaaef5ae6450cfe7fc59eb

data/README.md

@@ -4,14 +4,6 @@
 [![Build status][build-badge]][build]
 [![Coverage Status][coverage-badge]][coverage]
 
-## Beta notes
-
-The next release of Pikelet will be capable of formatting flat-file databases
-for output. As part of this I will be dropping CSV support as it is
-constraining my options and, as far as I know, nobody is using it. For the
-time being I want to let it evolve as a pure flat-file database parser. In a
-future release I may restore CSV support, but I make no promises.
-
 ## Introduction
 
 A [pikelet][pikelet-recipe] is a small, delicious pancake popular in Australia
@@ -27,7 +19,7 @@ record types. Each record type has a different structure, though some types
 share common fields, and all types have a type signature.
 
 However, Pikelet will also handle more typical flat-file databases comprised
-of homogeneous records.
+of homogeneous records. It can also be used produce data in flat-file format.
 
 ## Installation
 
@@ -51,8 +43,8 @@ Let's say our file is a simple list of first and last names with each field
 being 10 characters in width, padded with spaces (vertical pipes used to
 indicate field boundaries).
 
-    |Nicolaus  |Copernicus|
-    |Tycho     |Brahe     |
+    |Grace     |Hopper    |
+    |Ada       |Lovelace  |
 
 We can describe this format using Pikelet as follows:
 
@@ -84,8 +76,19 @@ or this:
 to an array, or whatever else you people do with enumerators. In any case,
 what you'll end up with is a series of `Structs` like this:
 
-    #<struct first_name="Nicolaus", last_name="Copernicus">,
-    #<struct first_name="Tycho", last_name="Brahe">
+    #<struct first_name="Grace", last_name="Hopper">,
+    #<struct first_name="Ada", last_name="Lovelace">
+
+You can output these records in flat-file format like so:
+
+    definition.format(records)
+
+Which will return an array of strings:
+
+    [
+      "Grace     Hopper    ",
+      "Ada       Lovelace  "
+    ]
 
 ### A more complex case: heterogeneous records
 
@@ -93,13 +96,13 @@ Now let's say we're given a file consisting of names and addresses, each
 record contains a 4-character type signature - 'NAME' for names, 'ADDR' for
 addresses:
 
-    |NAME|Nicolaus  |Copernicus|
-    |ADDR|123 South Street     |Nowhereville        |45678Y    |Someplace           |
+    |NAME|Frida     |Kahlo     |
+    |ADDR|123 South Street     |Sometown            |45678Y    |Someplace           |
 
 We can describe it as follows:
 
-    Pikelet.define do
-      type_signature 0...4
+    definition = Pikelet.define signature_field: :type do
+      type 0...4
 
       record "NAME" do
         first_name  4...14
@@ -114,8 +117,8 @@ We can describe it as follows:
       end
     end
 
-Note that the type signature is described as a field like any other, but it
-must have the name `type_signature`.
+The `signature_field` option tells Pikelet which field to use to determine
+which record type to apply.
 
 Each record type is described using `record` statements, which take the
 record's type signature as a parameter and a block describing its fields.
@@ -123,37 +126,48 @@ record's type signature as a parameter and a block describing its fields.
 When we parse the data, we end up with this:
 
     #<struct
-      type_signature="NAME",
-      first_name="Nicolaus",
-      last_name="Copernicus">,
+      type="NAME",
+      first_name="Frida",
+      last_name="Kahlo">,
     #<struct
-      type_signature="ADDR",
+      type="ADDR",
       street_address="123 South Street",
-      city="Nowhereville",
+      city="Sometown",
       postal_code="45678Y",
       state="Someplace">
 
+As with the simple case of homogenous records, calling the `format` method on
+your definition with the records will output an array of strings:
+
+    [
+      "NAMEFrida     Kahlo                                                        ",
+      "ADDR123 South Street     Sometown            45678Y    Someplace           "
+    ]
+
+Note that each record is padded out to the full width of the widest record
+type.
+
 ### Inheritance
 
 Now we go back to our original example, starting with a simple list of names,
-but this time some of the records include a nickname:
+but this time some of the records include a middle name:
 
-    |PLAIN|Nicolaus  |Copernicus|
-    |FANCY|Tycho     |Brahe     |Tykester  |
+    |NAME |Rosa      |Parks     |
+    |NAME+|Rosalind  |Franklin  |Elsie     |
 
 The first and last name fields have the same boundaries in each case, but the
-"FANCY" records have an additional field. We can describe this by nesting the
-definition for FANCY records inside the definition for the PLAIN records:
+"NAME+" records have an additional field. We can describe this by nesting the
+definition for NAME+ records inside the definition for the NAME records:
 
-    Pikelet.define do
-      type_signature 0...5
+    Pikelet.define signature_field: :record_type do
+      record_type 0...5
 
-      record "PLAIN" do
+      record "NAME" do
         first_name  5...15
         last_name  15...25
 
-        record "FANCY" do
-          nickname 25...35
+        record "NAME+" do
+          middle_name 25...35
         end
       end
     end
@@ -164,14 +178,14 @@ you might have already figured this out if you were paying attention.
 Anyway, this is what we get when we parse it.
 
     #<struct
-      type_signature="SIMPLE",
-      first_name="Nicolaus",
-      last_name="Copernicus">,
+      record_type="NAME",
+      first_name="Rosa",
+      last_name="Parks">,
     #<struct
-      type_signature="FANCY",
-      first_name="Tycho",
-      last_name="Brahe",
-      nickname="Tykester">
+      record_type="NAME+",
+      first_name="Rosalind",
+      last_name="Franklin",
+      middle_name="Elsie">
 
 ### Custom field parsing
 
@@ -188,10 +202,101 @@ You can also use shorthand syntax:
       a_number 0...4, &:to_i
     end
 
+A parsers can also be supplied as an option.
+
+    Pikelet.define do
+      a_number  0... 4, parse: ->(value) { value.to_i }
+      some_text 4...10, parse: :upcase
+    end
+
+### Custom field formatters
+
+You can supply a custom formatter for a field.
+
+    definition = Pikelet.define do
+      username  0...10, format: :downcase
+      password 10...50, format: ->(v) { Digest::SHA1.hexdigest(v) }
+    end
+
+    definition.format([
+      OpenStruct.new(username: "Coleman",    password: "password"),
+      OpenStruct.new(username: "Savitskaya", password: "sekrit"  )
+    ])
+
+This will produce the following array of strings:
+
+    [
+      "coleman   5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
+      "savitskaya8d42e738c7adee551324955458b5e2c0b49ee655"
+    ]
+
+### Formatting options
+
+In addition to custom formatters, you can provide alignment and padding
+options.
+
+    definition = Pikelet.define do
+      number 0... 3, align: :right, pad: "0"
+      text   3...10, align: :left,  pad: " "
+    end
+
+There is also a `type` option, which is a shorthand for default alpha and
+numeric formatting.
+
+    definition = Pikelet.define do
+      number 0... 3, type: :numeric # right-align, pad with zeroes
+      text   3...10, type: :alpha   # left-align, pad with spaces
+    end
+
+### Custom record classes
+
+By default Pikelet will return records as `Struct` objects, but you can supply
+a custom class to use instead.
+
+    class Base
+      attr_reader :type
+
+      def initialize(**attrs)
+        @type = attrs[:type]
+      end
+    end
+
+    class Name < Base
+      attr_reader :name
+
+      def initialize(**attrs)
+        super(type: "NAME")
+        @name = attrs[:name]
+      end
+    end
+
+    class Address < Base
+      attr_reader :street, :city
+
+      def initialize(**attrs)
+        super(type: "ADDR")
+        @street = attrs[:street]
+        @city = attrs[:city]
+      end
+    end
+
+    Pikelet.define signature_field: :type, record_class: Base do
+      type 0...4
+
+      record "NAME", record_class: Name do
+        name 4...20
+      end
+
+      record "ADDR", record_class: Address do
+        street  4...20
+        city   20...30
+      end
+    end
+
+The only requirement on the class is that its constructor (ie. `initialize`
+method) should accept attributes as a hash with symbol keys.
 ## Thoughts/plans
 
-* With some work, Pikelet could produce flat file records as easily as it
-  consumes them.
 * I had a crack at supporting lazy enumeration, and it kinda works. Sometimes.
   If the moon is in the right quarter. I'd like to get it working properly.
 

data/lib/pikelet/field_definition.rb

@@ -11,7 +11,7 @@ module Pikelet
 
       @index = index
       @width = index.size
-      @parser = parse || block || :strip
+      @parser = parse || block
       @formatter = format || :to_s
 
       if type == :numeric
@@ -33,8 +33,13 @@ module Pikelet
     end
 
     def parse(record)
-      if value = record[index]
-        parser.to_proc.call(value)
+      # TODO: Test that fields are always stripped.
+      if value = record[index].strip
+        if parser
+          parser.to_proc.call(value)
+        else
+          value
+        end
       end
     end
 

data/lib/pikelet/version.rb

@@ -1,3 +1,3 @@
 module Pikelet
-  VERSION = "2.0.0.beta.7"
+  VERSION = "2.0.0.beta.8"
 end

data/spec/readme_examples_spec.rb

@@ -0,0 +1,177 @@
+require "spec_helper"
+require "pikelet"
+
+describe "README Examples:" do
+  def strip_data(text)
+    text.gsub(/^#{text.scan(/^[ \t]*(?=\S)/).min || ''}/, '').gsub('|', '').split("\n")
+  end
+
+  RSpec::Matchers.define :match do |expected|
+    def record_matches_hash?(record, hash)
+      hash.all? { |attr, value| record.send(attr) == value }
+    end
+
+    match do |actual|
+      actual.zip(expected).all? do |actual, expected|
+        record_matches_hash?(actual, expected)
+      end
+    end
+  end
+
+  shared_examples_for "parse the data" do
+    subject { definition.parse(strip_data(data)) }
+
+    it { is_expected.to match expected_records }
+  end
+
+  shared_examples_for "format the records" do
+    subject { definition.format(records) }
+
+    it { is_expected.to eq strip_data(expected_data) }
+  end
+
+  describe "Homogeneous records" do
+    let(:definition) do
+      Pikelet.define do
+        first_name  0...10
+        last_name  10...20
+      end
+    end
+
+    let(:data) do
+      <<-DATA
+        |Grace     |Hopper    |
+        |Ada       |Lovelace  |
+      DATA
+    end
+
+    let(:expected_records) do
+      [
+        { first_name: "Grace", last_name: "Hopper"   },
+        { first_name: "Ada",   last_name: "Lovelace" }
+      ]
+    end
+
+    it_will "parse the data"
+  end
+
+  describe "Heterogeneous records" do
+    let(:definition) do
+      Pikelet.define signature_field: :type do
+        type 0...4
+
+        record "NAME" do
+          first_name  4...14
+          last_name  14...24
+        end
+
+        record "ADDR" do
+          street_address  4...24
+          city           24...44
+          postal_code    44...54
+          state          54...74
+        end
+      end
+    end
+
+    let(:data) do
+      <<-DATA
+        |NAME|Frida     |Kahlo     |
+        |ADDR|123 South Street     |Sometown            |45678Y    |Someplace           |
+      DATA
+    end
+
+    let(:expected_records) do
+      [
+        { type: "NAME", first_name: "Frida", last_name: "Kahlo" },
+        { type: "ADDR", street_address: "123 South Street", city: "Sometown", postal_code: "45678Y", state: "Someplace" }
+      ]
+    end
+
+    it_will "parse the data"
+  end
+
+  describe "Inheritance" do
+    let(:definition) do
+      Pikelet.define signature_field: :record_type do
+        record_type 0...5
+
+        record "NAME" do
+          first_name  5...15
+          last_name  15...25
+
+          record "NAME+" do
+            middle_name 25...35
+          end
+        end
+      end
+    end
+
+    let(:data) do
+      <<-DATA
+        |NAME |Rosa      |Parks     |
+        |NAME+|Rosalind  |Franklin  |Elsie     |
+      DATA
+    end
+
+    let(:expected_records) do
+      [
+        { record_type: "NAME",  first_name: "Rosa",     last_name: "Parks" },
+        { record_type: "NAME+", first_name: "Rosalind", last_name: "Franklin", middle_name: "Elsie" }
+      ]
+    end
+
+    it_will "parse the data"
+  end
+
+  describe "Custom field parsing" do
+    let(:definition) do
+      Pikelet.define do
+        a_number(0... 4) { |value| value.to_i }
+
+        another_number      4... 8, &:to_i
+        yet_another_number  8...12, parse: ->(value) { value.to_i }
+        some_text          12...20, parse: :upcase
+      end
+    end
+
+    let(:data) do
+      <<-DATA
+        |  67|   3| 999|blah    |
+      DATA
+    end
+
+    let(:expected_records) do
+      [
+        { a_number: 67, another_number: 3, yet_another_number: 999, some_text: "BLAH" }
+      ]
+    end
+
+    it_will "parse the data"
+  end
+
+  describe "Custom field formatting" do
+    let(:definition) do
+      Pikelet.define do
+        username  0...10, format: :downcase
+        password 10...50, format: ->(v) { Digest::SHA1.hexdigest(v) }
+      end
+    end
+
+    let(:records) do
+      [
+        OpenStruct.new(username: "Coleman",    password: "password"),
+        OpenStruct.new(username: "Savitskaya", password: "sekrit"  )
+      ]
+    end
+
+    let(:expected_data) do
+      <<-DATA
+        |coleman   |5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8|
+        |savitskaya|8d42e738c7adee551324955458b5e2c0b49ee655|
+      DATA
+    end
+
+    it_will "format the records"
+  end
+end

data/spec/spec_helper.rb

@@ -83,4 +83,6 @@ RSpec.configure do |config|
     # a real object. This is generally recommended.
     mocks.verify_partial_doubles = true
   end
+
+  config.alias_it_behaves_like_to :it_will, "it will"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pikelet
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta.7
+  version: 2.0.0.beta.8
 platform: ruby
 authors:
 - John Carney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-24 00:00:00.000000000 Z
+date: 2015-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -136,6 +136,7 @@ files:
 - spec/pikelet/record_definer_spec.rb
 - spec/pikelet/record_definition_spec.rb
 - spec/pikelet_spec.rb
+- spec/readme_examples_spec.rb
 - spec/spec_helper.rb
 homepage: ''
 licenses:
@@ -166,4 +167,5 @@ test_files:
 - spec/pikelet/record_definer_spec.rb
 - spec/pikelet/record_definition_spec.rb
 - spec/pikelet_spec.rb
+- spec/readme_examples_spec.rb
 - spec/spec_helper.rb