laminar 0.3.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3fb0486b2d99158c6fa192d237100a61bc9ae40e
-  data.tar.gz: 0755f031eee6dfaefbb64d9301c3e27327c6088f
+SHA256:
+  metadata.gz: ea3e3d103dc6aa3041a22d958a120a73c7fa526f5dcbfc74b8f19503194362a6
+  data.tar.gz: 98289c18df72debb00c6df9877bae3262a6f6fda7d56b44197e09c6e9a980a2d
 SHA512:
-  metadata.gz: 5d7f0f34420a061583f4744cf16bfa6a899c8ccf8bd2cb2b8aa24c269c487290632084fbce0dd74e6f2f6540b54f4e605e6731f37e89e6c6bee5a5176f0f55fc
-  data.tar.gz: 2fbbbef809c51fff94be71195e63fab67c8c93f9cb1ed0b96228e7dcc84e21a34572d31f4a48e18e6e23514686115a690f6d125581333626c7c1c93e1f2eb38a
+  metadata.gz: 9b04f54ca23f10321e112675c6ddefdfbede105a744304e9fd969580145b32293ae5e52a9c8e78ffb8a4f1b65ed9bbabf0f660604e84609fcd7c6e2403ec1462
+  data.tar.gz: 8289147544e03879303d68d86f4f171461ceea552fc81feba510b9caced6dcca50e1ed7c088cffd1459d31658e06cf0c86ba81708db8cfd216e80ca21e811ab5

data/.gitignore

@@ -1,3 +1,4 @@
+.ruby-version
 *.gem
 Gemfile.lock
 /.bundle/

data/.rspec

@@ -1,3 +1,3 @@
---format documentation
 --color
 --require spec_helper
+--order random

data/.rubocop.yml

@@ -0,0 +1,22 @@
+Layout/LineLength:
+  Max: 99
+AllCops:
+  TargetRubyVersion: 2.3.0
+
+Metrics/MethodLength:
+  Max: 12
+
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true

data/.travis.yml

@@ -6,8 +6,13 @@ rvm:
   - 2.3
   - 2.4
   - 2.5
+  - 2.6
 before_install: gem install bundler -v 1.16.5
 script:
   - bundle exec rspec
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
 after_script:
   - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -1,8 +1,49 @@
-# Change Log
+# Changelog
 
-## [Unreleased](https://github.com/rmlockerd/laminar/tree/HEAD)
+## [v0.7.0](https://github.com/rmlockerd/laminar/tree/v0.7.0) (2020-06-13)
 
