trailblazer-activity 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df4bfa29ae42857b380ae366a8256d60b536f072
-  data.tar.gz: 562bf7c08d36f471eb5d609b4148067d0b95bd06
+  metadata.gz: cda2a49909b44be7195fed23b15bb82f6d4d4ac4
+  data.tar.gz: 3d17e44f5c91ca1a61797d1f3d5f8d515362c2ad
 SHA512:
-  metadata.gz: 7776c71ee513ab9638b81becb2b27cdca56e505d0d50d42ba28e61729409da6ab7e96d2356ee0454be5ea34094851f8fe7130da6be17e8de02994fd327c5d132
-  data.tar.gz: be1df204fd6f067d45533d1d881d6f9afbad3d4f7a29273506e23fb67ce8eb022b2ab6d5ebc8566a2179a00e7a610d0656eec2dd8354b78272fc20b3920241da
+  metadata.gz: 70ca9ad73d4993f6295ee2dfc40b527c46fc25fc7e3384ec6dd7f57f726db5c7599affda8cfec180430020cb8f6a4340892921008bd0a1b3e54f4fa362e3dcc8
+  data.tar.gz: 13400c97fecca6f83d0282205af04c7f60f7136b4f5f6a7175ed5035277a12e9bf9a22044102577fcca26187fa6badf5185246a3dba61c87e1eab5f06b98ac57

data/.travis.yml

@@ -8,6 +8,6 @@ rvm:
   - 2.4.0
 matrix:
   include:
-  - rvm: jruby-9.1.7.0
+  - rvm: jruby-9.1.13.0
     env: JRUBY_OPTS="--profile.api"
 before_install: gem install bundler

data/CHANGES.md

@@ -1,3 +1,27 @@
+# 0.2.0
+
+* The `Activity#call` API is now
+
+    ```ruby
+    signal, options, _ignored_circuit_options = Activity.( options, **circuit_options )
+    ```
+
+    The third return value, which is typically the `circuit_options`, is _ignored_ and for all task calls in this `Activity`, an identical, unchangeable set of `circuit_options` is passed to. This dramatically reduces unintended behavior with the task_wrap, tracing, etc. and usually simplifies tasks.
+
+    The new API allows using bare `Activity` instances as tasks without any clumsy nesting work, making nesting very simple.
+
+    A typical task will look as follows.
+
+    ```ruby
+    ->( (options, flow_options), **circuit_args ) do
+      [ signal, [options, flow_options], *this_will_be_ignored ]
+    end
+    ```
+
+    A task can only emit a signal and "options" (whatever data structure that may be), and can *not* change the `circuit_options` which usually contain activity-wide "global" configuration.
+
+
+
 # 0.1.6
 
 * `Nested` now is `Subprocess` because it literally does nothing else but calling a _process_ (or activity).

data/Gemfile

@@ -7,3 +7,4 @@ gem "minitest-line"
 gem "benchmark-ips"
 
 gem "trailblazer-test", git: "https://github.com/trailblazer/trailblazer-test"
+

data/NOTES

@@ -0,0 +1,36 @@
+  # NOT lowest level. if you need that, use your own proc.
+    # TODO: how do we track what goes into the callable?
+    #                 adjust what goes into it (e.g. without direction or with kw args)?
+    #                 pre contract -> step -> post contract (are these all just steps, in "mini nested pipe"?)
+    #
+    #
+    # aka "Atom".
+    def self.Task(instance: :context, method: :call, id:nil)
+
+
+      # * ingoing contract (could be implemented as a nested pipe with 3 steps. that would allow us
+      #   to compile it to native ruby method calls later)
+      ->(direction, options, **flow_options) {
+        instance = flow_options[:context] if instance==:context # TODO; implement different :context (e.g. :my_context).
+
+
+
+      # * incoming args
+        # step_args = [args] # TODO: overridable.
+        step_args = [ options, **options ]
+
+      # ** call the actual thing
+        res = instance.send(method, *step_args) # what goes in? kws?
+
+      # * interpret result (e.g. true=>Right) (should we keep doing that in the tie? so the op has it easier with success, etc?)
+      # * outgoing contract
+      # * outgoing args
+
+        [ *res, flow_options ]
+
+
+      # * tracing: incoming, outgoing, direction, etc. - do we want that in tasks, too?
+
+
+      }
+    end

data/README.md

@@ -1,163 +1,109 @@
-# Circuit
+# Activity
 
-_The Circuit of Life._
-
-Circuit provides a simplified [flowchart](https://en.wikipedia.org/wiki/Flowchart) implementation with terminals (for example, start or end state), connectors and tasks (processes). It allows to define the flow (the actual *circuit*) and execute it.
-
-Circuit refrains from implementing deciders. The decisions are encoded in the output signals of tasks.
-
-`Circuit` and `workflow` use [BPMN](http://www.bpmn.org/) lingo and concepts for describing processes and flows. This document can be found in the [Trailblazer documentation](http://trailblazer.to/gems/workflow/circuit.html), too.
-
-> The `circuit` gem is the lowest level of abstraction and is used in `operation` and `workflow`, which both provide higher-level APIs for the Railway pattern and complex BPMN workflows.
+An _activity_ is a collection of connected _tasks_ with one _start event_ and one (or many) _end_ events.
 
 ## Installation
 
-To use circuits, activities and nested tasks, you need one gem, only.
+To use activities you need one gem, only.
 
 ```ruby
-gem "trailblazer-circuit"
+gem "trailblazer-activity"
 ```
 
-The `trailblazer-circuit` gem is often just called the `circuit` gem. It ships with the `operation` gem and implements the internal Railway.
-
 ## Overview
 
-The following diagram illustrates a common use-case for `circuit`, the task of publishing a blog post.
-
-<img src="http://trailblazer.to/images/diagrams/blog-bpmn1.png">
-
-After writing and spell-checking, the author has the chance to publish the post or, in case of typos, go back, correct, and go through the same flow, again. Note that there's only a handful of defined transistions, or connections. An author, for example, is not allowed to jump from "correct" into "publish" without going through the check.
-
-The `circuit` gem allows you to define this *activity* and takes care of implementing the control flow, running the activity and making sure no invalid paths are taken.
+> Since TRB 2.1, we use [BPMN](http://www.bpmn.org/) lingo and concepts for describing workflows and processes.
 
-Your job is solely to implement the tasks and deciders put into this activity - you don't have to take care of executing it in the right order, and so on.
+An activity is a workflow that contains one or several tasks. It is the main concept to organize control flow in Trailblazer.
 
-## Definition
-
-In order to define an activity, you can use the BPMN editor of your choice and run it through the Trailblazer circuit generator, use our online tool (if [you're a PRO member](http://pro.trailblazer.to)) or simply define it using plain Ruby.
-
-```ruby
-activity = Activity.from_hash do |start, _end|
-  {
-    start            => { Circuit::Right => Blog::Write },
-    Blog::Write      => { Circuit::Right => Blog::SpellCheck },
-    Blog::SpellCheck => { Circuit::Right => Blog::Publish, Circuit::Left => Blog::Correct },
-    Blog::Correct    => { Circuit::Right => Blog::SpellCheck },
-    Blog::Publish    => { Circuit::Right => _end }
-  }
-end
-```
+The following diagram illustrates an exemplary workflow where a user writes and publishes a blog post.
 
-The `Activity` function is a convenient tool to create an activity. Note that the yielded object allows to access *events* from the activity, such as the `Start` and `End` event that are created per default.
+<img src="http://trb.to/images/diagrams/blog-bpmn1.png">
 
-This defines the control flow - the next step is to actually implement the tasks in this activity.
+After writing and spell-checking, the author has the chance to publish the post or, in case of typos, go back, correct, and go through the same flow, again. Note that there's only a handful of defined transistions, or connections. An author, for example, is not allowed to jump from "correct" into "publish" without going through the check.
 
-## Task
+The `activity` gem allows you to define this *activity* and takes care of implementing the control flow, running the activity and making sure no invalid paths are taken.
 
-A *task* usually maps to a particular box in your diagram. Its API is very simple: a task needs to expose a `call` method, allowing it to be a lambda or any other callable object.
+Your job is solely to implement the tasks and deciders put into this activity - Trailblazer makes sure it is executed it in the right order, and so on.
 
-```ruby
-module Blog
-  Write = ->(direction, options, *flow) do
-    options[:content] = options[:content].strip
-    [ Circuit::Right, options, *flow ]
-  end
-end
-```
+To eventually run this activity, three things have to be done.
 
-It receives all arguments returned from the task run before. This means a task should return everything it receives.
+1. The activity needs be defined. Easiest is to use the [Activity.from_hash builder](#activity-fromhash).
+2. It's the programmer's job (that's you!) to implement the actual tasks (the "boxes"). Use [tasks for that](#task).
+3. After defining and implementing, you can run the activity with any data [by `call`ing it](#activity-call).
 
-To transport data across the flow, you can change the return value. In this example, we use one global hash `options` that is passed from task to task and used for writing.
+## Operation vs. Activity
 
-The first return value is crucial: it dictates what will be the next step when executing the flow.
+An `Activity` allows to define and maintain a graph, that at runtime will be used as a "circuit". Or, in other words, it defines the boxes, circles, arrows and signals between them, and makes sure when running the activity, the circuit with your rules will be executed.
 
-For example, the `SpellCheck` task needs to decide which route to take.
+Please note that an `Operation` simply provides a neat DSL for creating an `Activity` with a railway-oriented wiring (left and right track). An operation _always_ maintains an activity internally.
 
 ```ruby
-SpellCheck = ->(direction, options, *flow) do
-  direction = SpellChecker.error_count(options[:content]) ? Circuit::Right : Circuit::Left
-  [ direction, options, *flow ]
+class Create < Trailblazer::Operation
+  step :exists?, pass_fast: true
+  step :policy
+  step :validate
+  fail :log_err
+  step :persist
+  fail :log_db_err
+  step :notify
 end
 ```
 
-It's as simple as returning the appropriate signal.
+Check the operation above. The DSL to create the activity with its graph is very different to `Activity`, but the outcome is a simple activity instance.
 
-> You can use any object as a direction signal and return it, as long as it's defined in the circuit.
+<img src="http://trb.to/images/graph/op-vs-activity.png">
 
-## Call
+When `call`ing an operation, several transformations on the arguments are applied, and those are passed to the `Activity#call` invocation. After the activity finished, its output is transformed into a `Result` object.
 
-After defining circuit and implementing the tasks, the circuit can be executed using its very own `call` method.
+## Activity
 
-```ruby
-direction, options, flow = activity.(
-  nil,
-  { content: "Let's start writing   " } # gets trimmed in Write.
-)
-```
-
-The first argument is where to start the circuit. Usually, this will be the activity's `Start` event accessable via `activity[:Start]`.
+To understand how an activity works and what it performs in your application logic, it's easiest to see how activities are defined, and used.
 
-All options are passed straight to the first task, which in turn has to make sure it returns an appropriate result set.
+## Activity: From_Hash
 
-The activity's return set is the last run task and all arguments from the last task.
-
-```ruby
-direction #=> #<End: default {}>
-options   #=> {:content=>"Let's start writing"}
-```
-
-As opposed to higher abstractions such as `Operation`, it is completely up to the developer what interfaces they provide to tasks and their return values. What is a mutable hash here could be an explicit array of return values in another implementation style, and so on.
-
-## Tracing
-
-For debugging or simply understanding the flows of circuits, you can use tracing.
+Instead of using an operation, you can manually define activities by using the `Activity.from_hash` builder.
 
 ```ruby
 activity = Activity.from_hash do |start, _end|
-  # Blog::Write=>"Blog::Write",Blog::SpellCheck=>"Blog::SpellCheck",Blog::Correct=>"Blog::Correct", Blog::Publish=>"Blog::Publish" }) { |evt|
   {
-    start      => { Circuit::Right => Blog::Write },
-    Blog::Write      => { Circuit::Right => Blog::SpellCheck },
-    Blog::SpellCheck => { Circuit::Right => Blog::Publish, Circuit::Left => Blog::Correct },
-    Blog::Correct    => { Circuit::Right => Blog::SpellCheck },
-    Blog::Publish    => { Circuit::Right => _end }
+    start            => { Trailblazer::Circuit::Right => Blog::Write },
+    Blog::Write      => { Trailblazer::Circuit::Right => Blog::SpellCheck },
+    Blog::SpellCheck => { Trailblazer::Circuit::Right => Blog::Publish,
+                          Trailblazer::Circuit::Left => Blog::Correct },
+    Blog::Correct    => { Trailblazer::Circuit::Right => Blog::SpellCheck },
+    Blog::Publish    => { Trailblazer::Circuit::Right => _end }
   }
 end
 ```
 
-The second argument to `Activity` takes debugging information, so you can set readable names for tasks.
 
-When invoking the activity, the `:runner` option will activate tracing and write debugging information about any executed task onto the `:stack` array.
+The block yields a generic start and end event instance. You then connect every _task_ in that hash (hash keys) to another task or event via the emitted _signal_.
 
-```ruby
-stack, _ = Circuit::Trace.( activity,
-  nil,
-  { content: "Let's start writing" }
-)
-```
+## Activity: Call
 
-The `stack` can then be passed to a presenter.
+To run the activity, you want to `call` it.
 
+```ruby
+my_options = {}
+last_signal, options, flow_options, _ = activity.( nil, my_options, {} )
 ```
-Circuit::Trace::Present.tree(stack)
- |--> #<Start: default {}>{:content=>"Let's start writing"}
- |--> Blog::Write{:content=>"Let's start writing"}
- |--> Blog::SpellCheck{:content=>"Let's start writing"}
- |--> Blog::Publish{:content=>"Let's start writing"}
- `--> #<End: default {}>{:content=>"Let's start writing"}
- ```
 
-Tracing is extremely efficient to find out what is going wrong and supersedes cryptic debuggers by many times. Note that tracing also works for deeply nested circuits.
+1. The `start` event is `call`ed and per default returns the generic _signal_`Trailblazer::Circuit::Right`.
+2. This emitted (or returned) signal is connected to the next task `Blog::Write`, which is now `call`ed.
+3. `Blog::Write` emits another `Right` signal that leads to `Blog::SpellCheck` being `call`ed.
+4. `Blog::SpellCheck` defines two outgoing signals and hence can decide what next task to call by emitting either `Right` if the spell check was ok, or `Left` if the post contains typos.
+5. ...and so on.
+
+<img src="http://trb.to/images/graph/blogpost-activity.png">
 
-> 🌅 In future versions of Trailblazer, our own debugger will take advantage of the explicit, traceable nature of circuits and also integrate with Ruby's exception handling.
-> Also, more options will make debugging of complex, nested workflows easier.
+Visualizing an activity as a graph makes it very straight-forward to understanding the mechanics of the flow.
 
-## Event
 
-* how to add more ends, etc.
+Note how signals translate to edges (or connections) in the graph, and tasks become vertices (or nodes).
 
-## Nested
+The return values are the `last_signal`, which is usually the end event (they return themselves as a signal), the last `options` that usually contains all kinds of data from running the activity, and additional args.
 
-## Operation
+## More
 
-If you need a higher abstraction of `circuit`, check out Trailblazer's [operation](http://trailblazer.to/gems/operation/2.0/api.html) implemenation which provides a simple Railway-oriented interface to create linear circuits.
+The [full documentation](http://trb.to/gems/activity/0.2/api.html) for this gem and many more interesting things can be found on the Trailblazer website.

data/lib/trailblazer/activity/subprocess.rb

@@ -1,21 +1,22 @@
 module Trailblazer
   class Activity
-      # Builder for running a nested process from a specific `start_at` position.
-    def self.Subprocess(*args, &block)
-      Subprocess.new(*args, &block)
+     # 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)
     end
 
     # Subprocess allows to have tasks with a different call interface and start event.
-    # @param activity Activity interface
+    # @param activity any object with an {Activity interface}
     class Subprocess
-      def initialize(activity, start_at: nil, call: :call, &block)
-        @activity, @start_at, @call, @block = activity, start_at, call, block
+      def initialize(activity, call: :call, **options)
+        @activity = activity
+        @options = options
+        @call     = call
       end
 
-      def call(start_at, *args)
-        return @block.(activity: activity, start_at: @start_at, args: args) if @block
-
-        @activity.public_send(@call, @start_at, *args)
+      def call(args, **circuit_options)
+        @activity.public_send(@call, args, circuit_options.merge(@options))
       end
 
       # @private
@@ -23,3 +24,7 @@ module Trailblazer
     end
   end
 end
+
+# circuit.( args, runner: Runner, start_at: raise, **circuit_flow_options )
+
+# subprocess.( options, flow_options, *args, start_event:<Event>, last_signal: signal )

data/lib/trailblazer/activity/trace.rb

@@ -8,18 +8,26 @@ module Trailblazer
     #
     # Hooks into the TaskWrap.
     module Trace
-      def self.call(activity, direction, options, flow_options={}, &block)
+      def self.call(activity, (options), *args, &block)
         tracing_flow_options = {
-          runner:       Wrap::Runner,
           stack:        Trace::Stack.new,
-          wrap_runtime: ::Hash.new(Trace.wirings),
           # Note that we don't pass :wrap_static here, that's handled by Task.__call__.
           introspection:        {}, # usually set that in Activity::call.
         }
 
-        direction, options, flow_options = call_circuit( activity, direction, options, tracing_flow_options.merge(flow_options), &block )
+        tracing_circuit_options = {
+          runner:       Wrap::Runner,
+          wrap_runtime: ::Hash.new(Trace.wirings), # FIXME: this still overrides existing wrap_runtimes.
+          wrap_static:  ::Hash.new( Trailblazer::Activity::Wrap.initial_activity ) # FIXME
+        }
+
+        last_signal, (options, flow_options) = call_circuit( activity, [
+          options,
+          # tracing_flow_options.merge(flow_options),
+          tracing_flow_options,
+        ], tracing_circuit_options, &block )
 
-        return flow_options[:stack].to_a, direction, options, flow_options
+        return flow_options[:stack].to_a, last_signal, options, flow_options
       end
 
       # TODO: test alterations with any wrap_circuit.
@@ -36,20 +44,26 @@ module Trailblazer
         ]
       end
 
-      def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
+      # def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
+      def self.capture_args((wrap_config, original_args), **circuit_options)
+        (original_options, original_flow_options, _) = original_args[0]
+
         original_flow_options[:stack].indent!
 
-        original_flow_options[:stack] << [ wrap_config[:task], :args, nil, options.dup, original_flow_options[:introspection] ]
+        original_flow_options[:stack] << [ wrap_config[:task], :args, nil, {}, original_flow_options[:introspection] ]
 
-        [ direction, options, flow_options, wrap_config, original_flow_options ]
+        [ Circuit::Right, [wrap_config, original_args ], **circuit_options ]
       end
 
-      def self.capture_return(direction, options, flow_options, wrap_config, original_flow_options)
-        original_flow_options[:stack] << [ wrap_config[:task], :return, flow_options[:result_direction], options.dup ]
+      def self.capture_return((wrap_config, original_args), **circuit_options)
+        (original_options, original_flow_options, _) = original_args[0]
+
+        original_flow_options[:stack] << [ wrap_config[:task], :return, wrap_config[:result_direction], {} ]
 
         original_flow_options[:stack].unindent!
 
-        [ direction, options, flow_options, wrap_config, original_flow_options ]
+
+        [ Circuit::Right, [wrap_config, original_args ], **circuit_options ]
       end
 
       # Mutable/stateful per design. We want a (global) stack!

data/lib/trailblazer/activity/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Activity
-    VERSION = "0.1.6"
+    VERSION = "0.2.0"
   end
 end

data/lib/trailblazer/activity/wrap.rb

@@ -5,31 +5,40 @@ class Trailblazer::Activity
     #
     # Here, we extend this, and wrap the task `call` into its own pipeline, so we can add external behavior per task.
     module Runner
+      # Runner signature: call( task, direction, options, static_wraps )
+      #
       # @api private
-      # Runner signature: call( task, direction, options, flow_options, static_wraps )
-      def self.call(task, direction, options, flow_options, static_wraps = Hash.new(Wrap.initial_activity))
-        wrap_config   = { task: task }
-        runtime_wraps = flow_options[:wrap_runtime] || raise("Please provide :wrap_runtime")
+      # @interface Runner
+      def self.call(task, (options, *args), wrap_runtime: raise, wrap_static: raise, **circuit_options)
+        wrap_ctx = { task: task }
 
-        task_wrap_activity = apply_wirings(task, static_wraps, runtime_wraps)
+        # this activity is "wrapped around" the actual `task`.
+        task_wrap_activity = apply_wirings(task, wrap_static, wrap_runtime)
 
-        # 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
-        # Pass empty flow_options to the task_wrap, so it doesn't infinite-loop.
+        # We save all original args passed into this Runner.call, because we want to return them later after this wrap
+        # is finished.
+        original_args = [ [options, *args], circuit_options.merge( wrap_runtime: wrap_runtime, wrap_static: wrap_static ) ]
 
         # call the wrap for the task.
-        ret = task_wrap_activity.( nil, options, {}, wrap_config, flow_options )
+        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 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).
 
-        [ *ret, static_wraps ] # return everything plus the static_wraps for the next task in the circuit.
+        # raise if wrap_ctx[:result_args][2] != static_wraps
+
+        # TODO: make circuit ignore all returned but the first
+        [ wrap_ctx[:result_direction], wrap_ctx[:result_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.
       def self.apply_wirings(task, wrap_static, wrap_runtime)
         wrap_activity = wrap_static[task]   # find static wrap for this specific task, or default wrap activity.
 
@@ -41,33 +50,30 @@ class Trailblazer::Activity
 
     # The call_task method implements one default step `Call` in the Wrap::Activity circuit.
     # It calls the actual, wrapped task.
-    def self.call_task(direction, options, flow_options, wrap_config, original_flow_options)
-      task  = wrap_config[:task]
+    def self.call_task((wrap_ctx, original_args), **circuit_options)
+      task  = wrap_ctx[:task]
 
       # Call the actual task we're wrapping here.
-      wrap_config[:result_direction], options, flow_options = task.( direction, options, original_flow_options )
+      puts "~~~~wrap.call: #{task}"
+      wrap_ctx[:result_direction], wrap_ctx[:result_args] = task.( *original_args )
 
-      [ direction, options, flow_options, wrap_config, original_flow_options ]
+      # DISCUSS: do we want original_args here to be passed on, or the "effective" result_args which are different to original_args now?
+      [ Trailblazer::Circuit::Right, [ wrap_ctx, original_args ], **circuit_options ]
     end
 
     Call = method(:call_task)
 
-    class End < Trailblazer::Circuit::End
-      def call(direction, options, flow_options, wrap_config, *args)
-        [ wrap_config[:result_direction], options, flow_options ] # note how we don't return the appended internal args.
-      end
-    end
-
     # Wrap::Activity is the actual circuit that implements the Task wrap. This circuit is
     # also known as `task_wrap`.
     #
     # Example with tracing:
     #
-    #   |-- Start
-    #   |-- Trace.capture_args   [optional]
-    #   |-- Call (call actual task)
-    #   |-- Trace.capture_return [optional]
-    #   |-- End
+          # 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
 
     # Activity = Trailblazer::Activity::Activity({ id: "task.wrap" }, end: { default: End.new(:default) }) do |act|
     #   {
@@ -79,7 +85,7 @@ class Trailblazer::Activity
     def self.initial_activity
       Trailblazer::Activity.from_wirings(
         [
-          [ :attach!, target: [ End.new(:default), type: :event, id: "End.default" ], edge: [ Trailblazer::Circuit::Right, {} ] ],
+          [ :attach!, target: [ Trailblazer::Circuit::End.new(:default), type: :event, id: "End.default" ], edge: [ Trailblazer::Circuit::Right, {} ] ],
           [ :insert_before!, "End.default", node: [ Call, id: "task_wrap.call_task" ], outgoing: [ Trailblazer::Circuit::Right, {} ], incoming: ->(*) { true } ]
         ]
       )

data/lib/trailblazer/activity.rb

@@ -75,14 +75,9 @@ module Trailblazer
     end
 
     def initialize(graph)
-      @graph       = graph
-      @start_event = @graph[:_wrapped]
-      @circuit     = to_circuit(@graph) # graph is an immutable object.
-    end
-
-    # Calls the internal circuit. `start_at` defaults to the Activity's start event if `nil` is given.
-    def call(start_at, *args)
-      @circuit.( start_at || @start_event, *args )
+      @graph               = graph
+      @default_start_event = graph[:_wrapped]
+      @circuit             = to_circuit( @graph ) # graph is an immutable object.
     end
 
     def end_events
@@ -97,6 +92,13 @@ module Trailblazer
       ::Hash[ graph.find_all { |node| graph.successors(node).size == 0 }.collect { |node| [ node[:_wrapped], { role: node[:role] } ] } ]
     end
 
+    def call(args, start_event: default_start_event, **circuit_options)
+      @circuit.(
+        args,
+        circuit_options.merge( task: start_event) , # this passes :runner to the {Circuit}.
+      )
+    end
+
     # @private
     attr_reader :circuit
     # @private
@@ -104,6 +106,8 @@ module Trailblazer
 
     private
 
+    attr_reader :default_start_event
+
     def to_circuit(graph)
       Circuit.new(graph.to_h( include_leafs: false ), end_events, {})
     end
@@ -121,5 +125,8 @@ module Trailblazer
         @graph.find_all { |node| node[:_wrapped] == task  }.first
       end
     end
+
+    module Interface
+    end
   end
 end

data/lib/trailblazer/circuit/testing.rb

@@ -42,3 +42,17 @@ class Trailblazer::Circuit
     target
   end
 end
+
+module Trailblazer::Activity::Inspect
+  # The "matcher":
+  # Finds out appropriate serializer and calls it.
+  def self.call(inspected)
+    Instance(inspected)
+  end
+
+  # Serializes an object instance with hex IDs.
+  #   <Trailblazer::Circuit::Start: @name=:default, @options={}>
+  def self.Instance(object)
+    object.inspect.gsub(/0x\w+/, "")
+  end
+end

data/lib/trailblazer/circuit.rb

@@ -19,28 +19,36 @@ module Trailblazer
       @name        = name
     end
 
-    Run = ->(activity, direction, *args) { activity.(direction, *args) }
+    # @param args [Array] all arguments to be passed to the task's `call`
+    # @param task [callable] task to call
+    Run = ->(task, args, **circuit_options) { task.(args, **circuit_options) }
 
-    # Runs the circuit. Stops when hitting a End event or subclass thereof.
-    # This method throws exceptions when the return value of a task doesn't match
+    # Runs the circuit until we hit a stop event.
+    #
+    # This method throws exceptions when the returned value of a task doesn't match
     # any wiring.
     #
-    # @param activity A task from the circuit where to start
-    # @param args An array of options passed to the first task.
-    def call(activity, options, flow_options={}, *args)
-      direction = nil
-      runner    = flow_options[:runner] || Run
-
+    # @param task An event or task of this circuit from where to start
+    # @param options anything you want to pass to the first task
+    # @param flow_options Library-specific flow control data
+    # @return [last_signal, options, flow_options, *args]
+    #
+    # DISCUSS: returned circuit_options are ignored when calling the runner.
+    def call(args, task: raise, runner: Run, **circuit_options)
       loop do
-        direction, options, flow_options, *args = runner.( activity, direction, options, flow_options, *args )
+        last_signal, args, _ignored_circuit_options = runner.(
+          task,
+          args,
+          circuit_options.merge( runner: runner ) # options for runner, to be discarded.
+        )
 
-        # Stop execution of the circuit when we hit a stop event (< End). This could be an activity's End or Suspend.
-        return [ direction, options, flow_options, *args ] if @stop_events.include?(activity)
+        # Stop execution of the circuit when we hit a stop event (< End). This could be an task's End or Suspend.
+        return [ last_signal, args ] if @stop_events.include?(task) # DISCUSS: return circuit_options here?
 
-        activity = next_for(activity, direction) do |next_activity, in_map|
-          activity_name = @name[activity] || activity # TODO: this must be implemented only once, somewhere.
-          raise IllegalInputError.new("#{@name[:id]} #{activity_name}") unless in_map
-          raise IllegalOutputSignalError.new("from #{@name[:id]}: `#{activity_name}`===>[ #{direction.inspect} ]") unless next_activity
+        task = next_for(task, last_signal) do |next_task, in_map|
+          task_name = @name[task] || task # TODO: this must be implemented only once, somewhere.
+          raise IllegalInputError.new("#{@name[:id]} #{task_name}") unless in_map
+          raise IllegalOutputSignalError.new("from #{@name[:id]}: `#{task_name}`===>[ #{last_signal.inspect} ]") unless next_task
         end
       end
     end
@@ -51,16 +59,16 @@ module Trailblazer
     end
 
   private
-    def next_for(last_activity, emitted_direction)
+    def next_for(last_task, emitted_signal)
       # p @map
       in_map        = false
-      cfg           = @map.keys.find { |t| t == last_activity } and in_map = true
+      cfg           = @map.keys.find { |t| t == last_task } and in_map = true
       cfg = @map[cfg] if cfg
       cfg         ||= {}
-      next_activity = cfg[emitted_direction]
-      yield next_activity, in_map
+      next_task = cfg[emitted_signal]
+      yield next_task, in_map
 
-      next_activity
+      next_task
     end
 
     class IllegalInputError < RuntimeError
@@ -77,13 +85,13 @@ module Trailblazer
         @options = options
       end
 
-      def call(direction, *args)
+      def call(*args)
         [ self, *args ]
       end
     end
 
     class Start < End
-      def call(direction, *args)
+      def call(*args)
         [ Right, *args ]
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-15 00:00:00.000000000 Z
+date: 2017-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hirb
@@ -92,6 +92,7 @@ files:
 - ".travis.yml"
 - CHANGES.md
 - Gemfile
+- NOTES
 - README.md
 - Rakefile
 - lib/trailblazer-activity.rb