bumblebee 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e63f0ffdddd7bea22fb6da178b542556cde964543a2d7c4c68ef6e85b3bb06f3
-  data.tar.gz: 28a41de9de06653b0d2d41d52818bb690d786f124e6e84be7e867a496da2a8c6
+  metadata.gz: c3b95d42104a7a73d3af191aa0ab43a3aaadf03e6ab6bb612c07bd741a3cbd76
+  data.tar.gz: 7b4ef3e1738d81605786d36a1be4dedb6d9233e4709a7ad189a0552ca0a6cb21
 SHA512:
-  metadata.gz: 3153683a9564325488926f6bde6cb77ce59d1674ac6fcb3a9e60911a21870a26905b9d14d851f660d2c0c74b7df34986eadfd488a85d21734b3a7ff515e3453c
-  data.tar.gz: 9d19b1ea86c98101bb523a8e2ab1d6e0a04230c6b6616a2ba76b0e9bf584ccf2fcb4184a9fb14980e467a5d93749a104bb2b87a26313e48b4b5d1e5653c6376e
+  metadata.gz: bc0eb85df6dd1c2562b92d485f407bdf7a3a5ea3a0b2315a66d9a5a314ffe93a05d2772df1b149af4744cdcee4b6d2ace0c3eafb4aba573f757d67eed9ab9bdc
+  data.tar.gz: ebbf2f57ee8c5f3b061d990478f7a1655dfe025e32e417c1cfce19f23373a6222a3d3cc23720e24bb51e7a8f3487bf29df90f69f357e216aab7662eaf592c766

data/.rubocop.yml

@@ -2,10 +2,10 @@ Metrics/LineLength:
   Max: 100
 
 Metrics/BlockLength:
-  ExcludedMethods: ['it', 'describe', 'context']
+  ExcludedMethods: ['let', 'it', 'describe', 'context']
 
 Metrics/MethodLength:
-  Max: 12
+  Max: 25
 
 AllCops:
   TargetRubyVersion: 2.3

data/.travis.yml

@@ -15,6 +15,6 @@ before_script:
   - ./cc-test-reporter before-build
 script:
   - bundle exec rubocop
-  - bundle exec rspec
+  - bundle exec rspec spec --format documentation
 after_script:
   - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 3.0.0 (March 7th, 2019)
+
+**Breaking Changes: Public API Re-Write**
+
+* Major lessons were learnt during the implementation of versions one and two.  Version three seeks to iron out the DSL to make it more intuitive and usable.  Therefore, the entire DSL has been re-written from the ground up with a whole new API.
+
 # 2.1.0 (March 4th, 2019)
 
 * Added two domain-specific language options for configuring Column objects through Template: subclass Template class or pass in block.  This is optional and is backwards compatible.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bumblebee (2.1.0)
+    bumblebee (3.0.0)
       acts_as_hashable (~> 1.0)
 
 GEM

data/README.md

@@ -33,18 +33,13 @@ id | name | dob        | phone
 Using the following column configuration:
 
 ````ruby
-columns = [
-  { field: :id },
-  { field: :name },
-  { field: :dob },
-  { field: :phone }
-]
+columns = %i[id name dob phone]
 ````
 
 We could parse this data and turn it into hashes:
 
 ````ruby
-objects = Bumblebee.parse_csv(columns, data)
+objects = Bumblebee::Template.new(columns: columns).parse(data)
 ````
 
 Then `objects` is this array of hashes:
@@ -72,12 +67,12 @@ ID # | First Name | Date of Birth | Phone #
 Then we can explicitly map those as:
 
 ````ruby
-columns = [
-  { field: :id,     header: 'ID #' },
-  { field: :name,   header: 'First Name' },
-  { field: :dob,    header: 'Date of Birth' },
-  { field: :phone,  header: 'Phone #' }
-]
+columns = {
+  'ID #': { property: :id },
+  'First Name': { property: :name },
+  'Date of Birth': { property: :dob },
+  'Phone #': { property: :phone }
+}
 ````
 
 ### Nested Objects
@@ -118,183 +113,220 @@ ID # | First Name | Date of Birth | Phone #
 Using the following column config:
 
 ````ruby
