hashematics 1.0.0

data/bin/benchmark

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'csv'
+require 'faker'
+require 'hashematics'
+require 'pry'
+require 'benchmark'
+
+def read(name)
+  File.open(name, 'r:bom|utf-8')
+end
+
+# rubocop:disable Security/YAMLLoad
+def yaml_read(name)
+  YAML.load(read(name))
+end
+# rubocop:enable Security/YAMLLoad
+
+def csv_read(name)
+  CSV.new(read(name), headers: true).map(&:to_h)
+end
+
+def make_people_rows(num)
+  (1..num).map do |i|
+    [
+      "#{i}-#{Faker::IDNumber.invalid}",
+      Faker::Name.first_name,
+      Faker::Name.last_name,
+      Faker::Boolean.boolean,
+      Faker::Date.birthday(16, 102)
+    ]
+  end
+end
+
+def make_house_rows(num, id_prefix)
+  (1..num).map do |k|
+    [
+      "#{id_prefix}-#{k}-#{Faker::Number.between(1, 9_999_999)}",
+      Faker::Address.street_address,
+      Faker::Address.secondary_address,
+      Faker::Address.city,
+      Faker::Address.state,
+      Faker::Address.zip
+    ]
+  end
+end
+
+number_of_people    = (ARGV[0] || 1_000).to_i
+number_of_cars      = (ARGV[1] || 20).to_i
+number_of_houses    = (ARGV[2] || 20).to_i
+always_generate     = ARGV[3] == 't'
+file_name           = ARGV[4] || File.join('tmp', 'benchmark_example.csv')
+config_file_name    = ARGV[5] || File.join('spec', 'fixtures', 'config.yml')
+
+puts 'Options'
+puts '-------------------------------------'
+puts "number_of_people: #{number_of_people}"
+puts "number_of_cars:   #{number_of_cars}"
+puts "number_of_houses: #{number_of_houses}"
+puts "always_generate:  #{always_generate}"
+puts "file_name:        #{file_name}"
+puts "config_file_name: #{config_file_name}"
+puts '-------------------------------------'
+
+if always_generate || !File.exist?(file_name)
+  total_rows = number_of_people * number_of_cars * number_of_houses
+  puts "Generating benchmark file: #{file_name} with #{total_rows} rows"
+
+  headers = [
+    'ID #',
+    'First',
+    'Last',
+    'Smoker',
+    'DOB',
+    'Car ID #',
+    'Make',
+    'Model',
+    'Year',
+    'House ID #',
+    'Street 1',
+    'Street 2',
+    'City',
+    'St',
+    'Zip',
+    'Plate ID #',
+    'Plate Number'
+  ]
+
+  people_rows = make_people_rows(number_of_people)
+
+  CSV.open(file_name, 'w') do |csv|
+    csv << headers
+
+    people_rows.each_with_index do |person_row, i|
+      house_rows = make_house_rows(number_of_houses, i)
+
+      (1..number_of_cars).each do |j|
+        car_row = [
+          "#{i}-#{j}-#{Faker::Vehicle.vin}",
+          Faker::Vehicle.make,
+          Faker::Vehicle.model,
+          Faker::Vehicle.year
+        ]
+
+        plate_row = [
+          "#{i}-#{j}-0-#{Faker::Number.between(1, 9_999_999)}",
+          Faker::Vehicle.license_plate
+        ]
+
+        house_rows.each do |house_row|
+          csv << person_row + car_row + house_row + plate_row
+        end
+      end
+    end
+  end
+
+  puts 'Benchmark file generated.'
+end
+
+puts 'Loading prerequisites'
+configuration = yaml_read(config_file_name)
+groups = ::Hashematics::Configuration.new(configuration).groups
+graph = ::Hashematics::Graph.new(groups)
+
+puts 'Loading data'
+rows = csv_read(file_name)
+
+puts "Executing benchmark for #{rows.length} rows"
+Benchmark.bm do |x|
+  x.report('ADD')   { graph.add(rows) }
+  x.report('DATA')  { graph.data('people') }
+end

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'hashematics'
+
+# 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.
+
+require 'pry'
+Pry.start

