trailblazer-activity 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cda2a49909b44be7195fed23b15bb82f6d4d4ac4
-  data.tar.gz: 3d17e44f5c91ca1a61797d1f3d5f8d515362c2ad
+  metadata.gz: 81fa1b9e57d3f63ee5ee4b5caadea44250fcdbad
+  data.tar.gz: ba3e8fc06d51e146702ac7b6eb6765fe3af6e7ee
 SHA512:
-  metadata.gz: 70ca9ad73d4993f6295ee2dfc40b527c46fc25fc7e3384ec6dd7f57f726db5c7599affda8cfec180430020cb8f6a4340892921008bd0a1b3e54f4fa362e3dcc8
-  data.tar.gz: 13400c97fecca6f83d0282205af04c7f60f7136b4f5f6a7175ed5035277a12e9bf9a22044102577fcca26187fa6badf5185246a3dba61c87e1eab5f06b98ac57
+  metadata.gz: 62291d8bbb37376be5e1c6548c35d7df00a7edf654697ac26ed786d55a2bdf49de6130ad0bcfa3a221ff1dbf30935f9ae6d7f2fbe3d143bd4ae42c52d106b110
+  data.tar.gz: 3503a6d13258343169a5eddbcc99fa63a169f493dcde5e42962e03775b97c9f09bb9ed68aaa9891ee13a262539dda4051ac4b7e5895b3f01a93f3b4acdd08184

data/CHANGES.md

@@ -1,3 +1,8 @@
+# 0.2.1
+
+* Restructure all `Wrap`-specific tasks.
+* Remove `Hash::Immutable`, we will use the `hamster` gem instead.
+
 # 0.2.0
 
 * The `Activity#call` API is now

data/lib/trailblazer/activity.rb

@@ -11,9 +11,16 @@ module Trailblazer
   require "trailblazer/activity/version"
   require "trailblazer/activity/graph"
   require "trailblazer/activity/subprocess"
+
+  require "trailblazer/activity/wrap"
+  require "trailblazer/wrap/variable_mapping"
+  require "trailblazer/wrap/call_task"
+  require "trailblazer/wrap/trace"
+  require "trailblazer/wrap/inject"
+  require "trailblazer/wrap/runner"
+
   require "trailblazer/activity/trace"
   require "trailblazer/activity/present"
-  require "trailblazer/activity/wrap"
 
     # Only way to build an Activity.
     def self.from_wirings(wirings, &block)
@@ -125,8 +132,5 @@ module Trailblazer
         @graph.find_all { |node| node[:_wrapped] == task  }.first
       end
     end
-
-    module Interface
-    end
   end
 end

data/lib/trailblazer/activity/trace.rb

@@ -36,36 +36,17 @@ module Trailblazer
         block.(activity, *args)
       end
 
-      # Default tracing tasks to be plugged into the wrap circuit.
+      # Graph insertions for the trace tasks that capture the arguments just before calling the task,
+      # and before the TaskWrap is finished.
+      #
+      # Note that the TaskWrap steps are implemented in Activity::Wrap::Trace.
       def self.wirings
         [
-          [ :insert_before!, "task_wrap.call_task", node: [ Trace.method(:capture_args),   id: "task_wrap.capture_args" ], outgoing: [ Circuit::Right, {} ], incoming: ->(*) { true } ],
-          [ :insert_before!, "End.default",      node: [ Trace.method(:capture_return), id: "task_wrap.capture_return" ], outgoing: [ Circuit::Right, {} ], incoming: ->(*) { true } ],
+          [ :insert_before!, "task_wrap.call_task", node: [ Wrap::Trace.method(:capture_args),   id: "task_wrap.capture_args" ], outgoing: [ Circuit::Right, {} ], incoming: ->(*) { true } ],
+          [ :insert_before!, "End.default",         node: [ Wrap::Trace.method(:capture_return), id: "task_wrap.capture_return" ], outgoing: [ Circuit::Right, {} ], incoming: ->(*) { true } ],
         ]
       end
 
