trailblazer-circuit 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 760ef971087c4983eb7d4f624bca5d78130be9b2
-  data.tar.gz: f763cd9f2193d16440514a183cb0935955d2158a
+  metadata.gz: c9e50c60fbd29ee44bc11f122198acec25c02122
+  data.tar.gz: de1fb71290d6c4a817827bfad946cf739a1d4291
 SHA512:
-  metadata.gz: 8d6ae7c2daa02a06ae5db0846cb78068cb09b8d489ff2ec5b8ad5d3e2308e055051cb4b0e9d25be64c2709650619f434d78b910852d8d046631a8fa4af94002f
-  data.tar.gz: b306b440d01b1aa11c3faf587ef7970603dc58b95a3c4636eda3a76bad486c32c363db8a2ca449fd069396dbf12d8a2c052267a4cbadeaa0380ce4ac19075493
+  metadata.gz: c8b5ea44e5ca1a618da4c4b4c5130d27700ada1766c621e4753e4d58765995f6799490e3b842f89183ec1ea860704e0c3d55549270cc1a539fab93b5f503269c
+  data.tar.gz: 0cf6a6dd1cc39496a236eb2d816e360efca4f60d263a0d591a8f799890bc5e29bd3a8a0ccdcf9b89aa04b11071b40cf7aa0b196e6a7d41f2bf1273df2c646747

data/CHANGES.md

@@ -1,3 +1,9 @@
+# 0.0.4
+
+* Simpler tracing with `Stack`.
+* Added `Context`.
+* Simplified `Circuit#call`.
+
 # 0.0.3
 
 * Make the first argument to `#Activity` (`@name`) always a Hash where `:id` is a reserved key for the name of the circuit.

data/lib/trailblazer/circuit/present.rb

@@ -1,24 +1,35 @@
+require "hirb"
+
 module Trailblazer
   class Circuit
-    class Trace
+    module Trace
       # TODO:
       # * Struct for debug_item
       module Present
-        FREE_SPACE = (' ' * 3).freeze
         module_function
 
-        def tree(stack, level = 1)
+        def tree(stack, level=1, 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 |debug_item|
-            puts FREE_SPACE * level + delimeter(stack, debug_item) + '--' + '> ' + to_name(debug_item) + to_options(debug_item)
+            if debug_item.size == 2 # flat
+              tree << [ level,  debug_item[0].last[debug_item[0][0]] || debug_item[0][0] ]
+            else # nesting
+              tree << [ level, debug_item[0][0] ]
+
+              tree_for(debug_item[1..-2], level + 1, tree)
 
-            if debug_item.last.is_a?(Array)
-              tree(debug_item.last, level + 1)
+              tree << [ level+1, debug_item[-1][0] ]
             end
+
+            tree
           end
         end
 
-        # private
-
         def to_name(debug_item)
           track = debug_item[2]
           klass = track.class == Class ? track : track.class
@@ -56,14 +67,6 @@ module Trailblazer
             pink:   35
           }
         end
-
-        def delimeter(stack, debug_item)
-          if stack.last == debug_item || debug_item.last.is_a?(Array)
-            '`'
-          else
-            '|'
-          end
-        end
       end
     end
   end

data/lib/trailblazer/circuit/task.rb

@@ -40,7 +40,7 @@ class Trailblazer::Circuit
       # Make the context's instance method a "lambda" and reuse #call!.
       # TODO: should we make :context a kwarg?
       def meth!(proc, direction, options, flow_options, *args)
-        call!(flow_options[:context].method(proc), direction, options, flow_options, *args)
+        call!(flow_options[:exec_context].method(proc), direction, options, flow_options, *args)
       end
     end
   end

data/lib/trailblazer/circuit/trace.rb

@@ -1,22 +1,77 @@
 module Trailblazer
   class Circuit
