bumblebee 2.1.0 → 3.0.0

data/bin/console

@@ -7,9 +7,5 @@ require 'bumblebee'
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start
+require 'pry'
+Pry.start

data/lib/bumblebee/bumblebee.rb

@@ -7,68 +7,22 @@
 # LICENSE file in the root directory of this source tree.
 #
 
+require 'bigdecimal'
 require 'csv'
-require 'acts_as_hashable'
-require 'ostruct'
-
+require 'date'
+require 'forwardable'
+
+# Monkey-patching core libaries
+require_relative 'core_ext/hash'
+Hash.include ::Bumblebee::CoreExt::Hash
+
+# Load library
+require_relative 'object_interface'
+require_relative 'mutator'
+require_relative 'null_converter'
+require_relative 'converter'
+require_relative 'simple_converter'
 require_relative 'column'
+require_relative 'column_set'
+require_relative 'column_dsl'
 require_relative 'template'
-
-# The top-level module provides the two main methods for convenience.
-# You can also consume these in a more OOP way using the Template class or a more
-# procedural way using these.
-module Bumblebee
-  class << self
-    # Two signatures for consumption:
-    #
-    # ::Bumblebee.generate_csv(columns = [], objects = [], options = {})
-    #
-    # or
-    #
-    # ::Bumblebee.generate_csv(objects = [], options = {}) do |t|
-    #   t.column :id, header: 'ID #'
-    #   t.column :first, header: 'First Name'
-    # end
-    def generate_csv(*args, &block)
-      if block_given?
-        objects = args[0] || []
-        options = args[1] || {}
-      else
-        objects = args[1] || []
-        options = args[2] || {}
-      end
-
-      template(args, &block).generate_csv(objects, options)
-    end
-
-    # Two signatures for consumption:
-    #
-    # ::Bumblebee.parse_csv(columns = [], string = '', options = {})
-    #
-    # or
-    #
-    # ::Bumblebee.parse_csv(string = '', options = {}) do |t|
-    #   t.column :id, header: 'ID #'
-    #   t.column :first, header: 'First Name'
-    # end
-    def parse_csv(*args, &block)
-      if block_given?
-        string  = args[0] || ''
-        options = args[1] || {}
-      else
-        string  = args[1] || ''
-        options = args[2] || {}
-      end
-
-      template(args, &block).parse_csv(string, options)
-    end
-
-    private
-
-    def template(args, &block)
-      columns = block_given? ? [] : (args[0] || [])
-
-      ::Bumblebee::Template.new(columns, &block)
-    end
-  end
-end

data/lib/bumblebee/column.rb

@@ -8,83 +8,61 @@
 #
 
 module Bumblebee
-  # This is main piece of logic that defines a column which can go from objects to csv cell values
-  # and csv rows to objects.
+  # This is main piece of logic that defines a column which can go
+  # from objects to csv cell values and csv rows to objects.
   class Column
-    acts_as_hashable
-
-    attr_reader :field,
-                :to_object,
-                :header,
-                :to_csv
-
-    def initialize(field:, header: nil, to_csv: nil, to_object: nil)
-      raise ArgumentError, 'field is required' unless field
-
-      @field      = field
-      @header     = make_header(header || field)
-      @to_csv     = Array(to_csv || field)
-      @to_object  = Array(to_object || @header)
+    attr_reader :header,
+                :property,
+                :through,
+                :to_csv,
+                :to_object
+
+    def initialize(
+      header,
+      property: nil,
+      through: [],
+      to_csv: nil,
+      to_object: nil
+    )
+      raise ArgumentError, 'header is required' if header.to_s.empty?
+
+      @header       = header.to_s
+      @property     = property || @header
+      @through      = Array(through)
+      @to_csv       = ::Bumblebee::Mutator.new(to_csv)
+      @to_object    = ::Bumblebee::Mutator.new(to_object)
+
+      freeze
     end
 