data/hashematics.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require './lib/hashematics/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'hashematics'
+  s.version     = Hashematics::VERSION
+  s.summary     = 'Configurable Data Shaper'
+
+  s.description = <<-DESCRIPTION
+    Hashematics is a configuration-based object graphing tool which can turn a flat, single dimensional dataset into a structure of deeply nested objects.
+  DESCRIPTION
+
+  s.authors     = ['Matthew Ruggio']
+  s.email       = ['mruggio@bluemarblepayroll.com']
+  s.files       = `git ls-files`.split("\n")
+  s.test_files  = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.homepage    = 'https://github.com/bluemarblepayroll/hashematics'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 2.3.8'
+
+  s.add_development_dependency('faker', '~>1')
+  s.add_development_dependency('guard-rspec', '~>4.7')
+  s.add_development_dependency('pdf-inspector', '~>1')
+  s.add_development_dependency('pry', '~>0')
+  s.add_development_dependency('rspec', '~> 3.8')
+  s.add_development_dependency('rubocop', '~>0.63.1')
+  s.add_development_dependency('simplecov', '~>0.16.1')
+  s.add_development_dependency('simplecov-console', '~>0.4.2')
+end

data/lib/hashematics.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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.
+#
+
+require_relative 'hashematics/hashematics'

data/lib/hashematics/category.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 Hashematics
+  # A Category is an index of objects.  It holds two things:
+  # 1. list of top-level objects
+  # 2. list of top-level objects cross-referenced by a parent.
+  class Category
+    attr_reader :id_key, :include_blank, :parent_key
+
+    def initialize(id_key:, include_blank: false, parent_key: nil)
+      raise ArgumentError, 'id_key is required' unless id_key
+
+      @default_parent_id  = Id.default
+      @id_key             = Key.get(id_key)
+      @include_blank      = include_blank || false
+      @lookup             = {}
+      @parent_key         = Key.get(parent_key)
+
+      freeze
+    end
+
+    def records(parent_record = nil)
+      parent_id = parent_record&.id(parent_key) || default_parent_id
+
+      get(parent_id).values
+    end
+
+    def add(record)
+      return self if skip_record?(record)
+
+      set(
+        record.id(parent_key),
+        record.id(id_key),
+        record
+      )
+    end
+
+    private
+
+    attr_reader :default_parent_id, :lookup
+
+    def skip_record?(record)
+      !include_record?(record)
+    end
+
+    def include_record?(record)
+      include_blank || record.id?(id_key)
+    end
+
+    def get(parent_id)
+      lookup[parent_id] ||= {}
+    end
+
+    def set(parent_id, id, record)
+      get(parent_id)[id] = record
+
+      self
+    end
+  end
+end

