trailblazer-future 2.1.0.rc1

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

@@ -0,0 +1,97 @@
+module Trailblazer::V2_1
+  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
+
+        # 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), **builder_options)
+          path_adds = Path.InitialAdds(**builder_options)
+
+          end_adds = adds(
+            failure_end,
+
+            Path::EndEventPolarizations(builder_options),
+
+            {},
+            { group: :end },
+
+            magnetic_to:  [failure_color],
+            id:           "End.#{failure_color}",
+            plus_poles:   {},
+          )
+
+          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/v2_1/activity/dsl/magnetic/builder/state.rb

@@ -0,0 +1,58 @@
+module Trailblazer::V2_1
+  class Activity::Magnetic::Builder
+    # Maintain Builder instance plus Adds/Process/Outputs as immutable objects.
+    module State
+      def self.build(builder_class, normalizer, builder_options)
+        builder, adds = builder_class.for(normalizer, builder_options) # e.g. Path.for(...) which creates a Builder::Path instance.
+
+        recompile(builder.freeze, adds.freeze)
+      end
+
+      def self.add(builder, adds, strategy, polarizer, *args, &block)
+        new_adds, *returned_options = builder.insert(strategy, polarizer, *args, &block) # TODO: move that out of here.
+
+        adds = adds + new_adds
+
+        recompile(builder, adds.freeze, returned_options)
+      end
+
+      private
+
+      # @return {builder, Adds, Process, outputs}, returned_options
+      def self.recompile(builder, adds, *args)
+        circuit, outputs = recompile_circuit(adds)
+
+        return builder, adds, circuit.freeze, outputs.freeze, *args
+      end
+
+      def self.recompile_circuit(adds)
+        circuit, outputs = Recompile.( adds )
+      end
+
+      module Recompile
+        # Recompile the circuit and outputs from the {ADDS} instance that collects circuit tasks and connections.
+        #
+        # @return [Process, Hash] The {Process} instance and its outputs hash.
+        def self.call(adds)
+          circuit, end_events = Finalizer.(adds)
+          outputs             = recompile_outputs(end_events)
+
+          return circuit, outputs
+        end
+
+        private
+
+        def self.recompile_outputs(end_events)
+          ary = end_events.collect do |evt|
+            [
+              semantic = evt.to_h[:semantic],
+              Activity::Output(evt, semantic)
+            ]
+          end
+
+          ::Hash[ ary ]
+        end
+      end # Recompile
+    end # State
+  end
+end

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

@@ -0,0 +1,51 @@
+module Trailblazer::V2_1
+  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 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.
+        def self.end_events_for(circuit_hash)
+          ary = circuit_hash.collect do |task, connections|
+            task.kind_of?(Activity::End) && connections.empty? ? task : nil
+          end
+
+          ary.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Trailblazer::V2_1
+  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/v2_1/activity/dsl/magnetic/merge.rb

@@ -0,0 +1,16 @@
+class Trailblazer::V2_1::Activity < Module
+  module Magnetic
+    module Merge
+      def merge!(merged)
+        merged[:record].each do |key, args|
+          dsl_method, *args = args
+
+          return send( dsl_method, args[0], args[1], &args[2] ) if args[2]
+          send( dsl_method, args[0], args[1] )
+        end
+
+        self
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+module Trailblazer::V2_1
+  module Activity::Magnetic
+    module DSL
+      # 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, 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, 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, plus_poles, &block)
+          output = output_for(output, plus_poles) if output.kind_of?(Activity::DSL::OutputSemantic)
+
+          if task.kind_of?(Activity::End)
+            # raise %{An end event with semantic `#{task.to_h[:semantic]}` has already been added. Please use an ID reference: `=> "End.#{task.to_h[:semantic]}"`} if
+            new_edge = "#{id}-#{output.signal}"
+
+            [
+              Polarization.new( output: output, color: new_edge ),
+              [ [:add, [task.to_h[:semantic], [ [new_edge], task, [] ], group: :end]] ]
+            ]
+          # procs come from DSL calls such as `Path() do ... end`.
+          elsif task.is_a?(Proc)
+            start_color, activity = task.(block)
+
+            adds = activity.to_h[:adds]
+
+            [
+              Polarization.new( output: output, color: start_color ),
+              # TODO: this is a pseudo-"merge" and should be public API at some point.
+            # TODO: we also need to merge all the other states such as debug.
+              adds[1..-1] # drop start
+            ]
+          elsif task.is_a?(Activity::DSL::Track) # An additional plus polarization. Example: Output => :success
+            [
+              Polarization.new( output: output, color: task.color )
+            ]
+          else  # ID: existing step
+            new_edge = "#{id}-#{output.signal}-#{task}" # edge from <id> to <target>
+
+            [
+              Polarization.new( output: output, color: new_edge ),
+              [[ :magnetic_to, [ task, [new_edge] ] ]], # mark target (`task`) as magnetic to the new edge.
+            ]
+          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
+    end # DSL
+  end
+end

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

@@ -0,0 +1,44 @@
+module Trailblazer::V2_1
+  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/v2_1/activity/dsl/magnetic/structure/plus_poles.rb

@@ -0,0 +1,85 @@
+module Trailblazer::V2_1
+  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
+
+      # FIXME: should this be a hash or whatever?
+      #
+      # @return Hash All {Output}s mapped to their (guessed) semantic: `{ Output(Right, :success) => :success }`
+      def self.initial(outputs)
+        new.merge(Hash[ outputs.collect { |semantic, output| [output, semantic] } ])
+      end
+    end
+  end
+end
+