hashematics 1.0.0

data/lib/hashematics/group.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 Hashematics
+  # A group is a node in a tree structure connected to other groups through the children
+  # attribute.  A group essentially represents an object within the object graph and its:
+  # 1. Category (index) for the parent to use as a lookup
+  # 2. Type that describes the object properties, field mapping, etc.
+  class Group
+    attr_reader :category, :name, :type
+
+    def initialize(category:, children:, name:, type:)
+      @category         = category
+      @child_dictionary = Dictionary.new.add(children, &:name)
+      @name             = name
+      @type             = type
+
+      freeze
+    end
+
+    def add(record)
+      category.add(record)
+
+      child_dictionary.each { |c| c.add(record) }
+
+      self
+    end
+
+    def children
+      child_dictionary.map(&:name)
+    end
+
+    def visit(parent_record = nil)
+      category.records(parent_record).map do |record|
+        Visitor.new(group: self, record: record)
+      end
+    end
+
+    def visit_children(name, parent_record = nil)
+      child_group(name)&.visit(parent_record) || []
+    end
+
+    private
+
+    attr_reader :child_dictionary
+
+    def child_group(group_name)
+      child_dictionary.get(group_name)
+    end
+  end
+end

data/lib/hashematics/hashematics.rb

@@ -0,0 +1,36 @@
+# 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 'digest'
+require 'forwardable'
+require 'ostruct'
+
+require_relative 'category'
+require_relative 'configuration'
+require_relative 'dictionary'
+require_relative 'graph'
+require_relative 'group'
+require_relative 'key'
+require_relative 'id'
+require_relative 'object_interface'
+require_relative 'record'
+require_relative 'record_set'
+require_relative 'type'
+require_relative 'visitor'
+
+# Top-level API syntactic sugar that holds the common library use(s).
+module Hashematics
+  class << self
+    def graph(config: {}, rows: [])
+      groups = ::Hashematics::Configuration.new(config).groups
+
+      ::Hashematics::Graph.new(groups).add(rows)
+    end
+  end
+end

data/lib/hashematics/id.rb

@@ -0,0 +1,29 @@
+# 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
+  # An ID is just like a Key except its value is digested (hashed).  The main rationale for this
+  # is ID's also contains user data, which could be unbound data, which could potentially
+  # consume lots of memory.  To limit this, we digest it.
+  class Id < Key
+    class << self
+      # This method is class-level to expose the underlying hashing algorithm used.
+      def digest(val = '')
+        # MD5 was chosen for its speed, it was not chosen for security.
+        Digest::MD5.hexdigest(val)
+      end
+    end
+
+    private
+
+    def make_value
+      self.class.digest(parts.map(&:to_s).join(SEPARATOR))
+    end
+  end
+end

data/lib/hashematics/key.rb

@@ -0,0 +1,76 @@
+# 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 Key is a unique identifier and can be used for hash keys, comparison, etc.
+  # Essentially it is a joined and hashed list of strings.
+  class Key
+    extend Forwardable
+
+    class << self
+      # This class-level method allows for the caching/memoization of Key objects already
+      # allocated.  Since Key objects will have such a high instantiation count with
+      # the potential of a lof of re-use, it makes sense to try to be a bit more
+      # memory-optimized here.
+      def get(parts = [])
+        return parts if parts.is_a?(self)
+
+        keys[parts] ||= new(parts)
+      end
+      alias default get
+
+      private
+
+      def keys
+        @keys ||= {}
+      end
+    end
+
+    SEPARATOR = '::'
+
+    private_constant :SEPARATOR
+
+    def_delegators :parts, :each_with_object, :map, :any?
+
+    attr_reader :parts, :value
+
+    def initialize(parts = [])
+      @parts = Array(parts)
+      @value = make_value
+
+      freeze
+    end
+
+    # We can compare a Key object to a non-Key object since its constructor is rather pliable.
+    # This means we can do things like this:
+    # - Key.make(['id', :name]) == ['id', 'name']
+    # - Key.make(:id) == 'id'
+    # - Key.make(['id']) == :id
+    # Those are all equivalent and should return true.
+    def eql?(other)
+      return eql?(self.class.get(other)) unless other.is_a?(self.class)
+
+      value == other.value
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+
+    def hash
+      value.hash
+    end
+
+    private
+
+    def make_value
+      parts.map(&:to_s).join(SEPARATOR)
+    end
+  end
+end

data/lib/hashematics/object_interface.rb