-    # Take a object and convert to a value.
-    def object_to_csv(object)
-      val = object
-
-      # Iterate over keys until we reach a nil or the end of keys.
-      to_csv.each do |f|
-        # short-circuit out of the extract method
-        return nil unless val
+    # Extract from object and set on hash
+    def csv_set(data_object, hash)
+      value = extract(traverse(data_object), property)
 
-        val = single_extract(val, f)
-      end
-
-      val
+      to_csv.set(hash, header, value)
     end
 
-    def csv_to_object(csv_hash)
-      return nil unless csv_hash
-
-      value = csv_hash
+    def object_set(csv_object, hash)
+      pointer = build(hash)
+      value   = csv_object[header]
 
-      to_object.each do |f|
-        value = single_extract(value, f)
-      end
+      to_object.set(pointer, property, value)
 
-      hash = {}
-      hash.tap { hash[field] = value }
+      hash
     end
 
     private
 
-    # Loop through all values, contcatenating their string equivalent with an underscore.
-    # Since we allow procs, but we want deterministic headers, we will simply transform
-    # theem to _proc_.  This is not perfect and could create naming clashes, but it really
-    # should not be.  You should really leave proc's out of header and field.
-    def make_header(value)
-      Array(value).map do |v|
-        if v.is_a?(Proc)
-          'proc'
-        else
-          v.to_s
-        end
-      end.join('_')
+    def traverse(object)
+      ::Bumblebee::ObjectInterface.traverse(object, through)
+    end
+
+    def extract(object, key)
+      ::Bumblebee::ObjectInterface.get(object, key)
     end
 
-    # Take an object and attempt to extract a value from it.
-    # First, see if the key is a proc, if so, then delegate to the proc.
-    # Next, see if the object responds to the key, if so, then call it.
-    # Lastly, see if it responds to brackets, if so, then call the brackets method sending
-    # in the key.
-    # Finally if all else fails, return nil.
-    def single_extract(object, key)
-      if key.is_a?(Proc)
-        key.call(object)
-      elsif object.respond_to?(key)
-        object.send(key)
-      elsif object.respond_to?(:[])
-        object[key]
-      end
+    def build(object)
+      ::Bumblebee::ObjectInterface.build(object, through)
     end
   end
 end

data/lib/bumblebee/column_dsl.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Bumblebee
+  # Defines a class-level interace for specifying columns.
+  module ColumnDsl
+    extend Forwardable
+
+    def_delegators :column_set, :columns
+
+    def column_set
+      @column_set ||= ::Bumblebee::ColumnSet.new
+    end
+
+    def column(header, opts = {})
+      column_set.column(header, opts)
+
+      self
+    end
+
+    def all_column_sets
+      # the reverse preserves the order of inheritance to go from parent -> child
+      ancestors.reverse_each.with_object(::Bumblebee::ColumnSet.new) do |ancestor, set|
+        ancestor < ::Bumblebee::Template ? set.add(ancestor.columns) : set
+      end
+    end
+
+    def all_columns
+      all_column_sets.columns
+    end
+  end
+end

