hash_math 0.0.1 → 1.2.0

data/lib/hash_math.rb

@@ -7,6 +7,15 @@
 # LICENSE file in the root directory of this source tree.
 #
 
+require 'acts_as_hashable'
+
+require_relative 'hash_math/mapper'
+require_relative 'hash_math/matrix'
+require_relative 'hash_math/record'
+require_relative 'hash_math/table'
+require_relative 'hash_math/unpivot'
+
 # Top-level namespace
 module HashMath
+  class KeyOutOfBoundsError < StandardError; end
 end

data/lib/hash_math/mapper.rb

@@ -0,0 +1,65 @@
+# 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 'mapper/mapping'
+
+module HashMath
+  # A Mapper instance can hold multiple constant-time object lookups and then is able to map
+  # a hash to its corresponding lookup values.  It's main use-case is to fill in missing or
+  # update existing key-value pairs with its corresponding relationships.
+  class Mapper
+    attr_reader :mappings_by_name
+
+    # Accepts an array of Mapping instances of hashes containing the Mapping instance attributes
+    # to initialize.
+    def initialize(mappings = [])
+      mappings          = Mapping.array(mappings)
+      @mappings_by_name = pivot_by_name(mappings)
+
+      freeze
+    end
+
+    # Add an enumerable list of lookup records to this instance's lookup dataset.
+    # Raises ArgumentError if name is blank.
+    def add_each(name, objects)
+      raise ArgumentError, 'name is required' if name.to_s.empty?
+
+      tap { objects.each { |o| add(name, o) } }
+    end
+
+    # Add a lookup record to this instance's lookup dataset.
+    # Raises ArgumentError if name is blank.
+    def add(name, object)
+      raise ArgumentError, 'name is required' if name.to_s.empty?
+
+      tap { mappings_by_name.fetch(name.to_s).add(object) }
+    end
+
+    # Returns a new hash with the added/updated key-value pairs.  Note that this only does a
+    # shallow copy using Hash#merge.
+    def map(hash)
+      map!({}.merge(hash || {}))
+    end
+
+    # Mutates the inpuuted hash with the added/updated key-value pairs.
+    def map!(hash)
+      mappings_by_name.values.each_with_object(hash) do |mapping, _memo|
+        mapping.map!(hash)
+      end
+    end
+
+    private
+
+    def pivot_by_name(array)
+      array.each_with_object({}) do |object, memo|
+        memo[object.name.to_s] = object
+      end
+    end
+  end
+end

data/lib/hash_math/mapper/lookup.rb

@@ -0,0 +1,56 @@
+# 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 HashMath
+  class Mapper
+    # A Lookup instance maintains its own list of objects using its own key extraction method,
+    # called 'by' which will be used to extract the key's value for the lookup.
+    # If 'by' is a Proc then it will be called when extracting a new lookup record's lookup value.
+    # If it is anything other than a Proc and it will call #[] on the object.
+    class Lookup
+      acts_as_hashable
+
+      attr_reader :name, :by
+
+      def initialize(name:, by:)
+        @name    = name
+        @by      = by
+        @objects = {}
+
+        freeze
+      end
+
+      def add_each(array) # :nodoc:
+        tap { array.each { |o| add(o) } }
+      end
+
+      def add(object) # :nodoc:
+        id = proc_or_brackets(object, by)
+
+        objects[id] = object
+
+        self
+      end
+
+      def get(value) # :nodoc:
+        objects[value]
+      end
+
+      private
+
+      attr_reader :objects
+
+      def proc_or_brackets(object, thing)
+        return nil unless object
+
+        thing.is_a?(Proc) ? thing.call(object) : object[thing]
+      end
+    end
+  end
+end

data/lib/hash_math/mapper/mapping.rb

@@ -0,0 +1,77 @@
+# 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 'lookup'
+
+module HashMath
+  class Mapper
+    # Represents one complete configuration for mapping one key-value pair to one lookup.
+    #
+    # Example:
+    # ----------------------------------------------------------------------------------------------
+    # mapping = Mapper.make(
+    #   lookup: { name: :patient_statuses, by: :name },
+    #   value: :status,
+    #   set: :patient_status_id,
+    #   with: :id
+    # ).add(id: 1, name: 'active').add(id: 2, name: 'inactive')
+    #
+    # patient        = { id: 1, code: 'active' }
+    # mapped_patient = mapping.map!(patient)
+    # ----------------------------------------------------------------------------------------------
+    #
+    # mapped_patient now equals: { id: 1, code: 'active', patient_status_id: 1 }
+    class Mapping
+      extend Forwardable
+      acts_as_hashable
+
+      attr_reader :value, :set, :with, :lookup
+
+      def_delegators :lookup, :name, :by
+
+      # lookup: can either be a Mapper#Lookup instance or a hash with the attributes to initialize
+      # for a Mapper#Lookup instance.
+      # value: the key to use to get the 'value' from the object to lookup.
+      # set: the key to set once the lookup record is identified.
+      # with: the key use, on the lookup, to get the new value.
+      def initialize(lookup:, value:, set:, with:)
+        @lookup = Lookup.make(lookup)
+        @value  = value
+        @set    = set
+        @with   = with
+
+        freeze
+      end
+
+      def add_each(array) # :nodoc:
+        tap { lookup.add_each(array) }
+      end
+
+      def add(object) # :nodoc:
+        tap { lookup.add(object) }
+      end
+
+      def map!(hash) # :nodoc:
+        lookup_value  = proc_or_brackets(hash, value)
+        lookup_object = lookup.get(lookup_value)
+        hash[set]     = proc_or_brackets(lookup_object, with)
+
+        self
+      end
+
+      private
+
+      def proc_or_brackets(object, thing)
+        return nil unless object
+
+        thing.is_a?(Proc) ? thing.call(object) : object[thing]
+      end
+    end
+  end
+end

data/lib/hash_math/matrix.rb

@@ -0,0 +1,60 @@
+# 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 'matrix/key_value_pair'
+
+module HashMath
+  # A Matrix allows you to build up a hash of key and values, then it will generate the
+  # product of all values.
+  class Matrix
+    extend Forwardable
+    include Enumerable
+
+    def_delegators :pair_products, :each
+
+    def initialize
+      @pairs_by_key = {}
+
+      freeze
+    end
+
+    def add_each(key, vals)
+      tap { kvp(key).add_each(vals) }
+    end
+
+    def add(key, val)
+      tap { kvp(key).add(val) }
+    end
+
+    private
+
+    attr_reader :pairs_by_key
+
+    def kvp(key)
+      pairs_by_key[key] ||= KeyValuePair.new(key)
+    end
+
+    def make_pair_groups
+      pairs_by_key.values.map(&:pairs)
+    end
+
+    def pair_products
+      pair_groups = make_pair_groups
+
+      products = pair_groups.inject(pair_groups.shift) { |memo, f| memo.product(f) }
+                            &.map { |f| f.is_a?(KeyValuePair::Pair) ? [f] : f.flatten } || []
+
+      products.map { |pairs| recombine(pairs) }
+    end
+
+    def recombine(pairs)
+      pairs.each_with_object({}) { |p, memo| memo[p.key] = p.value }
+    end
+  end
+end

data/lib/hash_math/matrix/key_value_pair.rb

@@ -0,0 +1,38 @@
+# 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 HashMath
+  class Matrix
+    # A hash-like structure that allows you to gradually build up keys.
+    class KeyValuePair
+      Pair = Struct.new(:key, :value)
+
+      attr_reader :key, :value
+
+      def initialize(key)
+        @key    = key
+        @value  = Set.new
+
+        freeze
+      end
+
+      def add_each(vals)
+        tap { vals.each { |val| add(val) } }
+      end
+
+      def add(val)
+        tap { value << val }
+      end
+
+      def pairs
+        value.map { |value| Pair.new(key, value) }
+      end
+    end
+  end
+end

data/lib/hash_math/record.rb