-    #   direction, result = circuit.( circuit[:Start], options, runner: Circuit::Trace.new, stack: [] )
+    # Trace#call will call the activities and trace what steps are called, options passed,
+    # and the order and nesting.
+    #
+    #   stack, _ = Trailblazer::Circuit::Trace.(activity, activity[:Start], { id: 1 })
+    #   puts Trailblazer::Circuit::Present.tree(stack) # renders the trail.
+    module Trace
+      def self.call(activity, direction, options, flow_options={})
+        # activity_wrap is the circuit/pipeline that wraps each step and implements tracing (and more, like input/output contracts, etc!).
+        activity_wrap = Activity::Before( Activity::Wrapped::Activity, Activity::Wrapped::Call, Trace.method(:capture_args), direction: Right )
+        activity_wrap = Activity::Before( activity_wrap, Activity::Wrapped::Activity[:End], Trace.method(:capture_return), direction: Right )
 
-    # Every `activity.call` is considered nested
-    class Trace
-      # Trace is passed in as the `:runner` into Circuit#call and is called per task.
-      def call(activity, direction, args, debug:raise, stack:raise, **flow_options)
-        activity_name, _ = debug[activity]
-        activity_name ||= activity
+        step_runners = {
+          nil   => activity_wrap, # call all steps with tracing.
+        }
 
-        # Use Circuit::Run to actually call the task.
-        direction, options, _flow_options = Run.(activity, direction, args, flow_options.merge(stack: []))
+        tracing_flow_options = {
+          runner:       Activity::Wrapped::Runner,
+          stack:        Circuit::Trace::Stack.new,
+          step_runners: step_runners,
+          debug:        activity.circuit.instance_variable_get(:@name)
+        }
 
-        # TODO: fix the inspect, we need a snapshot, deep-nested.
-        stack << [activity_name, activity, direction, options, options.inspect, _flow_options[:stack].any? ? _flow_options[:stack] : nil ]
+        direction, options, flow_options = activity.( direction, options, tracing_flow_options.merge(flow_options) )
 
-        return direction, options, _flow_options.merge(stack: stack, debug: debug)
+        return flow_options[:stack].to_a, direction, options, flow_options
       end
-    end # Trace
+
+      def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
+        original_flow_options[:stack].indent!
+
+        original_flow_options[:stack] << [ wrap_config[:step], :args, nil, options.dup, original_flow_options[:debug] ]
+
+        [ direction, options, flow_options, wrap_config, original_flow_options ]
+      end
+
+      def self.capture_return(direction, options, flow_options, wrap_config, original_flow_options)
+        original_flow_options[:stack] << [ wrap_config[:step], :return, flow_options[:result_direction], options.dup ]
+
+        original_flow_options[:stack].unindent!
+
+        [ direction, options, flow_options, wrap_config, original_flow_options ]
+      end
+
+      # Mutable/stateful per design. We want a (global) stack!
+      class Stack
+        def initialize
+          @nested  = []
+          @stack   = [ @nested ]
+        end
+
+        def indent!
+          current << indented = []
+          @stack << indented
+        end
+
+        def unindent!
+          @stack.pop
+        end
+
+        def <<(args)
+          current << args
+        end
+
+        def to_a
+          @nested
+        end
+
+        private
+        def current
+          @stack.last
+        end
+      end # Stack
+    end
   end
 end

data/lib/trailblazer/circuit/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Circuit
-    VERSION = "0.0.3"
+    VERSION = "0.0.4"
   end
 end

data/lib/trailblazer/circuit/wrapped.rb

