trailblazer-circuit 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d3c9b6666028fb2423dace64b0d84dfd67427e3a
-  data.tar.gz: a2ec4fb343197e3c512a0a0bb1c1a924ecdbee57
+  metadata.gz: f5dc593717272d4f702fc5f2f9f0ba48481cfbad
+  data.tar.gz: 108fd37110388fb3d4d45f79787ab284e7434b3a
 SHA512:
-  metadata.gz: 72059d24e47902a25d385fd8103907bec6bcdccfbf1bccc443779c2b9d9390bd37c9cced154089aff1741f8974d586350e615ee98a422e32bd89957dc2974cf6
-  data.tar.gz: 5a9312bd96dafe6e8675a17c0b8f6c6f32504a15437f48ade8f2131f8c0178ba458456f3102b03d62e1beab93bc08c56c7e7abafdd6c30ab4707e0fcf5bb91c8
+  metadata.gz: 69bbd08cd6cba1c394bc5da24c4d1df1cf7cf6420a3a60c23caf085bd627d5460ffe9c965d7f703466b37f3756347b220c3f8d1fcbf6ddf06abab5b1b6dc220e
+  data.tar.gz: 1714df50a75d590b5ce04c914b1ab0ac6910bf583998551b577697367a22ca69d43d8e47ba8f5b8bb04bbc868c140f5d16bfc0cb7c3f9cd0dd2f3d178da1dd5b

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.0.6
+
+* `Wrapped` is now `Wrap`. Also, a consistent `Alterations` interface allows tweaking here.
+
 # 0.0.5
 
 * The `Wrapped::Runner` now applies `Alterations` to each task's `Circuit`. This means you can inject `:task_alterations` into `Circuit#call`, which will then be merged into the task's original circuit, and then run. While this might sound like crazy talk, this allows any kind of external injection (tracing, input/output contracts, step dependency injections, ...) for specific or all tasks of any circuit.

data/lib/trailblazer/circuit.rb

@@ -123,6 +123,6 @@ require "trailblazer/circuit/task"
 require "trailblazer/circuit/alter"
 require "trailblazer/circuit/trace"
 require "trailblazer/circuit/present"
-require "trailblazer/circuit/wrapped"
+require "trailblazer/circuit/wrap"
 
 require "trailblazer/context"

data/lib/trailblazer/circuit/trace.rb

@@ -6,26 +6,30 @@ module Trailblazer
     #   stack, _ = Trailblazer::Circuit::Trace.(activity, activity[:Start], { id: 1 })
     #   puts Trailblazer::Circuit::Present.tree(stack) # renders the trail.
     module Trace
-      def self.call(activity, direction, options, flow_options={})
+      def self.call(activity, direction, options, flow_options={}, &block)
         tracing_flow_options = {
-          runner:           Activity::Wrapped::Runner,
-          stack:            Trace::Stack.new,
-          wrap_alterations: Activity::Wrapped::Alterations.new(Trace.Alterations),
-          task_wraps:       Activity::Wrapped::Wraps.new(Activity::Wrapped::Activity),
-          debug: {}, # TODO: set that in Activity::call?
+          runner:       Wrap::Runner,
+          stack:        Trace::Stack.new,
+          wrap_runtime: Wrap::Alterations.new(default: Trace.Alterations),
+          wrap_static:  Wrap::Alterations.new,
+          debug:        {}, # usually set that in Activity::call.
         }
 
-        direction, options, flow_options = activity.( direction, options, tracing_flow_options.merge(flow_options) )
+        direction, options, flow_options = call_circuit( activity, direction, options, tracing_flow_options.merge(flow_options), &block )
 
         return flow_options[:stack].to_a, direction, options, flow_options
       end
 
       # TODO: test alterations with any wrap_circuit.
+      def self.call_circuit(activity, *args, &block)
+        return activity.(*args) unless block
+        block.(activity, *args)
+      end
 
       # Default tracing tasks to be plugged into the wrap circuit.
       def self.Alterations
         [
-        ->(wrap_circuit) { Activity::Before( wrap_circuit, Activity::Wrapped::Call, Trace.method(:capture_args),   direction: Right ) },
+        ->(wrap_circuit) { Activity::Before( wrap_circuit, Wrap::Call, Trace.method(:capture_args),   direction: Right ) },
         ->(wrap_circuit) { Activity::Before( wrap_circuit, wrap_circuit[:End],      Trace.method(:capture_return), direction: Right ) },
         ]
       end