-      # def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
-      def self.capture_args((wrap_config, original_args), **circuit_options)
-        (original_options, original_flow_options, _) = original_args[0]
-
-        original_flow_options[:stack].indent!
-
-        original_flow_options[:stack] << [ wrap_config[:task], :args, nil, {}, original_flow_options[:introspection] ]
-
-        [ Circuit::Right, [wrap_config, original_args ], **circuit_options ]
-      end
-
-      def self.capture_return((wrap_config, original_args), **circuit_options)
-        (original_options, original_flow_options, _) = original_args[0]
-
-        original_flow_options[:stack] << [ wrap_config[:task], :return, wrap_config[:result_direction], {} ]
-
-        original_flow_options[:stack].unindent!
-
-
-        [ Circuit::Right, [wrap_config, original_args ], **circuit_options ]
-      end
-
       # Mutable/stateful per design. We want a (global) stack!
       class Stack
         def initialize

data/lib/trailblazer/activity/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Activity
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/trailblazer/activity/wrap.rb

@@ -1,68 +1,5 @@
 class Trailblazer::Activity
   module Wrap
-    # The runner is passed into Activity#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
-      # Runner signature: call( task, direction, options, static_wraps )
-      #
-      # @api private
-      # @interface Runner
-      def self.call(task, (options, *args), wrap_runtime: raise, wrap_static: raise, **circuit_options)
-        wrap_ctx = { task: task }
-
-        # this activity is "wrapped around" the actual `task`.
-        task_wrap_activity = apply_wirings(task, wrap_static, wrap_runtime)
-
-        # We save all original args passed into this Runner.call, because we want to return them later after this wrap
-        # is finished.
-        original_args = [ [options, *args], circuit_options.merge( wrap_runtime: wrap_runtime, wrap_static: wrap_static ) ]
-
-        # call the wrap for the task.
-        wrap_end_signal, ( wrap_ctx, _ ) = task_wrap_activity.(
-          [ wrap_ctx, original_args ] # we omit circuit_options here on purpose, so the wrapping activity uses the plain Runner.
-        )
-
-        # don't return the wrap's end signal, but the one from call_task.
-        # return all original_args for the next "real" task in the circuit (this includes circuit_options).
-
-        # raise if wrap_ctx[:result_args][2] != static_wraps
-
-        # TODO: make circuit ignore all returned but the first
-        [ wrap_ctx[:result_direction], wrap_ctx[:result_args] ]
-      end
-
-      private
-
-      # Compute the task's wrap by applying alterations both static and from runtime.
-      #
-      # NOTE: this is for performance reasons: we could have only one hash containing everything but that'd mean
-      # unnecessary computations at `call`-time since steps might not even be executed.
-      def self.apply_wirings(task, wrap_static, wrap_runtime)
-        wrap_activity = wrap_static[task]   # find static wrap for this specific task, or default wrap activity.
-
-        # Apply runtime alterations.
-        # Grab the additional wirings for the particular `task` from `wrap_runtime` (returns default otherwise).
-        wrap_activity = Trailblazer::Activity.merge(wrap_activity, wrap_runtime[task])
-      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((wrap_ctx, original_args), **circuit_options)
-      task  = wrap_ctx[:task]
-
-      # Call the actual task we're wrapping here.
-      puts "~~~~wrap.call: #{task}"
-      wrap_ctx[:result_direction], wrap_ctx[:result_args] = task.( *original_args )
-
-      # DISCUSS: do we want original_args here to be passed on, or the "effective" result_args which are different to original_args now?
-      [ Trailblazer::Circuit::Right, [ wrap_ctx, original_args ], **circuit_options ]
-    end
-
-    Call = method(:call_task)
-
     # Wrap::Activity is the actual circuit that implements the Task wrap. This circuit is
     # also known as `task_wrap`.
     #
