laminar 0.3.0

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'laminar'
+
+# 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(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/laminar.gemspec

@@ -0,0 +1,42 @@
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'laminar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'laminar'
+  spec.version       = Laminar::VERSION
+  spec.authors       = ['Robert Lockerd']
+  spec.email         = ['rmlockerd@gmail.com']
+
+  spec.summary       = 'Simple, composable business objects & workflow'
+  spec.homepage      = 'https://github.com/rmlockerd/laminar'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set
+  # the 'allowed_push_host' to allow pushing to a single host or delete
+  # this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise 'RubyGems 2.0 or newer is required to protect against ' \
+  #     'public gem pushes.'
+  # end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been
+  # added into git.
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'activesupport', '>= 4.2'
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov', '~> 0.16'
+end

data/lib/laminar.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'laminar/version'
+require 'laminar/callbacks'
+require 'laminar/context'
+require 'laminar/particle_stopped'
+require 'laminar/particle'
+require 'laminar/flow'
+
+# Simple engine for executing flows of atomic
+# logic operations.
+module Laminar
+end

data/lib/laminar/callbacks.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Laminar
+  module Callbacks
+    def self.included(klass)
+      klass.class_eval do
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+
+    # Class methods and attributes.
+    module ClassMethods
+      def before(*args, &block)
+        before_list.concat(args)
+        before_list << block if block
+      end
+      alias before_call before
+
+      def after(*args, &block)
+        after_list.concat(args)
+        after_list << block if block
+      end
+      alias after_call after
+
+      def before_list
+        @before_list ||= []
+      end
+
+      def after_list
+        @after_list ||= []
+      end
+    end
+
+    # Additional instance methods
+    module InstanceMethods
+
+      private
+
+      def run_before_callbacks
+        run_callbacks(self.class.before_list)
+      end
+
+      def run_after_callbacks
+        run_callbacks(self.class.after_list)
+      end
+
+      def run_callbacks(list)
+        list.each { |cb| cb.is_a?(Symbol) ? send(cb) : instance_exec(&cb) }
+      end
+    end
+  end
+end

data/lib/laminar/context.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Laminar
+  # The environment and state of a particle (or flow) invocation. The
+  # context provides data required for a particle to do its job. A particle can
+  # modify the context during execution to return results, errors, etc.
+  class Context < Hash
+    def self.build(context = {})
+      case context
+      when self
+        context
+      else
+        new.merge!(context || {})
+      end
+    end
+
+    def initialize
+      @halted = false
+      @failed = false
+    end
+
+    def success?
+      !failed?
+    end
+
+    def failed?
+      @failed
+    end
+
+    def halted?
+      @halted
+    end
+
+    def halt!(context = {})
+      @halted = true
+      merge!(context)
+      raise ParticleStopped, self
+    end
+
+    def fail!(context = {})
+      @failed = true
+      halt!(context)
+    end
+  end
+end