data/lib/trailblazer/circuit/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Circuit
-    VERSION = "0.0.5"
+    VERSION = "0.0.6"
   end
 end

data/lib/trailblazer/circuit/wrap.rb

@@ -0,0 +1,107 @@
+class Trailblazer::Circuit
+  module Wrap
+    # The runner is passed into Circuit#call( runner: Runner ) and is called for every task in the circuit.
+    # Its primary job is to actually `call` the task.
+    #
+    # Here, we extend this, and wrap the task `call` into its own pipeline, so we can add external behavior per task.
+    module Runner
+      NIL_WRAPS      = "Please provide :wrap_static"  # here for Ruby 2.0 compat.
+      NIL_ALTERATION = "Please provide :wrap_runtime" # here for Ruby 2.0 compat.
+
+      # @api private
+      def self.call(task, direction, options, wrap_static:raise(NIL_WRAPS), wrap_runtime:raise(NIL_ALTERATION), **flow_options)
+        task_wrap   = apply_alterations(task, wrap_static, wrap_runtime)
+
+        wrap_config = { task: task }
+
+        # Call the task_wrap circuit:
+        #   |-- Start
+        #   |-- Trace.capture_args   [optional]
+        #   |-- Call (call actual task)
+        #   |-- Trace.capture_return [optional]
+        #   |-- End
+        # Pass empty flow_options to the task_wrap, so it doesn't infinite-loop.
+        task_wrap.( task_wrap[:Start], options, {}, wrap_config, flow_options.merge( wrap_static: wrap_static, wrap_runtime: wrap_runtime) )
+      end
+
+      private
+
+      # Compute the task's wrap by applying alterations both static and from runtime.
+      def self.apply_alterations(task, wrap_static, wrap_runtime, default_wrap=Activity)
+        task_wrap = wrap_static.(task, Activity)   # find static wrap for this specific task, Activity is the default wrap.
+        task_wrap = wrap_runtime.(task, task_wrap) # apply runtime alterations.
+      end
+    end # Runner
+
+    # The call_task method implements one default step `Call` in the Wrap::Activity circuit.
+    # It calls the actual, wrapped task.
+    def self.call_task(direction, options, flow_options, wrap_config, original_flow_options)
+      task  = wrap_config[:task]
+
+      # Call the actual task we're wrapping here.
+      wrap_config[:result_direction], options, flow_options = task.( direction, options, original_flow_options )
+
+      [ direction, options, flow_options, wrap_config, original_flow_options ]
+    end
+
+    Call = method(:call_task)
+
+    class End < Trailblazer::Circuit::End
+      def call(direction, options, flow_options, wrap_config, *args)
+        [ wrap_config[:result_direction], options, flow_options ] # note how we don't return the appended internal args.
+      end
+    end
+
+    # Wrap::Activity is the actual circuit that implements the Task wrap. This circuit is
+    # also known as `task_wrap`.
+    #
+    # Example with tracing:
+    #
+    #   |-- Start
+    #   |-- Trace.capture_args   [optional]
+    #   |-- Call (call actual task)
+    #   |-- Trace.capture_return [optional]
+    #   |-- End
+    Activity = Trailblazer::Circuit::Activity({ id: "task.wrap" }, end: { default: End.new(:default) }) do |act|
+      {
+        act[:Start] => { Right => Call }, # see Wrap::call_task
+        Call        => { Right => act[:End] },
+      }
+    end # Activity
+
+    # Alterations#call finds alterations for `task` and applies them to `task_wrap`.
+    # Each alteration receives the result of the former one, starting with `task_wrap`.
+    #
+    # This is used to add tracing steps, input/output contracts, and more at runtime,
+    # or to maintain specific static task_wraps, as for each step in an operation.
+    #
+    # Note that an alteration doesn't have to respect its `task_wrap` and can simply return
+    # an arbitrary Circuit.
+    #
+    # === DESIGN
+    # By moving the "default" decision to this object, you can control what task gets wrapped
+    # with what wrap, allowing you to only wrap "focussed" tasks, for example.
+    #
+    # It also allows to inject, say, a tracing alteration that is only applied to a specific task
+    # and returns all others unchanged.
+    class Alterations
+      PassThrough = ->(task_wrap) { task_wrap }
+
+      def initialize(map: {}, default: [ PassThrough ])
+        @default_alterations, @map = default, map
+      end
+
+      # @returns Circuit
+      def call(task, target_wrap)
+        get(task). # list of alterations.
+          inject(target_wrap) { |circuit, alteration| alteration.(circuit) }
+      end
+
+      private
+
+      def get(task)
+        @map[task] || @default_alterations
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-circuit
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-07 00:00:00.000000000 Z
+date: 2017-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -103,7 +103,7 @@ files:
 - lib/trailblazer/circuit/testing.rb
 - lib/trailblazer/circuit/trace.rb
 - lib/trailblazer/circuit/version.rb
