trailblazer-activity 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bed08027bb74c9466a7dee0325bf2eb5fddc637eb2e46f3f86a3292e522fe083
-  data.tar.gz: 3a89ef72fbbb55f084779cb376f68ef542486d4a5b0fe8af1200e594fea6f6b4
+  metadata.gz: b12275a2f1dfc9e9c90d7b3df76d2eab01db0964c453d61a23a307296cda2378
+  data.tar.gz: 93b881493ecec9eb50516cb1185ff1129c6fbc5efe478bc429604adae077c552
 SHA512:
-  metadata.gz: 1c221eba23024d176d6c6c3376fd3aa6c5a668806d3b2cccd09e7a85496a07c833dddb74fa30e6c346eb0e8093b8186f1f8cc1557a21a37f1feddb7a9fabd7a9
-  data.tar.gz: 27e679eab5c94988e821e05a7bdb25c301e656091f8bc100bb84a142cec3ec0f7fced3c61bb7ef0d5b2e89cd0847d22e7db2ca17c783906316628216dad93e12
+  metadata.gz: 7245451409ba95340e9a3ef5e9404df93b3e2f7aa9325fe2132bc45f4f7fbcd49370200dfe9532fb5fa8f4307fdd3f4c6eae480920927e232228361712ac8cef
+  data.tar.gz: a127529dea689958ff467558c6a373b37cfe0e2e2475b99b24f854488b672ff012cb8cccdfc3b02339e1b20e62eecbd92e5148fbe7e80ad5da7b8242e7f2c793

data/.travis.yml

@@ -9,6 +9,6 @@ rvm:
   - 2.5.0
 matrix:
   include:
-  - rvm: jruby-9.1.15.0
+  - rvm: jruby-head
     env: JRUBY_OPTS="--profile.api"
 before_install: gem install bundler

data/CHANGES.md

@@ -1,3 +1,10 @@
+# 0.4.3
+
+* Make `:outputs` the canonical way to define outputs, and not `:plus_poles`. The latter is computed by the DSL if not passed.
+* Allow injecting `inspect` implementations into `Introspect` methods.
+* Add `Nested`.
+* Add `TaskBuilder::Task#to_s`.
+
 # 0.4.2
 
 * `End` is not a `Struct` so we can maintain more state, and are immutable.

data/README.md

@@ -4,7 +4,7 @@ The `activity` gem brings a light-weight DSL to define business processes, and t
 
 A process is a set of arbitrary pieces of logic you define, chained together and put into a meaningful context by an activity. Activity lets you focus on the implementation of steps while Trailblazer takes care of the control flow.
 
