tree_branch 1.0.0

data/lib/tree_branch/processor.rb

@@ -0,0 +1,47 @@
+# 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 TreeBranch
+  # This class understands how to take a tree, digest it given a context, set of comparators, and a
+  # block, then returns a new tree structure.
+  class Processor
+    def process(node, context: nil, comparators: [], &block)
+      return nil if at_least_one_comparator_returns_false?(node.data, context, comparators)
+
+      valid_children = process_children(node.children, context, comparators, &block)
+
+      if block_given?
+        yield(node.data, valid_children, context)
+      else
+        ::TreeBranch::Node.new(node.data)
+                          .add(valid_children)
+      end
+    end
+
+    private
+
+    def at_least_one_comparator_returns_false?(data, context, comparators)
+      Array(comparators).any? { |c| execute_comparator(c, data, context) == false }
+    end
+
+    def process_children(children, context, comparators, &block)
+      children.map do |node|
+        process(node, context: context, comparators: comparators, &block)
+      end.compact
+    end
+
+    def execute_comparator(comparator, data, context)
+      if comparator.is_a?(Proc)
+        comparator.call(OpenStruct.new(data), OpenStruct.new(context))
+      else
+        comparator.new(data: data, context: context).valid?
+      end
+    end
+  end
+end

data/lib/tree_branch/simple_node.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 TreeBranch
+  # A basic subclass of Node that makes the data element a deterministic and comparable OpenStruct
+  # object.
+  class SimpleNode < Node
+    acts_as_hashable
+
+    def initialize(data: {}, children: [])
+      @data     = OpenStruct.new(data)
+      @children = self.class.array(children)
+    end
+  end
+end

data/lib/tree_branch/tree_branch.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.
+#
+
+require 'acts_as_hashable'
+require 'ostruct'
+
+require_relative 'comparator'
+require_relative 'node'
+require_relative 'simple_node'
+require_relative 'processor'
+
+# Top-level namespace of the library.  The methods contained here should be considered the
+# main public API.
+module TreeBranch
+  class << self
+    def process(node: {}, context: {}, comparators: [], &block)
+      ::TreeBranch::Processor.new
+                             .process(
+                               normalize_node(node),
+                               context: context,
+                               comparators: comparators,
+                               &block
+                             )
+    end
+
+    private
+
+    def normalize_node(node)
+      node.is_a?(::TreeBranch::Node) ? node : ::TreeBranch::SimpleNode.make(node, nullable: false)
+    end
+  end
+end

data/lib/tree_branch/version.rb

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

data/lib/tree_branch.rb

@@ -0,0 +1,10 @@
+# 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.
+#
+
+require_relative 'tree_branch/tree_branch'

data/spec/fixtures/born_after1915.yml

@@ -0,0 +1,13 @@
+:data:
+  name: Matt
+  :dob: '1920-01-04'
+  state: IL
+:children:
+- :data:
+    :name: Nick
+    dob: '1930-04-04'
+    :state: WI
+- :data:
+    :name: Sam
+    dob: '1940-09-12'
+    :state: AK

data/spec/fixtures/born_after1915_with_m_or_s.yml

@@ -0,0 +1,9 @@
+:data:
+  name: Matt
+  :dob: '1920-01-04'
+  state: IL
+:children:
+- :data:
+    :name: Sam
+    dob: '1940-09-12'
+    :state: AK

data/spec/fixtures/node.yml

@@ -0,0 +1,18 @@
+:data:
+  name: Matt
+  :dob: '1920-01-04'
+  state: IL
+:children:
+- :data:
+    :name: Nick
+    dob: '1930-04-04'
+    :state: WI
+  :children:
+  - :data:
+      name: Katie
+      :dob: '1820-02-05'
+      :state: 'CA'
+- :data:
+    :name: Sam
+    dob: '1940-09-12'
+    :state: AK

data/spec/fixtures/node_with_injected.yml

@@ -0,0 +1,22 @@
+:data:
+  name: Matt
+  :dob: '1920-01-04'
+  state: IL
+  injected: Mattcakes!!
+:children:
+- :data:
+    :name: Nick
+    dob: '1930-04-04'
+    :state: WI
+    injected: Nickcakes!!
+  :children:
+  - :data:
+      name: Katie
+      :dob: '1820-02-05'
+      :state: CA
+      injected: Katiecakes!!
+- :data:
+    :name: Sam
+    dob: '1940-09-12'
+    :state: AK
+    injected: Samcakes!!

