trailblazer-activity 0.3.2 → 0.4.o

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

@@ -0,0 +1,105 @@
+module Trailblazer
+  module Activity::Magnetic
+    # The {Normalizer} 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::Binary, default_plus_poles: Normalizer.InitialPlusPoles(), pipeline: Pipeline, extension:[], **options)
+        return new(
+          default_plus_poles: default_plus_poles,
+          extension:          extension,
+          task_builder:       task_builder,
+          pipeline:           pipeline,
+        ), options
+      end
+
+      # @private Might be removed.
+      def self.InitialPlusPoles
+        Activity::Magnetic::DSL::PlusPoles.new.merge(
+          Activity.Output(Activity::Right, :success) => nil,
+          Activity.Output(Activity::Left,  :failure) => nil,
+        )
+      end
+
+      def initialize(task_builder:, default_plus_poles:, pipeline:, **options)
+        @task_builder       = task_builder
+        @default_plus_poles = default_plus_poles
+        @pipeline           = pipeline # TODO: test me.
+        freeze
+      end
+
+      def call(task, options)
+        ctx = {
+          task: task, options:  options,
+          task_builder:         @task_builder,
+          default_plus_poles:   @default_plus_poles,
+        }
+
+        signal, (ctx, ) = @pipeline.( [ctx] )
+
+        return ctx[:options][:task], ctx[:local_options], ctx[:connection_options], ctx[:sequence_options]
+      end
+
+      # needs the basic Normalizer
+
+      # :default_plus_poles is an injectable option.
+      module Pipeline
+        extend Trailblazer::Activity::Path( normalizer_class: DefaultNormalizer, plus_poles: Builder::Path.default_plus_poles )
+
+        def self.split_options( ctx, task:, options:, ** )
+          keywords = extract_dsl_keywords(options)
+
+           # sort through the "original" user DSL options.
+          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] = local_options, options, sequence_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, DSL::Output::Semantic])
+          options.keys - options.keys.find_all { |k| connection_classes.include?( k.class ) }
+        end
+
+        # FIXME; why don't we use the extensions passed into the initializer?
+        def self.normalize_extension_option( ctx, local_options:, ** )
+          local_options[:extension] = (local_options[:extension]||[]) + [ Activity::Introspect.method(:add_introspection) ] # fixme: this sucks
+        end
+
+        # Normalizes ctx[:options]
+        def self.normalize_for_macro( ctx, task:, options:, task_builder:, ** )
+          ctx[:options] =
+            if task.is_a?(::Hash) # macro.
+              options = options.merge(extension: (options[:extension]||[])+(task[:extension]||[]) ) # FIXME.
+
+              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
+
+        # Merge user options over defaults.
+        def self.defaultize( ctx, local_options:, default_plus_poles:, ** ) # TODO: test :default_plus_poles
+          ctx[:local_options] =
+            {
+              plus_poles: default_plus_poles,
+            }
+            .merge(local_options)
+        end
+
+        task Activity::TaskBuilder::Binary.( method(:normalize_for_macro) ),        id: "normalize_for_macro"
+        task Activity::TaskBuilder::Binary.( method(:split_options) ),              id: "split_options"
+        task Activity::TaskBuilder::Binary.( method(:normalize_extension_option) ), id: "normalize_extension_option"
+        task Activity::TaskBuilder::Binary.( method(:defaultize) ),                 id: "defaultize"
+        # task ->((ctx, _), **) { pp ctx; [Activity::Right, [ctx, _]] }
+      end
+    end # Normalizer
+
+  end
+end

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

@@ -14,14 +14,10 @@ module Trailblazer
           )
         end
 
-        def self.plan(options={}, normalizer=DefaultNormalizer.new(plus_poles: default_plus_poles), &block)
-          plan_for( *Path.for(normalizer, options), &block )
-        end
-
         def task(task, options={}, &block)
           polarizations = Path.TaskPolarizations( @builder_options.merge( type: options[:type] ) ) # DISCUSS: handle :type here? Really?
 
-          insert_element( Path, polarizations, task, options, &block )
+          return Path, polarizations, task, options, block
         end
 
 
@@ -32,35 +28,38 @@ module Trailblazer
         end
 
         # @return [Adds] list of Adds instances that can be chained or added to an existing sequence.
