trailblazer-activity-dsl-linear 0.1.0

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

@@ -0,0 +1,220 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        # Normalizers are linear activities that process and normalize the options from a DSL call. They're
+        # usually invoked from {Strategy#task_for}, which is called from {Path#step}, {Railway#pass}, etc.
+        module Normalizer
+          module_function
+
+          #   activity_normalizer.([{options:, user_options:, normalizer_options: }])
+          def activity_normalizer(sequence)
+            seq = Activity::Path::DSL.prepend_to_path( # this doesn't particularly put the steps after the Path steps.
+              sequence,
+
+              {
+              "activity.normalize_step_interface"       => method(:normalize_step_interface),      # first
+              "activity.normalize_override"             => method(:normalize_override),
+              "activity.normalize_for_macro"            => method(:merge_user_options),
+              "activity.normalize_normalizer_options"   => method(:merge_normalizer_options),
+              "activity.normalize_context"              => method(:normalize_context),
+              "activity.normalize_id"                   => method(:normalize_id),
+              "activity.wrap_task_with_step_interface"  => method(:wrap_task_with_step_interface), # last
+              },
+
+              Linear::Insert.method(:Append), "Start.default"
+            )
+
+            seq = Trailblazer::Activity::Path::DSL.prepend_to_path( # this doesn't particularly put the steps after the Path steps.
+              seq,
+
+              {
+              "activity.normalize_outputs_from_dsl"     => method(:normalize_outputs_from_dsl),     # Output(Signal, :semantic) => Id()
+              "activity.normalize_connections_from_dsl" => method(:normalize_connections_from_dsl),
+              },
+
+              Linear::Insert.method(:Prepend), "path.wirings"
+            )
+
+            seq = Trailblazer::Activity::Path::DSL.prepend_to_path( # this doesn't particularly put the steps after the Path steps.
+              seq,
+
+              {
+              "activity.cleanup_options"     => method(:cleanup_options),
+              },
+
+              Linear::Insert.method(:Prepend), "End.success"
+            )
+# pp seq
+            seq
+          end
+
+          # Specific to the "step DSL": if the first argument is a callable, wrap it in a {step_interface_builder}
+          # since its interface expects the step interface, but the circuit will call it with circuit interface.
+          def normalize_step_interface((ctx, flow_options), *)
+            options = ctx[:options] # either a <#task> or {} from macro
+
+            unless options.is_a?(::Hash)
+              # task = wrap_with_step_interface(task: options, step_interface_builder: ctx[:user_options][:step_interface_builder]) # TODO: make this optional with appropriate wiring.
+              task = options
+
+              ctx = ctx.merge(options: {task: task, wrap_task: true})
+            end
+
+            return Trailblazer::Activity::Right, [ctx, flow_options]
+          end
+
+          def wrap_task_with_step_interface((ctx, flow_options), **)
+            return Trailblazer::Activity::Right, [ctx, flow_options] unless ctx[:wrap_task]
+
+            step_interface_builder = ctx[:step_interface_builder] # FIXME: use kw!
+            task                   = ctx[:task] # FIXME: use kw!
+
+            wrapped_task = step_interface_builder.(task)
+
+            return Trailblazer::Activity::Right, [ctx.merge(task: wrapped_task), flow_options]
+          end
+
+          def normalize_id((ctx, flow_options), **)
+            id = ctx[:id] || ctx[:task]
+
+            return Trailblazer::Activity::Right, [ctx.merge(id: id), flow_options]
+          end
+
+          # {:override} really only makes sense for {step Macro(), {override: true}} where the {user_options}
+          # dictate the overriding.
+          def normalize_override((ctx, flow_options), *)
+            user_options = ctx[:user_options]
+            user_options = user_options.merge(replace: ctx[:options][:id] || raise) if ctx[:user_options][:override]
+
+            return Trailblazer::Activity::Right, [ctx.merge(user_options: user_options), flow_options]
+          end
+
+          # make ctx[:options] the actual ctx
+          def merge_user_options((ctx, flow_options), *)
+            options = ctx[:options] # either a <#task> or {} from macro
+
+            ctx = ctx.merge(options: options.merge(ctx[:user_options])) # Note that the user options are merged over the macro options.
+
+            return Trailblazer::Activity::Right, [ctx, flow_options]
+          end
+
+          # {:normalizer_options} such as {:track_name} get overridden by user/macro.
+          def merge_normalizer_options((ctx, flow_options), *)
+            normalizer_options = ctx[:normalizer_options] # either a <#task> or {} from macro
+
+            ctx = ctx.merge(options: normalizer_options.merge(ctx[:options])) #
+
+            return Trailblazer::Activity::Right, [ctx, flow_options]
+          end
+
+          def normalize_context((ctx, flow_options), *)
+            ctx = ctx[:options]
+
+            return Trailblazer::Activity::Right, [ctx, flow_options]
+          end
+
+          # Compile the actual {Seq::Row}'s {wiring}.
+          def compile_wirings((ctx, flow_options), *)
+            connections = ctx[:connections] || raise # FIXME
+            outputs = ctx[:outputs] || raise # FIXME
+
+            ctx[:wirings] =
+              connections.collect do |semantic, (search_strategy_builder, *search_args)|
+                output = outputs[semantic] || raise("No `#{semantic}` output found for #{outputs.inspect}")
+
+                search_strategy_builder.( # return proc to be called when compiling Seq, e.g. {ById(output, :id)}
+                  output,
+                  *search_args
+                )
+              end
+
+            return Trailblazer::Activity::Right, [ctx, flow_options]
+          end
+
+          # Process {Output(:semantic) => target}.
+          def normalize_connections_from_dsl((ctx, flow_options), *)
+            new_ctx = ctx.reject { |output, cfg| output.kind_of?(Activity::DSL::Linear::OutputSemantic) }
+            connections = new_ctx[:connections]
+            adds        = new_ctx[:adds]
+
+            # Find all {Output() => Track()/Id()/End()}
+            (ctx.keys - new_ctx.keys).each do |output|
+              cfg = ctx[output]
+
+              new_connections, add =
+                if cfg.is_a?(Activity::DSL::Linear::Track)
+                  [output_to_track(ctx, output, cfg), cfg.adds]
+                elsif cfg.is_a?(Activity::DSL::Linear::Id)
+                  [output_to_id(ctx, output, cfg.value), []]
+                elsif cfg.is_a?(Activity::End)
+                  _adds = []
+
+                  end_id     = Linear.end_id(cfg)
+                  end_exists = Insert.find_index(ctx[:sequence], end_id)
+
+                  _adds      = [add_end(cfg, magnetic_to: end_id, id: end_id)] unless end_exists
+
+                  [output_to_id(ctx, output, end_id), _adds]
+                end
+
+              connections = connections.merge(new_connections)
+              adds += add
+            end
+
+            new_ctx = new_ctx.merge(connections: connections, adds: adds)
+
+            return Trailblazer::Activity::Right, [new_ctx, flow_options]
+          end
+
+          def output_to_track(ctx, output, target)
+            {output.value => [Linear::Search.method(:Forward), target.color]}
+          end
+
+          def output_to_id(ctx, output, target)
+            {output.value => [Linear::Search.method(:ById), target]}
+          end
+
+          # {#insert_task} options to add another end.
+          def add_end(end_event, magnetic_to:, id:)
+
+            options = Path::DSL.append_end_options(task: end_event, magnetic_to: magnetic_to, id: id)
+            row     = Linear::Sequence.create_row(options)
+
+            {
+              row:    row,
+              insert: row[3][:sequence_insert]
+            }
+          end
+
+          # Output(Signal, :semantic) => Id()
+          def normalize_outputs_from_dsl((ctx, flow_options), *)
+            new_ctx = ctx.reject { |output, cfg| output.kind_of?(Activity::Output) }
+
+            outputs     = ctx[:outputs]
+            dsl_options = {}
+
+            (ctx.keys - new_ctx.keys).collect do |output|
+              cfg      = ctx[output] # e.g. Track(:success)
+
+              outputs = outputs.merge(output.semantic => output)
+              dsl_options = dsl_options.merge(Linear.Output(output.semantic) => cfg)
+            end
+
+            new_ctx = new_ctx.merge(outputs: outputs).merge(dsl_options)
+
+            return Trailblazer::Activity::Right, [new_ctx, flow_options]
+          end
+
+          # TODO: make this extendable!
+          def cleanup_options((ctx, flow_options), *)
+            new_ctx = ctx.reject { |k, v| [:connections, :outputs, :end_id, :step_interface_builder, :failure_end, :track_name, :sequence].include?(k) }
+
+            return Trailblazer::Activity::Right, [new_ctx, flow_options]
+          end
+        end
+
+      end # Normalizer
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        # A {State} instance is kept per DSL client, which usually is a subclass of {Path}, {Railway}, etc.
+        class State
+            # remembers how to call normalizers (e.g. track_color), TaskBuilder
+            # remembers sequence
+          def initialize(normalizers:, initial_sequence:, **normalizer_options)
+            @normalizer         = normalizers # compiled normalizers.
+            @sequence           = initial_sequence
+            @normalizer_options = normalizer_options
+          end
+
+          # Called to "inherit" a state.
+          def copy
+            self.class.new(normalizers: @normalizer, initial_sequence: @sequence, **@normalizer_options)
+          end
+
+          def to_h
+            {sequence: @sequence, normalizers: @normalizer, normalizer_options: @normalizer_options} # FIXME.
+          end
+
+          def update_sequence(&block)
+            @sequence = yield(to_h)
+          end
+
+          # Compiles and maintains all final normalizers for a specific DSL.
+          class Normalizer
+            def compile_normalizer(normalizer_sequence)
+              process = Trailblazer::Activity::DSL::Linear::Compiler.(normalizer_sequence)
+              process.to_h[:circuit]
+            end
+
+            # [gets instantiated at compile time.]
+            #
+            # We simply compile the activities that represent the normalizers for #step, #pass, etc.
+            # This can happen at compile-time, as normalizers are stateless.
+            def initialize(normalizer_sequences)
+              @normalizers = Hash[
+                normalizer_sequences.collect { |name, seq| [name, compile_normalizer(seq)] }
+              ]
+            end
+
+            # Execute the specific normalizer (step, fail, pass) for a particular option set provided
+            # by the DSL user. This is usually when you call Operation::step.
+            def call(name, *args)
+              normalizer = @normalizers.fetch(name)
+              signal, (options, _) = normalizer.(*args)
+              options
+            end
+          end
+        end # State
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        # {Activity}
+        #   holds the {@schema}
+        #   provides DSL step/merge!
+        #   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
+
+          def inherited(inheriter)
+            super
+
+            # inherits the {@sequence}, and options.
+            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)
+
+            # {#update_sequence} is the only way to mutate the state instance.
+            state.update_sequence do |sequence:, normalizers:, normalizer_options:|
+              # Compute the sequence rows.
+              options = normalizers.(type, normalizer_options: normalizer_options, options: task, user_options: options.merge(sequence: sequence))
+
+              sequence = Activity::DSL::Linear::DSL.apply_adds_from_dsl(sequence, options)
+            end
+          end
+
+          # @public
+          private def step(*args, &block)
+            recompile_activity_for(:step, *args, &block)
+          end
+
+          private def recompile_activity_for(type, *args, &block)
+            args = forward_block(args, block)
+
+            seq  = @state.send(type, *args)
+
+            recompile_activity!(seq)
+          end
+
+          private def recompile_activity!(seq)
+            schema    = Compiler.(seq)
+
+            @activity = Activity.new(schema)
+          end
+
+          private def forward_block(args, block)
+            options = args[1]
+            if options.is_a?(Hash) # FIXME: doesn't account {task: <>} and repeats logic from Normalizer.
+              output, proxy = (options.find { |k,v| v.is_a?(BlockProxy) } or return args)
+              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?
+              return args[0], options.merge(output => Linear.Path(**shared_options, **proxy.options, &block))
+            end
+
+            args
+          end
+
+          extend Forwardable
+          def_delegators Linear, :Output, :End, :Track, :Id, :Subprocess
+
+          def Path(options) # we can't access {block} here, syntactically.
+            BlockProxy.new(options)
+          end
+
+          BlockProxy = Struct.new(:options)
+
+          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
+
+            seq = Linear.Merge(old_seq, new_seq, end_id: "End.success")
+
+            @state.instance_variable_set(:@sequence, seq) # FIXME: hate this so much.
+          end
+
+          extend Forwardable
+          def_delegators :@activity, :to_h, :call
+        end # Strategy
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# DSL step for Magnetic::Normalizer.
+# Translates `:input` and `:output` into VariableMapping taskWrap extensions.
+def self.normalizer_step_for_input_output(ctx, *)
+  options, io_config = Magnetic::Options.normalize( ctx[:options], [:input, :output] )
+
+  return if io_config.empty?
+
+  ctx[:options] = options # without :input and :output
+  ctx[:options] = options.merge(Trailblazer::Activity::TaskWrap::VariableMapping(io_config) => true)
+end
+
+
+# @private
+def self.filter_for(filter)
+  if filter.is_a?(::Array) || filter.is_a?(::Hash)
+    TaskWrap::DSL.filter_from_dsl(filter)
+  else
+    filter
+  end
+end
+
+# Returns an Extension instance to be thrown into the `step` DSL arguments.
+def self.VariableMapping(input:, output:)
+  input = Input.new(
+    Input::Scoped.new(
+      Trailblazer::Option::KW( filter_for(input) )
+    )
+  )
+
+  output = Output.new(
+    Output::Unscoped.new(
+      Trailblazer::Option::KW( filter_for(output) )
+    )
+  )
+
+  VariableMapping.extension_for(input, output)
+end
+
+module Input
+  class Scoped
+    def initialize(filter)
+      @filter = filter
+    end
+
+    def call(original_ctx, circuit_options)
+      Trailblazer::Context( # TODO: make this interchangeable so we can work on faster contexts?
+        @filter.(original_ctx, **circuit_options)
+      )
+    end
+  end
+end
+
+module DSL
+  # The returned filter compiles a new hash for Scoped/Unscoped that only contains
+  # the desired i/o variables.
+  def self.filter_from_dsl(map)
+    hsh = DSL.hash_for(map)
+
+    ->(incoming_ctx, kwargs) { Hash[hsh.collect { |from_name, to_name| [to_name, incoming_ctx[from_name]] }] }
+  end
+
+  def self.hash_for(ary)
+    return ary if ary.instance_of?(::Hash)
+    Hash[ary.collect { |name| [name, name] }]
+  end
+end
+
+module Output
+  # Merge the resulting {@filter.()} hash back into the original ctx.
+  # DISCUSS: do we need the original_ctx as a filter argument?
+  class Unscoped
+    def initialize(filter)
+      @filter = filter
+    end
+
+    def call(original_ctx, new_ctx, **circuit_options)
+      original_ctx.merge(
+        @filter.(new_ctx, **circuit_options)
+      )
+    end
+  end
+end