trailblazer-activity-dsl-linear 0.5.0 → 1.0.0.beta1

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

@@ -8,108 +8,153 @@ module Trailblazer
         #   provides DSL inheritance
         #   provides run-time {call}
         #   maintains the {state} with {seq} and normalizer options
-        module Strategy
-          def initialize!(state)
-            @state    = state
-
-            recompile_activity!(@state.to_h[:sequence])
-          end
+        # This could be a class but we decided to leave it as a module that then gets
+        # extended into {Path} and friends. This won't trigger the inheritance (because)
+        # there is nothing to inherit.
+        class Strategy
+          extend Linear::Helper # import {Subprocess()} and friends as class methods. creates shortcuts to {Strategy.Output} etc.
+          include Linear::Helper::Constants
+
+          class << self
+            def initialize!(state)
+              @state = state
+            end
 
-          def inherited(inheriter)
-            super
+            def inherited(inheriter)
+              super
 
-            # inherits the {@sequence}, and options.
-            inheriter.initialize!(@state.copy)
-          end
+              # Inherits the {State:sequencer} and other options without recomputing anything.
+              inheriter.initialize!(@state.copy)
+            end
 
-          # Called from {#step} and friends.
-          def self.task_for!(state, type, task, options={}, &block)
-            options = options.merge(dsl_track: type)
+            # @public
+              # We forward `step` to the Dsl (State) object.
+              # Recompiling the activity/sequence is a matter specific to Strategy (Railway etc).
+            def step(*args, &block); recompile_activity_for(:step, *args, &block); end
+            def terminus(*args);     recompile_activity_for(:terminus, *args); end
 
-            # {#update_sequence} is the only way to mutate the state instance.
-            state.update_sequence do |sequence:, normalizers:, normalizer_options:, fields:|
-              # Compute the sequence rows.
-              options = normalizers.(type, normalizer_options: normalizer_options, options: task, user_options: options.merge(sequence: sequence))
+            private def recompile_activity_for(type, *args, &block)
+              sequence = apply_step_on_sequence_builder(type, *args, &block)
 
-              sequence = Activity::DSL::Linear::DSL.apply_adds_from_dsl(sequence, **options)
+              recompile!(sequence)
             end
-          end
 
-          # @public
-          private def step(*args, &block)
-            recompile_activity_for(:step, *args, &block)
-          end
+            # TODO: make {rescue} optional, only in dev mode.
+            # @return Sequence
+            private def apply_step_on_sequence_builder(type, arg, options={}, &block)
+              return Sequence::Builder.(type, arg, options,
+                sequence:           @state.get(:sequence),
+                normalizers:        @state.get(:normalizers),
 
-          private def recompile_activity_for(type, *args, &block)
-            args = forward_block(args, block)
+                normalizer_options: @state.get(:normalizer_options),
 
-            seq  = @state.send(type, *args)
+                 &block
+              )
 
-            recompile_activity!(seq)
-          rescue Sequence::IndexError
-            # re-raise this exception with activity class prepended
-            # to the message this time.
-            raise $!, "#{self}:#{$!.message}"
-          end
+            rescue Activity::Adds::IndexError
+              # re-raise this exception with activity class prepended
+              # to the message this time.
+              raise $!, "#{self}:#{$!.message}"
+            end
 
-          private def recompile_activity!(seq)
-            schema    = Compiler.(seq)
+            private def recompile_activity(sequence)
+              schema = Sequence::Compiler.(sequence)
+              Activity.new(schema)
+            end
 
-            @activity = Activity.new(schema)
-          end
+            # DISCUSS: this should be the only way to "update" anything on state.
+            def recompile!(sequence)
+              activity = recompile_activity(sequence)
 
-          private def forward_block(args, block)
-            options = args[1]
+              @state.update!(:sequence) { |*| sequence }
+              @state.update!(:activity) { |*| activity }
+            end
 
-            return args unless options.is_a?(Hash)
+            # Used only once per strategy class body.
+            def compile_strategy!(strategy, **options)
+              options = strategy.OptionsForSequenceBuilder(**options)
 