data/lib/hashematics/configuration.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 Hashematics
+  # This class understands how to take in a hash of options and construct an array of groups.
+  # See test fixtures for examples.
+  class Configuration
+    module Keys
+      BY                = :by
+      GROUPS            = :groups
+      INCLUDE_BLANK     = :include_blank
+      OBJECT_CLASS      = :object_class
+      PROPERTIES        = :properties
+      TYPE              = :type
+      TYPES             = :types
+    end
+    include Keys
+
+    attr_reader :groups
+
+    def initialize(config = {})
+      types = build_types(config_value(config, TYPES))
+      @type_dictionary = Dictionary.new(Type.null_type).add(types, &:name)
+
+      @groups = build_groups(config_value(config, GROUPS))
+
+      freeze
+    end
+
+    private
+
+    attr_reader :type_dictionary
+
+    def build_types(type_config = {})
+      (type_config || {}).map do |name, options|
+        properties = config_value(options, PROPERTIES)
+        object_class = config_value(options, OBJECT_CLASS)
+
+        Type.new(name: name, properties: properties, object_class: object_class)
+      end
+    end
+
+    def build_groups(group_config = {}, parent_key_parts = [])
+      (group_config || {}).map do |name, options|
+        id_key_parts = make_id_key_parts(options)
+
+        category = Category.new(
+          id_key: id_key_parts,
+          include_blank: include_blank?(options),
+          parent_key: parent_key_parts
+        )
+
+        Group.new(
+          category: category,
+          children: make_children(options, parent_key_parts + id_key_parts),
+          name: name,
+          type: make_type(options)
+        )
+      end
+    end
+
+    def include_blank?(options)
+      options.is_a?(Hash) ? config_value(options, INCLUDE_BLANK) : false
+    end
+
+    def make_id_key_parts(options)
+      options.is_a?(Hash) ? Array(config_value(options, BY)) : Array(options)
+    end
+
+    def make_children(options, parent_key_parts)
+      options.is_a?(Hash) ? build_groups(config_value(options, GROUPS), parent_key_parts) : []
+    end
+
+    def make_type(options)
+      type_name = options.is_a?(Hash) ? config_value(options, TYPE) : nil
+
+      type_dictionary.get(type_name)
+    end
+
+    def config_value(config, key)
+      ObjectInterface.get(config, key)
+    end
+  end
+end

data/lib/hashematics/dictionary.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 Hashematics
+  # A Dictionary is an array with a constant O(1) lookup time.  It is basically a cross of a hash
+  # and an array.  We could easily use a hashes everywhere, but explicitly coding our intentions
+  # of this common intra-library hash use is a nice way to communicate intentions while minimizing
+  # duplication.
+  class Dictionary
+    extend Forwardable
+
+    attr_reader :default_value
+
+    def_delegators :lookup, :keys
+
+    def_delegator :lookup, :values, :all
+
+    def initialize(default_value = nil)
+      @default_value = default_value
+      @lookup = {}
+
+      freeze
+    end
+
+    def add(enumerable)
+      raise ArgumentError, 'block must be given for key resolution' unless block_given?
+
+      enumerable.each do |entry|
+        key = yield entry
+        set(key, entry)
+      end
+
+      self
+    end
+
+    def set(key, object)
+      lookup[key.to_s] = object
+
+      self
+    end
+
+    def get(key)
+      exist?(key) ? lookup[key.to_s] : default_value
+    end
+
+    def exist?(key)
+      lookup.key?(key.to_s)
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      all.each { |o| yield o }
+    end
+
+    def map(&block)
+      return enum_for(:map) unless block_given?
+
+      all.map(&block)
+    end
+
+    private
+
+    attr_reader :lookup
+  end
+end

data/lib/hashematics/graph.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-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 Hashematics
+  # Graph serves as the main point of entry for this system.
+  # Basic use:
+  # 1. Initialize a Graph by passing in an array of groups (tree structures)
+  # 2. Feed in objects into the graph using the #add method
+  # 3. Use the #groups, #records, and #objects methods to interact with the generated object graph.
+  class Graph
+    extend Forwardable
+
+    attr_reader :group_dictionary, :record_set
+
+    def_delegators :record_set, :rows
+
+    def initialize(groups = [])
+      @group_dictionary = Dictionary.new.add(groups, &:name)
+      @record_set       = RecordSet.new
+
+      freeze
+    end
+
+    def add(enumerable)
+      enumerable.each { |object| add_one(object) }
+
+      self
+    end
+
+    def children
+      group_dictionary.map(&:name)
+    end
+
+    def visit(name)
+      group(name)&.visit || []
+    end
+
+    def data(name)
+      visit(name).map { |v| v.data(true) }
+    end
+
+    private
+
+    def group(name)
+      group_dictionary.get(name)
+    end
+
+    def add_one(object)
+      record = record_set.add(object)
+
+      group_dictionary.each do |group|
+        group.add(record)
+      end
+    end
+  end
+end