trailblazer-activity 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14060aa9266dec50a2538bfddacb622d1fcefeba94b92fade757e039ea8aab4f
-  data.tar.gz: 4bcd28d5b77dc9023c43edb0d762a4ac228fa36012a275f3830f56db9e71e795
+  metadata.gz: 656825c80059310cf4a2d89a2214a20618bbd688c182285e8d3c24c8475b8233
+  data.tar.gz: 4fb358255fe07a12fcb94172a05f466ce3ac0cb66d3b9502a3622d2a4392a71f
 SHA512:
-  metadata.gz: 95e528103b854970aa5b168ce89e8164ae0bdd64ffa21deec24fbd05aa6ca8700d2aa252f5ee3b7b12d2ffe9e592fbb6f3424a9208aa86be96b167fb7bc0c036
-  data.tar.gz: '09e520f7372cd6d604dc5444484bc561e29e4c1462fd2298bc6d9d4d6a1571eadb37dd7150988cf94a53fe0b218a94529e0fd38e5e2fb31a57ca3ae017640dbc'
+  metadata.gz: 74361dffc29b0108e198a3a2bee9637b6519b2ad56b4fb9172aceffc92bee1bcb5dc5e1417dab33d9ba48340749bd5f4306bd16a2c22a1f5eb66cfea4991f04b
+  data.tar.gz: ad2fd6a2d6d4df1a2c8e167fd395ef05899f7389b95f8219239d4533c75632001992ff38eb240b300d1b2260544b85abd276372783f8a4c2480afc2a3e45a1a5

data/.travis.yml

@@ -1,14 +1,8 @@
 sudo: false
 language: ruby
 rvm:
-  # - 2.0
-  - 2.1
-  - 2.2
-  - 2.3.3
-  - 2.4.3
-  - 2.5.0
-matrix:
-  include:
-  - rvm: jruby-head
-    env: JRUBY_OPTS="--profile.api"
+  - 2.5.1
+  - 2.4.4
+  - 2.3.7
+  - 2.2.10
 before_install: gem install bundler

data/CHANGES.md

@@ -1,3 +1,25 @@
+# 0.6.0
+
+* The `:task` option in `Circuit::call` is now named `:start_task` for consistency.
+* Removed the `:argumenter` option for `Activity::call`. Instead, an `Activity` passes itself via the `:activity` option.
+* Removed the `:extension` option. Instead, any option from the DSL that `is_a?(DSL::Extension)` will be processed in `add_task!`.
+* Replace argumenters with `TaskWrap::invoke`. This simplifies the whole `call` process, and moves all initialization of args to the top.
+* Added `Introspect::Graph::find`.
+* Removed `Introspect::Enumerator` in favor of the `Graph` API.
+
+# 0.5.4
+
+* Introducing `Introspect::Enumerator` and removing `Introspect.find`. `Enumerator` contains `Enumerable` and exposes all necessary utility methods.
+
+# 0.5.3
+
+* In Path(), allow referencing an existing task, instead of creating an end event.
+    This avoids having to use two `Output() => ..` and is much cleaner.
+
+    ```ruby
+    Path( end_id: :find_model) do .. end
+    ```
+
 # 0.5.2
 
 * In `Path()`, we removed the `#path` method in favor of a cleaner `task` DSL method. We now use the default plus_poles `success` and `failure` everywhere for consistency. This means that a `task` has two outputs, and if you referenced `Output(:success)`, that would be only one of them. We're planning to have `pass` back which has one `success` plus_pole, only. This change makes the DSL wiring behavior much more consistent.

data/lib/trailblazer/activity/dsl/add_task.rb

@@ -12,10 +12,10 @@ class Trailblazer::Activity < Module
         self[:circuit] = circuit
         self[:outputs] = outputs
 
-        _, local_options = returned_options
+        _, local_options, connections, sequence_options, extension_options = returned_options
 
         # {Extension API} call all extensions.
-        local_options[:extension].collect { |ext| ext.( self, *returned_options, original_dsl_args: [name, task, options, block] ) } if local_options[:extension]
+        extension_options.keys.collect { |ext| ext.( self, *returned_options, original_dsl_args: [name, task, options, block] ) }
       end
     end
   end