-        def self.InitialAdds(track_color:raise, end_semantic:raise, default_plus_poles: self.default_plus_poles, track_end: Activity.End(track_color, end_semantic), **o)
+        def self.InitialAdds(track_color:raise, end_semantic:raise, default_plus_poles: self.default_plus_poles, track_end: Activity.End(track_color, end_semantic), **)
 
           builder_options={ track_color: track_color, end_semantic: end_semantic }
 
           start_adds = adds(
-            "Start.default", Activity::Start.new(:default),
+            Activity::Start.new(:default),
 
-            default_plus_poles,
             TaskPolarizations(builder_options),
-            [],
 
             {}, { group: :start },
-            [] # magnetic_to
+
+            id:           "Start.default",
+            magnetic_to:  [],
+            plus_poles:   default_plus_poles
           )
 
           end_adds = adds(
-            "End.#{track_color}", track_end,
+            track_end,
 
-            {}, # plus_poles
             TaskPolarizations(builder_options.merge( type: :End )),
-            [],
 
-            {}, { group: :end }
+            {}, { group: :end },
+
+            id:         "End.#{track_color}",
+            plus_poles: {},
+            magnetic_to: nil,
           )
 
           start_adds + end_adds
         end
 
-        def self.TaskPolarizations(track_color:raise, type: :task, **o)
+        def self.TaskPolarizations(track_color:raise, type: :task, **)
           return [EndPolarization.new( track_color: track_color )] if type == :End # DISCUSS: should this dispatch be here?
 
           [TaskPolarization.new( track_color: track_color )]

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

@@ -10,20 +10,16 @@ module Trailblazer
           )
         end
 
-        def self.plan(options={}, normalizer=DefaultNormalizer.new(plus_poles: default_plus_poles), &block)
-          plan_for( *Railway.for(normalizer, options), &block )
-        end
-
         def step(task, options={}, &block)
-          insert_element( Railway, Railway.StepPolarizations(@builder_options), task, options, &block )
+          return Railway, Railway.StepPolarizations(@builder_options), task, options, block
         end
 
         def fail(task, options={}, &block)
-          insert_element( Railway, Railway.FailPolarizations(@builder_options), task, options, &block )
+          return Railway, Railway.FailPolarizations(@builder_options), task, options, block
         end
 
         def pass(task, options={}, &block)
-          insert_element( Railway, Railway.PassPolarizations(@builder_options), task, options, &block )
+          return Railway, Railway.PassPolarizations(@builder_options), task, options, block
         end
 
         def self.default_plus_poles
@@ -39,15 +35,16 @@ module Trailblazer
           path_adds = Path.InitialAdds(**builder_options)
 
           end_adds = adds(
-            "End.#{failure_color}", failure_end,
+            failure_end,
 
-            {}, # plus_poles
             Path::TaskPolarizations(builder_options.merge( type: :End )),
-            [],
 
             {},
             { group: :end },
-            [failure_color]
+
+            magnetic_to:  [failure_color],
+            id:           "End.#{failure_color}",
+            plus_poles:   {},
           )
 
           path_adds + end_adds

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

@@ -59,11 +59,14 @@ module Trailblazer
             ]
           # procs come from DSL calls such as `Path() do ... end`.
           elsif task.is_a?(Proc)
-            start_color, adds = task.(block)
+            start_color, activity = task.(block)
+
+            adds = activity.decompose[: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
             ]
           else # An additional plus polarization. Example: Output => :success

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

@@ -34,7 +34,7 @@ module Trailblazer
         def self.circuit_hash_to_process(circuit_hash)
           end_events = end_events_for(circuit_hash)
 
-          return Activity::Process.new( circuit_hash, end_events ), end_events
+          return Circuit.new(circuit_hash, end_events), end_events
         end
 
         # Filters out unconnected ends, e.g. the standard end in nested tracks that weren't used.

data/lib/trailblazer/activity/magnetic/merge.rb

@@ -0,0 +1,18 @@
+class Trailblazer::Activity < Module
+  module Magnetic
+    module Merge
+      # THIS IS HIGHLY EXPERIMENTAL AS WE'RE NOT MERGING taskWrap etc.
+      def merge!(merged)
+        merged_adds = Builder.merge(self[:adds], merged[:adds])
+        # TODO: MERGE DEBUG, TASK_WRAP
+        builder, adds, circuit, outputs, = State.recompile(self[:builder], merged_adds)
+
+        self[:adds] = adds
+        self[:circuit] = circuit
+        self[:outputs] = outputs
+
+        self
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/present.rb

@@ -1,7 +1,7 @@
 require "hirb"
 
 module Trailblazer
-  class Activity
+  class Activity < Module
     module Trace
       # TODO: make this simpler.
       module Present

data/lib/trailblazer/activity/schema/dependencies.rb

@@ -29,13 +29,18 @@ module Trailblazer
         @order.collect{ |name| @groups[name].to_a }.flatten(1)
       end
 
-      # private
+      # @api private
       def find(id)
         @groups.find do |name, group|
           index = group.send( :find_index, id )
           return group, index if index
         end
       end
+
+      # @api private
+      def self.sequence_keywords
+        [ :group, :before, :after, :replace, :delete ]
+      end
     end
   end
 end

data/lib/trailblazer/activity/state.rb