-              # FIXME: doesn't account {task: <>} and repeats logic from Normalizer.
+              compile_strategy_for!(**options)
+            end
 
-            # DISCUSS: THIS SHOULD BE DONE IN DSL.Path() which is stateful! the block forwarding should be the only thing happening here!
-            evaluated_options =
-            options.find_all { |k,v| v.is_a?(BlockProxy) }.collect do |output, proxy|
-              shared_options = {step_interface_builder: @state.instance_variable_get(:@normalizer_options)[:step_interface_builder]} # FIXME: how do we know what to pass on and what not?
+            def compile_strategy_for!(sequence:, normalizers:, **normalizer_options)
+              @state.update!(:normalizers)        { normalizers }        # immutable
+              @state.update!(:normalizer_options) { normalizer_options } # immutable
 
-              [output, Linear.Path(**shared_options, **proxy.options, &(proxy.block || block))] # FIXME: the || sucks.
+              recompile!(sequence)
             end
 
-            evaluated_options = Hash[evaluated_options]
+            # Mainly used for introspection.
+            def to_h
+              activity = @state.get(:activity)
 
-            return args[0], options.merge(evaluated_options)
-          end
+              activity.to_h.to_h.merge(
+                activity: activity,
+                sequence: @state.get(:sequence),
+              )
+            end
 
-          def Path(**options, &block) # syntactically, we can't access the {do ... end} block here.
-            BlockProxy.new(options, block)
-          end
+            # @Runtime
+            # Injects {:exec_context} so that {:instance_method}s work.
+            def call(args, **circuit_options)
+              activity = @state.get(:activity)
 
-          BlockProxy = Struct.new(:options, :block)
+              activity.(
+                args,
+                **circuit_options.merge(exec_context: new)
+              )
+            end
 
-          private def merge!(activity)
-            old_seq = @state.instance_variable_get(:@sequence) # TODO: fixme
-            new_seq = activity.instance_variable_get(:@state).instance_variable_get(:@sequence) # TODO: fix the interfaces
+            def invoke(*args)
+              TaskWrap.invoke(self, *args)
+            end
+          end # class << self
+          # FIXME: do we want class << self?!
 
-            seq = Linear.Merge(old_seq, new_seq, end_id: "End.success")
+          module DSL
+            module_function
 
-            @state.instance_variable_set(:@sequence, seq) # FIXME: hate this so much.
-          end
+            def start_sequence(wirings: [])
+              start_default = Activity::Start.new(semantic: :default)
+              start_event   = Linear::Sequence.create_row(task: start_default, id: "Start.default", magnetic_to: nil, wirings: wirings)
+              _sequence     = Linear::Sequence[start_event]
+            end
 
-          def to_h
-            @activity.to_h.to_h.merge(activity: @activity)
-          end
+            def Build(strategy, **options, &block)
+              Class.new(strategy) do
+                compile_strategy!(strategy::DSL, normalizers: @state.get(:normalizers), **options)
 
-          # Injects {:exec_context} so that {:instance_method}s work.
-          def call(args, **circuit_options)
-            @activity.(
-              args,
-              **circuit_options.merge(exec_context: new)
-            )
-          end
+                class_exec(&block) if block_given?
+              end
+            end
+          end # DSL
 
-          def invoke(*args)
-            TaskWrap.invoke(self, *args)
+          # FIXME: move to State#dup
+          def self.copy(value, **) # DISCUSS: should that be here?
+            value.copy
           end
+
+          require_relative "feature/merge"
+          extend Merge::DSL # {Strategy.merge!}
+
+          state = Declarative::State(
+            normalizers: [nil, {}],        # immutable
+            normalizer_options: [nil, {}], # immutable
+
+            sequence:  [nil, {}], # when inherited, call #dup
+            activity:  [nil, {}], # when inherited, call #dup
+
+            fields:    [Hash.new, {}],
+          )
+
+          initialize!(state) # build an empty State instance that can be copied and recompiled.
+          # override :sequencer, :sequence, :activity
+          # This is done in every subclass.
+          recompile!(DSL.start_sequence)
         end # Strategy
       end
     end
   end
 end
