trailblazer-activity 0.2.1 → 0.3.0

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

@@ -0,0 +1,123 @@
+module Trailblazer
+  module Activity::Magnetic
+    class Builder
+      class Railway < Builder
+        def self.for(normalizer, builder_options={}) # Build the Builder.
+          Activity::Magnetic::Builder(
+            Railway,
+            normalizer,
+            { track_color: :success, end_semantic: :success, failure_color: :failure }.merge( builder_options )
+          )
+        end
+
+        def self.plan(options={}, normalizer=DefaultNormalizer.new(plus_poles: default_plus_poles), &block)
+          plan_for( *Railway.for(normalizer, options), &block )
+        end
+
+        def self.keywords
+          [:type]
+        end
+
+        def step(task, options={}, &block)
+          insert_element( Railway, Railway.StepPolarizations(@builder_options), task, options, &block )
+        end
+
+        def fail(task, options={}, &block)
+          insert_element( Railway, Railway.FailPolarizations(@builder_options), task, options, &block )
+        end
+
+        def pass(task, options={}, &block)
+          insert_element( 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
+        end
+
+        # Adds the End.failure end to the Path sequence.
+        # @return [Adds] list of Adds instances that can be chained or added to an existing sequence.
+        def self.InitialAdds(failure_color:raise, failure_end: Activity.End(failure_color, :failure), **builder_options)
+          path_adds = Path.InitialAdds(**builder_options)
+
+          end_adds = adds(
+            "End.#{failure_color}", failure_end,
+
+            {}, # plus_poles
+            Path::TaskPolarizations(builder_options.merge( type: :End )),
+            [],
+
+            {},
+            { group: :end },
+            [failure_color]
+          )
+
+          path_adds + end_adds
+        end
+
+        # ONLY JOB: magnetic_to and Outputs ("Polarization") via PlusPoles.merge
+        def self.StepPolarizations(**options)
+          [
+            *Path.TaskPolarizations(options),
+            StepPolarization.new(options)
+          ]
+        end
+
+        def self.PassPolarizations(options)
+          [
+            Railway::PassPolarization.new( options )
+          ]
+        end
+
+        def self.FailPolarizations(options)
+          [
+            Railway::FailPolarization.new( options )
+          ]
+        end
+
+        class StepPolarization
+          def initialize(track_color: :success, failure_color: :failure, **o)
+            @track_color, @failure_color = track_color, failure_color
+          end
+
+          # Returns the polarization for a DSL call. Takes care of user options such as :magnetic_to.
+          def call(magnetic_to, plus_poles, options)
+            [
+              magnetic_to || default_magnetic_to,
+              plus_poles_for(plus_poles, options),
+            ]
+          end
+
+          private
+
+          def plus_poles_for(plus_poles, options)
+            plus_poles.reconnect( :failure => @failure_color )
+          end
+
+          def default_magnetic_to
+            [@track_color]
+          end
+        end
+
+        class PassPolarization < StepPolarization
+          def plus_poles_for(plus_poles, options)
+            plus_poles.reconnect( :failure => @track_color, :success => @track_color )
+          end
+        end
+
+        class FailPolarization < StepPolarization
+          def default_magnetic_to
+            [@failure_color]
+          end
+
+          def plus_poles_for(plus_poles, options)
+            plus_poles.reconnect( :failure => @failure_color, :success => @failure_color )
+          end
+        end
+
+      end # Railway
+    end # Builder
+  end
+end

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

@@ -0,0 +1,90 @@
+module Trailblazer
+  module Activity::Magnetic
+    module DSL
+      class Polarization
+        def initialize( output:raise, color:raise )
+          @output, @color = output, color
+        end
+
+        def call(magnetic_to, plus_poles, options)
+          [
+            magnetic_to,
+            plus_poles.merge( @output => @color ) # this usually adds a new Output to the task.
+          ]
+        end
+      end # Polarization
+
+      # This module only processes additional "wiring" options from the DSL calls
+      #   Output(:success) => End("my.new")
+      #
+      # Returns PlusPoles and additional sequence alterations.
+      module ProcessOptions
+        module_function
+
+        # Output => target (End/"id"/:color)
+        # @return [PlusPole]
+        # @return additional alterations
+        #
+        # options:
+        #   { DSL::Output[::Semantic] => target }
+        #
+        def call(id, options, initial_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)
+              }.
+              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)
+
+          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]] ]
+            ]
+          elsif task.is_a?(String) # let's say this means an existing step
+            new_edge = "#{output.signal}-#{task}"
+
+            [
+              Polarization.new( output: output, color: new_edge ),
+              [[ :magnetic_to, [ task, [new_edge] ] ]],
+            ]
+          # procs come from DSL calls such as `Path() do ... end`.
+          elsif task.is_a?(Proc)
+            start_color, adds = task.(block)
+
+            [
+              Polarization.new( output: output, color: start_color ),
+              # TODO: this is a pseudo-"merge" and should be public API at some point.
+              adds[1..-1] # drop start
+            ]
+          else # An additional plus polarization. Example: Output => :success
+            [
+              Polarization.new( output: output, color: task )
+            ]
+          end
+        end
+
+        # @param semantic DSL::Output::Semantic
+        def output_for(semantic, plus_poles)
+          # DISCUSS: review PlusPoles#[]
+          output, _ = plus_poles.instance_variable_get(:@plus_poles)[semantic.value]
+          output or raise("Couldn't find existing output for `#{semantic.value.inspect}`.")
+        end
+      end # OptionsProcessing
+
+      # DSL datastructures
+      module Output
+        Semantic = Struct.new(:value)
+      end
+    end # DSL
+  end
+end

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