@@ -86,7 +23,7 @@ class Trailblazer::Activity
       Trailblazer::Activity.from_wirings(
         [
           [ :attach!, target: [ Trailblazer::Circuit::End.new(:default), type: :event, id: "End.default" ], edge: [ Trailblazer::Circuit::Right, {} ] ],
-          [ :insert_before!, "End.default", node: [ Call, id: "task_wrap.call_task" ], outgoing: [ Trailblazer::Circuit::Right, {} ], incoming: ->(*) { true } ]
+          [ :insert_before!, "End.default", node: [ Wrap.method(:call_task), id: "task_wrap.call_task" ], outgoing: [ Trailblazer::Circuit::Right, {} ], incoming: ->(*) { true } ]
         ]
       )
     end

data/lib/trailblazer/context.rb

@@ -60,38 +60,6 @@ module Trailblazer
         end
       end
     end
-
-    # FIXME
-      # TODO: rename Context::Hash::Immutable
-      class Immutable
-        def initialize(hash)
-          @hash = hash
-        end
-
-        def [](key)
-          @hash[key]
-        end
-
-        def to_hash # DISCUSS: where do we call this?
-          @hash.to_hash # FIXME: should we do this?
-        end
-
-        def key?(key)
-          @hash.key?(key)
-        end
-
-        def merge(hash)
-          @hash.merge(hash)
-        end
-
-        def keys
-          @hash.keys
-        end
-
-        # DISCUSS: raise in #[]=
-        # each
-        # TODO: Skill could inherit
-      end
   end
 
   def self.Context(wrapped_options, mutable_options={})

data/lib/trailblazer/wrap/call_task.rb

@@ -0,0 +1,19 @@
+class Trailblazer::Activity
+  module Wrap
+    # TaskWrap step that calls the actual wrapped task and passes all `original_args` to it.
+    #
+    # It writes to wrap_ctx[:result_direction], wrap_ctx[:result_args]
+    def self.call_task((wrap_ctx, original_args), **circuit_options)
+      task  = wrap_ctx[:task]
+
+      # Call the actual task we're wrapping here.
+      puts "~~~~wrap.call: #{task}"
+      result_direction, result_args = task.( *original_args ) # we lose :exec_context here.
+
+      # DISCUSS: do we want original_args here to be passed on, or the "effective" result_args which are different to original_args now?
+      wrap_ctx = wrap_ctx.merge( result_direction: result_direction, result_args: result_args )
+
+      [ Trailblazer::Circuit::Right, [ wrap_ctx, original_args ], **circuit_options ]
+    end
+  end # Wrap
+end

data/lib/trailblazer/wrap/inject.rb

@@ -0,0 +1,32 @@
+class Trailblazer::Activity
+  module Wrap
+    module Inject
+      # Returns an Alteration wirings that, when applied, inserts the {ReverseMergeDefaults} task
+      # before the {Wrap::Call} task. This is meant for macros and steps that accept a dependency
+      # injection but need a default parameter to be set if not injected.
+      # @returns Alteration
+      def self.Defaults(default_dependencies)
+        [
+          [ :insert_before!, "task_wrap.call_task", node: [ ReverseMergeDefaults.new( default_dependencies ), id: "ReverseMergeDefaults#{default_dependencies}" ], incoming: Proc.new{ true }, outgoing: [ Trailblazer::Circuit::Right, {} ] ]
+        ]
+      end
+
+      # @api private
+      # @returns Task
+      # @param Hash list of key/value that should be set if not already assigned/set before (or injected from the outside).
+      class ReverseMergeDefaults
+        def initialize(defaults)
+          @defaults = defaults
+        end
+
+        def call((wrap_ctx, original_args), **circuit_options)
+          ctx = original_args[0][0]
+
+          @defaults.each { |k, v| ctx[k] ||= v }
+
+          [ Trailblazer::Circuit::Right, [wrap_ctx, original_args] ]
+        end
+      end
+    end # Inject
+  end
+end