+
+

data/lib/trailblazer/activity/dsl/linear/version.rb

@@ -3,7 +3,7 @@ module Trailblazer
     module Activity
       module DSL
         module Linear
-          VERSION = "0.5.0"
+          VERSION = "1.0.0.beta1"
         end
       end
     end

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

@@ -1,4 +1,5 @@
 require "trailblazer-activity"
+require "trailblazer/declarative"
 
 class Trailblazer::Activity
   module DSL
@@ -6,193 +7,36 @@ class Trailblazer::Activity
     #
     # Produces {Implementation} and {Intermediate}.
     module Linear
-      module_function
-
-      # {Sequence} consists of rows.
-      # {Sequence row} consisting of {[magnetic_to, task, connections_searches, data]}.
-      class Sequence < Array
-        # Return {Sequence row} consisting of {[magnetic_to, task, connections_searches, data]}.
-        def self.create_row(task:, magnetic_to:, wirings:, **options)
-          [
-            magnetic_to,
-            task,
-            wirings,
-            options # {id: "Start.success"}
-          ]
-        end
-
-        # @returns Sequence New sequence instance
-        # TODO: name it {apply_adds or something}
-        def self.insert_row(sequence, row:, insert:)
-          insert_function, *args = insert
-
-          insert_function.(sequence, [row], *args)
-        end
-
-        def self.apply_adds(sequence, adds)
-          adds.each do |add|
-            sequence = insert_row(sequence, **add)
-          end
-
-          sequence
-        end
-
-        class IndexError < IndexError
-          attr_reader :step_id
-
-          def initialize(sequence, step_id)
-            @step_id  = step_id
-            valid_ids = sequence.collect{ |row| row[3][:id].inspect }
-
-            message = "\n" \
-              "\e[31m#{@step_id.inspect} is not a valid step ID. Did you mean any of these ?\e[0m\n" \
-              "\e[32m#{valid_ids.join("\n")}\e[0m"
-
-            super(message)
-          end
-        end
-      end
-
-      # Sequence
-      module Search
-        module_function
-
-        # From this task onwards, find the next task that's "magnetic to" {target_color}.
-        # Note that we only go forward, no back-references are done here.
-        def Forward(output, target_color)
-          ->(sequence, me) do
-            target_seq_row = find_in_range(sequence[sequence.index(me)+1..-1], target_color)
-
-            return output, target_seq_row
-          end
-        end
-
-        # Tries to find a track colored step by doing a Forward-search, first, then wraps around going
-        # through all steps from sequence start to self.
-        def WrapAround(output, target_color)
-          ->(sequence, me) do
-            my_index      = sequence.index(me)
-            # First, try all elements after me, then go through the elements preceding myself.
-            wrapped_range = sequence[my_index+1..-1] + sequence[0..my_index-1]
-
-            target_seq_row = find_in_range(wrapped_range, target_color)
-
-            return output, target_seq_row
-          end
-        end
-
-        def Noop(output)
-          ->(sequence, me) do
-            return output, [nil,nil,nil,{}] # FIXME
-          end
-        end
-
-        # Find the seq_row with {id} and connect the current node to it.
-        def ById(output, id)
-          ->(sequence, me) do
-            index          = Insert.find_index(sequence, id) or return output, sequence[0] # FIXME # or raise "Couldn't find {#{id}}"
-            target_seq_row = sequence[index]
-
-            return output, target_seq_row
-          end
-        end
-
-        # @private
-        def find_in_range(range, target_color)
-          _target_seq_row = range.find { |seq_row| seq_row[0] == target_color }
-        end
-      end # Search
-
-      # Sequence
-      # Functions to mutate the Sequence by inserting, replacing, or deleting tasks.
-      # These functions are called in {insert_task}
+      # TODO: remove this deprecation for 1.1.
       module Insert