-columns = [
-  { field: :id,                 header: 'ID #' },
-  { field: [:name, :first],     header: 'First Name' },
-  { field: [:demo, :dob],       header: 'Date of Birth' },
-  { field: [:contact, :phone],  header: 'Phone #' }
+columns = {
+  'ID #': {
+    property: :id
+  },
+  'First Name': {
+    property: :first,
+    through: :name
+  },
+  'Date of Birth': {
+    property: :dob,
+    through: :demo
+  },
+  'Phone #': {
+    property: :phone,
+    through: :contact
+  }
 ]
 ````
 
 And executing the following:
 
 ````ruby
-csv = Bumblebee.generate_csv(columns, objects)
+csv = Bumblebee::Template.new(columns: columns).generate(objects)
 ````
 
 The above columns config would work both ways, so if we received the CSV, we could parse it to an array of nested hashes.  Unfortunately, for now, we cannot do better than an array of nested hashes.
 
-### Custom To CSV Formatting
+### Custom  Formatting
 
-You can also pass in functions that can do the value formatting.  For example:
+You can also pass in built-in or custom functions that can do the value formatting.  For example:
 
 ````ruby
-columns = [
-  {
-    field: :id,
-    header: 'ID #'
+columns = {
+  'ID #': {
+    property: :id,
+    to_object: :integer
   },
-  {
-    field: :name,
-    header: 'First Name',
-    to_csv: [:name, :first, ->(o) { o.to_s.upcase }]
+  'First Name': {
+    property: :first,
+    through: :name,
+    to_csv: ->(v) { v.to_s.upcase }
   },
-  {
-    field: :dob,
-    header: 'Date of Birth',
-    to_csv: [:demo, :dob]
+  'Date of Birth': {
+    property: :dob,
+    through: :demo,
+    to_object: { type: :date, nullable: true }
   },
-  {
-    field: :phone,
-    header: 'Phone #',
-    to_csv: [:contact, :phone]
+  'Phone #': {
+    property: :phone,
+    through: :contact
   }
-]
+}
 ````
 
-would ensure the CSV has only upper-case `First Name` values.
+would ensure:
 
-### Custom To Object Formatting
+* id is an integer data type when parsed
+* the CSV has only upper-case `First Name` values
+* dob is a date data type when parsed
 
-You can also choose a custom method how the CSV's value is parsed just like you can customize how values are set for a CSV.  This helps function as an intermediate extractor/formatter/converter, in theory, should be able to give you alot more custom control over the parsing.
+Other formatting functions that can be used for to_object and/or to_csv:
 
-A previous example above showed a custom nested object-to-csv flow.  This time, let's go csv-to-object with this dataset:
+* bigdecimal: converts to BigDecimal (nullable, non-nullable default is 0)
+* boolean: converts to flexible boolean (nullable; non-nullable default is false).  1,t,true,y,yes all parse to true, 0,f,false,n,no all parse to false
+* date: converts to Date (nullable; non-nullable default is 1900-01-01)
+* integer: converts to Fixnum (nullable, non-nullable default is 0)
+* join: array is joined by separator option (defaults to comma)
+* float: converts to Float (nullable, non-nullable default is 0.0f)
+* function: custom lambda function (input is the resolved value, output of lambda will be used resolved value)
+* pluck_join: map the sub-property (sub_property option) then join them with separator (defaults to comma)
+* pluck_split: array is split by separator option (defaults to comma), then new object (object_class option) is created and sub-property (sub_property option) set.
+* split: array is split by separator option (defaults to comma)
+* string: calls to_s method on the value
 
-ID # | First Name | Date of Birth | Phone #
----- | ---------- | ------------- | ------------
-1    | Matt       | 1901-02-03    | 555-555-5555
-2    | Nick       | 1921-09-03    | 444-444-4444
-3    | Sam        | 1932-12-12    | 333-333-3333
+### Pluck Join / Pluck Split Explained
 
-Using the following column config:
+Pluck join and pluck split comes in handy when you have an array of objects and would like to:
+
+* map one value from each object and join it (in order to output in a CSV)
+* take a string value, split it, the map each value to a new object (in order to parse as objects)
+
+Take this input and configuration for example:
 
 ````ruby
-columns = [
+objects = [
   {
-    field: :id,
-    header: 'ID #',
-    to_object: ->(o) { o['ID #'].to_i }
+    id: 1,
+    name:     { first: 'Matt' },
+    demo:     { dob: '1901-02-03' },
+    contact:  { phone: '555-555-5555' },
+    children: [ { id: 9, name: 'Spunky' }, { id: 10, name: 'Dunker' } ]
   },
   {
-    field: :name,
-    header: 'First Name',
-    to_csv: %i[name first],
-    to_object: ->(o) { { first: o['First Name'] } }
-  },
-  { field: :demo,
-    header: 'Date of Birth',
-    to_csv: %i[demo dob],
-    to_object: ->(o) { { dob: o['Date of Birth'] } }
+    id: 2,
+    name:     { first: 'Nick' },
+    demo:     { dob: '1921-09-03' },
+    contact:  { phone: '444-444-4444' },
+    children: [ { id: 11, name: 'Bonzi' }, { id: 12, name: 'Buddy' } ]
   },
-  { field: :contact,
-    header: 'Phone #',
-    to_csv: %i[contact phone],
-    to_object: ->(o) { { phone: o['Phone #'] } }
+  {
+    id: 3,
+    name:     { first: 'Sam' },
+    demo:     { dob: '1932-12-12' },
+    contact:  { phone: '333-333-3333' }
   }
 ]
+
+columns = {
+  'ID #': {
+    property: :id,
+    to_object: :integer
+  },
+  'Children ID #s': {
+    property: :children,
+    to_csv: { type: :pluck_join, separator: ';', sub_property: :id },
+    to_object: { type: :pluck_split, separator: ';', sub_property: :id },
+  }
+}
+````
+
+Generating a CSV:
+
+````ruby
+csv = Bumblebee::Template.new(columns: columns).generate(objects)
 ````
 
-Executing the following:
+would output:
+
+ID # | Children ID #s
+---- | --------------
+1    | 9;10
+2    | 11;12
+
+Parsing a CSV:
 
 ````ruby
-objects = Bumblebee.parse_csv(columns, data)
+objects = Bumblebee::Template.new(columns: columns).parse(csv)
 ````
 
-Would give us the following:
+would output:
 
 ````ruby
 objects = [
   {
     id: 1,
-    name: { first: 'Matt' },
-    demo: { dob: '1901-02-03' },
-    contact: { phone: '555-555-5555' }
+    children: [ { id: 9 }, { id: 10 } ]
   },
   {
     id: 2,
-    name: { first: 'Nick' },
-    demo: { dob: '1921-09-03' },
-    contact: { phone: '444-444-4444' }
+    children: [ { id: 11 }, { id: 12 } ]
   },
   {
-    id: 3,
-    name: { first: 'Sam' },
-    demo: { dob: '1932-12-12' },
-    contact: { phone: '333-333-3333' }
+    id: 3
   }
 ]
 ````
 
-#### Further CSV Customization
-
-The two main methods:
-
-* generate_csv
-* parse_csv
+### Parsing Into Custom Classes
 
-also accept custom options that [Ruby's CSV::new](https://ruby-doc.org/stdlib-2.6/libdoc/csv/rdoc/CSV.html#method-c-new) accepts.  The only caveat is that Bumblebee needs headers for its mapping, so it overrides the header options.
-
-#### Template DSL
-
-You can choose to pass in a block for template/column specification if you would rather prefer a code-first approach over a configuration-first approach.
-
-##### Using Blocks
+Hash is the default return type when parsing a CSV.  You can change this by providing a Hash-like class:
 
 ````ruby
-csv = Bumblebee.generate_csv(objects) do |t|
-  t.column :id,    header: 'ID #',
-                   to_object: ->(o) { o['ID #'].to_i }
+objects = Bumblebee::Template.new(columns: columns, object_class: OpenStruct).parse(csv)
+````
 
-  t.column :first, header: 'First Name',
-                   to_csv: %i[name first],
-                   to_object: ->(o) { { first: o['First Name'] } }
-end
+Objects will now be an array of OpenStruct objects instead of Hash objects.
 
-objects = Bumblebee.parse_csv(data) do |t|
-  t.column :id,    header: 'ID #',
-                   to_object: ->(o) { o['ID #'].to_i }
+* Note: you must also specify this in pluck_split:
 
-  t.column :first, header: 'First Name',
-                   to_csv: %i[name first],
-                   to_object: ->(o) { { first: o['First Name'] } }
-end
+````ruby
+columns = {
+  'ID #': {
+    property: :id,
+    to_object: :integer
+  },
+  'Children ID #s': {
+    property: :children,
+    to_csv: { type: :pluck_join, separator: ';', sub_property: :id },
+    to_object: { type: :pluck_split, separator: ';', sub_property: :id, object_class: OpenStruct },
+  }
+}
 ````
 
-##### Interacting Directly With ::Bumblebee::Template
+#### Further CSV Customization
 
-You can also choose to interact/build templates directly instead of going through the top-level API:
+The two main methods:
 
-````ruby
-template = Bumblebee::Template.new(columns)
+* Template#generate
+* Template#parse
 
-# or
+also accept custom options that [Ruby's CSV::new](https://ruby-doc.org/stdlib-2.6/libdoc/csv/rdoc/CSV.html#method-c-new) accepts.  The only caveat is that Bumblebee needs headers for its mapping, so it overrides the header options.
 
-template = Bumblebee::Template.new do |t|
-  t.column :id,    header: 'ID #',
-                   to_object: ->(o) { o['ID #'].to_i }
+#### Template DSL
 
-  t.column :first, header: 'First Name',
-                   to_csv: %i[name first],
-                   to_object: ->(o) { { first: o['First Name'] } }
-end
-````
+You can choose to pass in a block for template/column specification if you would rather prefer a code-first approach over a configuration-first approach.
 
-Template class has the same top-level methods:
+##### Using Blocks
 
 ````ruby
-csv = template.generate_csv(objects)
+csv = Bumblebee::Template.new do |t|
+  t.column 'ID #',        property: :id,
+                          to_object: :integer
 
-objects = template.parse_csv(data)
+  t.column 'First Name',  property: :first,
+                          through: :name
+end.generate(objects)
+
+objects = Bumblebee::Template.new do |t|
+  t.column 'ID #',        property: :id,
+                          to_object: :integer
+
+  t.column 'First Name',  property: :first,
+                          through: :name
+end.parse(data)
 ````
 
 ##### Subclassing ::Bumblebee::Template
@@ -303,19 +335,17 @@ Another option is to subclass Template and declare your columns at the class-lev
 
 ````ruby
 class PersonTemplate < Bumblebee::Template
-  column :id,    header: 'ID #',
-                 to_object: ->(o) { o['ID #'].to_i }
+  column 'ID #',        property: :id,
+                        to_object: :integer
 
-  column :first, header: 'First Name',
-                 to_csv: %i[name first],
-                 to_object: ->(o) { { first: o['First Name'] } }
+  column 'First Name',  property: :first,
+                        through: :name,
+                        to_object: :pluck_split
 end
 
-# Usage
-
 template  = PersonTemplate.new
-csv       = template.generate_csv(objects)
-objects   = template.parse_csv(data)
+csv       = template.generate(objects)
+objects   = template.parse(data)
 ````
 
 ##### Column Precedence
@@ -330,18 +360,22 @@ To illustrate all three:
 
 ````ruby
 class PersonTemplate < Bumblebee::Template # first
-  column :id,    header: 'ID #',
-                 to_object: ->(o) { o['ID #'].to_i }
+  column 'ID #',        property: :id,
+                        to_object: :integer
 
-  column :first, header: 'First Name',
-                 to_csv: %i[name first],
-                 to_object: ->(o) { { first: o['First Name'] } }
+  column 'First Name',  property: :first,
+                        through: :name,
+                        to_object: :pluck_split
 end
 
-# Usage
+columns = {
+  'Middle Name': {
+    property: :middle
+  }
+}
 
-template  = PersonTemplate.new({ field: :middle, header: 'Middle Name' }) do |t| # second
-  t.column :last, header: 'Last Name' # third
+template  = PersonTemplate.new(columns: columns) do |t| # second
+  t.column 'Last Name', property: :last # third
 end
 
 ````