trailblazer-future 2.1.0.rc1

data/lib/trailblazer/v2_1/activity/present.rb

@@ -0,0 +1,95 @@
+require "hirb"
+
+module Trailblazer::V2_1
+  class Activity < Module
+
+    # Task < Array
+    # [ input, ..., output ]
+
+    module Trace
+      # TODO: make this simpler.
+      module Present
+        module_function
+
+        def call(stack, level=1, tree=[])
+          tree(stack.to_a, level, tree)
+        end
+
+        def tree(stack, level, tree)
+          tree_for(stack, level, tree)
+
+          Hirb::Console.format_output(tree, class: :tree, type: :directory)
+        end
+
+        def tree_for(stack, level, tree)
+          stack.each do |task| # always a Stack::Task[input, ..., output]
+            input, output, nested = input_output_nested_for_task(task)
+
+            task = input.task
+
+            graph = Introspect::Graph(input.activity)
+
+            name = (node = graph.find { |node| node[:task] == task }) ? node[:id] : task
+            name ||= task # FIXME: bullshit
+
+            tree << [ level, name ]
+
+            if nested.any? # nesting
+              tree_for(nested, level + 1, tree)
+            end
+
+            tree
+          end
+        end
+
+        # DISCUSS: alternatively, we can have Task<input: output: data: >
+        def input_output_nested_for_task(task)
+          input  = task[0]
+          output = task[-1]
+
+          output, nested = output.is_a?(Entity::Output) ? [output, task-[input, output]] : [nil, task[1..-1]]
+
+          return input, output, nested
+        end
+
+        def to_name(debug_item)
+          track = debug_item[2]
+          klass = track.class == Class ? track : track.class
+          color = color_map[klass]
+
+          return debug_item[0].to_s unless color
+          colorify(debug_item[0], color)
+        end
+
+        def to_options(debug_item)
+          debug_item[4]
+        end
+
+
+
+        def colorify(string, color)
+          "\e[#{color_table[color]}m#{string}\e[0m"
+        end
+
+        def color_map
+          {
+            Trailblazer::V2_1::Activity::Start => :blue,
+            Trailblazer::V2_1::Activity::End   => :pink,
+            Trailblazer::V2_1::Activity::Right => :green,
+            Trailblazer::V2_1::Activity::Left  => :red
+          }
+        end
+
+        def color_table
+          {
+            red:    31,
+            green:  32,
+            yellow: 33,
+            blue:   34,
+            pink:   35
+          }
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/activity/structures.rb