-        module_function
-
-        # Append {new_row} after {insert_id}.
-        def Append(sequence, new_rows, insert_id)
-          index, sequence = find(sequence, insert_id)
-
-          sequence.insert(index+1, *new_rows)
-        end
-
-        # Insert {new_rows} before {insert_id}.
-        def Prepend(sequence, new_rows, insert_id)
-          index, sequence = find(sequence, insert_id)
-
-          sequence.insert(index, *new_rows)
-        end
-
-        def Replace(sequence, new_rows, insert_id)
-          index, sequence = find(sequence, insert_id)
+        def self.method(name)
+          warn "[Trailblazer] Using `Trailblazer::Activity::DSL::Linear::Insert.method(:#{name})` is deprecated.
+  Please use `Trailblazer::Activity::Adds::Insert.method(:#{name})`."
 
-          sequence[index], _ = *new_rows # TODO: replace and insert remaining, if any.
-          sequence
+          Trailblazer::Activity::Adds::Insert.method(name)
         end
-
-        def Delete(sequence, _, insert_id)
-          index, sequence = find(sequence, insert_id)
-
-          sequence.delete(sequence[index])
-          sequence
-        end
-
-        # @private
-        def find_index(sequence, insert_id)
-          sequence.find_index { |seq_row| seq_row[3][:id] == insert_id } # TODO: optimize id location!
-        end
-
-        def find(sequence, insert_id)
-          index = find_index(sequence, insert_id) or raise Sequence::IndexError.new(sequence, insert_id)
-
-          return index, sequence.clone # Ruby doesn't have an easy way to avoid mutating arrays :(
-        end
-      end
-
-      def Merge(old_seq, new_seq, end_id: "End.success") # DISCUSS: also Insert
-        new_seq = strip_start_and_ends(new_seq, end_id: end_id)
-
-        _seq = Insert.Prepend(old_seq, new_seq, end_id)
       end
-      def strip_start_and_ends(seq, end_id:) # TODO: introduce Merge namespace?
-        cut_off_index = end_id.nil? ? seq.size : Insert.find_index(seq, end_id) # find the "first" end.
-
-        seq[1..cut_off_index-1]
-      end
-
-      module DSL
-        module_function
-
-        # Insert the task into the sequence using the {sequence_insert} strategy.
-        # @return Sequence sequence after applied insertion
-# FIXME: DSL for strategies
-        def insert_task(sequence, sequence_insert:, **options)
-          new_row = Sequence.create_row(**options)
-
-          # {sequence_insert} is usually a function such as {Linear::Insert::Append} and its arguments.
-          _seq = Sequence.insert_row(sequence, row: new_row, insert: sequence_insert)
-        end
-
-        # Add one or several rows to the {sequence}.
-        # This is usually called from DSL methods such as {step}.
-        def apply_adds_from_dsl(sequence, sequence_insert:, adds:, **options)
-          # This is the ADDS for the actual task.
-          task_add = {row: Sequence.create_row(**options), insert: sequence_insert} # Linear::Insert.method(:Prepend), end_id
-
-          Sequence.apply_adds(sequence, [task_add] + adds)
-        end
-      end # DSL
-
-    end
+    end # Linear
   end
 end
 
+require "trailblazer/activity/dsl/linear/sequence"
+require "trailblazer/activity/dsl/linear/sequence/builder"
+require "trailblazer/activity/dsl/linear/sequence/search"
+require "trailblazer/activity/dsl/linear/sequence/compiler"
 require "trailblazer/activity/dsl/linear/normalizer"
-require "trailblazer/activity/dsl/linear/state"
+require "trailblazer/activity/dsl/linear/normalizer/terminus"
 require "trailblazer/activity/dsl/linear/helper"
+require "trailblazer/activity/dsl/linear/helper/path"
 require "trailblazer/activity/dsl/linear/strategy"
-require "trailblazer/activity/dsl/linear/compiler"
 require "trailblazer/activity/path"
 require "trailblazer/activity/railway"
 require "trailblazer/activity/fast_track"