data/spec/spec_helper.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.
+#
+
+require 'date'
+require 'yaml'
+
+require './lib/tree_branch'
+
+def fixture_path(filename)
+  File.join('spec', 'fixtures', filename)
+end
+
+def fixture(filename)
+  YAML.load_file(fixture_path(filename))
+end

data/spec/tree_branch/comparator_spec.rb

@@ -0,0 +1,47 @@
+# 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.
+#
+
+require './spec/spec_helper'
+
+describe ::TreeBranch::Comparator do
+  let(:data_hash) do
+    {
+      'name': 'Matt',
+      dob: '1920-01-04',
+      'state' => 'IL'
+    }
+  end
+
+  let(:context_hash) do
+    {
+      letters: %w[M S]
+    }
+  end
+
+  it 'should initialize from hashes correctly' do
+    comparator = ::TreeBranch::Comparator.new(data: data_hash, context: context_hash)
+
+    expect(comparator.data['name']).to      eq(data_hash['name'])
+    expect(comparator.data[:dob]).to        eq(data_hash[:dob])
+    expect(comparator.data['state']).to     eq(data_hash['state'])
+    expect(comparator.context[:letters]).to eq(context_hash[:letters])
+  end
+
+  it 'should initialize from OpenStruct objects correctly' do
+    data = OpenStruct.new(data_hash)
+    context = OpenStruct.new(context_hash)
+
+    comparator = ::TreeBranch::Comparator.new(data: data, context: context)
+
+    expect(comparator.data.name).to       eq(data.name)
+    expect(comparator.data.dob).to        eq(data.dob)
+    expect(comparator.data.state).to      eq(data.state)
+    expect(comparator.context.letters).to eq(context.letters)
+  end
+end

data/spec/tree_branch/node_spec.rb

@@ -0,0 +1,24 @@
+# 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.
+#
+
+require './spec/spec_helper'
+
+describe ::TreeBranch::Node do
+  let(:node_hash) { fixture('node.yml') }
+
+  let(:node) { ::TreeBranch::SimpleNode.make(node_hash) }
+
+  it 'should initialize and equality compare correctly' do
+    expected_data     = OpenStruct.new(node_hash[:data])
+    expected_children = ::TreeBranch::SimpleNode.array(node_hash[:children])
+
+    expect(node.data).to      eq(expected_data)
+    expect(node.children).to  eq(expected_children)
+  end
+end

data/spec/tree_branch/tree_branch_spec.rb