data/lib/bumblebee/column_set.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Bumblebee
+  # Maintains a list (dictionary) of columns where each header can only exist once.
+  # If columns with same header are re-added, then they are overwritten.
+  # This class also provides a factory interface through #add for adding columns
+  class ColumnSet
+    extend Forwardable
+
+    FACTORY_ADD_METHODS = [
+      [::Bumblebee::Column, :assign],
+      [Hash, :add_header_column_hash]
+    ].freeze
+
+    private_constant :FACTORY_ADD_METHODS
+
+    def_delegator :column_hash, :keys, :headers
+
+    def_delegator :column_hash, :values, :columns
+
+    def initialize(columns = nil)
+      @column_hash = {}
+
+      add(columns)
+    end
+
+    def column(header, opts = {})
+      column = ::Bumblebee::Column.new(header, opts.symbolize_keys)
+
+      column_hash[column.header] = column
+
+      self
+    end
+
+    def add(*args)
+      args.flatten.compact.each { |arg| factory_add(arg) }
+
+      self
+    end
+
+    private
+
+    attr_reader :column_hash
+
+    def assign(column)
+      column_hash[column.header] = column
+
+      self
+    end
+
+    def add_header_column_hash(hash)
+      hash.each_pair do |header, opts|
+        column = ::Bumblebee::Column.new(header, opts.symbolize_keys)
+
+        assign(column)
+      end
+
+      self
+    end
+
+    def factory_add(arg)
+      FACTORY_ADD_METHODS.each do |factory_add_method|
+        class_constant = factory_add_method.first
+        method_sym = factory_add_method.last
+
+        if arg.is_a?(class_constant)
+          send(method_sym, arg)
+          return self
+        end
+      end
+
+      # Base case, use arg as the header
+      column(arg)
+    end
+  end
+end

data/lib/bumblebee/converter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Bumblebee
+  # Base class that defines the general interface and structure for a converter class.
+  # Subclasses should use the 'visitor' pattern and imeplement a visit_* method for each of the
+  # Types.
+  class Converter
+    module Types
+      BIGDECIMAL  = :bigdecimal
+      BOOLEAN     = :boolean
+      DATE        = :date
+      INTEGER     = :integer
+      JOIN        = :join
+      FLOAT       = :float
+      FUNCTION    = :function
+      PLUCK_JOIN  = :pluck_join
+      PLUCK_SPLIT = :pluck_split
+      SPLIT       = :split
+      STRING      = :string
+    end
+    include Types
+
+    DEFAULT_DATE_FORMAT = '%Y-%m-%d'
+    DEFAULT_SEPARATOR   = ','
+    VISITOR_METHOD_PREFIX = 'process_'
+
+    private_constant :VISITOR_METHOD_PREFIX
+
+    attr_reader :function,
+                :object_class,
+                :per,
+                :sub_property,
+                :type
+
+    def initialize(arg)
+      if arg.is_a?(Proc)
+        @type         = FUNCTION
+        @function     = arg
+        @object_class = Hash
+      elsif arg.is_a?(Hash)
+        hash = arg.symbolize_keys
+        initialize_from_hash(hash)
+      else
+        @type         = make_type(arg)
+        @per          = make_converter
+        @object_class = Hash
+      end
+
+      freeze
+    end
+
+    def convert(val)
+      send("#{VISITOR_METHOD_PREFIX}#{type}", val)
+    end
+
+    private
+
+    def make_type(val)
+      Types.const_get(val.to_s.upcase.to_sym)
+    end
+
+    def initialize_from_hash(hash)
+      @type         = make_type(hash[:type])
+      @function     = hash[:function]
+      @nullable     = hash[:nullable]
+      @separator    = hash[:separator]
+      @date_format  = hash[:date_format]
+      @sub_property = hash[:sub_property]
+      @object_class = hash[:object_class] || Hash
+      @per          = make_converter(hash[:per])
+    end
+
+    def nullable
+      @nullable || false
+    end
+    alias nullable? nullable
+
+    def separator
+      @separator || DEFAULT_SEPARATOR
+    end
+
+    def date_format
+      @date_format || DEFAULT_DATE_FORMAT
+    end
+
+    def make_converter(arg = nil)
+      arg ? self.class.new(arg) : ::Bumblebee::NullConverter.new
+    end
+  end
+end

data/lib/bumblebee/core_ext/hash.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Bumblebee
+  class CoreExt
+    # Monkey-patches for the core Hash class.  These will be manually mixed in separately.
+    module Hash
+      unless method_defined?(:symbolize_keys)
+        def symbolize_keys
+          map { |k, v| [k.to_sym, v] }.to_h
+        end
+      end
+    end
+  end
+end