-require "trailblazer/activity/dsl/linear/variable_mapping"
+require "trailblazer/activity/dsl/linear/feature/variable_mapping"
+require "trailblazer/activity/dsl/linear/feature/variable_mapping/dsl"
+require "trailblazer/activity/dsl/linear/feature/patch"
+
+# feature/variable_mapping
+Trailblazer::Activity::DSL::Linear::VariableMapping.extend!(Trailblazer::Activity::Path, :step)
+Trailblazer::Activity::DSL::Linear::VariableMapping.extend!(Trailblazer::Activity::Railway, :step, :pass, :fail)
+Trailblazer::Activity::DSL::Linear::VariableMapping.extend!(Trailblazer::Activity::FastTrack, :step, :pass, :fail)

data/lib/trailblazer/activity/fast_track.rb

@@ -1,61 +1,52 @@
 module Trailblazer
   class Activity
-    def self.FastTrack(options)
-      Class.new(FastTrack) do
-        initialize!(Railway::DSL::State.new(**FastTrack::DSL.OptionsForState(**options)))
-      end
-    end
-
-    # Implementation module that can be passed to `Activity()`.
-    class FastTrack
-      Linear = Activity::DSL::Linear
+    # Implementation of the "FastTrack" layout that is also used for `Operation`.
+    class FastTrack < Activity::DSL::Linear::Strategy
 
       # Signals
       FailFast = Class.new(Signal)
       PassFast = Class.new(Signal)
 
       module DSL
-        module_function
-
-        def normalizer
-          step_options(Trailblazer::Activity::Railway::DSL.normalizer)
-        end
+        Linear = Activity::DSL::Linear
 
-        def normalizer_for_fail
-          pipeline = step_options(Trailblazer::Activity::Railway::DSL.normalizer_for_fail)
+        module_function
 