-- lib/trailblazer/circuit/wrapped.rb
+- lib/trailblazer/circuit/wrap.rb
 - lib/trailblazer/context.rb
 - trailblazer-circuit.gemspec
 homepage: http://trailblazer.to/gems/workflow
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: BPMN-compliant workflows or state machines.

data/lib/trailblazer/circuit/wrapped.rb

@@ -1,72 +0,0 @@
-class Trailblazer::Circuit
-  # Lingo: task_wrap
-  module Activity::Wrapped
-    # The runner is passed into Circuit#call( runner: Runner ) and is called for every task in the circuit.
-    # Its primary job is to actually `call` the task.
-    #
-    # Here, we extend this, and wrap the task `call` into its own pipeline, so we can add external behavior per task.
-    class Runner
-      # private flow_options[ :task_wraps ] # DISCUSS: move to separate arg?
-      # @api private
-      def self.call(task, direction, options, task_wraps:raise, wrap_alterations:{}, **flow_options)
-        # TODO: test this decider!
-        task_wrap   = task_wraps[task] || raise("test me!")
-        task_wrap   = wrap_alterations.(task, task_wrap)
-
-        wrap_config = { task: task }
-
-        # Call the task_wrap circuit:
-        #   |-- Start
-        #   |-- Trace.capture_args   [optional]
-        #   |-- Call (call actual task)
-        #   |-- Trace.capture_return [optional]
-        #   |-- End
-        # Pass empty flow_options to the task_wrap, so it doesn't infinite-loop.
-        task_wrap.( task_wrap[:Start], options, {}, wrap_config, flow_options.merge( task_wraps: task_wraps, wrap_alterations: wrap_alterations) )
-      end
-    end # Runner
-
-    class Wraps
-      def initialize(default, hash={})
-        @default, @hash = default, hash
-      end
-
-      def [](task)
-        @hash.fetch(task) { @default }
-      end
-    end
-
-    class Alterations < Wraps
-      # Find alterations for `task` and apply them to `task_wrap`.
-      # This usually means that tracing steps/tasks are added, input/output contracts added, etc.
-      def call(task, task_wrap)
-        self[task].
-          inject(task_wrap) { |circuit, alteration| alteration.(circuit) }
-      end
-    end
-
-    def self.call_activity(direction, options, flow_options, wrap_config, original_flow_options)
-      task  = wrap_config[:task]
-
-      # Call the actual task we're wrapping here.
-      wrap_config[:result_direction], options, flow_options = task.( direction, options, original_flow_options )
-
-      [ direction, options, flow_options, wrap_config, original_flow_options ]
-    end
-
-    Call = method(:call_activity)
-
-    class End < Trailblazer::Circuit::End
-      def call(direction, options, flow_options, wrap_config, *args)
-        [ wrap_config[:result_direction], options, flow_options ] # note how we don't return the appended internal args.
-      end
-    end
-
-    Activity = Trailblazer::Circuit::Activity({ id: "task.wrap" }, end: { default: End.new(:default) }) do |act|
-      {
-        act[:Start] => { Right => Call },                  # options from outside
-        Call        => { Right => act[:End] },
-      }
-    end # Activity
-  end
-end