laminar 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfa336597901d8c1c25976ced526555e981b731613daa6f916394b2ac71cb7a9
-  data.tar.gz: 9f5db130a19de3dda3ef4579bff68e103bf667e79759f5be0726c413efbacff1
+  metadata.gz: 697f7db8e9717c6795e2e95abfcc3601c50994e90fba9cc5275b27b0a8995b92
+  data.tar.gz: fc4d199a808988c03b9ce8b8b12fa6cd9b6c4886a0f605b0dc53072970813c3d
 SHA512:
-  metadata.gz: 9d054d187381bc5c768b490df36c65a02466a0ea30f198db208006491610fa23f371e1235a0e9f37ae251ad0a3997ecfaad7490dacb909912532c5e406d5af35
-  data.tar.gz: 6cb99ce2b271f7f6f1782de44a3fc1b2585412441a375cd4be77ea31544fd9813f7ecfe02f3cfe8968e121762933853a7da5f533185202106e860dc42d203feb
+  metadata.gz: 6fbe3e9b76547ef3e9cbb62ff3a05c552aba735fa280bcbc24c5d3bcffd2bb7f9c9d799e84489e7ffb035ca84697f78216f9e67924e6536d1d8bd463290537a1
+  data.tar.gz: 26523b261d6927e59f629abe85f11a788435b5c304d60eacbedd148882e52f9432d2fb0255d3a52dbcffc544e7e2fab4483e70228c97f5d0c8b1019a4ff96255

data/.rubocop.yml

@@ -0,0 +1,7 @@
+Metrics/LineLength:
+  Max: 99
+AllCops:
+  TargetRubyVersion: 2.3.0
+
+Metrics/MethodLength:
+  Max: 12

data/CHANGELOG.md

@@ -1,8 +1,30 @@
 # Change Log
 
-## [Unreleased](https://github.com/rmlockerd/laminar/tree/HEAD)
+## [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)
 
-[Full Changelog](https://github.com/rmlockerd/laminar/compare/v0.2.0...HEAD)
+**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:**
 

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/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
@@ -34,7 +35,6 @@ module Laminar
 
     # Additional instance methods
     module InstanceMethods
-
       private
 
       def run_before_callbacks

data/lib/laminar/context.rb

@@ -31,10 +31,14 @@ module Laminar
       @halted
     end
 
-    def halt!(context = {})
+    def halt(context = {})
       @halted = true
       merge!(context)
-      raise ParticleStopped.new(self)
+    end
+
+    def halt!(context = {})
+      halt(context)
+      raise ParticleStopped, self
     end
 
     def fail!(context = {})

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,35 @@ 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)
+
+        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 +161,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
@@ -41,7 +39,7 @@ module Laminar
 
       def run_condition(target)
         if @condition.is_a?(Proc)
-          @condition.call()
+          @condition.call(target.context)
         else
           target.send(@condition)
         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

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)
@@ -43,7 +44,7 @@ module Laminar
 
         param_list = context_slice
         param_list.empty? ? call : call(context_slice)
-        run_after_callbacks
+        run_after_callbacks unless context.halted?
         context
       end
 

data/lib/laminar/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: laminar
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Robert Lockerd
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-12 00:00:00.000000000 Z
+date: 2018-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -91,6 +91,7 @@ files:
 - ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md