trailblazer-circuit 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c9e50c60fbd29ee44bc11f122198acec25c02122
-  data.tar.gz: de1fb71290d6c4a817827bfad946cf739a1d4291
+  metadata.gz: d3c9b6666028fb2423dace64b0d84dfd67427e3a
+  data.tar.gz: a2ec4fb343197e3c512a0a0bb1c1a924ecdbee57
 SHA512:
-  metadata.gz: c8b5ea44e5ca1a618da4c4b4c5130d27700ada1766c621e4753e4d58765995f6799490e3b842f89183ec1ea860704e0c3d55549270cc1a539fab93b5f503269c
-  data.tar.gz: 0cf6a6dd1cc39496a236eb2d816e360efca4f60d263a0d591a8f799890bc5e29bd3a8a0ccdcf9b89aa04b11071b40cf7aa0b196e6a7d41f2bf1273df2c646747
+  metadata.gz: 72059d24e47902a25d385fd8103907bec6bcdccfbf1bccc443779c2b9d9390bd37c9cced154089aff1741f8974d586350e615ee98a422e32bd89957dc2974cf6
+  data.tar.gz: 5a9312bd96dafe6e8675a17c0b8f6c6f32504a15437f48ade8f2131f8c0178ba458456f3102b03d62e1beab93bc08c56c7e7abafdd6c30ab4707e0fcf5bb91c8

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 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.
+
 # 0.0.4
 
 * Simpler tracing with `Stack`.

data/lib/trailblazer/circuit/trace.rb

@@ -7,19 +7,12 @@ module Trailblazer
     #   puts Trailblazer::Circuit::Present.tree(stack) # renders the trail.
     module Trace
       def self.call(activity, direction, options, flow_options={})
-        # activity_wrap is the circuit/pipeline that wraps each step and implements tracing (and more, like input/output contracts, etc!).
-        activity_wrap = Activity::Before( Activity::Wrapped::Activity, Activity::Wrapped::Call, Trace.method(:capture_args), direction: Right )
-        activity_wrap = Activity::Before( activity_wrap, Activity::Wrapped::Activity[:End], Trace.method(:capture_return), direction: Right )
-
-        step_runners = {
-          nil   => activity_wrap, # call all steps with tracing.
-        }
-
         tracing_flow_options = {
-          runner:       Activity::Wrapped::Runner,
-          stack:        Circuit::Trace::Stack.new,
-          step_runners: step_runners,
-          debug:        activity.circuit.instance_variable_get(:@name)
+          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?
         }
 
         direction, options, flow_options = activity.( direction, options, tracing_flow_options.merge(flow_options) )
@@ -27,16 +20,26 @@ module Trailblazer
         return flow_options[:stack].to_a, direction, options, flow_options
       end
 
+      # TODO: test alterations with any wrap_circuit.
+
+      # 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_circuit[:End],      Trace.method(:capture_return), direction: Right ) },
+        ]
+      end
+
       def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
         original_flow_options[:stack].indent!
 
-        original_flow_options[:stack] << [ wrap_config[:step], :args, nil, options.dup, original_flow_options[:debug] ]
+        original_flow_options[:stack] << [ wrap_config[:task], :args, nil, options.dup, original_flow_options[:debug] ]
 
         [ direction, options, flow_options, wrap_config, original_flow_options ]
       end
 
       def self.capture_return(direction, options, flow_options, wrap_config, original_flow_options)
-        original_flow_options[:stack] << [ wrap_config[:step], :return, flow_options[:result_direction], options.dup ]
+        original_flow_options[:stack] << [ wrap_config[:task], :return, flow_options[:result_direction], options.dup ]
 
         original_flow_options[:stack].unindent!
 

data/lib/trailblazer/circuit/version.rb

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

data/lib/trailblazer/circuit/wrapped.rb

@@ -1,9 +1,52 @@
 class Trailblazer::Circuit
+  # Lingo: task_wrap
   module Activity::Wrapped
-    # Input  = ->(direction, options, flow_options) { [direction, options, flow_options] }
+    # 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[:step]
+      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 )
@@ -13,46 +56,17 @@ class Trailblazer::Circuit
 
     Call = method(:call_activity)
 
-    # Output = ->(direction, options, flow_options) { [direction, options, flow_options] }
-
     class End < Trailblazer::Circuit::End
       def call(direction, options, flow_options, wrap_config, *args)
-        [ wrap_config[:result_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
-        # Input                => { Circuit::Right => Trace::CaptureArgs },
-        # MyInject               => { Circuit::Right => Trace::CaptureArgs },
-        # Trace::CaptureArgs   => { Circuit::Right => Call  },
-        Call                 => { Right => act[:End] },
-        # Trace::CaptureReturn => { Circuit::Right => Output },
-        # Output               => { Circuit::Right => act[:End] }
+        act[:Start] => { Right => Call },                  # options from outside
+        Call        => { Right => act[:End] },
       }
-    end
-
-    # Find the respective wrap per task, and run it.
-    class Runner
-      # private flow_options[ :step_runners ]
-      def self.call(task, direction, options, flow_options)
-        # TODO: test this decider!
-        task_wrap = flow_options[:step_runners][task] || flow_options[:step_runners][nil] # DISCUSS: default could be more explicit@
-
-        # we can't pass :runner in here since the Step::Pipeline would call itself again, then.
-        # However, we need the runner in nested activities.
-        wrap_config = { step: 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 ) # all tasks in Wrap have to implement this signature.
-      end
-    end # Runner
+    end # Activity
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-circuit
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-06 00:00:00.000000000 Z
+date: 2017-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler