trailblazer-activity-dsl-linear 1.1.0 → 1.2.1

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

@@ -6,10 +6,7 @@ module Trailblazer
         # and then get processed in the normalizer.
         #
         # @private
-        OutputSemantic = Struct.new(:value)
-        Id             = Struct.new(:value)
-        Track          = Struct.new(:color, :adds, :options)
-        Extension      = Struct.new(:callable) do
+        Extension = Struct.new(:callable) do
           def call(*args, &block)
             callable.(*args, &block)
           end
@@ -27,14 +24,14 @@ module Trailblazer
 
           #   Output( Left, :failure )
           #   Output( :failure ) #=> Output::Semantic
-          def Output(signal, semantic=nil)
-            return OutputSemantic.new(signal) if semantic.nil?
+          def Output(signal, semantic = nil)
+            return Normalizer::OutputTuples::Output::Semantic.new(signal) if semantic.nil?
 
-            Activity.Output(signal, semantic)
+            Normalizer::OutputTuples::Output::CustomOutput.new(signal, semantic)
           end
 
           def End(semantic)
-            Activity.End(semantic)
+            Normalizer::OutputTuples::End.new(semantic).freeze
           end
 
           def end_id(semantic:, **)
@@ -42,15 +39,15 @@ module Trailblazer
           end
 
           def Track(color, wrap_around: false)
-            Track.new(color, [], wrap_around: wrap_around).freeze
+            Normalizer::OutputTuples::Track.new(color, [], wrap_around: wrap_around).freeze
           end
 
           def Id(id)
-            Id.new(id).freeze
+            Normalizer::OutputTuples::Id.new(id).freeze
           end
 
           def Path(**options, &block)
-            options = options.merge(block: block) if block_given?
+            options = options.merge(block: block) if block
 
             Linear::PathBranch.new(options) # picked up by normalizer.
           end
@@ -59,27 +56,39 @@ module Trailblazer
           # @param :strict If true, all outputs of {activity} will be wired to the track named after the
           #   output's semantic.
           def Subprocess(activity, patch: {}, strict: false)
-            activity = Linear.Patch(activity, patch)
+            activity = Linear::Patch.customize(activity, options: patch)
 
             outputs  = activity.to_h[:outputs]
             options  = {}
 
             if strict
               options.merge!(
-                outputs.collect { |output| [Output(output.semantic), Track(output.semantic)] }.to_h
+                outputs.collect { |output| [Normalizer::OutputTuples::Output::Semantic.new(output.semantic, true), Track(output.semantic)] }.to_h
               )
             end
 
             {
               task:    activity,
               outputs: outputs.collect { |output| [output.semantic, output] }.to_h,
-            }.
-            merge(options)
+            }
+              .merge(options)
           end
 
-          def In(**kws);     VariableMapping::DSL::In(**kws); end
-          def Out(**kws);    VariableMapping::DSL::Out(**kws); end
-          def Inject(*args, **kws); VariableMapping::DSL::Inject(*args, **kws); end
+          def In(**kws)
+            VariableMapping::DSL::In(**kws)
+          end
+
+          def Out(**kws)
+            VariableMapping::DSL::Out(**kws)
+          end
+
+          def Inject(*args, **kws)
+            VariableMapping::DSL::Inject(*args, **kws)
+          end
+
+          def Extension(*args, **kws)
+            Normalizer::Extensions.Extension(*args, **kws)
+          end
 
           def DataVariable
             DataVariableName.new

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

@@ -0,0 +1,63 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        module Normalizer
+          # Implements {:extensions} option and allows adding taskWrap extensions using
+          # Linear::Normalizer::Extensions.Extension().
+          module Extensions
+            module_function
+
+            Extension = Struct.new(:generic?, :id)
+
+            def Extension(is_generic: false)
+              Extension.new(is_generic, rand) # {id} has to be unique for every Extension instance (for Hash identity).
+            end
+
+            # Convert {:extensions} option to {Extension} tuples. The new way of adding extensions is
+            #   step ..., Extension() => my_extension
+            def convert_extensions_option_to_tuples(ctx, non_symbol_options:, extensions: nil, **)
+              return unless extensions
+              # TODO: deprecate {:extensions} in the DSL?
+
+              extensions_tuples = extensions.collect { |ext| [Extension(), ext] }.to_h
+
+              ctx.merge!(
+                non_symbol_options: non_symbol_options.merge(extensions_tuples)
+              )
+            end
+
+            def compile_extensions(ctx, non_symbol_options:, **)
+              extensions_ary =
+                non_symbol_options
+                  .find_all { |k, v| k.instance_of?(Extension) }
+                  .to_h
+                  .values
+
+              ctx.merge!(
+                extensions: extensions_ary
+              )
+            end
+
+            # Don't record Extension()s created by the DSL! This happens in VariableMapping, for instance.
+            # Either the user also inherits I/O tuples and the extension will be recreated,
+            # or they really don't want this particular extension to be inherited.
+            def compile_recorded_extensions(ctx, non_symbol_options:, **)
+              recorded_extension_tuples =
+                non_symbol_options
+                  .find_all { |k, v| k.instance_of?(Extension) }
+                  .reject   { |k, v| k.generic? }
+                  .to_h
+
+              ctx.merge!(
+                non_symbol_options: non_symbol_options.merge(
+                  Normalizer::Inherit.Record(recorded_extension_tuples, type: :extensions)
+                )
+              )
+            end
+          end # Extensions
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        module Normalizer
+          # Implements the generic {:inherit} option.
+          # Features such as variable mapping or the Wiring API can
+          # use the generic behavior for their inheritance.
+
+          # "generic": built by the DSL from options, options that are inherited, so you might not want to record or inherit generic options
+          module Inherit
+            module_function
+
+            # Options you want to have stored and inherited can be
+            # declared using Record.
+            Record = Struct.new(:options, :type, :non_symbol_options?) # FIXME: i hate symbol vs. non-symbol.
+
+            def Record(options, type:, non_symbol_options: true)
+              {Record.new(options, type, non_symbol_options) => nil}
+            end
+
+            # Currently, the {:inherit} option copies over {:extensions} from the original step and merges them with new :extensions.
+            #
+            ### Recall
+            # Fetch remembered options and add them to the processed options.
+            def recall_recorded_options(ctx, non_symbol_options:, sequence:, id:, inherit: nil, extensions: [], **)
+              return unless inherit === true || inherit.is_a?(Array)
+
+              # E.g. {variable_mapping: true, wiring_api: true}
+              types_to_recall =
+                if inherit === true
+                  # we want to inherit "everything": extensions, output_tuples, variable_mapping
+                  Hash.new { true }
+                else
+                  inherit.collect { |type| [type, true] }.to_h
+                end
+
+              row = find_row(sequence, id) # from this row we're inheriting options.
+
+              # DISCUSS: should we maybe revert the idea of separating options by type?
+              # Anyway, key idea here is that Record() users don't have to know these details
+              # about symbol vs. non-symbol.
+              symbol_options_to_merge     = {}
+              non_symbol_options_to_merge = {}
+
+              row.data[:recorded_options].each do |type, record|
+                next unless types_to_recall[type]
+
+                target = record.non_symbol_options? ? non_symbol_options_to_merge : symbol_options_to_merge
+                target.merge!(record.options)
+              end
+
+              ctx[:non_symbol_options] = non_symbol_options_to_merge.merge(non_symbol_options)
+
+              ctx.merge!(symbol_options_to_merge)
+
+              ctx.merge!(
+                inherited_recorded_options: row.data[:recorded_options]
+              )
+            end
+
+            def find_row(sequence, id)
+              index = Activity::Adds::Insert.find_index(sequence, id)
+              sequence[index]
+            end
+
+            ### Record
+            # Figure out what to remember from the options and store it in {row.data[:recorded_options]}.
+            # Note that this is generic logic not tied to variable_mapping, OutputTuples or anything.
+            def compile_recorded_options(ctx, non_symbol_options:, **)
+              recorded_options = {}
+
+              non_symbol_options
+                .find_all { |k, v| k.instance_of?(Record) }
+                .collect  do |k, v|
+                  recorded_options[k.type] = k   # DISCUSS: we overwrite potential data with same type.
+                end
+
+              ctx.merge!(
+                recorded_options:   recorded_options,
+                # add {row.data[:recorded_options]} in Sequence:
+                non_symbol_options: non_symbol_options.merge(Strategy.DataVariable() => :recorded_options)
+              )
+            end
+          end # Inherit
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        module Normalizer
+          # Implements Output(:success) => Track(:success)
+          # Internals are documented: https://trailblazer.to/2.1/docs/internals.html#internals-wiring-api-output-tuples
+          module OutputTuples
+            module_function
+
+            # Connector when using Id(:validate).
+            class Id < Struct.new(:value)
+              def to_a(*)
+                return [Linear::Sequence::Search.method(:ById), value], [] # {value} is the "target".
+              end
+            end
+
+            # Connector when using Track(:success).
+            class Track < Struct.new(:color, :adds, :options)
+              def to_a(*)
+                search_strategy = options[:wrap_around] ? :WrapAround : :Forward
+
+                return [Linear::Sequence::Search.method(search_strategy), color], adds
+              end
+            end
+
+            # Connector representing a (to-be-created?) terminus when using End(:semantic).
+            class End < Struct.new(:semantic)
+              def to_a(ctx)
+                end_id     = Linear::Strategy.end_id(semantic: semantic)
+                end_exists = Activity::Adds::Insert.find_index(ctx[:sequence], end_id)
+
+                terminus = Activity.End(semantic)
+
+                adds = end_exists ? [] : OutputTuples::Connections.add_terminus(terminus, id: end_id, sequence: ctx[:sequence], normalizers: ctx[:normalizers])
+
+                return [Linear::Sequence::Search.method(:ById), end_id], adds
+              end
+            end
+
+            # Logic related to {Output() => ...}, called "Wiring API".
+            # TODO: move to different namespace (feature/dsl)
+            def Output(semantic, is_generic: true)
+              Normalizer::OutputTuples::Output::Semantic.new(semantic, is_generic)
+            end
+
+            module Output
+              # Note that both {Semantic} and {CustomOutput} are {is_a?(Output)}
+              Semantic      = Struct.new(:semantic, :generic?).include(Output)
+              CustomOutput  = Struct.new(:signal, :semantic, :generic?).include(Output) # generic? is always false
+            end
+
+            def normalize_output_tuples(ctx, non_symbol_options:, **)
+              output_tuples = non_symbol_options.find_all { |k, v| k.is_a?(OutputTuples::Output) }
+
+              ctx.merge!(output_tuples: output_tuples)
+            end
+
+            # Remember all custom (non-generic) {:output_tuples}.
+            def remember_custom_output_tuples(ctx, output_tuples:, non_symbol_options:, **)
+              # We don't include generic OutputSemantic (from Subprocess(strict: true)) for inheritance, as this is not a user customization.
+              custom_output_tuples = output_tuples.reject { |k, v| k.generic? }
+
+              # save Output() tuples under {:custom_output_tuples} for inheritance.
+              ctx.merge!(
+                non_symbol_options: non_symbol_options.merge(
+                  Normalizer::Inherit.Record(custom_output_tuples.to_h, type: :custom_output_tuples)
+                )
+              )
+            end
+
+            # Take all Output(signal, semantic), convert to OutputSemantic and extend {:outputs}.
+            # Since only users use this style, we don't have to filter.
+            def register_additional_outputs(ctx, output_tuples:, outputs:, **)
+              # We need to preserve the order when replacing Output with OutputSemantic,
+              # that's why we recreate {output_tuples} here.
+              output_tuples =
+                output_tuples.collect do |(output, connector)|
+                  if output.is_a?(Output::CustomOutput)
+                    # add custom output to :outputs.
+                    outputs = outputs.merge(output.semantic => Activity.Output(output.signal, output.semantic))
+
+                    # Convert Output to OutputSemantic.
+                    [Strategy.Output(output.semantic), connector]
+                  else
+                    [output, connector]
+                  end
+                end
+
+              ctx.merge!(
+                output_tuples: output_tuples,
+                outputs:       outputs
+              )
+            end
+
+            # Implements {inherit: :outputs, strict: false}
+            # return connections from {parent} step which are supported by current step
+            def filter_inherited_output_tuples(ctx, outputs:, output_tuples:, inherit: false, inherited_recorded_options: {}, **)
+              return unless inherit === true
+              strict_outputs = false # TODO: implement "strict outputs" for inherit! meaning we connect all inherited Output regardless of the new activity's interface
+              return if strict_outputs === true
+
+              # Grab the inherited {:custom_output_tuples} so we can throw those out if the new activity doesn't support
+              # the respective outputs.
+              inherited_output_tuples_record  = inherited_recorded_options[:custom_output_tuples]
+              inherited_output_tuples         = inherited_output_tuples_record ? inherited_output_tuples_record.options : {}
+
+              allowed_semantics     = outputs.keys # these outputs are exposed by the inheriting step.
+              inherited_semantics   = inherited_output_tuples.collect { |output, _| output.semantic }
+              unsupported_semantics = inherited_semantics - allowed_semantics
+
+              filtered_output_tuples = output_tuples.reject { |output, _| unsupported_semantics.include?(output.semantic) }
+
+              ctx.merge!(
+                output_tuples: filtered_output_tuples.to_h
+              )
+            end
+
+            # Compile connections from tuples.
+            module Connections
+              module_function
+
+              # we want this in the end:
+              # {output.semantic => search strategy}
+              # Process {Output(:semantic) => target} and make them {:connections}.
+              # This combines {:connections} and {:outputs}
+              def compile_wirings(ctx, adds:, output_tuples:, outputs:, id:, **)
+                # DISCUSS: how could we add another magnetic_to to an end?
+                # Go through all {Output() => Track()/Id()/End()} tuples.
+                wirings =
+                  output_tuples.collect do |output, connector|
+                    (search_builder, search_args), connector_adds = connector.to_a(ctx) # Call {#to_a} on Track/Id/End/...
+
+                    adds += connector_adds
+
+                    semantic = output.semantic
+                    output   = outputs[semantic] || raise("No `#{semantic}` output found for #{id.inspect} and outputs #{outputs.inspect}")
+
+                    # return proc to be called when compiling Seq, e.g. {ById(output, :id)}
+                    search_builder.(output, *search_args)
+                  end
+
+                ctx[:wirings] = wirings
+                ctx[:adds]    = adds
+              end
+
+              # Returns ADDS for the new terminus.
+              # @private
+              def add_terminus(end_event, id:, sequence:, normalizers:)
+                step_options = Linear::Sequence::Builder.invoke_normalizer_for(:terminus, end_event, {id: id}, sequence: sequence, normalizer_options: {}, normalizers: normalizers)
+
+                step_options[:adds]
+              end
+            end # Connections
+          end # OutputTuples
+        end
+      end
+    end
+  end
+end

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

