trailblazer-future 2.1.0.rc1

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

@@ -0,0 +1,101 @@
+module Trailblazer::V2_1
+  module Activity::Magnetic
+
+    # TODO: move?
+    module Options
+      # Produce two hashes, one "local" options with DSL-specific options such as `:fast_track`,
+      # one with generic DSL options, for example tuples like `Right=>Output(:failure)`.
+      def self.normalize(options, local_keys)
+        local, foreign = {}, {}
+        options.each { |k,v| local_keys.include?(k) ? local[k] = v : foreign[k] = v }
+
+        return foreign, local
+      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(...)
+
+      return builder, implementation.InitialAdds(builder_options)
+    end
+
+    class Builder
+      def initialize(normalizer, builder_options)
+        @normalizer, @builder_options = normalizer, builder_options
+      end
+
+      def self.merge(activity_adds, merged_adds)
+        merged_adds = merged_adds[2..-1] || []
+
+        activity_adds + merged_adds
+      end
+
+      # DSL method to create a Path within an activity which is embedded.
+      #
+      # Output(:success) => Path() {}
+      def Path(*args)
+        Activity::DSL.Path(@normalizer, *args)
+      end
+
+      # Public top-level entry point.
+      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, 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, 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, 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, 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)
+
+        polarizations = polarizations + polarizations_from_user_options
+
+        result = adds(task, polarizations, local_options, sequence_options, local_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)
+        DSL::ProcessOptions.(id, options, plus_poles, &block)
+      end
+
+      # 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 = PlusPoles.apply_polarizations(
+          polarizations,
+          magnetic_to,
+          plus_poles,
+          options
+        )
+
+        Add( id, task, magnetic_to, plus_poles,
+          options,         #{ fast_track: true },
+          sequence_options #{ group: :main }
+        )
+      end
+
+      def self.Add(id, task, magnetic_to, plus_poles, options, sequence_options)
+        [
+          [ :add, [id, [ magnetic_to, task, plus_poles ], sequence_options] ],
+        ]
+      end
+    end # Builder
+  end
+end
+
+

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

@@ -0,0 +1,26 @@
+module Trailblazer::V2_1
+  module Activity::Magnetic
+    # This normalizer only processes basic input and is meant for bootstrapping.
+    #
+    #   task Callable, id: "success", before: "another"
+    class DefaultNormalizer
+      # Declarative::Variables
+      def self.build(plus_poles:, **options)
+        return new(plus_poles: plus_poles), options
+      end
+
+      def initialize(**default_options)
+        @default_options = default_options
+      end
+
+      # Processes the user arguments from the DSL
+      def call(task, options)
+        local_options = @default_options.merge(options) # here, we merge default :plus_poles.
+
+        local_options, sequence_options = Options.normalize( local_options, Activity::Schema::Dependencies.sequence_keywords )
+
+        return task, local_options, {}, sequence_options, {}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# TODO: move me to Operation.
+module Trailblazer::V2_1
+  module Activity::Magnetic
+    class Builder
+
+      class FastTrack < Builder
+        def self.for(normalizer, builder_options={}) # Build the Builder.
+          Activity::Magnetic::Builder(
+            FastTrack,
+            normalizer,
+            { track_color: :success, end_semantic: :success, failure_color: :failure }.merge( builder_options )
+          )
+        end
+
+        def self.StepPolarizations(**options)
+          [
+            *Railway.StepPolarizations(options),
+            StepPolarization.new(options)
+          ]
+        end
+
+        def self.FailPolarizations(**options)
+          [
+            *Railway.FailPolarizations(options),
+            FailPolarization.new(options)
+          ]
+        end
+
+        def self.PassPolarizations(**options)
+          [
+            *Railway.PassPolarizations(options),
+            PassPolarization.new(options)
+          ]
+        end
+
+        # pass_fast: true simply means: color my :success Output with :pass_fast color
+        class StepPolarization < Railway::StepPolarization
+          def call(magnetic_to, plus_poles, options)
+            plus_poles = plus_poles.reconnect( :success   => :pass_fast ) if options[:pass_fast]
+            plus_poles = plus_poles.reconnect( :failure   => :fail_fast ) if options[:fail_fast]
+
+            # add fast track outputs if :fast_track
+            plus_poles = plus_poles.reverse_merge(
+              Activity.Output(Activity::FastTrack::FailFast, :fail_fast) => :fail_fast,
+              Activity.Output(Activity::FastTrack::PassFast, :pass_fast) => :pass_fast
+            ) if options[:fast_track]
+
+            [
+              magnetic_to,
+              plus_poles
+            ]
+          end
+        end
+
+        class FailPolarization < Railway::StepPolarization
+          def call(magnetic_to, plus_poles, options)
+            plus_poles = plus_poles.reconnect( :failure => :fail_fast, :success => :fail_fast ) if options[:fail_fast]
+            plus_poles = plus_poles.reverse_merge( Activity.Output(Activity::FastTrack::FailFast, :fail_fast) => :fail_fast, Activity.Output(Activity::FastTrack::PassFast, :pass_fast) => :pass_fast ) if options[:fast_track]
+
+            [
+              magnetic_to,
+              plus_poles
+            ]
+          end
+        end
+
+        class PassPolarization < Railway::StepPolarization
+          def call(magnetic_to, plus_poles, options)
+            plus_poles = plus_poles.reconnect( :success => :pass_fast, :failure => :pass_fast ) if options[:pass_fast]
+            plus_poles = plus_poles.reverse_merge( Activity.Output(Activity::FastTrack::FailFast, :fail_fast) => :fail_fast, Activity.Output(Activity::FastTrack::PassFast, :pass_fast) => :pass_fast ) if options[:fast_track]
+
+            [
+              magnetic_to,
+              plus_poles
+            ]
+          end
+        end
+
+        def self.default_plus_poles(*args)
+          Railway.default_plus_poles(*args)
+        end
+
+        # Adds the End.fail_fast and End.pass_fast end to the Railway sequence.
+        def self.InitialAdds(pass_fast_end: Activity.End(:pass_fast), fail_fast_end: Activity.End(:fail_fast), **builder_options)
+          path_adds = Railway.InitialAdds(**builder_options)
+
+          ends =
+            adds(
+              pass_fast_end,
+
+              Path::EndEventPolarizations(builder_options),
+
+              {},
+              { group: :end },
+
+              id:           "End.pass_fast",
+              magnetic_to:  [:pass_fast],
+              plus_poles:   {},
+            )+
+            adds(
+              fail_fast_end,
+
+              Path::EndEventPolarizations(builder_options),
+
+              {},
+              { group: :end },
+
+              magnetic_to:  [:fail_fast],
+              id:           "End.fail_fast",
+              plus_poles:   {},
+            )
+
+          path_adds + ends
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+module Trailblazer::V2_1
+  module Activity::Magnetic
+    # 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.method(:Binary), default_outputs: Builder::Path.default_outputs, pipeline: Pipeline, extension:[], **options)
+        return new(
+          default_outputs: default_outputs,
+          extension:       extension,
+          task_builder:    task_builder,
+          pipeline:        pipeline,
+        ), options
+      end
+
+      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_outputs: @default_outputs,
+        }
+
+        signal, (ctx, ) = @pipeline.( [ctx], {} )
+
+        return ctx[:options][:task], ctx[:local_options], ctx[:connection_options], ctx[:sequence_options], ctx[:extension_options]
+      end
+
+      # needs the basic Normalizer
+
+      # :default_plus_poles is an injectable option.
+      module Pipeline
+        extend Trailblazer::V2_1::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)
+          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],
+          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`.
+        def self.extract_dsl_keywords(options, connection_classes = [Activity::Output, Activity::DSL::OutputSemantic])
+          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.initialize_extension_option( ctx, options:, ** )
+          ctx[:options] = options.merge( Activity::DSL::Extension.new( Activity::DSL.method(:record) ) => true )
+        end
+
+        # 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.
+              task.merge(options) # Note that the user options are merged over the macro options.
+            else # user step
+              { id: task }
+                .merge(options)                     # default :id
+                .merge( task: task_builder.(task) )
+            end
+        end
+
+        # :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: PlusPoles.initial(outputs),
+            }
+            .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( Activity::TaskWrap::VariableMapping.method(:normalizer_step_for_input_output) )
+
+        task Activity::TaskBuilder::Binary( method(:split_options) ),              id: "split_options"
+        task Activity::TaskBuilder::Binary( method(:initialize_plus_poles) ),      id: "initialize_plus_poles"
+        # task ->((ctx, _), **) { pp ctx; [Activity::Right, [ctx, _]] }
+      end
+    end # Normalizer
+
+  end
+end

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

@@ -0,0 +1,105 @@
+module Trailblazer::V2_1
+  module Activity::Magnetic
+    class Builder
+
+      class Path < Builder
+          # strategy_options:
+          #   :track_color
+          #   :end_semantic
+        def self.for(normalizer, builder_options={}) # Build the Builder.
+          Activity::Magnetic::Builder(
+            Path,
+            normalizer,
+            { track_color: :success, end_semantic: :success }.merge( builder_options )
+          )
+        end
+
+        # In most cases, a task has a binary signal, which is why we decided to make that
+        # the default output set.
+        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(**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 }
+
+          adds(
+            Activity::Start.new(semantic: :default),
+
+            TaskPolarizations(builder_options),
+
+            {}, { group: :start },
+
+            id:           "Start.default",
+            magnetic_to:  [],
+            plus_poles:   PlusPoles.initial(start_outputs), # FIXME: this is actually redundant with Normalizer
+          )
+        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 }
+
+            adds(
+              track_end,
+
+              EndEventPolarizations(builder_options), # only sets :magnetic_to.
+
+              {}, { group: :end },
+
+              id:         "End.#{track_color}",
+              plus_poles: {},
+              magnetic_to: nil,
+            )
+          end
+        end
+
+        def self.TaskPolarizations(track_color:, **)
+          [TaskPolarization.new( track_color: track_color )]
+        end
+
+        def self.EndEventPolarizations(track_color:, **)
+          [EndEventPolarization.new( track_color: track_color )]
+        end
+
+        class TaskPolarization
+          def initialize(track_color:)
+            @track_color = track_color
+          end
+
+          def call(magnetic_to, plus_poles, options)
+            [
+              magnetic_to || [@track_color],
+              plus_poles.reconnect( :success => @track_color )
+            ]
+          end
+        end # TaskPolarization
+
+        class EndEventPolarization < TaskPolarization
+          def call(magnetic_to, plus_poles, options)
+            [
+              magnetic_to || [@track_color],
+              {}
+            ]
+          end
+        end # EndEventPolarization
+      end # Path
+    end # Builder
+  end
+end