@@ -0,0 +1,44 @@
+module Trailblazer
+  module Activity::Magnetic
+    module DSL
+      # works on a generic Dependencies structure that has no knowledge of magnetism.
+      class Alterations
+        def initialize
+          @groups = Activity::Schema::Dependencies.new
+          @future_magnetic_to = {} # DISCUSS: future - should it be here?
+        end
+
+        def add(id, options, **sequence_options)
+          @groups.add(id, options, **sequence_options)
+
+          # DISCUSS: future - should it be here?
+          if magnetic_to = @future_magnetic_to.delete(id)
+            magnetic_to( id, magnetic_to )
+          end
+
+          self
+        end
+
+        # make `id` magnetic_to
+        def magnetic_to(id, magnetic_to)
+          group, index = @groups.find(id) # this can be a future task!
+
+          unless group # DISCUSS: future - should it be here?
+            @future_magnetic_to[id] = magnetic_to
+            return
+          end
+
+          arr = group[index].configuration.dup
+
+          arr[0] = arr[0] + magnetic_to
+          group.add(id, arr, replace: id)
+        end
+
+        # Returns array of tripletts.
+        def to_a
+          @groups.to_a
+        end
+      end
+    end # DSL
+  end
+end

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

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

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

@@ -0,0 +1,55 @@
+module Trailblazer
+  module Activity::Magnetic
+    class Builder
+      module Finalizer
+
+        def self.call(adds)
+          tripletts = adds_to_tripletts(adds)
+
+          circuit_hash = tripletts_to_circuit_hash( tripletts )
+
+          circuit_hash_to_process( circuit_hash )
+        end
+
+        def self.adds_to_tripletts(adds)
+          alterations = adds_to_alterations(adds)
+
+          alterations.to_a
+        end
+
+        def self.adds_to_alterations(adds)
+          alterations = DSL::Alterations.new
+
+          adds = adds.compact # TODO: test me explicitly, and where does this come from anyway?
+
+          adds.each { |method, cfg| alterations.send( method, *cfg ) }
+
+          alterations
+        end
+
+        def self.tripletts_to_circuit_hash(tripletts)
+          Activity::Magnetic::Generate.( tripletts )
+        end
+
+        def self.circuit_hash_to_process(circuit_hash)
+          end_events = end_events_for(circuit_hash)
+
+          return Activity::Process.new( circuit_hash, end_events ), end_events
+        end
+
+        # Filters out unconnected ends, e.g. the standard end in nested tracks that weren't used.
+        def self.end_events_for(circuit_hash)
+          tasks_with_incoming_edge = circuit_hash.values.collect { |connections| connections.values }.flatten(1)
+
+          ary = circuit_hash.collect do |task, connections|
+            task.kind_of?(Activity::End) &&
+              connections.empty? &&
+              tasks_with_incoming_edge.include?(task) ? task : nil
+          end
+
+          ary.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Trailblazer
+  module Activity::Magnetic
+    # Transforms an array of {Triplett}s into a circuit hash.
+    module Generate
+      Line      = Struct.new(:source, :output)
+      MinusPole = Struct.new(:color)
+
+      class OpenLines
+        def initialize
+          @arr = []
+        end
+
+        def pop(signal, &block)
+          lines = @arr.find_all { |line| line.output.color == signal }
+          @arr -= lines
+
+          lines.each(&block)
+          lines.any?
+        end
+
+        def <<((node, output))
+          @arr << Line.new(node, output)
+        end
+      end
+
+      def self.call(tasks)
+        open_plus_poles  = OpenLines.new
+        open_minus_poles = OpenLines.new
+        circuit_hash     = {}
+
+        tasks.each do |(magnetic_to, node, outputs)|
+          circuit_hash[ node ] ||= {} # DISCUSS: or needed?
+
+          magnetic_to.each do |edge_color| # minus poles
+            open_plus_poles.pop(edge_color) do |line|
+              connect( circuit_hash, line.source, line.output.signal, node )
+            end and next
+
+            # only run when there were no open_minus_poles
+            open_minus_poles << [node, MinusPole.new(edge_color)] # open inputs on a node, waiting to be connected.
+          end
+
+          outputs.each do |output|
+            open_minus_poles.pop(output.color) do |line|
+              connect( circuit_hash, node, output.signal, line.source )
+            end and next
+
+            # only run when there were no open_plus_poles
+            open_plus_poles << [node, output]
+          end
+        end
+
+        circuit_hash
+      end
+
+      #                               plus            minus
+      def self.connect(circuit_hash, source, signal, target)
+        circuit_hash[ source ][ signal ] = target
+      end
+    end # Magnetic
+  end
+end