data/lib/trailblazer/wrap/runner.rb

@@ -0,0 +1,48 @@
+class Trailblazer::Activity
+  module Wrap
+    # The runner is passed into Activity#call( runner: Runner ) and is called for every task in the circuit.
+    # It runs the TaskWrap per task.
+    #
+    # (wrap_ctx, original_args), **wrap_circuit_options
+    module Runner
+      # Runner signature: call( task, direction, options, static_wraps )
+      #
+      # @api private
+      # @interface Runner
+      def self.call(task, args, wrap_runtime: raise, wrap_static: raise, **circuit_options)
+        wrap_ctx = { task: task }
+
+        # this activity is "wrapped around" the actual `task`.
+        task_wrap_activity = apply_wirings(task, wrap_static, wrap_runtime)
+
+        # We save all original args passed into this Runner.call, because we want to return them later after this wrap
+        # is finished.
+        original_args = [ args, circuit_options.merge( wrap_runtime: wrap_runtime, wrap_static: wrap_static ) ]
+
+        # call the wrap {Activity} around the task.
+        wrap_end_signal, ( wrap_ctx, _ ) = task_wrap_activity.(
+          [ wrap_ctx, original_args ] # we omit circuit_options here on purpose, so the wrapping activity uses the default, plain Runner.
+        )
+
+        # don't return the wrap's end signal, but the one from call_task.
+        # return all original_args for the next "real" task in the circuit (this includes circuit_options).
+
+        [ wrap_ctx[:result_direction], wrap_ctx[:result_args] ]
+      end
+
+      private
+
+      # Compute the task's wrap by applying alterations both static and from runtime.
+      #
+      # NOTE: this is for performance reasons: we could have only one hash containing everything but that'd mean
+      # unnecessary computations at `call`-time since steps might not even be executed.
+      def self.apply_wirings(task, wrap_static, wrap_runtime)
+        wrap_activity = wrap_static[task]   # find static wrap for this specific task, or default wrap activity.
+
+        # Apply runtime alterations.
+        # Grab the additional wirings for the particular `task` from `wrap_runtime` (returns default otherwise).
+        wrap_activity = Trailblazer::Activity.merge(wrap_activity, wrap_runtime[task])
+      end
+    end # Runner
+  end
+end

data/lib/trailblazer/wrap/trace.rb

@@ -0,0 +1,27 @@
+class Trailblazer::Activity
+  module Wrap
+    module Trace
+      # def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
+      def self.capture_args((wrap_config, original_args), **circuit_options)
+        (original_options, original_flow_options, _) = original_args[0]
+
+        original_flow_options[:stack].indent!
+
+        original_flow_options[:stack] << [ wrap_config[:task], :args, nil, {}, original_flow_options[:introspection] ]
+
+        [ Trailblazer::Circuit::Right, [wrap_config, original_args], **circuit_options ]
+      end
+
+      def self.capture_return((wrap_config, original_args), **circuit_options)
+        (original_options, original_flow_options, _) = original_args[0]
+
+        original_flow_options[:stack] << [ wrap_config[:task], :return, wrap_config[:result_direction], {} ]
+
+        original_flow_options[:stack].unindent!
+
+
+        [ Trailblazer::Circuit::Right, [wrap_config, original_args], **circuit_options ]
+      end
+    end
+  end
+end

data/lib/trailblazer/wrap/variable_mapping.rb