@@ -0,0 +1,57 @@
+# 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 HashMath
+  # A Record serves as a prototype for a Hash.  It will allow the output of hashes
+  # conforming to a strict (#make!) or non-strict (#make) shape.
+  class Record
+    extend Forwardable
+
+    def_delegators :prototype, :key?, :keys
+
+    def initialize(keys = [], base_value = nil)
+      @prototype = keys.map { |key| [key, base_value] }.to_h
+
+      freeze
+    end
+
+    def make!(hash = {})
+      make(hash, true)
+    end
+
+    def make(hash = {}, bound = false)
+      hash.each_with_object(shallow_copy_prototype) do |(key, value), memo|
+        next unless assert_key_in_bounds(key, bound)
+
+        memo[key] = value
+      end
+    end
+
+    private
+
+    attr_reader :prototype
+
+    # raise error if key is not in key set and bound is true
+    # return true if key is in key set and bound is false
+    # return false if key is not in key set and bound is false
+    def assert_key_in_bounds(key, bound)
+      raise KeyOutOfBoundsError, "[#{key}] for: #{keys}" if not_key?(key) && bound
+
+      key?(key)
+    end
+
+    def not_key?(key)
+      !key?(key)
+    end
+
+    def shallow_copy_prototype
+      {}.merge(prototype)
+    end
+  end
+end

data/lib/hash_math/table.rb

@@ -0,0 +1,61 @@
+# 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 HashMath
+  # The main data structure for a virtual table that can be treated as a key-value builder.
+  # Basically, it is a hash with a default 'prototype' assigned to it, which serves as the
+  # base record.  Then, #add is called over and over passing in row_id, field_id, and value,
+  # which gives it enough information to pinpoint where to insert the data (memory-wise.)
+  # Imagine a two-dimensional table where X is the field_id axis and row is the Y axis.
+  # Since it is essentially backed by a hash, the row_id and field_id can be anything that
+  # implements #hash, #eql? and #== properly.
+  class Table
+    extend Forwardable
+    include Enumerable
+
+    Row = Struct.new(:row_id, :fields)
+
+    attr_reader :lookup, :record
+
+    def_delegators :record, :keys, :key?
+
+    def initialize(record)
+      raise ArgumentError, 'record is required' unless record
+
+      @lookup = {}
+      @record = record
+
+      freeze
+    end
+
+    def add(row_id, field_id, value)
+      raise KeyOutOfBoundsError, "field_id: #{field_id} not allowed." unless key?(field_id)
+
+      tap { set(row_id, field_id, value) }
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      lookup.map do |row_id, fields|
+        Row.new(row_id, record.make!(fields)).tap { |row| yield(row) }
+      end
+    end
+
+    private
+
+    def row(row_id)
+      lookup[row_id] ||= {}
+    end
+
+    def set(row_id, field_id, value)
+      row(row_id)[field_id] = value
+    end
+  end
+end

data/lib/hash_math/unpivot.rb

@@ -0,0 +1,54 @@
+# 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 'unpivot/pivot_set'
+
+module HashMath
+  # This class has the ability to extrapolate one hash (row) into multiple hashes (rows) while
+  # unpivoting specific keys into key-value pairs.
+  class Unpivot
+    extend Forwardable
+
+    attr_reader :pivot_set
+
+    def_delegators :pivot_set, :add
+
+    def initialize(pivot_set = PivotSet.new)
+      @pivot_set = PivotSet.make(pivot_set, nullable: false)
+
+      freeze
+    end
+
+    # The main method for this class that performs the un-pivoting and hash expansion.
+    # Pass in a hash and it will return an array of hashes.
+    def expand(hash)
+      return [hash] unless pivot_set.any?
+
+      all_combinations = pivot_set.expand(hash)
+
+      products = all_combinations.inject(all_combinations.shift) do |memo, array|
+        memo.product(array)
+      end
+
+      recombine(products)
+    end
+
+    private
+
+    def recombine(products)
+      products.map do |pairs|
+        if pairs.is_a?(Array)
+          pairs.inject(pairs.shift) { |memo, p| memo.merge(p) }
+        else
+          pairs
+        end
+      end
+    end
+  end
+end