@@ -0,0 +1,58 @@
+class Trailblazer::Circuit
+  module Activity::Wrapped
+    # Input  = ->(direction, options, flow_options) { [direction, options, flow_options] }
+
+    def self.call_activity(direction, options, flow_options, wrap_config, original_flow_options)
+      task  = wrap_config[:step]
+
+      # Call the actual task we're wrapping here.
+      wrap_config[:result_direction], options, flow_options = task.( direction, options, original_flow_options )
+
+      [ direction, options, flow_options, wrap_config, original_flow_options ]
+    end
+
+    Call = method(:call_activity)
+
+    # Output = ->(direction, options, flow_options) { [direction, options, flow_options] }
+
+    class End < Trailblazer::Circuit::End
+      def call(direction, options, flow_options, wrap_config, *args)
+        [ wrap_config[:result_direction], options, flow_options, wrap_config, *args ]
+      end
+    end
+
+    Activity = Trailblazer::Circuit::Activity({ id: "task.wrap" }, end: { default: End.new(:default) }) do |act|
+      {
+        act[:Start]          => { Right => Call },                  # options from outside
+        # Input                => { Circuit::Right => Trace::CaptureArgs },
+        # MyInject               => { Circuit::Right => Trace::CaptureArgs },
+        # Trace::CaptureArgs   => { Circuit::Right => Call  },
+        Call                 => { Right => act[:End] },
+        # Trace::CaptureReturn => { Circuit::Right => Output },
+        # Output               => { Circuit::Right => act[:End] }
+      }
+    end
+
+    # Find the respective wrap per task, and run it.
+    class Runner
+      # private flow_options[ :step_runners ]
+      def self.call(task, direction, options, flow_options)
+        # TODO: test this decider!
+        task_wrap = flow_options[:step_runners][task] || flow_options[:step_runners][nil] # DISCUSS: default could be more explicit@
+
+        # we can't pass :runner in here since the Step::Pipeline would call itself again, then.
+        # However, we need the runner in nested activities.
+        wrap_config = { step: task }
+
+        # Call the task_wrap circuit:
+        #   |-- Start
+        #   |-- Trace.capture_args   [optional]
+        #   |-- Call (call actual task)
+        #   |-- Trace.capture_return [optional]
+        #   |-- End
+        # Pass empty flow_options to the task_wrap, so it doesn't infinite-loop.
+        task_wrap.( task_wrap[:Start], options, {}, wrap_config, flow_options ) # all tasks in Wrap have to implement this signature.
+      end
+    end # Runner
+  end
+end

data/lib/trailblazer/circuit.rb

@@ -29,16 +29,15 @@ module Trailblazer
     #
     # @param activity A task from the circuit where to start
     # @param args An array of options passed to the first task.
-    def call(activity, args, runner: Run, **flow_options)
-      # TODO: args
-      direction    = nil
-      flow_options = { runner: runner, debug: @name }.merge(flow_options) # DISCUSS: make this better?
+    def call(activity, options, flow_options={}, *args)
+      direction = nil
+      runner    = flow_options[:runner] || Run
 
       loop do
-        direction, args, flow_options = runner.( activity, direction, args, flow_options )
+        direction, options, flow_options = runner.( activity, direction, options, flow_options, *args )
 
         # Stop execution of the circuit when we hit a stop event (< End). This could be an activity's End or Suspend.
-        return [ direction, args, flow_options ] if @stop_events.include?(activity)
+        return [ direction, options, flow_options ] if @stop_events.include?(activity)
 
         activity = next_for(activity, direction) do |next_activity, in_map|
           activity_name = @name[activity] || activity # TODO: this must be implemented only once, somewhere.
@@ -97,10 +96,20 @@ module Trailblazer
     end
 
     # Builder for running a nested process from a specific `start_at` position.
-    def self.Nested(activity, start_with=activity[:Start])
-      ->(start_at, options, *args) {
-        activity.(start_with, options, *args)
-      }
+    def self.Nested(*args)
+      Nested.new(*args)
+    end
+
+    class Nested
+      def initialize(activity, start_with=activity[:Start])
+        @activity, @start_with = activity, start_with
+      end
+
+      def call(start_at, *args)
+        @activity.(@start_with, *args)
+      end
+
+      attr_reader :activity
     end
 
     class Direction;         end