data/lib/laminar/flow.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'laminar/flow/branch'
+require 'laminar/flow/flow_error'
+require 'laminar/flow/step'
+require 'laminar/flow/specification'
+
+module Laminar
+  # Implements a DSL for defining a chain of Particles. Each step (particle)
+  # contributes to an overall answer/outcome via a shared context.
+  #
+  # Simple branching and looping is supported via conditional jumps.
+  #
+  # The most basic flow is a simple set of steps executed sequentially.
+  # @example
+  #   flow do
+  #     step :first
+  #     step :then_me
+  #     step :last_step
+  #   end
+  #
+  # Each step symbol names a class that includes Laminar::Particle. The call
+  # method specifies keyword arguments that the flow uses to determine which
+  # parts of the execution context to pass to the step.
+  #
+  # By default, the flow uses the step label as the implementation particle
+  # name. You can use the class directive to specify an alternate class
+  # name. This can be a String or Symbol. Very useful when your particles
+  # are organised into modules.
+  # @example
+  #   flow do
+  #     step :first
+  #     step :then_me, class: :impl_class
+  #     step :third, class: 'MyModule::DoSomething'
+  #   end
+  #
+  # Branching is implemented via the goto directive. These directives are
+  # evaluated immediately following the execution of a step.
+  #
+  # @example
+  #   flow do
+  #     step :first do
+  #       goto :last_step, if: :should_i?
+  #     end
+  #     step :then_me
+  #     step :do_something
+  #     step :last_step
+  #   end
+  #
+  # In the previous example, execution will pass to last_step is the supplied
+  # method should_i? (on the flow instance) returns true. If no branch
+  # satisfies its conditions, execution will fall through to the next step.
+  #
+  # A step can have
+  # muluple goto directives; the flow will take the first branch that
+  # it finds that satisfies its specified condition (if any).
+  # @example
+  #   flow do
+  #     step :first do
+  #       goto :last_step, if: :should_i?
+  #       goto :do_something, unless: :another?
+  #     end
+  #     step :then_me
+  #     step :do_something
+  #     step :last_step
+  #   end
+  #
+  # You can use the special goto tag :endflow to conditionally teriminate
+  # the flow.
+  # @example
+  #   flow do
+  #     step check_policy do
+  #       goto :endflow, if :failed_policy?
+  #     end
+  #   end
+  #
+  module Flow
+    def self.included(base)
+      base.class_eval do
+        include Particle
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+
+    # Add class methods and attributes.
+    module ClassMethods
+      # @!attribute [r] flowspec
+      #  @return [FlowSpec] specification of the class' ruleflow.
+      attr_reader :flowspec
+
+      # Entry point for defining a flow.
+      def flow(args = {}, &block)
+        @flowspec = Specification.new(args, &block)
+      end
+    end
+
+    # Add instance methods and attributes
+    module InstanceMethods
+      # @return [FlowSpec] the flow specification for the class.
+      def flowspec
+        self.class.flowspec
+      end
+
+      # Initiates evaluation of the flow.
+      # @param object the context/input on which the flow will operate. This
+      #   is usually a Hash but in simple cases can be a single object. The
+      #   implementing flow class should provide a #context_valid? method
+      #   that returns true is the given context contains the minimum required
+      #   information.
+      def call(*)
+        return context if flowspec.nil?
+
+        step = flowspec.steps[flowspec.first_step]
+        loop do
+          break unless invoke_step(step)
+
+          step = next_step(step)
+        end
+        context
+      end
+
+      private
+
+      def invoke_step(step)
+        return if step.nil?
+        run_callbacks(flowspec.before_each_callbacks)
+        run_callbacks(step.before_callbacks)
+        step.particle.call!(context)
+        run_callbacks(step.after_callbacks)
+        run_callbacks(flowspec.after_each_callbacks)
+        !context.halted?
+      end
+
+      # Given a step, returns the next step that satisfies the
+      # execution/branch conditions.
+      def next_step(current)
+        next_name = current.next_step_name(self)
+        return nil unless next_name && next_name != :endflow
+        unless flowspec.steps.key?(next_name)
+          raise FlowError, "No rule with name or alias of #{next_name}"
+        end
+
+        flowspec.steps[next_name]
+      end
+    end
+  end
+end

data/lib/laminar/flow/branch.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'laminar/flow/options_validator'
+
+module Laminar
+  module Flow
+    # Specification for a target rule transition.
+    class Branch
+      include OptionsValidator
+
+      valid_options %i[if unless].freeze
+
+      # @!attribute name
+      #   @return target rule to branch to
+      #
+      # @!attribute condition
+      #   @return the branch condition (method name symbol or Proc/lambda)
+      attr_accessor :name, :condition, :condition_type
+
+      def initialize(name, options = {})
+        unless name.class.method_defined?(:to_sym)
+          raise ArgumentError, 'invalid name'
+        end
+
+        validate_options(options)
+        @name = name.to_sym
+        define_condition(options)
+      end
+
+      # @param [RuleBase] context a given rule implementation
+      #
+      # @return [Boolean] true if condition is satisfied in the context.
+      def meets_condition?(target)
+        return true if condition.nil?
+
+        result = run_condition(target)
+        condition_type == :if ? result : !result
+      end
+
+      private
+
+      def run_condition(target)
+        target.send(@condition)
+      end
+
+      def define_condition(options)
+        @condition_type = (options.keys & %i[if unless]).first
+        return if @condition_type.nil?
+
+        @condition = options[@condition_type]
+        return if @condition.nil? || @condition.is_a?(Symbol)
+
+        raise TypeError, 'condition must be a method (symbol).'
+      end
+    end
+  end
+end

data/lib/laminar/flow/flow_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Laminar
+  module Flow
+    # Exception to immediately terminate rule processing
+    class FlowError < StandardError
+    end
+  end
+end

data/lib/laminar/flow/options_validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Laminar
+  module Flow
+    # Concern that adds ability to validate arbitrary directive options.
+    module OptionsValidator
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+        end
+      end
+
+      # Add class methods and attributes.
+      module ClassMethods
+        attr_reader :option_list
+
+        # Entry point for defining a flow.
+        def valid_options(*args)
+          @option_list = args.flatten
+        end
+      end
+
+      # Add instance methods and attributes
+      module InstanceMethods
+        def validate_options(options)
+          valid = self.class.option_list
+          options.each_key do |k|
+            next if valid.include?(k)
+
+            raise ArgumentError,
+                  "Unknown key: #{k.inspect}. Valid keys are: "\
+                  "#{valid.map(&:inspect).join(', ')}."
+          end
+        end
+      end
+    end
+  end
+end