-[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.2.0...HEAD)
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.6.0...v0.7.0)
+
+**Fixed bugs:**
+
+- Fix 3.0-compatibility warnings with Ruby 2.7.x [\#13](https://github.com/rmlockerd/laminar/issues/13)
+
+## [v0.6.0](https://github.com/rmlockerd/laminar/tree/v0.6.0) (2020-04-15)
+
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.5.1...v0.6.0)
+
+## [v0.5.1](https://github.com/rmlockerd/laminar/tree/v0.5.1) (2020-03-06)
+
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.5.0...v0.5.1)
+
+## [v0.5.0](https://github.com/rmlockerd/laminar/tree/v0.5.0) (2018-11-12)
+
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.4.0...v0.5.0)
+
+**Implemented enhancements:**
+
+- Add 'soft' halt capability for flows [\#11](https://github.com/rmlockerd/laminar/issues/11)
+- Check starting context for a flow [\#9](https://github.com/rmlockerd/laminar/issues/9)
+
+**Fixed bugs:**
+
+- Branch conditionals \(if:/unless:\) do not get context passed [\#10](https://github.com/rmlockerd/laminar/issues/10)
+
+## [v0.4.0](https://github.com/rmlockerd/laminar/tree/v0.4.0) (2018-10-12)
+
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.3.0...v0.4.0)
+
+**Implemented enhancements:**
+
+- Shorthand for branching to end [\#8](https://github.com/rmlockerd/laminar/issues/8)
+
+**Fixed bugs:**
+
+- branch if/unless don't accept blocks/Procs [\#7](https://github.com/rmlockerd/laminar/issues/7)
+
+## [v0.3.0](https://github.com/rmlockerd/laminar/tree/v0.3.0) (2018-10-01)
+
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.2.0...v0.3.0)
 
 **Implemented enhancements:**
 
@@ -13,10 +54,13 @@
 - Add before/after particle callbacks [\#1](https://github.com/rmlockerd/laminar/issues/1)
 
 ## [v0.2.0](https://github.com/rmlockerd/laminar/tree/v0.2.0) (2018-09-27)
+
+[Full Changelog](https://github.com/rmlockerd/laminar/compare/8bd9c0f01bae6cfd7f5df58c3c792068fa30366d...v0.2.0)
+
 **Fixed bugs:**
 
 - .gemspec missing active\_support dependency [\#4](https://github.com/rmlockerd/laminar/issues/4)
 
 
 
-\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/README.md

@@ -1,8 +1,9 @@
 # Laminar
 
+[![Gem Version](https://badge.fury.io/rb/laminar.svg)](https://badge.fury.io/rb/laminar)
 [![Build Status](https://travis-ci.org/rmlockerd/laminar.svg?branch=master)](https://travis-ci.org/rmlockerd/laminar)
-[![Maintainability](https://img.shields.io/codeclimate/maintainability/rmlockerd/laminar.svg)](https://codeclimate.com/github/rmlockerd/laminar)
-[![Test Coverage](https://img.shields.io/codeclimate/coverage-letter/rmlockerd/laminar.svg)](https://codeclimate.com/github/rmlockerd/laminar)
+[![Maintainability](https://api.codeclimate.com/v1/badges/6b2d761ca042af6461e3/maintainability)](https://codeclimate.com/github/rmlockerd/laminar/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/6b2d761ca042af6461e3/test_coverage)](https://codeclimate.com/github/rmlockerd/laminar/test_coverage)
 
 A simple Chain-of-Responsibility/Interactor gem that helps MVC applications organise their business logic, keeping their models and controllers skinny and their logic easily testable. Individual chunks of business logic (called particles) can be easily composed into more complex chains called flows.
 
@@ -237,6 +238,31 @@ class CheckEquipment
 end
 ```
 
+#### Flow Parameters
+Flows do not get the benefit of keyword argument checking like ordinary
+Particles, since their #call method is implemented by the Flow mixin.
+You can, however, specify a list of required context keys in the flow
+definition itself:
+
+```ruby
+flow do
+  context_must_have :product_sku, :unit_price
+  ...
+end
+```
+
+The context is simply checked for the presence of the specified
+list of keys. If you need to do more complicated validation of
+context, use a ``#before`` callback that halts the flow if
+validation fails.
+
+Context validation happens just prior to execution of the
+first step in the flow (and any ``#before_each``) callbacks, but after
+execution of the Flow's own ``#before`` callbacks. Since you can
+manipulate context in a callback, this is useful to set up
+context required by a flow's particles that you don't necessarily
+expect your caller to provide.
+
 #### Flow Branching
 Ordinarily particle execution is sequential in the order specified.
 However, you can optionally branch to a different label with `branch`.
@@ -250,7 +276,7 @@ However, you can optionally branch to a different label with `branch`.
   end
 ```
 
-You can use the special symbol :endflow to jump terminate the flow
+You can use the endflow directive to terminate the flow gracefully
 (skipping all remaining steps).
 
 ```ruby
@@ -309,6 +335,11 @@ no condition is satisfied, execution drops to the next step.
    step :last_step
   end
 ```
+#### Halting a Flow
+If a particle calls ``#halt!`` or ``#fail!`` on its context, execution
+of any surrounding Flow (or nested flows) stops immediately via a
+``ParticleStopped`` error. To gracefully signal that an enclosing
+flow should stop without raising an error, use ``#halt`` instead.
 
 #### Flow Callbacks
 
@@ -318,11 +349,15 @@ A flow can specify callback(s) to run before/after every step:
 class MyFlow
   include Laminar::Flow
 
-  before_each :thing, :thing2  # method
-  before_each { ... } # block
+  flow do
+    before_each :thing, :thing2  # method
+    before_each { ... } # block
 
-  after_each :thing, :thing2  # method
-  after_each { ... } # block
+    after_each :thing, :thing2  # method
+    after_each { ... } # block
+
+    # steps ...
+  end
 ```
 
 The order of execution for callbacks in a flow looks like:

data/laminar.gemspec

@@ -33,10 +33,10 @@ Gem::Specification.new do |spec|
   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 'activesupport', '~> 4.2'
 
   spec.add_development_dependency 'bundler', '~> 1.16'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 12.3', '>= 12.3.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'simplecov', '~> 0.16'
 end

data/lib/laminar/callbacks.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Laminar
+  # Callback hooks for particles
   module Callbacks
     def self.included(klass)
       klass.class_eval do
@@ -23,6 +24,11 @@ module Laminar
       end
       alias after_call after
 
+      def finalize(*args, &block)
+        final_list.concat(args)
+        final_list << block if block
+      end
+
       def before_list
         @before_list ||= []
       end
@@ -30,11 +36,14 @@ module Laminar
       def after_list
         @after_list ||= []
       end
+
+      def final_list
+        @final_list ||= []
+      end
     end
 
     # Additional instance methods
     module InstanceMethods
-
       private
 
       def run_before_callbacks
@@ -45,6 +54,10 @@ module Laminar
         run_callbacks(self.class.after_list)
       end
 
+      def run_final_callbacks
+        run_callbacks(self.class.final_list)
+      end
+
       def run_callbacks(list)
         list.each { |cb| cb.is_a?(Symbol) ? send(cb) : instance_exec(&cb) }
       end

data/lib/laminar/context.rb

@@ -31,9 +31,13 @@ module Laminar
       @halted
     end
 
-    def halt!(context = {})
+    def halt(context = {})
       @halted = true
       merge!(context)
+    end
+
+    def halt!(context = {})
+      halt(context)
       raise ParticleStopped, self
     end
 

data/lib/laminar/flow.rb

@@ -103,14 +103,11 @@ module Laminar
       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.
+      # @param object the context/input on which the flow will operate.
       def call(*)
         return context if flowspec.nil?
 
+        validate_required_context
         step = flowspec.steps[flowspec.first_step]
         loop do
           break unless invoke_step(step)
@@ -124,14 +121,36 @@ module Laminar
 
       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[:__flow_step__] = step.name
+        pre_step_callbacks(step)
+        run_particle(step)
+        post_step_callbacks(step)
         !context.halted?
       end
 
+      def post_step_callbacks(step)
+        guarded_callback(step.after_callbacks)
+        guarded_callback(flowspec.after_each_callbacks)
+      end
+
+      def pre_step_callbacks(step)
+        guarded_callback(flowspec.before_each_callbacks)
+        guarded_callback(step.before_callbacks)
+      end
+
+      def run_particle(step)
+        return if context.halted?
+
+        step.particle.call!(context)
+      end
+
+      def guarded_callback(list)
+        return if context.halted?
+
+        run_callbacks(list)
+      end
+
       # Given a step, returns the next step that satisfies the
       # execution/branch conditions.
       def next_step(current)
@@ -143,6 +162,19 @@ module Laminar
 
         flowspec.steps[next_name]
       end
+
+      def validate_required_context
+        missing = []
+        flowspec.flow_params.each do |param|
+          next if context.key?(param)
+
+          missing << param
+        end
+
+        return if missing.empty?
+
+        raise ArgumentError, "missing context: #{missing.join(', ')}"
+      end
     end
   end
 end

data/lib/laminar/flow/branch.rb

@@ -18,9 +18,7 @@ module Laminar
       attr_accessor :name, :condition, :condition_type
 
       def initialize(name, options = {})
-        unless name.class.method_defined?(:to_sym)
-          raise ArgumentError, 'invalid name'
-        end
+        raise ArgumentError, 'invalid name' unless name.class.method_defined?(:to_sym)
 
         validate_options(options)
         @name = name.to_sym
@@ -40,7 +38,11 @@ module Laminar
       private
 
       def run_condition(target)
-        target.send(@condition)
+        if @condition.is_a?(Proc)
+          @condition.call(target.context)
+        else
+          target.send(@condition)
+        end
       end
 
       def define_condition(options)
@@ -48,9 +50,9 @@ module Laminar
         return if @condition_type.nil?
 
         @condition = options[@condition_type]
-        return if @condition.nil? || @condition.is_a?(Symbol)
+        return if @condition.nil? || @condition.is_a?(Symbol) || @condition.is_a?(Proc)
 
-        raise TypeError, 'condition must be a method (symbol).'
+        raise TypeError, 'condition must be a method symbol or Proc).'
       end
     end
   end

data/lib/laminar/flow/specification.rb

@@ -23,6 +23,14 @@ module Laminar
         @prev_step = step
       end
 
+      def context_must_have(*params)
+        flow_params.concat(params.flatten)
+      end
+
+      def flow_params
+        @flow_params ||= []
+      end
+
       def before_each(*args, &block)
         before_each_callbacks.concat(args)
         before_each_callbacks << block if block

data/lib/laminar/flow/step.rb

@@ -14,9 +14,7 @@ module Laminar
       valid_options %i[class].freeze
 
       def initialize(name, options = {}, &block)
-        unless name.class.method_defined?(:to_sym)
-          raise ArgumentError, 'invalid name'
-        end
+        raise ArgumentError, 'invalid name' unless name.class.method_defined?(:to_sym)
 
         validate_options(options)
         @class_name = (options[:class] || name).to_s.camelize
@@ -43,6 +41,10 @@ module Laminar
       end
       alias goto branch
 
+      def endflow(options = {})
+        branches << Branch.new(:endflow, options)
+      end
+
       # Find the next rule in the flow. Examines the branches associated
       # with the current rule and returns the name of the first branch
       # that satisfies its condition.

data/lib/laminar/particle.rb

@@ -26,6 +26,7 @@ module Laminar
       end
     end
 
+    # Laminar::Particle instance methods.
     module InstanceMethods
       def initialize(context = {})
         @context = Context.build(context)
@@ -38,12 +39,18 @@ module Laminar
       end
 
       def invoke!
-        run_before_callbacks
-        return context if context.halted?
+        begin
+          run_before_callbacks
+          return context if context.halted?
 
-        param_list = context_slice
-        param_list.empty? ? call : call(context_slice)
-        run_after_callbacks
+          param_list = context_slice
+          param_list.empty? ? call : call(**context_slice)
+          run_after_callbacks unless context.halted?
+        rescue ParticleStopped
+          run_final_callbacks
+          raise
+        end
+        run_final_callbacks
         context
       end
 

data/lib/laminar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Laminar
-  VERSION = '0.3.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: laminar
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Robert Lockerd
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-01 00:00:00.000000000 Z
+date: 2020-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
 - !ruby/object:Gem::Dependency
@@ -44,14 +44,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -91,6 +97,7 @@ files:
 - ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -132,8 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Simple, composable business objects & workflow