@@ -113,3 +122,7 @@ require "trailblazer/circuit/activity"
 require "trailblazer/circuit/task"
 require "trailblazer/circuit/alter"
 require "trailblazer/circuit/trace"
+require "trailblazer/circuit/present"
+require "trailblazer/circuit/wrapped"
+
+require "trailblazer/context"

data/lib/trailblazer/context.rb

@@ -0,0 +1,78 @@
+# "di" step_di: order:  1. runtime, 2. { contract.class: A } (dynamic at runtime?)
+
+=begin
+  * test "stripe scenario"
+    def pay!(options, stripe: Stripe.new) # can be overridden in e.g. test via runtime dependencies or container.
+  * problem: HOW TO payment.stripe.engine ? step M, underscore_dots: true
+  * Create["payment.stripe.engine"] = Stripe.new
+
+=end
+
+=begin
+* In an operation, there's always a Context object that holds the Containers and the initial mutable data.
+* SIMPLE/CURRENT WAY: we can simply pass this on without wrapping (no boundaries)
+  * wrap for Nested, unwrap after Nested
+=end
+
+# TODO: mark/make all but mutable_options as frozen.
+# The idea of Skill is to have a generic, ordered read/write interface that
+# collects mutable runtime-computed data while providing access to compile-time
+# information.
+# The runtime-data takes precedence over the class data.
+module Trailblazer
+  # Holds local options (aka `mutable_options`) and "original" options from the "outer"
+  # activity (aka wrapped_options).
+
+  # only public creator: Build
+  class Context # :data object:
+    def initialize(wrapped_options, mutable_options)
+      @wrapped_options, @mutable_options = wrapped_options, mutable_options
+    end
+
+    def [](name)
+      @mutable_options[name] || @wrapped_options[name]
+    end
+
+    def []=(name, value)
+      @mutable_options[name] = value
+    end
+
+    def merge(hash)
+      original, mutable_options = decompose
+
+      ctx = Trailblazer::Context( original, mutable_options.merge(hash) )
+    end
+
+    # Return the Context's two components. Used when computing the new output for
+    # the next activity.
+    def decompose
+      # it would be cool if that could "destroy" the original object.
+      # also, if those hashes were immutable, that'd be amazing.
+      [ @wrapped_options, @mutable_options ]
+    end
+
+    # TODO: massive performance bottleneck. also, we could already "know" here what keys the
+    # transformation wants.
+    def to_hash
+      {}.tap do |hash|
+        # arr = to_runtime_data << to_mutable_data << tmp_options
+
+        # the "key" here is to call to_hash on all containers.
+        [ @wrapped_options.to_hash, @mutable_options.to_hash ].each do |options|
+          options.each { |k, v| hash[k.to_sym] = v }
+        end
+      end
+    end
+
+    def Build
+      wrapped_options, mutable_options = *decompose
+      wrapped_options = yield(wrapped_options, mutable_options) if block_given?
+
+      Trailblazer::Context(wrapped_options)
+    end
+  end
+
+  def self.Context(wrapped_options, mutable_options={})
+    Context.new(wrapped_options, mutable_options)
+  end
+end

data/trailblazer-circuit.gemspec

@@ -24,5 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "raise"
 
+  spec.add_dependency "hirb"
+
   spec.required_ruby_version = '>= 2.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-circuit
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-11 00:00:00.000000000 Z
+date: 2017-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: hirb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: BPMN-compliant workflows or state machines. Used in Trailblazer's Operation
   to implement the Railway.
 email:
@@ -89,6 +103,8 @@ files:
 - lib/trailblazer/circuit/testing.rb
 - lib/trailblazer/circuit/trace.rb
 - lib/trailblazer/circuit/version.rb
+- lib/trailblazer/circuit/wrapped.rb
+- lib/trailblazer/context.rb
 - trailblazer-circuit.gemspec
 homepage: http://trailblazer.to/gems/workflow
 licenses: []