data/lib/trailblazer/activity/present.rb

@@ -3,8 +3,7 @@ require "hirb"
 module Trailblazer
   class Activity
     module Trace
-      # TODO:
-      # * Struct for debug_item
+      # TODO: make this simpler.
       module Present
         module_function
 
@@ -14,24 +13,18 @@ module Trailblazer
           Hirb::Console.format_output(tree, class: :tree, type: :directory)
         end
 
-        # API HERE is: we only know the current element (e.g. task), input, output, and have an "introspection" object that tells us more about the element.
-        # TODO: the debug_item's "api" sucks, this should be a struct.
         def tree_for(stack, level, tree)
-          stack.each do |debug_item|
-            task = debug_item[0][0]
+          stack.each do |captured, *returned|
+            task = captured.task
 
-            if debug_item.size == 2 # flat
-              introspect = debug_item[0].last
+            name = (node = captured.introspection[task]) ? node[:id] : task
 
-              name = (node = introspect[task]) ? node[:id] : task
-
-              tree << [ level,  name ]
+            if returned.size == 1 # flat
+              tree << [ level, name ]
             else # nesting
-              tree << [ level, task ]
-
-              tree_for(debug_item[1..-2], level + 1, tree)
+              tree << [ level, name ]
 
-              tree << [ level+1, debug_item[-1][0] ]
+              tree_for(returned[0..-2], level + 1, tree)
             end
 
             tree
@@ -59,10 +52,10 @@ module Trailblazer
 
         def color_map
           {
-            Trailblazer::Circuit::Start => :blue,
-            Trailblazer::Circuit::End   => :pink,
-            Trailblazer::Circuit::Right => :green,
-            Trailblazer::Circuit::Left  => :red
+            Trailblazer::Activity::Start => :blue,
+            Trailblazer::Activity::End   => :pink,
+            Trailblazer::Activity::Right => :green,
+            Trailblazer::Activity::Left  => :red
           }
         end