@@ -10,28 +10,28 @@ module Trailblazer
             def Normalizer
               normalizer_steps =
                 {
-                "activity.normalize_step_interface"       => Normalizer.Task(Normalizer.method(:normalize_step_interface)),      # first
-                "activity.merge_library_options"          => Normalizer.Task(Normalizer.method(:merge_library_options)),    # Merge "macro"/user options over library options.
-                "activity.normalize_for_macro"            => Normalizer.Task(Normalizer.method(:merge_user_options)),
-                "activity.normalize_normalizer_options"   => Normalizer.Task(Normalizer.method(:merge_normalizer_options)),
-                "activity.normalize_non_symbol_options"   => Normalizer.Task(Normalizer.method(:normalize_non_symbol_options)),
-                "activity.normalize_context"              => Normalizer.method(:normalize_context),
-                "terminus.normalize_task"                 => Normalizer.Task(Terminus.method(:normalize_task)),
-                "terminus.normalize_id"                   => Normalizer.Task(method(:normalize_id)),
-                "terminus.normalize_magnetic_to"          => Normalizer.Task(Terminus.method(:normalize_magnetic_to)),
-                "terminus.append_end"                     => Normalizer.Task(Terminus.method(:append_end)),
+                  "activity.normalize_step_interface"       => Normalizer.Task(Normalizer.method(:normalize_step_interface)),      # first
+                  "activity.merge_library_options"          => Normalizer.Task(Normalizer.method(:merge_library_options)),    # Merge "macro"/user options over library options.
+                  "activity.normalize_for_macro"            => Normalizer.Task(Normalizer.method(:merge_user_options)),
+                  "activity.normalize_normalizer_options"   => Normalizer.Task(Normalizer.method(:merge_normalizer_options)),
+                  "activity.normalize_non_symbol_options"   => Normalizer.Task(Normalizer.method(:normalize_non_symbol_options)),
+                  "activity.normalize_context"              => Normalizer.method(:normalize_context),
+                  "terminus.normalize_task"                 => Normalizer.Task(Terminus.method(:normalize_task)),
+                  "terminus.normalize_id"                   => Normalizer.Task(method(:normalize_id)),
+                  "terminus.normalize_magnetic_to"          => Normalizer.Task(Terminus.method(:normalize_magnetic_to)),
+                  "terminus.append_end"                     => Normalizer.Task(Terminus.method(:append_end)),
 
-                "activity.compile_data" => Normalizer.Task(Normalizer.method(:compile_data)), # FIXME
-                "activity.create_row" => Normalizer.Task(Normalizer.method(:create_row)),
-                "activity.create_add" => Normalizer.Task(Normalizer.method(:create_add)),
-                "activity.create_adds" => Normalizer.Task(Normalizer.method(:create_adds)),
+                  "activity.compile_data" => Normalizer.Task(Normalizer.method(:compile_data)), # FIXME: redundant with {Linear::Normalizer}.
+                  "activity.create_row" => Normalizer.Task(Normalizer.method(:create_row)),
+                  "activity.create_add" => Normalizer.Task(Normalizer.method(:create_add)),
+                  "activity.create_adds" => Normalizer.Task(Normalizer.method(:create_adds)),
                 }
 
               TaskWrap::Pipeline.new(normalizer_steps.to_a)
             end
 
             # @private