@@ -0,0 +1,394 @@
+# 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.
+#
+
+require './spec/spec_helper'
+
+describe ::TreeBranch do
+  # We will use this spec to also test ::TreeBranch::Node#process since ::TreeBranch#process
+  # fully delegates to that method.
+  describe '#process' do
+    let(:node_hash) { fixture('node.yml') }
+
+    let(:node_hash_with_injected) { fixture('node_with_injected.yml') }
+
+    let(:node) { ::TreeBranch::SimpleNode.make(node_hash) }
+
+    let(:node_with_injected) { ::TreeBranch::SimpleNode.make(node_hash_with_injected) }
+
+    let(:born_after1915_hash) { fixture('born_after1915.yml') }
+
+    let(:born_after1915) { ::TreeBranch::SimpleNode.make(born_after1915_hash) }
+
+    let(:born_after1915_starts_with_m_or_s_hash) do
+      fixture('born_after1915_with_m_or_s.yml')
+    end
+
+    let(:born_after1915_starts_with_m_or_s) do
+      ::TreeBranch::SimpleNode.make(born_after1915_starts_with_m_or_s_hash)
+    end
+
+    class BornAfter1915 < ::TreeBranch::Comparator
+      def valid?
+        Date.parse(data.dob).year > 1915
+      end
+    end
+
+    class NameStartsWith < ::TreeBranch::Comparator
+      def valid?
+        context[:letters].include?(data.name.to_s[0])
+      end
+    end
+
+    let(:name_starts_with_lambda) do
+      lambda do |data, context|
+        context.letters.include?(data.name.to_s[0])
+      end
+    end
+
+    it 'should return everything when no comparators are given' do
+      expect(::TreeBranch.process(node: node_hash)).to eq(node)
+    end
+
+    it 'should return nil when no comparators pass for top level node' do
+      # The base comparator class returns false by default
+      expect(::TreeBranch.process(node: node_hash, comparators: ::TreeBranch::Comparator)).to be nil
+    end
+
+    it 'should return valid nodes with one comparator' do
+      actual = ::TreeBranch.process(node: node_hash, comparators: BornAfter1915)
+
+      expect(actual).to eq(born_after1915)
+    end
+
+    it 'should return valid nodes with two class comparators' do
+      input = {
+        node:         node_hash,
+        context:      { letters: %w[M S] },
+        comparators:  [BornAfter1915, NameStartsWith]
+      }
+
+      expect(::TreeBranch.process(input)).to eq(born_after1915_starts_with_m_or_s)
+    end
+
+    it 'should return valid nodes with one class comparator and one lambda comparator' do
+      input = {
+        node:         node_hash,
+        context:      { letters: %w[M S] },
+        comparators:  [BornAfter1915, name_starts_with_lambda]
+      }
+
+      expect(::TreeBranch.process(input)).to eq(born_after1915_starts_with_m_or_s)
+    end
+
+    it 'should execute the block after node processing' do
+      outside_variable = '!!'
+
+      input = {
+        node:     node,
+        context:  OpenStruct.new(suffix: 'cakes')
+      }
+
+      processed = ::TreeBranch.process(input) do |data, children, context|
+        local_node = ::TreeBranch::SimpleNode.new(data: data, children: children)
+
+        local_node.data.injected = "#{local_node.data.name}#{context.suffix}#{outside_variable}"
+
+        local_node
+      end
+
+      expect(processed).to eq(node_with_injected)
+    end
+  end
+
+  describe 'README Examples' do
+    class StateComparator < ::TreeBranch::Comparator
+      STATE_OPS = {
+        none: %i[open],
+        passive: %i[open save close print],
+        active: %i[open save close print cut copy paste]
+      }.freeze
+
+      def valid?
+        data.command.nil? || Array(STATE_OPS[context[:state]]).include?(data.command)
+      end
+    end
+
+    let(:menu) do
+      {
+        data: { name: 'Menu' },
+        children: [
+          {
+            data: { name: 'File' },
+            children: [
+              { data: { name: 'Open', command: :open } },
+              { data: { name: 'Save', command: :save, right: :write } },
+              { data: { name: 'Close', command: :close } },
+              {
+                data: { name: 'Print', command: :print },
+                children: [
+                  { data: { name: 'Print' } },
+                  { data: { name: 'Print Preview' } }
+                ]
+              }
+            ]
+          },
+          {
+            data: { name: 'Edit' },
+            children: [
+              { data: { name: 'Cut', command: :cut } },
+              { data: { name: 'Copy', command: :copy } },
+              { data: { name: 'Paste', command: :paste } }
+            ]
+          }
+        ]
+      }
+    end
+
+    it 'should compute state: none' do
+      no_file_menu = ::TreeBranch.process(
+        node: menu,
+        comparators: StateComparator,
+        context: { state: :none }
+      ) do |data, children, _context|
+        ::TreeBranch::SimpleNode.new(data: data, children: children)
+      end
+
+      expected = ::TreeBranch::SimpleNode.new(
+        data: { name: 'Menu' },
+        children: [
+          {
+            data: { name: 'File' },
+            children: [
+              { data: { name: 'Open', command: :open } }
+            ]
+          },
+          {
+            data: { name: 'Edit' }
+          }
+        ]
+      )
+
+      expect(no_file_menu).to eq(expected)
+    end
+
+    it 'should compute state: passive' do
+      no_file_menu = ::TreeBranch.process(
+        node: menu,
+        comparators: StateComparator,
+        context: { state: :passive }
+      ) do |data, children, _context|
+        ::TreeBranch::SimpleNode.new(data: data, children: children)
+      end
+
+      expected = ::TreeBranch::SimpleNode.new(
+        data: { name: 'Menu' },
+        children: [
+          {
+            data: { name: 'File' },
+            children: [
+              { data: { name: 'Open', command: :open } },
+              { data: { name: 'Save', command: :save, right: :write } },
+              { data: { name: 'Close', command: :close } },
+              {
+                data: { name: 'Print', command: :print },
+                children: [
+                  { data: { name: 'Print' } },
+                  { data: { name: 'Print Preview' } }
+                ]
+              }
+            ]
+          },
+          {
+            data: { name: 'Edit' }
+          }
+        ]
+      )
+
+      expect(no_file_menu).to eq(expected)
+    end
+
+    it 'should compute state: active' do
+      no_file_menu = ::TreeBranch.process(
+        node: menu,
+        comparators: StateComparator,
+        context: { state: :active }
+      ) do |data, children, _context|
+        ::TreeBranch::SimpleNode.new(data: data, children: children)
+      end
+
+      expected = ::TreeBranch::SimpleNode.new(
+        data: { name: 'Menu' },
+        children: [
+          {
+            data: { name: 'File' },
+            children: [
+              { data: { name: 'Open', command: :open } },
+              { data: { name: 'Save', command: :save, right: :write } },
+              { data: { name: 'Close', command: :close } },
+              {
+                data: { name: 'Print', command: :print },
+                children: [
+                  { data: { name: 'Print' } },
+                  { data: { name: 'Print Preview' } }
+                ]
+              }
+            ]
+          },
+          {
+            data: { name: 'Edit' },
+            children: [
+              { data: { name: 'Cut', command: :cut } },
+              { data: { name: 'Copy', command: :copy } },
+              { data: { name: 'Paste', command: :paste } }
+            ]
+          }
+        ]
+      )
+
+      expect(no_file_menu).to eq(expected)
+    end
+
+    class AuthorizationComparator < ::TreeBranch::Comparator
+      def valid?
+        data.right.nil? || Array(context[:rights]).include?(data.right)
+      end
+    end
+
+    it 'should compute state: passive for read-only authorization' do
+      no_file_menu = ::TreeBranch.process(
+        node: menu,
+        comparators: [StateComparator, AuthorizationComparator],
+        context: { state: :passive }
+      ) do |data, children, _context|
+        ::TreeBranch::SimpleNode.new(data: data, children: children)
+      end
+
+      expected = ::TreeBranch::SimpleNode.new(
+        data: { name: 'Menu' },
+        children: [
+          {
+            data: { name: 'File' },
+            children: [
+              { data: { name: 'Open', command: :open } },
+              { data: { name: 'Close', command: :close } },
+              {
+                data: { name: 'Print', command: :print },
+                children: [
+                  { data: { name: 'Print' } },
+                  { data: { name: 'Print Preview' } }
+                ]
+              }
+            ]
+          },
+          {
+            data: { name: 'Edit' }
+          }
+        ]
+      )
+
+      expect(no_file_menu).to eq(expected)
+    end
+
+    it 'should compute state: passive for read/write authorization' do
+      no_file_menu = ::TreeBranch.process(
+        node: menu,
+        comparators: [StateComparator, AuthorizationComparator],
+        context: { state: :passive, rights: :write }
+      ) do |data, children, _context|
+        ::TreeBranch::SimpleNode.new(data: data, children: children)
+      end
+
+      expected = ::TreeBranch::SimpleNode.new(
+        data: { name: 'Menu' },
+        children: [
+          {
+            data: { name: 'File' },
+            children: [
+              { data: { name: 'Open', command: :open } },
+              { data: { name: 'Save', command: :save, right: :write } },
+              { data: { name: 'Close', command: :close } },
+              {
+                data: { name: 'Print', command: :print },
+                children: [
+                  { data: { name: 'Print' } },
+                  { data: { name: 'Print Preview' } }
+                ]
+              }
+            ]
+          },
+          {
+            data: { name: 'Edit' }
+          }
+        ]
+      )
+
+      expect(no_file_menu).to eq(expected)
+    end
+
+    let(:auth_comparator) do
+      lambda do |data, context|
+        data.right.nil? || Array(context.rights).include?(data.right)
+      end
+    end
+
+    class MenuItem
+      acts_as_hashable
+
+      attr_reader :menu_items, :name
+
+      def initialize(name: '', menu_items: [])
+        @name       = name
+        @menu_items = self.class.array(menu_items)
+      end
+
+      def eql?(other)
+        name == other.name && menu_items == other.menu_items
+      end
+
+      def ==(other)
+        eql?(other)
+      end
+    end
+
+    it 'should compute state: passive for read/write authorization and return MenuItem(s)' do
+      passive_read_write_menu =
+        ::TreeBranch.process(
+          node: menu,
+          comparators: [StateComparator, auth_comparator],
+          context: { state: :passive, rights: :write }
+        ) { |data, children, _context| MenuItem.new(name: data.name, menu_items: children) }
+
+      expected = MenuItem.new(
+        name: 'Menu',
+        menu_items: [
+          {
+            name: 'File',
+            menu_items: [
+              { name: 'Open' },
+              { name: 'Save' },
+              { name: 'Close' },
+              {
+                name: 'Print',
+                menu_items: [
+                  { name: 'Print' },
+                  { name: 'Print Preview' }
+                ]
+              }
+            ]
+          },
+          {
+            name: 'Edit'
+          }
+        ]
+      )
+
+      expect(passive_read_write_menu).to eq(expected)
+    end
+  end
+end