tree_branch 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15671327d19ea465e079da408e3e4a35ff0a26d03b8ec33251e7c96a49d9b87d
+  data.tar.gz: b40855cf7a130ed233b9e4da84224d81dd75d54de234cabd628d806bda81c9b2
+SHA512:
+  metadata.gz: 30b2df3207d1cea66da5197b9582744b8746b4e5fed1f188975f281e8895657bcdf6a96b07bbff9e86b60ff53d4eec492b3d6d4411af77e3258821e2b4d03b72
+  data.tar.gz: d6bf7412d4db03c36f2ce842f63705b70af25051d337e70672c23fc95ad442762285a57c956ad839781ddd364d043ea64ace974836381be454785218d138106c

data/.editorconfig

@@ -0,0 +1,8 @@
+# See http://editorconfig.org/
+
+[*]
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+end_of_line = lf

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+*.gem
+/tmp

data/.rubocop.yml

@@ -0,0 +1,8 @@
+Metrics/LineLength:
+  Max: 100
+
+Metrics/BlockLength:
+  ExcludedMethods: ['it', 'describe', 'context', 'let', 'specify']
+
+AllCops:
+  TargetRubyVersion: 2.3

data/.ruby-version

@@ -0,0 +1 @@
+2.6.0

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+# Build on the latest stable of all supported Rubies (https://www.ruby-lang.org/en/downloads/):
+- 2.3.8
+- 2.4.5
+- 2.5.3
+- 2.6.0
+cache: bundler
+script:
+- bundle exec rubocop
+- bundle exec rspec

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,89 @@
+PATH
+  remote: .
+  specs:
+    tree_branch (1.0.0)
+      acts_as_hashable (~> 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    acts_as_hashable (1.0.3)
+    ast (2.4.0)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    ffi (1.9.25)
+    formatador (0.2.5)
+    guard (2.15.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    jaro_winkler (1.5.1)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.13)
+    method_source (0.9.2)
+    nenv (0.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parallel (1.12.1)
+    parser (2.5.3.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rainbow (3.0.0)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.59.2)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.10.0)
+    ruby_dep (1.5.0)
+    shellany (0.0.1)
+    thor (0.20.3)
+    unicode-display_width (1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard-rspec (~> 4.7)
+  rspec (~> 3.8)
+  rubocop (~> 0.59)
+  tree_branch!
+
+BUNDLED WITH
+   1.17.2

data/Guardfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018 Blue Marble Payroll, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,431 @@
+# TreeBranch
+
+[![Build Status](https://travis-ci.org/bluemarblepayroll/tree_branch.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/tree_branch)
+
+This library allows you to traverse an entire tree structure, compare all nodes, and choose a tree structure to return.  The basic input is defined as:
+
+1. Initial Tree structure root node (required)
+2. Comparison classes or functions (optional)
+3. Block to convert each matching node (optional)
+
+And the output is defined as:
+
+1. Compared and/or converted tree structure (root node)
+
+The specific use-case this was designed for was a dynamic web application menu. In this specific example, we wanted either a static file or a database to store and define all possible menus. Then we wanted to input a request's lifecycle context (user, url, parameters, authorization, etc.) and return the menu that matched the current spot in the application.
+
+## Installation
+
+To install through Rubygems:
+
+````
+gem install install tree_branch
+````
+
+You can also add this to your Gemfile:
+
+````
+bundle add tree_branch
+````
+
+## Examples
+
+### Word Processor Application Menu Example
+
+Take the following application menu structure:
+
+````ruby
+menu = {
+  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 } }
+      ]
+    }
+  ]
+}
+````
+
+There are three application states:
+
+1. No file open (user has no file currently editing): NONE
+2. Passive file open: PASSIVE
+3. Active file open: ACTIVE
+
+The user is allowed only access to specific menu items depending on their state:
+
+1. NONE: open
+2. PASSIVE: open, save, close, print
+3. ACTIVE: open, save, close, print, cut, copy, paste
+
+We can implement this as a comparator class:
+
+````ruby
+class StateComparator < ::TreeBranch::Comparator
+  STATE_OPS = {
+    none: %i[open],
+    passive: %i[open save close print],
+    active: %i[open save close print cut copy paste]
+  }
+
+  def valid?
+    data.command.nil? || Array(STATE_OPS[context.state]).include?(data.command)
+  end
+end
+````
+
+Finally, we can process this for all three states:
+
+````ruby
+no_file_menu =
+  ::TreeBranch.process(
+    node: menu,
+    comparators: StateComparator,
+    context: { state: :none }
+  )
+
+passive_file_menu =
+  ::TreeBranch.process(
+    node: menu,
+    comparators: StateComparator,
+    context: { state: :passive }
+  )
+
+active_file_menu =
+  ::TreeBranch.process(
+    node: menu,
+    comparators: StateComparator,
+    context: { state: :active }
+  )
+````
+
+We would get the following structure back (in the form of a root Node object but expressed as a hash below):
+
+##### No File Menu Result
+
+````ruby
+{
+  data: { name: 'Menu' },
+  children: [
+    {
+      data: { name: 'File' },
+      children: [
+        { data: { name: 'Open', command: :open } }
+      ]
+    },
+    {
+      data: { name: 'Edit' }
+    }
+  ]
+}
+````
+
+##### Passive File Menu Result
+
+````ruby
+{
+  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' }
+    }
+  ]
+}
+````
+
+##### Active File Menu Result
+
+````ruby
+{
+  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 } }
+      ]
+    }
+  ]
+}
+````
+
+### Stacking Comparators
+
+You can also choose to input multiple comparators (technically 0 to N).  For example, let's stack authorization into our application menu example using this comparator:
+
+````ruby
+class AuthorizationComparator < ::TreeBranch::Comparator
+  def valid?
+    data.right.nil? || Array(context.rights).include?(data.right)
+  end
+end
+````
+
+Now, we can pass in our current user's rights and use them when appropriate:
+
+````ruby
+passive_read_only_menu =
+  ::TreeBranch.process(
+    node: menu,
+    comparators: [StateComparator, AuthorizationComparator],
+    context: { state: :passive }
+  )
+
+passive_read_write_menu =
+  ::TreeBranch.process(
+    node: menu,
+    comparators: [StateComparator, AuthorizationComparator],
+    context: { state: :passive, rights: :write }
+  )
+````
+
+##### Read-Only User Passively Editing Result
+
+````ruby
+{
+  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' }
+    }
+  ]
+}
+````
+
+##### Read/Write User Passively Editing Result
+
+````ruby
+{
+  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' }
+    }
+  ]
+}
+````
+
+Notice now our read-only menu is missing the 'save' item.
+
+### Comparator Creation
+
+There are two ways to create comparators:
+
+1. Subclass ::TreeBranch::Comparator and implement the ```valid?``` method to return true/false
+2. Create lambda/proc that accepts two arguments: data and context and returns true/false
+
+Option one is shown in the above example, while option two can be illustrated as:
+
+````ruby
+auth_comparator = lambda do |data, context|
+  data.right.nil? || Array(context.rights).include?(data.right)
+end
+
+passive_read_only_menu =
+  ::TreeBranch.process(
+    node: menu,
+    comparators: [StateComparator, auth_comparator],
+    context: { state: :passive }
+  )
+````
+
+### Node Post-Processing / Conversion
+
+After a node has been compared and is deemed to be valid, it will either return one of two things:
+
+1. ::TreeBranch::Node instance
+2. The return of the block passed into the process method produced *(Note: If nil it will be ignored as if it was invalid.)*
+
+In our above example we did not pass in a block so they would all return Node instances.  The passed in block is your chance to return instances of another class, or even do some other post-processing routines.  For example, lets return an instance of a new type: MenuItem as shown below:
+
+````ruby
+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
+````
+
+We can now convert this in the block:
+
+````ruby
+passive_read_write_menu =
+  ::TreeBranch.process(
+    node: menu,
+    comparators: [StateComparator, auth_comparator],
+    context: { state: :passive, rights: :write }
+  ) { |data, children, context| MenuItem.new(data.name, children) }
+````
+
+Our resulting data set (visualized as a hash):
+
+````ruby
+{
+  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'
+    }
+  ]
+}
+````
+
+## Contributing
+
+### Development Environment Configuration
+
+Basic steps to take to get this repository compiling:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check tree_branch.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/tree_branch.git)
+4. Navigate to the root folder (cd tree_branch)
+5. Install dependencies (bundle)
+
+### Running Tests
+
+To execute the test suite run:
+
+````
+bundle exec rspec spec --format documentation
+````
+
+Alternatively, you can have Guard watch for changes:
+
+````
+bundle exec guard
+````
+
+Also, do not forget to run Rubocop:
+
+````
+bundle exec rubocop
+````
+
+### Publishing
+
+Note: ensure you have proper authorization before trying to publish new versions.
+
+After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:
+
+1. Merge Pull Request into master
+2. Update [lib/tree_branch/version.rb](https://github.com/bluemarblepayroll/tree_branch/blob/master/lib/tree_branch/version.rb) [version number](https://semver.org/)
+3. Bundle
+4. Update CHANGELOG.md
+5. Commit & Push master to remote and ensure CI builds master successfully
+6. Build the project locally: `gem build tree_branch`
+7. Publish package to NPM: `gem push tree_branch-X.gem` where X is the version to push
+8. Tag master with new version: `git tag <version>`
+9. Push tags remotely: `git push origin --tags`
+
+## License
+
+This project is MIT Licensed.

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'tree_branch'
+
+# 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

data/lib/tree_branch/comparator.rb

@@ -0,0 +1,25 @@
+# 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 is the base class for all plug in comparators.  Derive subclasses from this class
+  # and declare them when calling ::TreeBranch::Node#process or ::TreeBranch#process.
+  class Comparator
+    attr_reader :data, :context
+
+    def initialize(data: {}, context: {})
+      @data     = data    || {}
+      @context  = context || {}
+    end
+
+    def valid?
+      false
+    end
+  end
+end

data/lib/tree_branch/node.rb

@@ -0,0 +1,42 @@
+# 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
+  # Main class the outlines the basic operations and structure of a node in the tree.
+  class Node
+    attr_reader :data, :children
+
+    def initialize(data)
+      @data     = data
+      @children = []
+    end
+
+    def add(*children_to_add)
+      children_to_add.flatten.each do |child|
+        raise ArgumentError, "Improper class: #{child.class.name}" unless child.is_a?(self.class)
+
+        @children << child
+      end
+
+      self
+    end
+
+    def eql?(other)
+      data == other.data && children == other.children
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+
+    def to_s
+      "[#{self.class.name}] Data: #{data}, Child Count: #{children.length}"
+    end
+  end
+end