@@ -0,0 +1,57 @@
+  module Trailblazer::V2_1
+    class Activity < Module
+      # Generic run-time structures that are built via the DSL.
+
+      # Builds an {Activity::End} instance.
+      def self.End(semantic)
+        End.new(semantic: semantic)
+      end
+
+      # Any instance of subclass of End will halt the circuit's execution when hit.
+
+      # An End event is a simple structure typically found as the last task invoked
+      # in an activity. The special behavior is that it
+      # a) maintains a semantic that is used to further connect that very event
+      # b) its `End#call` method returns the end instance itself as the signal.
+      class End
+        def initialize(semantic:, **options)
+          @options = options.merge(semantic: semantic)
+        end
+
+        def call(args, circuit_options)
+          return self, args, circuit_options
+        end
+
+        def to_h
+          @options
+        end
+
+        def to_s
+          %{#<#{self.class.name} #{@options.collect{ |k,v| "#{k}=#{v.inspect}" }.join(" ")}>}
+        end
+
+        alias_method :inspect, :to_s
+      end
+
+      class Start < End
+        def call(args, circuit_options)
+          return Activity::Right, args, circuit_options
+        end
+      end
+
+      class Signal;         end
+      class Right < Signal; end
+      class Left  < Signal; end
+
+      # signal:   actual signal emitted by the task
+      # color:    the mapping, where this signal will travel to. This can be e.g. Left=>:success. The polarization when building the graph.
+      #             "i am traveling towards :success because ::step said so!"
+      # semantic: the original "semantic" or role of the signal, such as :success. This usually comes from the activity hosting this output.
+      Output = Struct.new(:signal, :semantic)
+
+      # Builds an {Activity::Output} instance.
+      def self.Output(signal, color)
+        Output.new(signal, color).freeze
+      end
+    end
+  end

data/lib/trailblazer/v2_1/activity/task_builder.rb

@@ -0,0 +1,41 @@
+module Trailblazer::V2_1
+  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 signal binary: true=>Right, false=>Left.
+    # Passes through all subclasses of Direction.~~~~~~~~~~~~~~~~~
+    def self.Binary(user_proc)
+      Task.new(Trailblazer::V2_1::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_signal_for(result, on_true, on_false)
+      result.is_a?(Class) && result < Activity::Signal ? result : (result ? on_true : on_false)
+    end
+
+    class Task
+      def initialize(task, user_proc)
+        @task            = task
+        @user_proc       = user_proc
+
+        freeze
+      end
+
+      def call( (ctx, flow_options), **circuit_options )
+        # Execute the user step with TRB's kw args.
+        result = @task.( ctx, **circuit_options ) # circuit_options contains :exec_context.
+
+        # Return an appropriate signal which direction to go next.
+        signal = Activity::TaskBuilder.binary_signal_for( result, Activity::Right, Activity::Left )
+
+        return signal, [ ctx, flow_options ]
+      end
+
+      def inspect
+        %{#<Trailblazer::V2_1::Activity::TaskBuilder::Task user_proc=#{@user_proc}>}
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/trailblazer/v2_1/activity/task_wrap.rb

@@ -0,0 +1,40 @@
+module Trailblazer::V2_1
+  class 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::V2_1::Activity::Path(
+            name:             "taskWrap",
+            normalizer_class: Magnetic::DefaultNormalizer,
+            plus_poles:       Magnetic::PlusPoles.initial( :success => Magnetic::Builder::Path.default_outputs[:success] ) # DefaultNormalizer doesn't give us default PlusPoles.
+          )
+
+          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.invoke(activity, args, wrap_runtime: {}, **circuit_options)
+        circuit_options = circuit_options.merge(
+          runner:       TaskWrap::Runner,
+          wrap_runtime: wrap_runtime,
+
+          activity: { adds: [], circuit: {} }, # for Runner
+        )
+
+        # signal, (ctx, flow), circuit_options =
+        Runner.(activity, args, circuit_options)
+      end
+    end # TaskWrap
+  end
+end

data/lib/trailblazer/v2_1/activity/task_wrap/call_task.rb

@@ -0,0 +1,19 @@
+class Trailblazer::V2_1::Activity < Module
+  module TaskWrap
+    # TaskWrap step that calls the actual wrapped task and passes all `original_args` to it.
+    #
+    # It writes to wrap_ctx[:return_signal], wrap_ctx[:return_args]
+    def self.call_task((wrap_ctx, original_args), **circuit_options)
+      task  = wrap_ctx[:task]
+
+      # Call the actual task we're wrapping here.
+      # puts "~~~~wrap.call: #{task}"
+      return_signal, return_args = task.(*original_args)
+
+      # DISCUSS: do we want original_args here to be passed on, or the "effective" return_args which are different to original_args now?
+      wrap_ctx = wrap_ctx.merge( return_signal: return_signal, return_args: return_args )
+
+      return Right, [ wrap_ctx, original_args ]
+    end
+  end # Wrap
+end

data/lib/trailblazer/v2_1/activity/task_wrap/merge.rb

@@ -0,0 +1,23 @@
+module Trailblazer::V2_1
+  module Activity::TaskWrap
+    # This is instantiated via the DSL, and passed to the :extension API,
+    # allowing to add steps to the Activity's static_wrap.
+    # Compile-time function
+    class Merge
+      def initialize(extension_plan)
+        @extension_plan = extension_plan
+      end
+
+      # {:extension API}
+      def call(activity, task, local_options, *returned_options)
+        # we could make the default initial_activity injectable via the DSL, the value would sit in returned_options or local_options.
+        static_wrap = Activity::TaskWrap.wrap_static_for(task, activity: activity)
+
+        # # macro might want to apply changes to the static task_wrap (e.g. Inject)
+        new_wrap =  Activity::Path::Plan.merge( static_wrap, @extension_plan )
+
+        activity[:wrap_static, task] = new_wrap
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/activity/task_wrap/runner.rb

@@ -0,0 +1,62 @@
+class Trailblazer::V2_1::Activity < Module
+  module TaskWrap
+    # The runner is passed into Activity#call( runner: Runner ) and is called for every task in the circuit.
+    # It runs the TaskWrap per task.
+    #
+    # (wrap_ctx, original_args), **wrap_circuit_options
+    module Runner
+      # Runner signature: call( task, direction, options, static_wraps )
+      #
+      # @api private
+      # @interface Runner
+      def self.call(task, args, circuit_options)
+        wrap_ctx = { task: task }
+
+        # this activity is "wrapped around" the actual `task`.
+        task_wrap_activity = merge_static_with_runtime(task, circuit_options)
+
+        # We save all original args passed into this Runner.call, because we want to return them later after this wrap
+        # is finished.
+        original_args = [ args, circuit_options ]
+
+        # call the wrap {Activity} around the task.
+        wrap_end_signal, ( wrap_ctx, _ ) = task_wrap_activity.(
+          [ wrap_ctx, original_args ], # we omit circuit_options here on purpose, so the wrapping activity uses the default, plain Runner.
+          {}
+        )
+
+        # don't return the wrap's end signal, but the one from call_task.
+        # return all original_args for the next "real" task in the circuit (this includes circuit_options).
+
+        return wrap_ctx[:return_signal], wrap_ctx[:return_args]
+      end
+
+      private
+
+      # Compute the task's wrap by applying alterations both static and from runtime.
+      #
+      # NOTE: this is for performance reasons: we could have only one hash containing everything but that'd mean
+      # unnecessary computations at `call`-time since steps might not even be executed.
+      # TODO: make this faster.
+      def self.merge_static_with_runtime(task, wrap_runtime:, **circuit_options)
+        wrap_activity = TaskWrap.wrap_static_for(
+          task,
+          circuit_options
+        )  # find static wrap for this specific task, or default wrap activity.
+
+        # Apply runtime alterations.
+        # Grab the additional wirings for the particular `task` from `wrap_runtime` (returns default otherwise).
+        wrap_runtime[task] ? Trailblazer::V2_1::Activity::Path::Plan.merge(wrap_activity, wrap_runtime[task]) : wrap_activity
+      end
+    end # Runner
+
+    # Retrieve the static wrap config from {activity}.
+    # I do not like this part too much, I'd prefer computing the {:wrap_static} at compile-time for the entire
+    # object graph (including nesteds) and simply pass it through to all Runner calls.
+    # TODO: simplify that. See above
+    def self.wrap_static_for(task, activity:, default_activity: TaskWrap.initial_activity, **)
+      wrap_static = activity[:wrap_static] || {}
+      wrap_static[task] || default_activity
+    end
+  end
+end

data/lib/trailblazer/v2_1/activity/task_wrap/trace.rb

@@ -0,0 +1,44 @@
+class Trailblazer::V2_1::Activity < Module
+  module TaskWrap
+    # TaskWrap tasks for tracing.
+    module Trace
+      module_function
+
+      # taskWrap step to capture incoming arguments of a step.
+      # def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
+      def capture_args((wrap_config, original_args), **circuit_options)
+
+        original_args = capture_for(wrap_config[:task], *original_args)
+
+        return Trailblazer::V2_1::Activity::Right, [wrap_config, original_args], circuit_options
+      end
+
+      # taskWrap step to capture outgoing arguments from a step.
+      def capture_return((wrap_config, original_args), **circuit_options)
+        (original_options, original_flow_options, _) = original_args[0]
+
+        original_flow_options[:stack] << Trailblazer::V2_1::Activity::Trace::Entity::Output.new(
+          wrap_config[:task], {}, wrap_config[:return_signal]
+        ).freeze
+
+        original_flow_options[:stack].unindent!
+
+
+        return Trailblazer::V2_1::Activity::Right, [wrap_config, original_args], circuit_options
+      end
+
+      # It's important to understand that {flow[:stack]} is mutated by design. This is needed so
+      # in case of exceptions we still have a "global" trace - unfortunately Ruby doesn't allow
+      # us a better way.
+      def capture_for(task, (ctx, flow), activity:, **circuit_options)
+        flow[:stack].indent!
+
+        flow[:stack] << Trailblazer::V2_1::Activity::Trace::Entity::Input.new(
+          task, activity
+        ).freeze
+
+        return [ctx, flow], circuit_options.merge(activity: activity)
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/activity/task_wrap/variable_mapping.rb

@@ -0,0 +1,162 @@
+require "trailblazer/v2_1/context"
+
+class Trailblazer::V2_1::Activity < Module
+  module TaskWrap
+    # Creates taskWrap steps to map variables before and after the actual step.
+    # We hook into the Normalizer, process `:input` and `:output` directives and
+    # translate them into a {DSL::Extension}.
+    #
+    # Note that the two options are not the only way to create filters, you can use the
+    # more low-level {Scoped()} etc., too, and write your own filter logic.
+    module VariableMapping
+      # 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::V2_1::Activity::TaskWrap::VariableMapping(io_config) => true)
+      end
+
+      # The taskWrap extension that's included into the static taskWrap for a task.
+      def self.extension_for(input, output)
+        Trailblazer::V2_1::Activity::DSL::Extension.new(
+          Merge.new(
+            Module.new do
+              extend Path::Plan()
+
+              task input,  id: "task_wrap.input", before: "task_wrap.call_task"
+              task output, id: "task_wrap.output", before: "End.success", group: :end
+            end
+          )
+        )
+      end
+    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::V2_1::Option::KW( filter_for(input) ) ) )
+
+      output = Output.new(
+                Output::Unscoped.new(
+                  Trailblazer::V2_1::Option::KW( filter_for(output) ) ) )
+
+      VariableMapping.extension_for(input, output)
+    end
+
+    # TaskWrap step to compute the incoming {Context} for the wrapped task.
+    # This allows renaming, filtering, hiding, of the options passed into the wrapped task.
+    #
+    # Both Input and Output are typically to be added before and after task_wrap.call_task.
+    #
+    # @note Assumption: we always have :input _and_ :output, where :input produces a Context and :output decomposes it.
+
+    # Calls your {@filter} and replaces the original ctx with your returned one.
+    class Input
+      def initialize(filter)
+        @filter = filter
+      end
+
+      # `original_args` are the actual args passed to the wrapped task: [ [options, ..], circuit_options ]
+      #
+      def call( (wrap_ctx, original_args), circuit_options )
+        # let user compute new ctx for the wrapped task.
+        input_ctx = apply_filter(*original_args)
+
+        wrap_ctx = wrap_ctx.merge( vm_original_ctx: original_args[0][0] ) # remember the original ctx
+
+        # decompose the original_args since we want to modify them.
+        (original_ctx, original_flow_options), original_circuit_options = original_args
+
+        # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
+        return Trailblazer::V2_1::Activity::Right, [ wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options] ]
+      end
+
+      private
+
+      def apply_filter((ctx, original_flow_options), original_circuit_options)
+        @filter.( ctx, original_circuit_options ) # returns {new_ctx}.
+      end
+
+      class Scoped
+        def initialize(filter)
+          @filter = filter
+        end
+
+        def call(original_ctx, circuit_options)
+          Trailblazer::V2_1::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
+
+    # TaskWrap step to compute the outgoing {Context} from the wrapped task.
+    # This allows renaming, filtering, hiding, of the options returned from the wrapped task.
+    class Output
+      def initialize(filter)
+        @filter = filter
+      end
+
+      # Runs your filter and replaces the ctx in `wrap_ctx[:return_args]` with the filtered one.
+      def call( (wrap_ctx, original_args), **circuit_options )
+        (original_ctx, original_flow_options), original_circuit_options = original_args
+
+        returned_ctx, _ = wrap_ctx[:return_args] # this is the Context returned from `call`ing the task.
+        original_ctx    = wrap_ctx[:vm_original_ctx]
+        # let user compute the output.
+        output_ctx = @filter.(original_ctx, returned_ctx, **original_circuit_options)
+
+        wrap_ctx = wrap_ctx.merge( return_args: [output_ctx, original_flow_options] )
+
+        # and then pass on the "new" context.
+        return Trailblazer::V2_1::Activity::Right, [ wrap_ctx, original_args ]
+      end
+
+      private
+
+      # 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
+  end # Wrap
+end