-          TaskWrap::Pipeline.prepend(
-            pipeline,
-            "path.wirings",
+        def Normalizer(base_normalizer=Trailblazer::Activity::Railway::DSL.Normalizer())
+          Linear::Normalizer.prepend_to(
+            base_normalizer,
+            "activity.wirings",
 
             {
-              "fast_track.fail_fast_option_for_fail"  => Linear::Normalizer.Task(method(:fail_fast_option_for_fail)),
+              "fast_track.pass_fast_option"  => Linear::Normalizer.Task(method(:pass_fast_option)),
+              "fast_track.fail_fast_option"  => Linear::Normalizer.Task(method(:fail_fast_option)),
+              "fast_track.fast_track_option" => Linear::Normalizer.Task(method(:fast_track_option)),
             }
           )
         end
 
-        def normalizer_for_pass
-          pipeline = step_options(Trailblazer::Activity::Railway::DSL.normalizer_for_pass)
+        def NormalizerForFail
+          pipeline = Normalizer(Railway::DSL.NormalizerForFail())
 
-          TaskWrap::Pipeline.prepend(
+          Linear::Normalizer.prepend_to(
             pipeline,
-            "path.wirings",
+            "activity.wirings",
 
             {
-              "fast_track.pass_fast_option_for_pass"  => Linear::Normalizer.Task(method(:pass_fast_option_for_pass)),
+              "fast_track.fail_fast_option_for_fail"  => Linear::Normalizer.Task(method(:fail_fast_option_for_fail)),
             }
           )
         end
 
-        def step_options(pipeline)
-          TaskWrap::Pipeline.prepend(
+        def NormalizerForPass
+          pipeline = Normalizer(Railway::DSL.NormalizerForPass())
+
+          Linear::Normalizer.prepend_to(
             pipeline,
-            "path.wirings",
+            "activity.wirings",
 
             {
-              "fast_track.pass_fast_option"  => Linear::Normalizer.Task(method(:pass_fast_option)),
-              "fast_track.fail_fast_option"  => Linear::Normalizer.Task(method(:fail_fast_option)),
-              "fast_track.fast_track_option" => Linear::Normalizer.Task(method(:fast_track_option)),
+              "fast_track.pass_fast_option_for_pass"  => Linear::Normalizer.Task(method(:pass_fast_option_for_pass)),
             }
           )
         end
@@ -106,7 +97,7 @@ module Trailblazer
         def merge_connections_for!(ctx, option_name, semantic, magnetic_to=option_name, connections:, **)
           return ctx unless ctx[option_name]
 
-          ctx[:connections] = connections.merge(semantic => [Linear::Search.method(:Forward), magnetic_to])
+          ctx[:connections] = connections.merge(semantic => [Linear::Sequence::Search.method(:Forward), magnetic_to])
           ctx
         end
 
@@ -115,31 +106,28 @@ module Trailblazer
           ctx
         end
 
-        def initial_sequence(initial_sequence:, fail_fast_end: Activity::End.new(semantic: :fail_fast), pass_fast_end: Activity::End.new(semantic: :pass_fast), **_o)
-          sequence = initial_sequence
-
-          sequence = Path::DSL.append_end(sequence, task: fail_fast_end, magnetic_to: :fail_fast, id: "End.fail_fast")
-          sequence = Path::DSL.append_end(sequence, task: pass_fast_end, magnetic_to: :pass_fast, id: "End.pass_fast")
+        def initial_sequence(sequence:, fail_fast_end: Activity::End.new(semantic: :fail_fast), pass_fast_end: Activity::End.new(semantic: :pass_fast), **)
+          sequence = Path::DSL.append_terminus(sequence, fail_fast_end, magnetic_to: :fail_fast, id: "End.fail_fast", normalizers: Normalizers)
+          sequence = Path::DSL.append_terminus(sequence, pass_fast_end, magnetic_to: :pass_fast, id: "End.pass_fast", normalizers: Normalizers)
         end
 
-        # This is slow and should be done only once at compile-time,
-        # DISCUSS: maybe make this a function?
-        # These are the normalizers for an {Activity}, to be injected into a State.
-        Normalizers = Linear::State::Normalizer.new(
-          step: Linear::Normalizer.activity_normalizer( FastTrack::DSL.normalizer ), # here, we extend the generic FastTrack::step_normalizer with the Activity-specific DSL
-          fail: Linear::Normalizer.activity_normalizer( FastTrack::DSL.normalizer_for_fail ),
-          pass: Linear::Normalizer.activity_normalizer( FastTrack::DSL.normalizer_for_pass ),
+        # Normalizer pipelines taking care of processing your DSL options.
+        Normalizers = Linear::Normalizer::Normalizers.new(
+          step: FastTrack::DSL.Normalizer(),
+          fail: FastTrack::DSL.NormalizerForFail(),
+          pass: FastTrack::DSL.NormalizerForPass(),
+          terminus: Linear::Normalizer::Terminus.Normalizer(),
         )
 
-        def self.OptionsForState(normalizers: Normalizers, **options)
-          options = Railway::DSL.OptionsForState(**options).
-              merge(normalizers: normalizers)
+        def self.OptionsForSequenceBuilder(**options)
+
+          options = Railway::DSL.OptionsForSequenceBuilder(**options)
 
-          initial_sequence = FastTrack::DSL.initial_sequence(**options)
+          initial_sequence = DSL.initial_sequence(**options)
 
           {
             **options,
-            initial_sequence: initial_sequence,
+            sequence: initial_sequence,
           }
         end
       end # DSL
@@ -154,10 +142,11 @@ module Trailblazer
         end
       end
 
-      include Activity::DSL::Linear::Helper
-      extend Activity::DSL::Linear::Strategy
-
-      initialize!(Railway::DSL::State.new(**DSL.OptionsForState()))
+      compile_strategy!(DSL, normalizers: DSL::Normalizers)
     end # FastTrack
+
+    def self.FastTrack(**options, &block)
+      Activity::DSL::Linear::Strategy::DSL.Build(FastTrack, **options, &block)
+    end
   end
 end