@@ -0,0 +1,58 @@
+module Trailblazer
+  class Activity < Module   # @private
+    # Maintain Builder/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, name, *args, &block)
+        new_adds, *returned_options = builder.insert(name, *args, &block) # builder.task
+
+        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 = Magnetic::Builder::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.instance_variable_get(:@options)[:semantic], # DISCUSS: better API here?
+              Activity::Output(evt, semantic)
+            ]
+          end
+
+          ::Hash[ ary ]
+        end
+      end # Recompile
+    end # State
+  end
+end

data/lib/trailblazer/activity/structures.rb

@@ -1,6 +1,5 @@
   module Trailblazer
-    class Activity
-      # End event is just another callable task.
+    class Activity < Module     # End event is just another callable task.
       # Any instance of subclass of End will halt the circuit's execution when hit.
       class End
         def initialize(name, options={})

data/lib/trailblazer/activity/subprocess.rb

@@ -1,6 +1,5 @@
 module Trailblazer
-  class Activity
-     # A {Subprocess} is an instance of an abstract {Activity} that can be `call`ed.
+  class Activity < Module    # A {Subprocess} is an instance of an abstract {Activity} that can be `call`ed.
      # It is the runtime instance that runs from a specific start event.
     def self.Subprocess(*args)
       Subprocess.new(*args)
@@ -13,7 +12,7 @@ module Trailblazer
 
       def initialize(activity, call: :call, **options)
         @activity = activity
-        @options = options
+        @options  = options
         @call     = call
       end
 
@@ -29,6 +28,10 @@ module Trailblazer
       def debug
         @activity.debug
       end
+
+      def to_s
+        %{#<Trailblazer::Activity::Subprocess activity=#{@activity}>}
+      end
     end
   end
 end

data/lib/trailblazer/activity/task_builder.rb

@@ -0,0 +1,38 @@
+module Trailblazer
+  module Activity::TaskBuilder
+    # every step is wrapped by this proc/decider. this is executed in the circuit as the actual task.
+    # Step calls step.(options, **options, flow_options)
+    # Output direction binary: true=>Right, false=>Left.
+    # Passes through all subclasses of Direction.~~~~~~~~~~~~~~~~~
+    module Binary
+      def self.call(user_proc)
+        Task.new( Trailblazer::Option::KW( user_proc ), user_proc )
+      end
+
+      # Translates the return value of the user step into a valid signal.
+      # Note that it passes through subclasses of {Signal}.
+      def self.binary_direction_for(result, on_true, on_false)
+        result.is_a?(Class) && result < Activity::Signal ? result : (result ? on_true : on_false)
+      end
+    end
+
+    class Task
+      def initialize(task, user_proc)
+        @task      = task
+        @user_proc = user_proc
+
+        freeze
+      end
+
+      def call( (options, *args), **circuit_args )
+        # Execute the user step with TRB's kw args.
+        result = @task.( options, **circuit_args ) # circuit_args contains :exec_context.
+
+        # Return an appropriate signal which direction to go next.
+        direction = Binary.binary_direction_for( result, Activity::Right, Activity::Left )
+
+        [ direction, [ options, *args ], **circuit_args ]
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/task_wrap.rb

@@ -0,0 +1,46 @@
+class Trailblazer::Activity < Module
+    #
+    # Example with tracing:
+    #
+          # Call the task_wrap circuit:
+        #   |-- Start
+        #   |-- Trace.capture_args   [optional]
+        #   |-- Call (call actual task) id: "task_wrap.call_task"
+        #   |-- Trace.capture_return [optional]
+        #   |-- Wrap::End
+  module TaskWrap
+    # The actual activity that implements the taskWrap.
+    def self.initial_activity
+      Module.new do
+        extend Trailblazer::Activity::Path( name: "taskWrap", normalizer_class: Magnetic::DefaultNormalizer )
+
+        task TaskWrap.method(:call_task), id: "task_wrap.call_task" # ::call_task is defined in task_wrap/call_task.
+      end
+    end
+
+    # Compute runtime arguments necessary to execute a taskWrap per task of the activity.
+    def self.arguments_for_call(activity, (options, flow_options), **circuit_options)
+      circuit_options = circuit_options.merge(
+        runner:       TaskWrap::Runner,
+        wrap_runtime: circuit_options[:wrap_runtime] || {},
+        wrap_static:  activity[:wrap_static] || {},
+      )
+
+      return activity, [ options, flow_options ], circuit_options
+    end
+
+    module NonStatic
+      def self.arguments_for_call(activity, (options, flow_options), **circuit_options)
+        circuit_options = circuit_options.merge(
+          runner:       TaskWrap::Runner,
+          wrap_runtime: circuit_options[:wrap_runtime] || {}, # FIXME:this sucks. (was:) this overwrites wrap_runtime from outside.
+          wrap_static:  ::Hash.new(TaskWrap.initial_activity), # add a default static wrap.
+        )
+
+        return activity, [ options, flow_options ], circuit_options
+      end
+    end
+
+    # better: MyClass < Activity(TaskWrap, ...)
+  end
+end