@@ -0,0 +1,35 @@
+# 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
+  # ObjectInterface allows us to interact with external objects in a more standardized manner.
+  # For example: configuration and objects passed into the module can be a little more liberal
+  # in their specific types and key types.
+  class ObjectInterface
+    class << self
+      def get(object, key)
+        if object.is_a?(Hash)
+          indifferent_hash_get(object, key)
+        elsif object.respond_to?(key)
+          object.send(key)
+        end
+      end
+
+      private
+
+      def indifferent_hash_get(hash, key)
+        if hash.key?(key.to_s)
+          hash[key.to_s]
+        elsif hash.key?(key.to_s.to_sym)
+          hash[key.to_s.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/hashematics/record.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.
+#
+
+module Hashematics
+  # A Record object is composed of an inner object (most likely a hash) and provides extra
+  # methods for the library.
+  class Record
+    extend Forwardable
+
+    def_delegators :data, :keys, :hash
+
+    attr_reader :data
+
+    def initialize(data = {})
+      @data = data
+
+      freeze
+    end
+
+    def id?(key)
+      Key.get(key).any? { |p| data[p].to_s.length.positive? }
+    end
+
+    def id(key)
+      Id.get(id_parts(key))
+    end
+
+    def [](key)
+      ObjectInterface.get(data, key)
+    end
+
+    # This should allow for Record objects to be compared to:
+    # - Other Record objects
+    # - Other data payload objects (most likely Hash objects)
+    def eql?(other)
+      return eql?(self.class.new(other)) unless other.is_a?(self.class)
+
+      data == other.data
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+
+    private
+
+    def id_parts(key)
+      Key.get(key).each_with_object([]) do |p, arr|
+        arr << p
+        arr << data[p]
+      end
+    end
+  end
+end

data/lib/hashematics/record_set.rb

@@ -0,0 +1,29 @@
+# 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 RecordSet creates Records and maintains a master list of Records.
+  class RecordSet
+    attr_reader :records
+
+    def initialize
+      @records = []
+
+      freeze
+    end
+
+    def rows
+      records.map(&:data)
+    end
+
+    def add(object)
+      Record.new(object).tap { |r| records << r }
+    end
+  end
+end

data/lib/hashematics/type.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 Type defines an object.
+  class Type
+    class << self
+      def null_type
+        @null_type ||= new
+      end
+    end
+
+    HASH_VALUE = 'hash'
+    OPEN_STRUCT_VALUE = 'open_struct'
+
+    attr_reader :name, :object_class, :properties
+
+    def initialize(name: '', properties: nil, object_class: nil)
+      @name         = name
+      @properties   = make_properties(properties)
+      @object_class = object_class || HASH_VALUE
+
+      freeze
+    end
+
+    def convert(object, child_hash = {})
+      make_object(to_hash(object).merge(child_hash))
+    end
+
+    private
+
+    def to_hash(object)
+      (properties || default_properties(object)).map do |property, key|
+        [property, ObjectInterface.get(object, key)]
+      end.to_h
+    end
+
+    def default_properties(object)
+      if object.respond_to?(:keys)
+        make_properties(object.keys)
+      else
+        []
+      end
+    end
+
+    def make_object(hash)
+      if object_class.to_s == HASH_VALUE
+        hash
+      elsif object_class.to_s == OPEN_STRUCT_VALUE
+        OpenStruct.new(hash)
+      elsif object_class.is_a?(Proc)
+        object_class.call(hash)
+      else
+        object_class.new(hash)
+      end
+    end
+
+    def make_properties(val)
+      if val.is_a?(Array) || val.is_a?(String) || val.is_a?(Symbol)
+        Array(val).map { |v| [v, v] }.to_h
+      else
+        val
+      end
+    end
+  end
+end

data/lib/hashematics/version.rb

@@ -0,0 +1,12 @@
+# 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
+  VERSION = '1.0.0'
+end

data/lib/hashematics/visitor.rb

@@ -0,0 +1,50 @@
+# 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 Visitor is a Record found in the context of a Group.  When traversing the object
+  # graph (group tree), it will provide these Visitor objects instead of Record objects
+  # that allows you to view the Record in the context of the graph, while a Record is more of just
+  # the raw payload provided by the initial flat data set.
+  class Visitor
+    extend Forwardable
+
+    def_delegators :group, :children, :type
+
+    attr_reader :group, :record
+
+    def initialize(group:, record:)
+      @group  = group
+      @record = record
+
+      freeze
+    end
+
+    def data(include_children = false)
+      child_hash = include_children ? make_child_hash : {}
+
+      type.convert(record.data, child_hash)
+    end
+
+    def visit(name)
+      group.visit_children(name, record)
+    end
+
+    private
+
+    def make_child_hash
+      children.map do |name|
+        [
+          name,
+          visit(name).map { |v| v.data(true) }
+        ]
+      end.to_h
+    end
+  end
+end