data/lib/trailblazer/activity/dsl/helper.rb

@@ -15,6 +15,11 @@ module Trailblazer
     # @api private
     OutputSemantic = Struct.new(:value)
     Track          = Struct.new(:color)
+    Extension      = Struct.new(:callable) do
+      def call(*args, &block)
+        callable.(*args, &block)
+      end
+    end
 
     # Shortcut functions for the DSL. These have no state.
     module Helper

data/lib/trailblazer/activity/dsl/magnetic/builder/default_normalizer.rb

@@ -5,8 +5,8 @@ module Trailblazer
     #   task Callable, id: "success", before: "another"
     class DefaultNormalizer
       # Declarative::Variables
-      def self.build(plus_poles:, extension:[], **options)
-        return new(plus_poles: plus_poles, extension: extension), options
+      def self.build(plus_poles:, **options)
+        return new(plus_poles: plus_poles), options
       end
 
       def initialize(**default_options)
@@ -19,7 +19,7 @@ module Trailblazer
 
         local_options, sequence_options = Options.normalize( local_options, Activity::Schema::Dependencies.sequence_keywords )
 
-        return task, local_options, {}, sequence_options
+        return task, local_options, {}, sequence_options, {}
       end
     end
   end

data/lib/trailblazer/activity/dsl/magnetic/builder/normalizer.rb

@@ -30,9 +30,9 @@ module Trailblazer
           default_outputs: @default_outputs,
         }
 
-        signal, (ctx, ) = @pipeline.( [ctx] )
+        signal, (ctx, ) = @pipeline.( [ctx], {} )
 
-        return ctx[:options][:task], ctx[:local_options], ctx[:connection_options], ctx[:sequence_options]
+        return ctx[:options][:task], ctx[:local_options], ctx[:connection_options], ctx[:sequence_options], ctx[:extension_options]
       end
 
       # needs the basic Normalizer
@@ -42,15 +42,18 @@ module Trailblazer
         extend Trailblazer::Activity::Path( normalizer_class: DefaultNormalizer, plus_poles: PlusPoles.new.merge( Builder::Path.default_outputs.values ) ) # FIXME: the DefaultNormalizer actually doesn't need Left.
 
         def self.split_options( ctx, task:, options:, ** )
-          keywords = extract_dsl_keywords(options)
+          keywords   = extract_dsl_keywords(options)
+          extensions = extract_extensions(options)
 
            # sort through the "original" user DSL options.
+          options, extension_options      = Options.normalize( options, extensions ) # DISCUSS:
           options, local_options          = Options.normalize( options, keywords ) # DISCUSS:
           local_options, sequence_options = Options.normalize( local_options, Activity::Schema::Dependencies.sequence_keywords )
 
           ctx[:local_options],
           ctx[:connection_options],
-          ctx[:sequence_options] = local_options, options, sequence_options
+          ctx[:sequence_options],
+          ctx[:extension_options] = local_options, options, sequence_options, extension_options
         end
 
         # Filter out connections, e.g. `Output(:fail_fast) => :success` and return only the keywords like `:id` or `:replace`.
@@ -58,17 +61,19 @@ module Trailblazer
           options.keys - options.keys.find_all { |k| connection_classes.include?( k.class ) }
         end
 
+        def self.extract_extensions(options, extensions_classes = [Activity::DSL::Extension])
+          options.keys.find_all { |k| extensions_classes.include?( k.class ) }
+        end
+
         # FIXME; why don't we use the extensions passed into the initializer?
-        def self.normalize_extension_option( ctx, local_options:, ** )
-          local_options[:extension] = (local_options[:extension]||[]) + [ Activity::Introspect.method(:add_introspection), Activity::DSL.method(:record) ] # fixme: this sucks
+        def self.initialize_extension_option( ctx, options:, ** )
+          ctx[:options] = options.merge( Activity::DSL::Extension.new( Activity::DSL.method(:record) ) => true )
         end
 
-        # Normalizes ctx[:options]
+        # Normalizes ctx[:options] (the user-options via the DSL) into the internal Hash format.
         def self.normalize_for_macro( ctx, task:, options:, task_builder:, ** )
           ctx[:options] =
             if task.is_a?(::Hash) # macro.
-              options = options.merge(extension: (options[:extension]||[])+(task[:extension]||[]) ) # FIXME.
-
               task.merge(options) # Note that the user options are merged over the macro options.
             else # user step
               { id: task }
@@ -93,9 +98,9 @@ module Trailblazer
             .merge(local_options)
         end
 
+        task Activity::TaskBuilder::Binary( method(:initialize_extension_option) ), id: "initialize_extension_option"
         task Activity::TaskBuilder::Binary( method(:normalize_for_macro) ),        id: "normalize_for_macro"
         task Activity::TaskBuilder::Binary( method(:split_options) ),              id: "split_options"
-        task Activity::TaskBuilder::Binary( method(:normalize_extension_option) ), id: "normalize_extension_option"
         task Activity::TaskBuilder::Binary( method(:initialize_plus_poles) ),      id: "initialize_plus_poles"
         # task ->((ctx, _), **) { pp ctx; [Activity::Right, [ctx, _]] }
       end

data/lib/trailblazer/activity/dsl/magnetic/builder/path.rb

@@ -24,11 +24,15 @@ module Trailblazer
         end
 
         # @return [Adds] list of Adds instances that can be chained or added to an existing sequence.
-        def self.InitialAdds(track_color:raise, end_semantic:raise, start_outputs: {success: self.default_outputs[:success]}, track_end: Activity.End(end_semantic), **)
+        def self.InitialAdds(**options)
+          StartAdds(**options) + EndAdds(**options)
+        end
 
+        # TODO: make this nicer.
+        def self.StartAdds(track_color:, end_semantic:, start_outputs: {success: self.default_outputs[:success]}, **)
           builder_options={ track_color: track_color, end_semantic: end_semantic }
 
-          start_adds = adds(
+          adds(
             Activity::Start.new(semantic: :default),
 
             TaskPolarizations(builder_options),
@@ -39,20 +43,31 @@ module Trailblazer
             magnetic_to:  [],
             plus_poles:   PlusPoles.initial(start_outputs), # FIXME: this is actually redundant with Normalizer
           )
+        end
 
-          end_adds = adds(
-            track_end,
+        # TODO: make this nicer.
+        def self.EndAdds(track_color:, end_semantic:, track_end: Activity.End(end_semantic), end_id: nil, **)
+          # an end can either be a reference to another task,
+          # or a "real" end event.
+          if end_id
+            [[:magnetic_to,
+              [ end_id, [track_color] ] ]
+            ]
+          else
+            builder_options={ track_color: track_color, end_semantic: end_semantic }
 
-            EndEventPolarizations(builder_options),
+            adds(
+              track_end,
 
-            {}, { group: :end },
+              EndEventPolarizations(builder_options), # only sets :magnetic_to.
 
-            id:         "End.#{track_color}",
-            plus_poles: {},
-            magnetic_to: nil,
-          )
+              {}, { group: :end },
 
-          start_adds + end_adds
+              id:         "End.#{track_color}",
+              plus_poles: {},
+              magnetic_to: nil,
+            )
+          end
         end
 
         def self.TaskPolarizations(track_color:, **)

data/lib/trailblazer/activity/dsl/magnetic/builder.rb

@@ -42,23 +42,23 @@ module Trailblazer
       def insert(strategy, polarizer, task, options, &block)
         normalizer = options[:normalizer] || @normalizer # DISCUSS: do this at a deeper point?
 
-        task, local_options, connection_options, sequence_options = normalizer.(task, options)
+        task, local_options, connection_options, sequence_options, extension_options = normalizer.(task, options)
 
         polarizations = strategy.send(polarizer, @builder_options) # Railway.StepPolarizations( @builder_options )
 
-        insert_element( polarizations, task, local_options, connection_options, sequence_options, &block )
+        insert_element( polarizations, task, local_options, connection_options, sequence_options, extension_options, &block )
       end
 
       private
 
       # Internal top-level entry point to add task(s) and connections.
       # High level interface for DSL calls like ::task or ::step.
-      def insert_element(polarizations, task, local_options, connection_options, sequence_options, &block)
-        adds, *returned_options = Builder.adds_for(polarizations, task, local_options, connection_options, sequence_options, &block)
+      def insert_element(polarizations, task, local_options, connection_options, sequence_options, extension_options, &block)
+        adds, *returned_options = Builder.adds_for(polarizations, task, local_options, connection_options, sequence_options, extension_options, &block)
       end
 
       # @return Adds
-      def self.adds_for(polarizations, task, local_options, connection_options, sequence_options, &block)
+      def self.adds_for(polarizations, task, local_options, connection_options, sequence_options, extension_options, &block)
         # go through all wiring options such as Output()=>:color.
         polarizations_from_user_options, additional_adds = process_dsl_options(connection_options, local_options, &block)
 
@@ -66,7 +66,7 @@ module Trailblazer
 
         result = adds(task, polarizations, local_options, sequence_options, local_options)
 
-        return result + (local_options[:adds] || []) + additional_adds, task, local_options, connection_options, sequence_options
+        return result + (local_options[:adds] || []) + additional_adds, task, local_options, connection_options, sequence_options, extension_options
       end
 
       def self.process_dsl_options(options, id:nil, plus_poles:, **, &block)

data/lib/trailblazer/activity/dsl/magnetic/finalizer.rb

@@ -34,7 +34,7 @@ module Trailblazer
         def self.circuit_hash_to_process(circuit_hash)
           end_events = end_events_for(circuit_hash)
 
-          return Circuit.new(circuit_hash, end_events), end_events
+          return Circuit.new(circuit_hash, end_events, start_task: circuit_hash.keys.first), end_events
         end
 
         # Find all end events that don't have outgoing connections.

data/lib/trailblazer/activity/dsl/magnetic/process_options.rb

@@ -55,11 +55,11 @@ module Trailblazer
               Polarization.new( output: output, color: task.color )
             ]
           else  # ID: existing step
-            new_edge = "#{id}-#{output.signal}-#{task}"
+            new_edge = "#{id}-#{output.signal}-#{task}" # edge from <id> to <target>
 
             [
               Polarization.new( output: output, color: new_edge ),
-              [[ :magnetic_to, [ task, [new_edge] ] ]],
+              [[ :magnetic_to, [ task, [new_edge] ] ]], # mark target (`task`) as magnetic to the new edge.
             ]
           end
         end

data/lib/trailblazer/activity/dsl/strategy/path.rb

@@ -12,7 +12,6 @@ module Trailblazer
           builder_class:    Magnetic::Builder::Path, # we use the Activity-based Normalizer
           normalizer_class: Magnetic::Normalizer,
           default_outputs:  Magnetic::Builder::Path.default_outputs, # binary outputs
-          extension:        [ Introspect.method(:add_introspection) ],
 
           extend:           [
             # DSL.def_dsl(:task, Magnetic::Builder::Path,    :PassPolarizations),

data/lib/trailblazer/activity/introspect.rb

@@ -1,27 +1,52 @@
 module Trailblazer
-  class Activity < Module   # Introspection is not used at run-time except for rendering diagrams, tracing, and the like.
+  class Activity < Module
+    # Compile-time.
+    # Introspection is not used at run-time except for rendering diagrams, tracing, and the like.
     module Introspect
-      # {:argumenter} API
-      def self.arguments_for_call(activity, (options, flow_options), **circuit_options)
-        circuit_options = circuit_options.merge( introspect: activity.debug )
-
-        return activity, [ options, flow_options ], circuit_options
+      def self.Graph(*args)
+        Graph.new(*args)
       end
 
-      # {Extension} API
-      def self.add_introspection(activity, task, local_options, *returned_options)
-        activity[:debug, task] = { id: local_options[:id] || task }
-      end
+      # @private This API is still under construction.
+      class Graph
+        def initialize(activity)
+          @activity = activity
+          @circuit  = activity.to_h[:circuit]
+          @adds     = activity.to_h[:adds].compact # FIXME: why are there nils in Adds?
+        end
+
+        def find(id=nil, &block)
+          return find_by_id(id) unless block_given?
+          find_with_block(&block)
+        end
+
+        private
+
+        def find_by_id(id)
+          (_, (id, triplett)) = @adds.find { |(op, (_id, triplett))| _id == id }
+
+          Node(triplett[1], id, triplett[0])
+        end
+
+        def find_with_block(&block)
+          adds = @adds.find { |(op, (id, triplett))| yield( Node(triplett[1], id, triplett[0]) ) }
+          return nil unless adds
+
+          (op, (id, triplett)) = adds
 
+          Node(triplett[1], id, triplett[0])
+        end
 
-      # @api private
-      def self.find(activity, &block)
-        circuit = activity.to_h[:circuit]
+        def Node(*args)
+          Node.new(*args).freeze
+        end
 
-        circuit.instance_variable_get(:@map).find(&block)
+        Node = Struct.new(:task, :id, :magnetic_to)
       end
 
 
+      # FIXME: remove this
+      # @private This will be removed shortly.
       def self.collect(activity, options={}, &block)
         circuit      = activity.to_h[:circuit]
         circuit_hash = circuit.to_h[:map]

data/lib/trailblazer/activity/present.rb

@@ -17,7 +17,10 @@ module Trailblazer
           stack.each do |captured, *returned|
             task = captured.task
 
-            name = (node = captured.introspection[task]) ? node[:id] : task
+            graph = Introspect::Graph(captured.activity)
+
+            name = (node = graph.find { |node| node[:task] == task }) ? node[:id] : task
+            name ||= task # FIXME: bullshit
 
             if returned.size == 1 # flat
               tree << [ level, name ]

data/lib/trailblazer/activity/structures.rb

@@ -18,8 +18,8 @@
           @options = options.merge(semantic: semantic)
         end
 
-        def call(*args)
-          return self, *args
+        def call(args, circuit_options)
+          return self, args, circuit_options
         end
 
         def to_h
@@ -34,8 +34,8 @@
       end
 
       class Start < End
-        def call(*args)
-          return Activity::Right, *args
+        def call(args, circuit_options)
+          return Activity::Right, args, circuit_options
         end
       end
 

data/lib/trailblazer/activity/task_wrap/call_task.rb

@@ -8,7 +8,7 @@ class Trailblazer::Activity < Module
 
       # Call the actual task we're wrapping here.
       # puts "~~~~wrap.call: #{task}"
-      return_signal, return_args = task.( *original_args ) # we lose :exec_context here.
+      return_signal, return_args = task.(*original_args)
 
       # DISCUSS: do we want original_args here to be passed on, or the "effective" return_args which are different to original_args now?
       wrap_ctx = wrap_ctx.merge( return_signal: return_signal, return_args: return_args )

data/lib/trailblazer/activity/task_wrap/merge.rb

@@ -11,7 +11,7 @@ module Trailblazer
       # {:extension API}
       def call(activity, task, local_options, *returned_options)
         # we could make the default initial_activity injectable via the DSL, the value would sit in returned_options or local_options.
-        static_wrap = Activity::TaskWrap.wrap_static_for(task, wrap_static: activity[:wrap_static] || {})
+        static_wrap = Activity::TaskWrap.wrap_static_for(task, activity: activity)
 
         # # macro might want to apply changes to the static task_wrap (e.g. Inject)
         new_wrap =  Activity::Path::Plan.merge( static_wrap, @extension_plan )

data/lib/trailblazer/activity/task_wrap/runner.rb

@@ -9,7 +9,7 @@ class Trailblazer::Activity < Module
       #
       # @api private
       # @interface Runner
-      def self.call(task, args, **circuit_options)
+      def self.call(task, args, circuit_options)
         wrap_ctx = { task: task }
 
         # this activity is "wrapped around" the actual `task`.
@@ -18,9 +18,11 @@ class Trailblazer::Activity < Module
         # 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 ]
+
         # 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.
+          [ 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.
@@ -37,7 +39,10 @@ class Trailblazer::Activity < Module
       # unnecessary computations at `call`-time since steps might not even be executed.
       # TODO: make this faster.
       def self.merge_static_with_runtime(task, wrap_runtime:, **circuit_options)
-        wrap_activity = TaskWrap.wrap_static_for(task, circuit_options)  # find static wrap for this specific task, or default wrap activity.
+        wrap_activity = TaskWrap.wrap_static_for(
+          task,
+          circuit_options
+        )  # 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).
@@ -45,7 +50,12 @@ class Trailblazer::Activity < Module
       end
     end # Runner
 
-    def self.wrap_static_for(task, wrap_static:, default_activity: TaskWrap.initial_activity, **)
+    # Retrieve the static wrap config from {activity}.
+    # I do not like this part too much, I'd prefer computing the {:wrap_static} at compile-time for the entire
+    # object graph (including nesteds) and simply pass it through to all Runner calls.
+    # TODO: simplify that. See above
+    def self.wrap_static_for(task, activity:, default_activity: TaskWrap.initial_activity, **)
+      wrap_static = activity[:wrap_static] || {}
       wrap_static[task] || default_activity
     end
   end

data/lib/trailblazer/activity/task_wrap/trace.rb

@@ -2,26 +2,42 @@ class Trailblazer::Activity < Module
   module TaskWrap
     # TaskWrap tasks for tracing.
     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_circuit_options = original_args
+      module_function
 
-        original_flow_options[:stack].indent!
+      # taskWrap step to capture incoming arguments of a step.
+      # def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
+      def capture_args((wrap_config, original_args), **circuit_options)
 
-        original_flow_options[:stack] << Trailblazer::Activity::Trace::Entity.new( wrap_config[:task], :args, nil, {}, original_circuit_options[:introspect] )
+        original_args = capture_for(wrap_config[:task], *original_args)
 
-        [ Trailblazer::Activity::Right, [wrap_config, original_args], **circuit_options ]
+        return Trailblazer::Activity::Right, [wrap_config, original_args], circuit_options
       end
 
-      def self.capture_return((wrap_config, original_args), **circuit_options)
+      # taskWrap step to capture outgoing arguments from a step.
+      def capture_return((wrap_config, original_args), **circuit_options)
         (original_options, original_flow_options, _) = original_args[0]
 
-        original_flow_options[:stack] << Trailblazer::Activity::Trace::Entity.new(  wrap_config[:task], :return, wrap_config[:return_signal], {} )
+        original_flow_options[:stack] << Trailblazer::Activity::Trace::Entity.new(
+          wrap_config[:task], {}, :return, wrap_config[:return_signal]
+        )
 
         original_flow_options[:stack].unindent!
 
 
-        [ Trailblazer::Activity::Right, [wrap_config, original_args], **circuit_options ]
+        return Trailblazer::Activity::Right, [wrap_config, original_args], circuit_options
+      end
+
+      # It's important to understand that {flow[:stack]} is mutated by design. This is needed so
+      # in case of exceptions we still have a "global" trace - unfortunately Ruby doesn't allow
+      # us a better way.
+      def capture_for(task, (ctx, flow), activity:, **circuit_options)
+        flow[:stack].indent!
+
+        flow[:stack] << Trailblazer::Activity::Trace::Entity.new(
+          task, activity, :args, nil, {}
+        )
+
+        return [ctx, flow], circuit_options.merge(activity: activity)
       end
     end
   end

data/lib/trailblazer/activity/task_wrap.rb

@@ -24,29 +24,17 @@ module Trailblazer
       end
 
       # Compute runtime arguments necessary to execute a taskWrap per task of the activity.
-      def self.arguments_for_call(activity, (options, flow_options), **circuit_options)
+      def self.invoke(activity, args, wrap_runtime: {}, **circuit_options)
         circuit_options = circuit_options.merge(
           runner:       TaskWrap::Runner,
-          wrap_runtime: circuit_options[:wrap_runtime] || {},
-          wrap_static:  activity[:wrap_static] || {},
-        )
-
-        return activity, [ options, flow_options ], circuit_options
-      end
+          wrap_runtime: wrap_runtime,
 
-      module NonStatic
-        def self.arguments_for_call(activity, (options, flow_options), **circuit_options)
-          circuit_options = circuit_options.merge(
-            runner:       TaskWrap::Runner,
-            wrap_runtime: circuit_options[:wrap_runtime] || {}, # FIXME:this sucks. (was:) this overwrites wrap_runtime from outside.
-            wrap_static:  ::Hash.new(TaskWrap.initial_activity), # add a default static wrap.
-          )
+          activity: { adds: [], circuit: {} }, # for Runner
+        )
 
-          return activity, [ options, flow_options ], circuit_options
-        end
+        # signal, (ctx, flow), circuit_options =
+        Runner.(activity, args, circuit_options)
       end
-
-      # better: MyClass < Activity(TaskWrap, ...)
-    end
+    end # TaskWrap
   end
 end

data/lib/trailblazer/activity/testing.rb

@@ -0,0 +1,32 @@
+# DISCUSS: move to trailblazer-activity-test ?
+
+# Helpers to quickly create steps and tasks.
+module Trailblazer::Activity::Testing
+  # Creates a module with one step method for each name.
+  #
+  # @example
+  #   extend T.def_steps(:create, :save)
+  def self.def_steps(*names)
+    Module.new do
+      names.each do |name|
+        define_method(name) do | ctx, ** |
+          ctx[:seq] << name
+          ctx.key?(name) ? ctx[name] : true
+        end
+      end
+    end
+  end
+
+  # Creates a method instance with a task interface.
+  #
+  # @example
+  #   task task: T.def_task(:create)
+  def self.def_task(name)
+    Module.new do
+      define_singleton_method(name) do | (ctx, flow_options), ** |
+        ctx[:seq] << name
+        return Trailblazer::Activity::Right, [ctx, flow_options]
+      end
+    end.method(name)
+  end
+end

data/lib/trailblazer/activity/trace.rb

@@ -22,13 +22,10 @@ module Trailblazer
         return activity, [ options, flow_options.merge(tracing_flow_options) ], circuit_options.merge(tracing_circuit_options)
       end
 
-      def self.call(activity, (options, flow_options), *args)
-        activity, (options, flow_options), circuit_options = Trace.arguments_for_call( activity, [options, flow_options], {} ) # only run once for the entire circuit!
+      def self.call(activity, (options, flow_options), circuit_options={})
+        activity, (options, flow_options), circuit_options = Trace.arguments_for_call( activity, [options, flow_options], circuit_options ) # only run once for the entire circuit!
         last_signal, (options, flow_options) =
-          activity.(
-            [options, flow_options],
-            circuit_options.merge({ argumenter: [ Introspect.method(:arguments_for_call), TaskWrap.method(:arguments_for_call) ] })
-          )
+          Activity::TaskWrap.invoke(activity, [options, flow_options], circuit_options)
 
         return flow_options[:stack].to_a, last_signal, [options, flow_options]
       end
@@ -48,7 +45,7 @@ module Trailblazer
         end
       end
 
-      Entity = Struct.new(:task, :type, :value, :value2, :introspection)
+      Entity = Struct.new(:task, :activity, :type, :value, :value2)
 
       # Mutable/stateful per design. We want a (global) stack!
       class Stack

data/lib/trailblazer/activity/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Activity < Module
-    VERSION = "0.5.2"
+    VERSION = "0.6.0"
   end
 end

data/lib/trailblazer/activity.rb

@@ -1,10 +1,4 @@
-require "trailblazer/activity/version"
-
 module Trailblazer
-  def self.Activity(implementation=Activity::Path, options={})
-    Activity.new(implementation, state)
-  end
-
   class Activity < Module
     attr_reader :initial_state
 
@@ -51,6 +45,12 @@ module Trailblazer
       end
     end
 
+    # Reader and writer method for DSL objects.
+    # The writer {dsl[:key] = "value"} exposes immutable behavior and will replace the old
+    # @state with a new, modified copy.
+    #
+    # Always use the DSL::Accessor accessors to avoid leaking state to other components
+    # due to mutable write operations.
     module Accessor
       def []=(*args)
         @state = State::Config.send(:[]=, @state, *args)
@@ -81,12 +81,12 @@ module Trailblazer
     require "trailblazer/activity/dsl/magnetic/merge"
       include Magnetic::Merge # Activity#merge!
 
-      def call(args, argumenter: [], **circuit_options) # DISCUSS: the argumenter logic might be moved out.
-        _, args, circuit_options = argumenter.inject( [self, args, circuit_options] ) { |memo, argumenter| argumenter.(*memo) }
-
-        self[:circuit].( args, circuit_options.merge(argumenter: argumenter) )
+      # @private Note that {Activity.call} is considered private until the public API is stable.
+      def call(args, circuit_options={})
+        self[:circuit].( args, circuit_options.merge(activity: self) )
       end
     end
+
   end # Activity
 end
 

data/lib/trailblazer/circuit.rb

@@ -14,7 +14,7 @@ module Trailblazer
   #
   # This is the "pipeline operator"'s implementation.
   class Circuit
-    def initialize(map, stop_events, name: nil, start_task: map.keys.first)
+    def initialize(map, stop_events, start_task:, name: nil)
       @map         = map
       @stop_events = stop_events
       @name        = name
@@ -36,8 +36,9 @@ module Trailblazer
     # @return [last_signal, options, flow_options, *args]
     #
     # NOTE: returned circuit_options are discarded when calling the runner.
-    def call(args, task: @start_task, runner: Run, **circuit_options)
+    def call(args, start_task: @start_task, runner: Run, **circuit_options)
       circuit_options = circuit_options.merge( runner: runner ).freeze # TODO: set the :runner option via arguments_for_call to save the merge?
+      task            = start_task
 
       loop do
         last_signal, args, _discarded_circuit_options = runner.(
@@ -49,35 +50,22 @@ module Trailblazer
         # Stop execution of the circuit when we hit a stop event (< End). This could be an task's End or Suspend.
         return [ last_signal, args ] if @stop_events.include?(task) # DISCUSS: return circuit_options here?
 
-        task = next_for(task, last_signal) do |next_task, in_map|
-          raise IllegalInputError.new("#{task}") unless in_map
-          raise IllegalOutputSignalError.new("<#{@name}>[#{task}][ #{last_signal.inspect} ]") unless next_task
-        end
+        task = next_for(task, last_signal) or raise IllegalSignalError.new("<#{@name}>[#{task}][ #{last_signal.inspect} ]")
       end
     end
 
     # Returns the circuit's components.
     def to_h
-      { map: @map, end_events: @stop_events }
+      { map: @map, end_events: @stop_events, start_task: @start_task }
     end
 
   private
-    def next_for(last_task, emitted_signal)
-      # p @map
-      in_map        = false
-      cfg           = @map.keys.find { |t| t == last_task } and in_map = true
-      cfg = @map[cfg] if cfg
-      cfg         ||= {}
-      next_task = cfg[emitted_signal]
-      yield next_task, in_map
-
-      next_task
-    end
-
-    class IllegalInputError < RuntimeError
+    def next_for(last_task, signal)
+      outputs = @map[last_task]
+      outputs[signal]
     end
 
-    class IllegalOutputSignalError < RuntimeError
+    class IllegalSignalError < RuntimeError
     end
   end
 end

data/lib/trailblazer-activity.rb

@@ -1 +1,2 @@
+require "trailblazer/activity/version"
 require "trailblazer/activity"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-23 00:00:00.000000000 Z
+date: 2018-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hirb
@@ -111,7 +111,6 @@ files:
 - NOTES
 - README.md
 - Rakefile
-- inspeccccccccct.rb
 - lib/trailblazer-activity.rb
 - lib/trailblazer/activity.rb
 - lib/trailblazer/activity/config.rb
@@ -150,6 +149,7 @@ files:
 - lib/trailblazer/activity/task_wrap/merge.rb
 - lib/trailblazer/activity/task_wrap/runner.rb
 - lib/trailblazer/activity/task_wrap/trace.rb
+- lib/trailblazer/activity/testing.rb
 - lib/trailblazer/activity/trace.rb
 - lib/trailblazer/activity/version.rb
 - lib/trailblazer/circuit.rb

data/inspeccccccccct.rb

@@ -1,19 +0,0 @@
-
-module Inspect
-  def inspect
-    "nice view!"
-  end
-end
-
-module A
-  extend Inspect
-
-  def self.a
-  end
-end
-
-# jruby 9.1.7
-puts A.method(:a).inspect #=> #<Method: A.a>
-# 2.5
-puts A.method(:a).inspect #=> #<Method: nice view!.a>
-