-Please find the [full documentation on the Trailblazer website](http://trailblazer.to/2.1/activity). [Note that the docs are WIP.]
+Please find the [full documentation on the Trailblazer website](http://trailblazer.to/api-docs). [Note that the docs are WIP.]
 
 ## Example
 

data/inspeccccccccct.rb

@@ -0,0 +1,19 @@
+
+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>
+

data/lib/trailblazer/activity.rb

@@ -42,7 +42,7 @@ module Trailblazer
     module DSLHelper
       extend Forwardable
       def_delegators :@builder, :Path
-      def_delegators DSL::Helper, :Output, :End
+      def_delegators DSL::Helper, :Output, :End, :Nested
 
       def Path(*args, &block)
         self[:builder].Path(*args, &block)
@@ -95,6 +95,7 @@ require "trailblazer/activity/config"
 require "trailblazer/activity/implementation/build_state"
 require "trailblazer/activity/implementation/interface"
 require "trailblazer/activity/implementation/path"
+require "trailblazer/activity/implementation/plan"
 require "trailblazer/activity/implementation/railway"
 require "trailblazer/activity/implementation/fast_track"
 

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

@@ -44,6 +44,14 @@ module Trailblazer
           [ track_color, path ]
         }
       end
+
+      # Computes the :outputs options for {activity}
+      def Nested(activity)
+        {
+          task:    activity,
+          outputs: activity.outputs
+        }
+      end
     end
   end
 end

data/lib/trailblazer/activity/implementation/build_state.rb

@@ -22,6 +22,7 @@ class Trailblazer::Activity < Module
       return normalizer, options
     end
 
+    # @api private
     def self.build_state(normalizer, builder_class:, builder_options: {}, **options)
       builder, adds, circuit, outputs = State.build(builder_class, normalizer, options.merge(builder_options))
 

data/lib/trailblazer/activity/implementation/path.rb

@@ -11,45 +11,13 @@ module Trailblazer
         {
           builder_class:    Magnetic::Builder::Path, # we use the Activity-based Normalizer
           normalizer_class: Magnetic::Normalizer,
-          plus_poles:       Magnetic::Builder::Path.default_plus_poles,
+          default_outputs:  Magnetic::Builder::Path.default_outputs,
           extension:        [ Introspect.method(:add_introspection) ],
 
           extend:           [ DSL.def_dsl(:task) ],
         }
       end
-
-      def self.Plan()
-        Plan
-      end
-
-      module Plan
-        def self.extended(extended)
-          extended.singleton_class.send :attr_accessor, :record
-          extended.record = []
-          extended.extend(Methods)
-        end
-
-        module Methods
-          def task(*args, &block)
-            record << [:task, args, block]
-          end
-        end
-
-        def self.merge!(activity, plan)
-          plan.record.each { |(dsl_method, args, block)| activity.send(dsl_method, *args, &block)  }
-          activity
-        end
-
-        # Creates a copy of the {activity} module and merges the {Plan} into it.
-        #
-        # @params activity [Activity] The activity to extend
-        # @params plan [Plan] The plan providing additional steps
-        # @return [Activity] A new, merged activity
-        def self.merge(activity, plan)
-          merge!(activity.clone, plan)
-        end
-      end
-    end
+    end # Path
   end
 end
 

data/lib/trailblazer/activity/implementation/plan.rb

@@ -0,0 +1,36 @@
+module Trailblazer
+  class Activity::Path < Activity
+    def self.Plan()
+      Plan
+    end
+
+    module Plan
+      def self.extended(extended)
+        extended.singleton_class.send :attr_accessor, :record
+        extended.record = []
+        extended.extend(Methods)
+      end
+
+      module Methods
+        def task(*args, &block)
+          record << [:task, args, block]
+        end
+      end
+
+      def self.merge!(activity, plan)
+        plan.record.each { |(dsl_method, args, block)| activity.send(dsl_method, *args, &block)  }
+        activity
+      end
+
+      # Creates a copy of the {activity} module and merges the {Plan} into it.
+      #
+      # @params activity [Activity] The activity to extend
+      # @params plan [Plan] The plan providing additional steps
+      # @return [Activity] A new, merged activity
+      def self.merge(activity, plan)
+        merge!(activity.clone, plan)
+      end
+    end
+  end
+end
+

data/lib/trailblazer/activity/implementation/railway.rb

@@ -8,9 +8,9 @@ module Trailblazer
     class Railway < Activity
       def self.config
         Path.config.merge(
-          builder_class:  Magnetic::Builder::Railway,
-          plus_poles:     Magnetic::Builder::Railway.default_plus_poles,
-          extend:         [ DSL.def_dsl(:step), DSL.def_dsl(:fail), DSL.def_dsl(:pass) ],
+          builder_class:   Magnetic::Builder::Railway,
+          default_outputs: Magnetic::Builder::Railway.default_outputs,
+          extend:          [ DSL.def_dsl(:step), DSL.def_dsl(:fail), DSL.def_dsl(:pass) ],
         )
       end
     end

data/lib/trailblazer/activity/introspect.rb

@@ -35,6 +35,11 @@ module Trailblazer
       end
 
 
+      def self.inspect_task_builder(task)
+        proc = task.instance_variable_get(:@user_proc)
+        %{#<TaskBuilder{#{proc}}>}
+      end
+
         # FIXME: clean up that shit below.
 
 # render
@@ -42,14 +47,14 @@ module Trailblazer
         circuit_hash( circuit.to_h[:map], **options )
       end
 
-      def self.circuit_hash(circuit_hash, show_ids:false)
+      def self.circuit_hash(circuit_hash, show_ids:false, **options)
         content =
           circuit_hash.collect do |task, connections|
             conns = connections.collect do |signal, target|
-              " {#{signal}} => #{Task(target)}"
+              " {#{signal}} => #{inspect_with_matcher(target, **options)}"
             end
 
-            [ Task(task), conns.join("\n") ]
+            [ inspect_with_matcher(task, **options), conns.join("\n") ]
           end
 
           content = content.join("\n")
@@ -60,7 +65,7 @@ module Trailblazer
 
       def self.Ends(activity)
         end_events = activity.to_h[:end_events]
-        ends = end_events.collect { |evt| Task(evt) }.join(",")
+        ends = end_events.collect { |evt| inspect_end(evt) }.join(",")
         "[#{ends}]".gsub(/\d\d+/, "")
       end
 
@@ -70,9 +75,17 @@ module Trailblazer
           join("\n").gsub(/0x\w+/, "").gsub(/\d\d+/, "")
       end
 
-      def self.Task(task)
-        return task.inspect unless task.kind_of?(Trailblazer::Activity::End)
+      # If Ruby had pattern matching, this function wasn't necessary.
+      def self.inspect_with_matcher(task, inspect_task: method(:inspect_task), inspect_end: method(:inspect_end))
+        return inspect_task.(task) unless task.kind_of?(Trailblazer::Activity::End)
+        inspect_end.(task)
+      end
+
+      def self.inspect_task(task)
+        task.inspect
+      end
 
+      def self.inspect_end(task)
         class_name = strip(task.class)
         options    = task.to_h
 
@@ -108,7 +121,7 @@ module Trailblazer
           sequence.collect do |(magnetic_to, task, plus_poles)|
             pluses = plus_poles.collect { |plus_pole| PlusPole(plus_pole) }
 
-%{#{magnetic_to.inspect} ==> #{Activity::Introspect.Task(task)}
+%{#{magnetic_to.inspect} ==> #{Activity::Introspect.inspect_with_matcher(task)}
 #{pluses.empty? ? " []" : pluses.join("\n")}}
           end.join("\n")
 

data/lib/trailblazer/activity/magnetic.rb

@@ -16,8 +16,8 @@ module Trailblazer
 end
 
 require "trailblazer/activity/magnetic/dsl"
-require "trailblazer/activity/magnetic/dsl/plus_poles"
-require "trailblazer/activity/magnetic/dsl/alterations"
+require "trailblazer/activity/magnetic/structure/plus_poles"
+require "trailblazer/activity/magnetic/structure/alterations"
 
 require "trailblazer/activity/schema/dependencies"
 

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

@@ -15,6 +15,7 @@ module Trailblazer
       end
     end
 
+    # Called from Path/Railway/FastTrack, creates the specific {Builder} instance.
     def self.Builder(implementation, normalizer, builder_options={})
       builder = implementation.new(normalizer, builder_options.freeze).freeze # e.g. Path.new(...)
 
@@ -32,11 +33,14 @@ module Trailblazer
         activity_adds + merged_adds
       end
 
-      # Stateful helper.
+      # DSL method to create a Path within an activity which is embedded.
+      #
+      # Output(:success) => Path() {}
       def Path(*args)
         Activity::DSL::Helper.Path(@normalizer, *args)
       end
 
+      # Public top-level entry point.
       def insert(name, task, options, &block)
         normalizer = options[:normalizer] || @normalizer # DISCUSS: do this at a deeper point?
 
@@ -50,13 +54,12 @@ module Trailblazer
       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(impl, polarizations, task, local_options, connection_options, sequence_options, &block)
         adds, *returned_options = Builder.adds_for(polarizations, task, local_options, connection_options, sequence_options, &block)
       end
 
       # @return Adds
-      # High level interface for DSL calls like ::task or ::step.
-      # TODO: RETURN ALL OPTIONS
       def self.adds_for(polarizations, task, local_options, connection_options, sequence_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)
@@ -75,7 +78,7 @@ module Trailblazer
       # Low-level interface for DSL calls (e.g. Start, where "you know what you're doing")
       # @private
       def self.adds(task, polarizations, options, sequence_options, magnetic_to:nil, id:nil, plus_poles:, **) # DISCUSS: no :id ?
-        magnetic_to, plus_poles = apply_polarizations(
+        magnetic_to, plus_poles = PlusPoles.apply_polarizations(
           polarizations,
           magnetic_to,
           plus_poles,
@@ -88,19 +91,9 @@ module Trailblazer
         )
       end
 
-      # Called once per DSL method call, e.g. ::step.
-      #
-      # The idea is to chain a bunch of PlusPoles transformations (and magnetic_to "transformations")
-      # for each DSL call, and thus realize things like path+railway+fast_track
-      def self.apply_polarizations(polarizations, magnetic_to, plus_poles, options)
-        polarizations.inject([magnetic_to, plus_poles]) do |args, pol|
-          magnetic, plus_poles = pol.(*args, options)
-        end
-      end
-
       def self.Add(id, task, magnetic_to, plus_poles, options, sequence_options)
         [
-          [ :add, [id, [ magnetic_to, task, plus_poles.to_a ], sequence_options] ],
+          [ :add, [id, [ magnetic_to, task, plus_poles ], sequence_options] ],
         ]
       end
     end # Builder

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

@@ -1,40 +1,33 @@
 module Trailblazer
   module Activity::Magnetic
-    # The {Normalizer} is called for every DSL call (step/pass/fail etc.) and normalizes/defaults
+    # One {Normalizer} instance is called for every DSL call (step/pass/fail etc.) and normalizes/defaults
     # the user options, such as setting `:id`, connecting the task's outputs or wrapping the user's
     # task via {TaskBuilder::Binary} in order to translate true/false to `Right` or `Left`.
     #
     # The Normalizer sits in the `@builder`, which receives all DSL calls from the Operation subclass.
     class Normalizer
-      def self.build(task_builder: Activity::TaskBuilder::Binary, default_plus_poles: Normalizer.InitialPlusPoles(), pipeline: Pipeline, extension:[], **options)
+      def self.build(task_builder: Activity::TaskBuilder::Binary, default_outputs: Builder::Path.default_outputs, pipeline: Pipeline, extension:[], **options)
         return new(
-          default_plus_poles: default_plus_poles,
-          extension:          extension,
-          task_builder:       task_builder,
-          pipeline:           pipeline,
+          default_outputs: default_outputs,
+          extension:       extension,
+          task_builder:    task_builder,
+          pipeline:        pipeline,
         ), options
       end
 
-      # @private Might be removed.
-      def self.InitialPlusPoles
-        Activity::Magnetic::DSL::PlusPoles.new.merge(
-          Activity.Output(Activity::Right, :success) => nil,
-          Activity.Output(Activity::Left,  :failure) => nil,
-        )
-      end
-
-      def initialize(task_builder:, default_plus_poles:, pipeline:, **options)
-        @task_builder       = task_builder
-        @default_plus_poles = default_plus_poles
-        @pipeline           = pipeline # TODO: test me.
+      def initialize(task_builder:, default_outputs:, pipeline:, **options)
+        @task_builder    = task_builder
+        @default_outputs = default_outputs
+        @pipeline        = pipeline # TODO: test me.
         freeze
       end
 
       def call(task, options)
         ctx = {
-          task: task, options:  options,
-          task_builder:         @task_builder,
-          default_plus_poles:   @default_plus_poles,
+          task:            task,
+          options:         options,
+          task_builder:    @task_builder,
+          default_outputs: @default_outputs,
         }
 
         signal, (ctx, ) = @pipeline.( [ctx] )
@@ -46,7 +39,7 @@ module Trailblazer
 
       # :default_plus_poles is an injectable option.
       module Pipeline
-        extend Trailblazer::Activity::Path( normalizer_class: DefaultNormalizer, plus_poles: Builder::Path.default_plus_poles )
+        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)
@@ -84,11 +77,18 @@ module Trailblazer
             end
         end
 
-        # Merge user options over defaults.
-        def self.defaultize( ctx, local_options:, default_plus_poles:, ** ) # TODO: test :default_plus_poles
+        # :outputs passed: I know what I want to have connected.
+        # no :outputs: use default_outputs
+        # ALWAYS connect all outputs to their semantic-color.
+
+        # Create the `plus_poles: <PlusPoles>` tuple where the PlusPoles instance will act as the interface
+        # to rewire or add connections for the DSL.
+        def self.initialize_plus_poles( ctx, local_options:, default_outputs:, ** )
+          outputs = local_options[:outputs] || default_outputs
+
           ctx[:local_options] =
             {
-              plus_poles: default_plus_poles,
+              plus_poles: PlusPoles.initial(outputs),
             }
             .merge(local_options)
         end
@@ -96,7 +96,7 @@ module Trailblazer
         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(:defaultize) ),                 id: "defaultize"
+        task Activity::TaskBuilder::Binary.( method(:initialize_plus_poles) ),      id: "initialize_plus_poles"
         # task ->((ctx, _), **) { pp ctx; [Activity::Right, [ctx, _]] }
       end
     end # Normalizer

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

@@ -20,15 +20,16 @@ module Trailblazer
           return Path, polarizations, task, options, block
         end
 
-
-        def self.default_plus_poles
-          DSL::PlusPoles.new.merge(
-            Activity.Output( Activity::Right, :success ) => nil
-          ).freeze
+              # @private Might be removed.
+        def self.default_outputs
+          {
+            success: Activity.Output(Activity::Right, :success),
+            # failure: Activity.Output(Activity::Left,  :failure),
+          }
         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, default_plus_poles: self.default_plus_poles, track_end: Activity.End(end_semantic), **)
+        def self.InitialAdds(track_color:raise, end_semantic:raise, start_outputs: {success: self.default_outputs[:success]}, track_end: Activity.End(end_semantic), **)
 
           builder_options={ track_color: track_color, end_semantic: end_semantic }
 
@@ -41,7 +42,7 @@ module Trailblazer
 
             id:           "Start.default",
             magnetic_to:  [],
-            plus_poles:   default_plus_poles
+            plus_poles:   PlusPoles.initial(start_outputs), # FIXME: this is actually redundant with Normalizer
           )
 
           end_adds = adds(
@@ -59,14 +60,14 @@ module Trailblazer
           start_adds + end_adds
         end
 
-        def self.TaskPolarizations(track_color:raise, type: :task, **)
+        def self.TaskPolarizations(track_color:, type: :task, **)
           return [EndPolarization.new( track_color: track_color )] if type == :End # DISCUSS: should this dispatch be here?
 
           [TaskPolarization.new( track_color: track_color )]
         end
 
         class TaskPolarization
-          def initialize( track_color:raise )
+          def initialize(track_color:)
             @track_color = track_color
           end
 

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

@@ -22,11 +22,10 @@ module Trailblazer
           return Railway, Railway.PassPolarizations(@builder_options), task, options, block
         end
 
-        def self.default_plus_poles
-          DSL::PlusPoles.new.merge(
-            Activity.Output(Activity::Right, :success) => nil,
-            Activity.Output(Activity::Left,  :failure) => nil,
-          ).freeze
+        def self.default_outputs
+          Path.default_outputs.merge(
+            :failure => Activity.Output(Activity::Left,  :failure),
+          )
         end
 
         # Adds the End.failure end to the Path sequence.

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

@@ -28,30 +28,30 @@ module Trailblazer
         # options:
         #   { DSL::Output[::Semantic] => target }
         #
-        def call(id, options, initial_plus_poles, &block)
+        def call(id, options, plus_poles, &block)
           polarization, adds =
             options.
               collect { |key, task|
                 # this method call is the only thing that really matters here. # TODO: make this transformation a bit more obvious.
-                process_tuple(id, key, task, initial_plus_poles, &block)
+                process_tuple(id, key, task, plus_poles, &block)
               }.
               inject([[],[]]) { |memo, (polarization, adds)| memo[0]<<polarization; memo[1]<<adds; memo }
 
           return polarization, adds.flatten(1)
         end
 
-        def process_tuple(id, output, task, initial_plus_poles, &block)
-          output = output_for(output, initial_plus_poles) if output.kind_of?(DSL::Output::Semantic)
+        def process_tuple(id, output, task, plus_poles, &block)
+          output = output_for(output, plus_poles) if output.kind_of?(DSL::Output::Semantic)
 
           if task.kind_of?(Activity::End)
             new_edge = "#{id}-#{output.signal}"
 
             [
               Polarization.new( output: output, color: new_edge ),
-              [ [:add, [task.instance_variable_get(:@name), [ [new_edge], task, [] ], group: :end]] ]
+              [ [:add, [task.to_h[:semantic], [ [new_edge], task, [] ], group: :end]] ]
             ]
           elsif task.is_a?(String) # let's say this means an existing step
-            new_edge = "#{output.signal}-#{task}"
+            new_edge = "#{id}-#{output.signal}-#{task}"
 
             [
               Polarization.new( output: output, color: new_edge ),

data/lib/trailblazer/activity/magnetic/structure/plus_poles.rb

@@ -0,0 +1,92 @@
+module Trailblazer
+  module Activity::Magnetic
+    # A plus pole is associating an Output{:signal, :semantic} to a magnetic :color.
+    #
+    # When it comes to connecting tasks to each other, PlusPoles is the most important object
+    # here. When a task is added via the DSL, a PlusPoles is set up, and the DSL adds polarizations
+    # from the implementation and from the options (e.g. `Outputs(..) => ..`).
+    #
+    # These are then finalized and return the effective plus poles
+
+    # Polarization is one or multiple calls to PlusPoles
+
+
+
+
+
+    # Output(:signal, :semantic) => :color
+    # add / merge
+    #   change existing, => color
+    #
+    #
+    # Produces [ PlusPole, PlusPole, ] via `to_a`.
+    #
+    # @privat
+    # @note This is private until we know what we want.
+    class PlusPoles
+      def initialize(plus_poles={})
+        @plus_poles = plus_poles.freeze
+      end
+
+      #   merge( Activity::Magnetic.Output(Right, :success) => :success
+      def merge(output_to_color)
+        overrides = ::Hash[ output_to_color.collect { |output, color| [ output.semantic, [output, color] ] } ]
+        PlusPoles.new(@plus_poles.merge(overrides))
+      end
+
+      def reverse_merge(output_to_color)
+        existing_colors = @plus_poles.values.collect { |pole_cfg| pole_cfg.last }
+
+        # filter all outputs with a color that already exists.
+        overrides = output_to_color.find_all { |output, color| !existing_colors.include?(color) }
+        merge(overrides)
+      end
+
+      def reconnect(semantic_to_color)
+        ary = semantic_to_color.collect do |semantic, color|
+          existing_output, _ = @plus_poles[semantic]
+
+          next unless existing_output
+
+          [ Activity.Output(existing_output.signal, existing_output.semantic), color ]
+        end
+
+        merge( ::Hash[ary.compact] )
+      end
+
+      # Compile one {PlusPoles} instance from all a sequence of {Polarization}s.
+      # This is usually called once per `step` DSL call.
+      #
+      # @api private
+      def self.apply_polarizations(polarizations, magnetic_to, plus_poles, options)
+        magnetic_to, plus_poles = polarizations.inject([magnetic_to, plus_poles]) do |args, pol|
+          magnetic_to, plus_poles = pol.(*args, options)
+        end
+
+        return magnetic_to, plus_poles.to_a
+      end
+
+      # The DSL is a series of transformations that yield in tasks with several PlusPole instances each.
+      #
+      # @api private
+      def to_a
+        @plus_poles.values.collect { |output, color| PlusPole.new(output, color) }
+      end
+
+      # Builds PlusPoles from { semantic => Output }, which, surprisingly, is exactly what Activity::outputs looks like.
+      # The plus pole's color is set to the output's semantic.
+      def self.from_outputs(outputs)
+        ary = outputs.collect { |semantic, output| [ output, semantic ] }
+
+        new.merge(::Hash[ary])
+      end
+
+      # FIXME: should this be a hash or whatever?
+      #
+      # @return Hash All {Output}s mapped to their semantic: `{ Output(Right, :success) => :success }`
+      def self.initial(outputs)
+        new.merge(Hash[ outputs.collect { |semantic, output| [output, semantic] } ])
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/structures.rb

@@ -1,6 +1,6 @@
   module Trailblazer
     class Activity < Module     # End event is just another callable task.
-      # Builds an Activity::End instance.
+      # Builds an {Activity::End} instance.
       def self.End(semantic)
         End.new(semantic: semantic)
       end
@@ -48,6 +48,7 @@
       # semantic: the original "semantic" or role of the signal, such as :success. This usually comes from the activity hosting this output.
       Output = Struct.new(:signal, :semantic)
 
+      # Builds an {Activity::Output} instance.
       def self.Output(signal, color)
         Output.new(signal, color).freeze
       end

data/lib/trailblazer/activity/task_builder.rb

@@ -33,6 +33,11 @@ module Trailblazer
 
         [ direction, [ options, *args ], **circuit_args ]
       end
+
+      def inspect
+        %{#<Trailblazer::Activity::TaskBuilder::Task user_proc=#{@user_proc}>}
+      end
+      alias_method :to_s, :inspect
     end
   end
 end

data/lib/trailblazer/activity/task_wrap.rb

@@ -1,4 +1,5 @@
-class Trailblazer::Activity < Module
+module Trailblazer
+  class Activity < Module
     #
     # Example with tracing:
     #
@@ -8,39 +9,44 @@ class Trailblazer::Activity < Module
         #   |-- Call (call actual task) id: "task_wrap.call_task"
         #   |-- Trace.capture_return [optional]
         #   |-- Wrap::End
-  module TaskWrap
-    # The actual activity that implements the taskWrap.
-    def self.initial_activity
-      Module.new do
-        extend Trailblazer::Activity::Path( name: "taskWrap", normalizer_class: Magnetic::DefaultNormalizer )
+    module TaskWrap
+      # The actual activity that implements the taskWrap.
+      def self.initial_activity
+        Module.new do
+          extend Trailblazer::Activity::Path(
+            name:             "taskWrap",
+            normalizer_class: Magnetic::DefaultNormalizer,
+            plus_poles:       Magnetic::PlusPoles.initial( :success => Magnetic::Builder::Path.default_outputs[:success] ) # DefaultNormalizer doesn't give us default PlusPoles.
+          )
 
-        task TaskWrap.method(:call_task), id: "task_wrap.call_task" # ::call_task is defined in task_wrap/call_task.
+          task TaskWrap.method(:call_task), id: "task_wrap.call_task" # ::call_task is defined in task_wrap/call_task.
+        end
       end
-    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)
-      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
-
-    module NonStatic
+      # Compute runtime arguments necessary to execute a taskWrap per task of the activity.
       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.
+          wrap_runtime: circuit_options[:wrap_runtime] || {},
+          wrap_static:  activity[:wrap_static] || {},
         )
 
         return activity, [ options, flow_options ], circuit_options
       end
-    end
 
-    # better: MyClass < Activity(TaskWrap, ...)
+      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.
+          )
+
+          return activity, [ options, flow_options ], circuit_options
+        end
+      end
+
+      # better: MyClass < Activity(TaskWrap, ...)
+    end
   end
 end

data/lib/trailblazer/activity/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-24 00:00:00.000000000 Z
+date: 2018-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hirb
@@ -112,6 +112,7 @@ files:
 - NOTES_
 - README.md
 - Rakefile
+- inspeccccccccct.rb
 - lib/trailblazer-activity.rb
 - lib/trailblazer/activity.rb
 - lib/trailblazer/activity/config.rb
@@ -121,6 +122,7 @@ files:
 - lib/trailblazer/activity/implementation/fast_track.rb
 - lib/trailblazer/activity/implementation/interface.rb
 - lib/trailblazer/activity/implementation/path.rb
+- lib/trailblazer/activity/implementation/plan.rb
 - lib/trailblazer/activity/implementation/railway.rb
 - lib/trailblazer/activity/introspect.rb
 - lib/trailblazer/activity/magnetic.rb
@@ -131,11 +133,11 @@ files:
 - lib/trailblazer/activity/magnetic/builder/path.rb
 - lib/trailblazer/activity/magnetic/builder/railway.rb
 - lib/trailblazer/activity/magnetic/dsl.rb
-- lib/trailblazer/activity/magnetic/dsl/alterations.rb
-- lib/trailblazer/activity/magnetic/dsl/plus_poles.rb
 - lib/trailblazer/activity/magnetic/finalizer.rb
 - lib/trailblazer/activity/magnetic/generate.rb
 - lib/trailblazer/activity/magnetic/merge.rb
+- lib/trailblazer/activity/magnetic/structure/alterations.rb
+- lib/trailblazer/activity/magnetic/structure/plus_poles.rb
 - lib/trailblazer/activity/present.rb
 - lib/trailblazer/activity/schema/dependencies.rb
 - lib/trailblazer/activity/schema/sequence.rb

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

@@ -1,59 +0,0 @@
-module Trailblazer
-  module Activity::Magnetic
-    module DSL
-      # Output(:signal, :semantic) => :color
-      # add / merge
-      #   change existing, => color
-      #
-      # Mutable DSL datastructure for managing all PlusPoles for a particular task.
-      #
-      # Produces [ PlusPole, PlusPole, ] via `to_a`.
-      #
-      # @privat
-      # @note This is private until we know what we want.
-      class PlusPoles
-        def initialize(plus_poles={})
-          @plus_poles = plus_poles.freeze
-        end
-
-        #   merge( Activity::Magnetic.Output(Right, :success) => :success
-        def merge(output_to_color)
-          overrides = ::Hash[ output_to_color.collect { |output, color| [ output.semantic, [output, color] ] } ]
-          PlusPoles.new(@plus_poles.merge(overrides))
-        end
-
-        def reverse_merge(output_to_color)
-          existing_colors = @plus_poles.values.collect { |pole_cfg| pole_cfg.last }
-
-          overrides = output_to_color.find_all { |output, color| !existing_colors.include?(color) } # filter all outputs with a color that already exists.
-          merge(overrides)
-        end
-
-        def reconnect(semantic_to_color)
-          ary = semantic_to_color.collect do |semantic, color|
-            existing_output, _ = @plus_poles[semantic]
-
-            next unless existing_output
-
-            [ Activity.Output(existing_output.signal, existing_output.semantic), color ]
-          end
-
-          merge( ::Hash[ary.compact] )
-        end
-
-        # The DSL is a series of transformations that yield in tasks with several PlusPole instances each.
-        def to_a
-          @plus_poles.values.collect { |output, color| PlusPole.new(output, color) }
-        end
-
-        # Builds PlusPoles from { semantic => Output }, which, surprisingly, is exactly what Activity::outputs looks like.
-        # The plus pole's color is set to the output's semantic.
-        def self.from_outputs(outputs)
-          ary = outputs.collect { |semantic, output| [ output, semantic ] }
-
-          new.merge(::Hash[ary])
-        end
-      end
-    end
-  end
-end