-            def normalize_id(ctx, id: nil, semantic:, **)
+            def normalize_id(ctx, semantic:, id: nil, **)
               ctx.merge!(
                 id: id || Strategy.end_id(semantic: semantic)
               )
@@ -40,11 +40,11 @@ module Trailblazer
             # @private
             # Set {:task} and {:semantic}.
             def normalize_task(ctx, task:, **)
-              if task.kind_of?(Activity::End) # DISCUSS: do we want this check?
-                ctx = _normalize_task_for_end_event(ctx, **ctx)
+              if task.is_a?(Activity::End) # DISCUSS: do we want this check?
+                _ctx = _normalize_task_for_end_event(ctx, **ctx)
               else
                 # When used such as {terminus :found}, create the end event automatically.
-                ctx = _normalize_task_for_symbol(ctx, **ctx)
+                _ctx = _normalize_task_for_symbol(ctx, **ctx)
               end
             end
 
@@ -56,8 +56,8 @@ module Trailblazer
 
             def _normalize_task_for_symbol(ctx, task:, semantic: task, **)
               ctx.merge!(
-                task:     Strategy.End(semantic),
-                semantic: semantic,
+                task:     Activity.End(semantic),
+                semantic: semantic
               )
             end
 
@@ -68,19 +68,16 @@ module Trailblazer
             end
 
             # @private
-            def append_end(ctx, task:, semantic:, append_to: "End.success", **)
+            def append_end(ctx, task:, append_to: "End.success", non_symbol_options:, **)
               terminus_args = {
-                sequence_insert: [Activity::Adds::Insert.method(:Append), append_to],
-                stop_event:      true
+                sequence_insert:    [Activity::Adds::Insert.method(:Append), append_to],
+                stop_event:         true,
+                non_symbol_options: non_symbol_options.merge(Strategy.DataVariable() => [:stop_event, :semantic])
               }
 
               ctx.merge!(
-                wirings: [
-                  Linear::Sequence::Search::Noop(
-                    Activity::Output.new(task, semantic), # DISCUSS: do we really want to transport the semantic "in" the object?
-                  )
-                ],
-                adds: [],
+                wirings: [],
+                adds:    [],
                 **terminus_args
               )
             end