@@ -0,0 +1,92 @@
+class Trailblazer::Activity
+  module Wrap
+    # TaskWrap step to compute the incoming {Context} for the wrapped task.
+    # This allows renaming, filtering, hiding, of the options passed into the wrapped task.
+    #
+    # Both Input and Output are typically to be added before and after task_wrap.call_task.
+    #
+    # @note Assumption: we always have :input _and_ :output, where :input produces a Context and :output decomposes it.
+    class Input
+      def initialize(filter)
+        @filter = Trailblazer::Option(filter)
+      end
+
+      # `original_args` are the actual args passed to the wrapped task: [ [options, ..], circuit_options ]
+      #
+      def call((wrap_ctx, original_args), **circuit_options)
+        # let user compute new ctx for the wrapped task.
+        input_ctx = apply_filter(*original_args)
+
+        # TODO: make this unnecessary.
+        # wrap user's hash in Context if it's not one, already (in case user used options.merge).
+        # DISCUSS: should we restrict user to .merge and options.Context?
+        input_ctx = Trailblazer.Context({}, input_ctx) unless input_ctx.instance_of?(Trailblazer::Context)
+
+        wrap_ctx = wrap_ctx.merge( vm_original_args: original_args )
+
+        # decompose the original_args since we want to modify them.
+        (original_ctx, original_flow_options), original_circuit_options = original_args
+
+        # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
+        return Trailblazer::Circuit::Right, [ wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options] ]
+      end
+
+      private
+
+      def apply_filter((original_ctx, original_flow_options), original_circuit_options)
+        @filter.( original_ctx, **original_circuit_options )
+      end
+    end
+
+    # TaskWrap step to compute the outgoing {Context} from the wrapped task.
+    # This allows renaming, filtering, hiding, of the options returned from the wrapped task.
+    class Output
+      def initialize(filter, strategy=CopyMutableToOriginal)
+        @filter   = Trailblazer::Option(filter)
+        @strategy = strategy
+      end
+
+      # Runs the user filter and replaces the ctx in `wrap_ctx[:result_args]` with the filtered one.
+      def call((wrap_ctx, original_args), **circuit_options)
+        (original_ctx, original_flow_options), original_circuit_options = original_args
+
+        returned_ctx, _ = wrap_ctx[:result_args] # this is the context returned from `call`ing the task.
+
+        # returned_ctx is the Context object from the nested operation. In <=2.1, this might be a completely different one
+        # than "ours" we created in Input. We now need to compile a list of all added values. This is time-intensive and should
+        # be optimized by removing as many Context creations as possible (e.g. the one adding self[] stuff in Operation.__call__).
+        _, mutable_data = returned_ctx.decompose # FIXME: this is a weak assumption. What if the task returns a deeply nested Context?
+
+        # let user compute the output.
+        output = apply_filter(mutable_data, original_flow_options, original_circuit_options)
+
+        original_ctx = wrap_ctx[:vm_original_args][0][0]
+
+        new_ctx = @strategy.( original_ctx, output ) # here, we compute the "new" options {Context}.
+
+        wrap_ctx = wrap_ctx.merge( result_args: [new_ctx, original_flow_options] )
+
+        # and then pass on the "new" context.
+        return Trailblazer::Circuit::Right, [ wrap_ctx, original_args ]
+      end
+
+      private
+
+      # @note API not stable
+      def apply_filter(mutable_data, original_flow_options, original_circuit_options)
+        @filter.(mutable_data, **original_circuit_options)
+      end
+
+      # "merge" Strategy
+      class CopyMutableToOriginal
+        # @param original Context
+        # @param options  Context The object returned from a (nested) {Activity}.
+        def self.call(original, mutable)
+          mutable.each { |k,v| original[k] = v }
+
+          original
+        end
+      end
+    end
+  end # Wrap
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-11 00:00:00.000000000 Z
+date: 2017-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hirb
@@ -108,6 +108,11 @@ files:
 - lib/trailblazer/container_chain.rb
 - lib/trailblazer/context.rb
 - lib/trailblazer/option.rb
+- lib/trailblazer/wrap/call_task.rb
+- lib/trailblazer/wrap/inject.rb
+- lib/trailblazer/wrap/runner.rb
+- lib/trailblazer/wrap/trace.rb
+- lib/trailblazer/wrap/variable_mapping.rb
 - trailblazer-activity.gemspec
 homepage: http://trailblazer.to/gems/workflow
 licenses: