trailblazer-activity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2f76309405b46e6388f13ecd090c1ad50a527fbc
+  data.tar.gz: 9c0baac268666b6c6136d78b967f7a8e436ee245
+SHA512:
+  metadata.gz: 4cc934487e044fc7a59273a03e20c77cbae3f7eda9d51d6016f0ca5dc30f83d36168aca43cbce19e0909f8b73c7a28f155f631cd9a325056e3cf678d3164c6ba
+  data.tar.gz: ea8fb256973d8a6084d4c7a7a70e3b990cef945e1f53ee31cd87f90061e20628631b0fcc405e6ec65b5f925ec8fc92c8a9cd28f4325ee4042b2e5e9bafda5b8a

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,13 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3.3
+  - 2.4.0
+matrix:
+  include:
+  - rvm: jruby-9.1.7.0
+    env: JRUBY_OPTS="--profile.api"
+before_install: gem install bundler

data/CHANGES.md

@@ -0,0 +1,55 @@
+# 0.0.12
+
+* In `Activity::Before`, allow specifying what predecessing tasks to connect to the new_task via the
+`:predecessors` option, and without knowing the direction. This will be the new preferred style in `Trailblazer:::Sequence`
+where we can always assume directions are limited to `Right` and `Left` (e.g., with nested activities, this changes to a
+colorful selection of directions).
+
+# 0.0.11
+
+* Temporarily allow injecting a `to_hash` transformer into a `ContainerChain`. This allows to ignore
+certain container types such as `Dry::Container` in the KW transformation. Note that this is a temp
+fix and will be replaced with proper pattern matching.
+
+# 0.0.10
+
+* Introduce `Context::ContainerChain` to eventually replace the heavy-weight `Skill` object.
+* Fix a bug in `Option` where wrong args were passed when used without `flow_options`.
+
+# 0.0.9
+
+* Fix `Context#[]`, it returned `nil` when it should return `false`.
+
+# 0.0.8
+
+* Make `Trailblazer::Option` and `Trailblazer::Option::KW` a mix of lambda and object so it's easily extendable.
+
+# 0.0.7
+
+* It is now `Trailblazer::Args`.
+
+# 0.0.6
+
+* `Wrapped` is now `Wrap`. Also, a consistent `Alterations` interface allows tweaking here.
+
+# 0.0.5
+
+* The `Wrapped::Runner` now applies `Alterations` to each task's `Circuit`. This means you can inject `:task_alterations` into `Circuit#call`, which will then be merged into the task's original circuit, and then run. While this might sound like crazy talk, this allows any kind of external injection (tracing, input/output contracts, step dependency injections, ...) for specific or all tasks of any circuit.
+
+# 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.
+
+# 0.0.2
+
+* Make `flow_options` an immutable data structure just as `options`. It now needs to be returned from a `#call`.
+
+# 0.0.1
+
+* First release into an unsuspecting world. 🚀

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in workflow.gemspec
+gemspec
+
+gem "minitest-line"
+gem "benchmark-ips"

data/README.md

@@ -0,0 +1,117 @@
+# Circuit
+
+_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.
+
+{% callout %}
+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.
+{% endcallout %}
+
+## Installation
+
+To use circuits, activities and nested tasks, you need one gem, only.
+
+```ruby
+gem "trailblazer-circuit"
+```
+
+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="/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.
+
+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.
+
+## 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.
+
+{{ "test/docs/activity_test.rb:basic:../trailblazer-circuit" | tsnippet }}
+
+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.
+
+This defines the control flow - the next step is to actually implement the tasks in this activity.
+
+## Task
+
+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.
+
+{{ "test/docs/activity_test.rb:write:../trailblazer-circuit" | tsnippet }}
+
+It receives all arguments returned from the task run before. This means a task should return everything it receives.
+
+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.
+
+The first return value is crucial: it dictates what will be the next step when executing the flow.
+
+For example, the `SpellCheck` task needs to decide which route to take.
+
+{{ "test/docs/activity_test.rb:spell:../trailblazer-circuit" | tsnippet }}
+
+It's as simple as returning the appropriate signal.
+
+{% callout %}
+You can use any object as a direction signal and return it, as long as it's defined in the circuit.
+{% endcallout %}
+
+## Call
+
+After defining circuit and implementing the tasks, the circuit can be executed using its very own `call` method.
+
+{{ "test/docs/activity_test.rb:call:../trailblazer-circuit" | tsnippet }}
+
+The first argument is where to start the circuit. Usually, this will be the activity's `Start` event accessable via `activity[:Start]`.
+
+All options are passed straight to the first task, which in turn has to make sure it returns an appropriate result set.
+
+The activity's return set is the last run task and all arguments from the last task.
+
+{{ "test/docs/activity_test.rb:call-ret:../trailblazer-circuit" | tsnippet }}
+
+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.
+
+{{ "test/docs/activity_test.rb:trace-act:../trailblazer-circuit" | tsnippet }}
+
+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.
+
+{{ "test/docs/activity_test.rb:trace-call:../trailblazer-circuit" | tsnippet }}
+
+The `stack` can then be passed to a presenter.
+
+{{ "test/docs/activity_test.rb:trace-res:../trailblazer-circuit" | tsnippet }}
+
+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.
+
+{% callout %}
+🌅 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.
+{% endcallout %}
+
+## Event
+
+* how to add more ends, etc.
+
+## Nested
+
+## Operation
+
+If you need a higher abstraction of `circuit`, check out Trailblazer's [operation](localhost:4000/gems/operation/2.0/api.html) implemenation which provides a simple Railway-oriented interface to create linear circuits.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/lib/trailblazer-activity.rb

@@ -0,0 +1 @@
+require "trailblazer/activity"

data/lib/trailblazer/activity.rb

@@ -0,0 +1,119 @@
+require "trailblazer/activity/graph"
+require "trailblazer/activity/nested"
+require "trailblazer/activity/version"
+
+require "trailblazer/circuit"
+require "trailblazer/circuit/trace"
+require "trailblazer/circuit/present"
+require "trailblazer/circuit/wrap"
+
+require "trailblazer/option"
+require "trailblazer/context"
+require "trailblazer/container_chain"
+
+module Trailblazer
+  class Activity
+
+    # Only way to build an Activity.
+    def self.from_wirings(wirings, &block)
+      start_evt  = Circuit::Start.new(:default)
+      start_args = [ start_evt, { type: :event, id: [:Start, :default] } ]
+
+      start      = block ? Graph::Start( *start_args, &block ) : Graph::Start(*start_args)
+
+      wirings.each do |wiring|
+        start.send(*wiring)
+      end
+
+      new(start)
+    end
+
+    # Build an activity from a hash.
+    #
+    #   activity = Trailblazer::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
+    def self.from_hash(end_evt=Circuit::End.new(:default), start_evt=Circuit::Start.new(:default), &block)
+      hash  = yield(start_evt, end_evt)
+      graph = Graph::Start( start_evt, id: [:Start, :default] )
+
+      hash.each do |source_task, connections|
+        source = graph.find_all { |node| node[:_wrapped] == source_task }.first or raise "#{source_task} unknown"
+
+        connections.each do |signal, task| # FIXME: id sucks
+          if existing = graph.find_all { |node| node[:_wrapped] == task }.first
+            graph.connect!( source: source[:id], target: existing, edge: [signal, {}] )
+          else
+            graph.attach!( source: source[:id], target: [task, id: task], edge: [signal, {}] )
+          end
+        end
+      end
+
+      new(graph)
+    end
+
+    def self.merge(activity, wirings)
+      graph = activity.graph
+
+      # TODO: move this to Graph
+      # replace the old start node with the new one that's created in ::from_wirings.
+      cloned_graph_ary = graph[:graph].collect { |node, connections| [ node, connections.clone ] }
+      old_start_connections = cloned_graph_ary.delete_at(0)[1] # FIXME: what if some connection goes back to start?
+
+      from_wirings(wirings) do |start_node, data|
+        cloned_graph_ary.unshift [ start_node, old_start_connections ] # push new start node onto the graph.
+
+        data[:graph] = ::Hash[cloned_graph_ary]
+      end
+    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 )
+    end
+
+    def end_events
+      @circuit.to_fields[1]
+    end
+
+    # @private
+    attr_reader :circuit
+    # @private
+    attr_reader :graph
+
+    private
+
+    def to_circuit(graph)
+      end_events = graph.find_all { |node| graph.successors(node).size == 0 } # Find leafs of graph.
+        .collect { |n| n[:_wrapped] } # unwrap the actual End event instance from the Node.
+
+      Circuit.new(graph.to_h( include_leafs: false ), end_events, {})
+    end
+
+    class Introspection
+      # @param activity Activity
+      def initialize(activity)
+        @activity = activity
+        @graph    = activity.graph
+        @circuit  = activity.circuit
+      end
+
+      # Find the node that wraps `task` or return nil.
+      def [](task)
+        @graph.find_all { |node| node[:_wrapped] == task  }.first
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/graph.rb

@@ -0,0 +1,135 @@
+module Trailblazer
+  # Note that Graph is a superset of a real directed graph. For instance, it might contain detached nodes.
+  # == Design
+  # * This class is designed to maintain a graph while building up a circuit step-wise.
+  # * It can be imperformant as this all happens at compile-time.
+  module Activity::Graph
+    # Task => { name: "Nested{Task}", type: :subprocess, boundary_events: { Circuit::Left => {} }  }
+
+    # TODO: make Edge, Node, Start Hash::Immutable ?
+    class Edge
+      def initialize(data)
+        @data = data
+      end
+
+      def [](key)
+        @data[key]
+      end
+    end
+
+    class Node < Edge
+    end
+
+    class Start < Node
+      def initialize(data)
+        yield self, data if block_given?
+        super
+      end
+
+      # Single entry point for adding nodes and edges to the graph.
+      def connect_for!(source, edge, target)
+        # raise if find_all( source[:id] ).any?
+        self[:graph][source] ||= {}
+        self[:graph][target] ||= {} # keep references to all nodes, even when detached.
+        self[:graph][source][edge] = target
+      end
+      private :connect_for!
+
+      # Builds a node from the provided `:node` argument array.
+      def attach!(target:raise, edge:raise, source:self)
+        target = target.kind_of?(Node) ? target : Node(*target)
+
+        connect!(target: target, edge: edge, source: source)
+      end
+
+      def connect!(target:raise, edge:raise, source:self)
+        target = target.kind_of?(Node) ? target : (find_all { |_target| _target[:id] == target }[0] || raise( "#{target} not found"))
+        source = source.kind_of?(Node) ? source : (find_all { |_source| _source[:id] == source }[0] || raise( "#{source} not found"))
+
+        edge = Edge(*edge)
+
+        connect_for!(source, edge, target)
+
+        target
+      end
+
+      def insert_before!(old_node, node:raise, outgoing:nil, incoming:raise)
+        old_node = find_all(old_node)[0] || raise( "#{old_node} not found") unless old_node.kind_of?(Node)
+        new_node = Node(*node)
+
+        raise IllegalNodeError.new("The ID `#{new_node[:id]}` has been added before.") if find_all( new_node[:id] ).any?
+
+        incoming_tuples     = predecessors(old_node)
+        rewired_connections = incoming_tuples.find_all { |(node, edge)| incoming.(edge) }
+
+        # rewire old_task's predecessors to new_task.
+        if rewired_connections.size == 0 # this happens when we're inserting "before" an orphaned node.
+          self[:graph][new_node] = {} # FIXME: redundant in #connect_for!
+        else
+          rewired_connections.each { |(node, edge)| connect_for!(node, edge, new_node) }
+        end
+
+        # connect new_task --> old_task.
+        if outgoing
+          edge = Edge(*outgoing)
+
+          connect_for!(new_node, edge, old_node)
+        end
+
+        return new_node
+      end
+
+      def find_all(id=nil, &block)
+        nodes = self[:graph].keys + self[:graph].values.collect(&:values).flatten
+        nodes = nodes.uniq
+
+        block ||= ->(node) { node[:id] == id }
+
+        nodes.find_all(&block)
+      end
+
+      def Edge(wrapped, options)
+        edge = Edge.new(options.merge( _wrapped: wrapped ))
+      end
+
+      def Node(wrapped, options)
+        Node.new( options.merge( _wrapped: wrapped ) )
+      end
+
+      # private
+      def predecessors(target_node)
+        self[:graph].each_with_object([]) do |(node, connections), ary|
+          connections.each { |edge, target| target == target_node && ary << [node, edge] }
+        end
+      end
+
+      def successors(node)
+        ( self[:graph][node] || {} ).values
+      end
+
+      def to_h(include_leafs:true)
+        hash = ::Hash[
+          self[:graph].collect do |node, connections|
+            connections = connections.collect { |edge, node| [ edge[:_wrapped], node[:_wrapped] ] }
+
+            [ node[:_wrapped], ::Hash[connections] ]
+          end
+        ]
+
+        if include_leafs == false
+          hash = hash.select { |node, connections| connections.any? }
+        end
+
+        hash
+      end
+    end
+
+    def self.Start(wrapped, graph:{}, **data, &block)
+      block ||= ->(node, data) { data[:graph][node] = {} }
+      Start.new( { _wrapped: wrapped, graph: graph }.merge(data), &block )
+    end
+
+    class IllegalNodeError < RuntimeError
+    end
+  end # Graph
+end

data/lib/trailblazer/activity/nested.rb

@@ -0,0 +1,25 @@
+module Trailblazer
+  class Activity
+      # Builder for running a nested process from a specific `start_at` position.
+    def self.Nested(*args, &block)
+      Nested.new(*args, &block)
+    end
+
+    # Nested allows to have tasks with a different call interface and start event.
+    # @param activity Activity interface
+    class Nested
+      def initialize(activity, start_with=nil, &block)
+        @activity, @start_with, @block = activity, start_with, block
+      end
+
+      def call(start_at, *args)
+        return @block.(activity: activity, start_at: @start_with, args: args) if @block
+
+        @activity.(@start_with, *args)
+      end
+
+      # @private
+      attr_reader :activity # we actually only need this for introspection.
+    end
+  end
+end

data/lib/trailblazer/activity/version.rb

@@ -0,0 +1,5 @@
+module Trailblazer
+  class Activity
+    VERSION = "0.1.0"
+  end
+end

data/lib/trailblazer/circuit.rb

@@ -0,0 +1,100 @@
+module Trailblazer
+  # Running a Circuit instance will run all tasks sequentially depending on the former's result.
+  # Each task is called and retrieves the former task's return values.
+  #
+  # Note: Please use #Activity as a public circuit builder.
+  #
+  # @param map         [Hash] Defines the wiring.
+  # @param stop_events [Array] Tasks that stop execution of the circuit.
+  # @param name        [Hash] Names for tracing, debugging and exceptions. `:id` is a reserved key for circuit name.
+  #
+  #   result = circuit.(start_at, *args)
+  #
+  # @see Activity
+  # @api semi-private
+  class Circuit
+    def initialize(map, stop_events, name)
+      @map         = map
+      @stop_events = stop_events
+      @name        = name
+    end
+
+    Run = ->(activity, direction, *args) { activity.(direction, *args) }
+
+    # 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
+    # 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
+
+      loop do
+        direction, options, flow_options, *args = 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, options, flow_options, *args ] 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.
+          raise IllegalInputError.new("#{@name[:id]} #{activity_name}") unless in_map
+          raise IllegalOutputSignalError.new("from #{@name[:id]}: `#{activity_name}`===>[ #{direction.inspect} ]") unless next_activity
+        end
+      end
+    end
+
+    # Returns the circuit's components.
+    def to_fields
+      [ @map, @stop_events, @name]
+    end
+
+  private
+    def next_for(last_activity, emitted_direction)
+      # p @map
+      in_map        = false
+      cfg           = @map.keys.find { |t| t == last_activity } and in_map = true
+      cfg = @map[cfg] if cfg
+      cfg         ||= {}
+      next_activity = cfg[emitted_direction]
+      yield next_activity, in_map
+
+      next_activity
+    end
+
+    class IllegalInputError < RuntimeError
+    end
+
+    class IllegalOutputSignalError < RuntimeError
+    end
+
+    # 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={})
+        @name    = name
+        @options = options
+      end
+
+      def call(direction, *args)
+        [ self, *args ]
+      end
+    end
+
+    class Start < End
+      def call(direction, *args)
+        [ Right, *args ]
+      end
+    end
+
+    # Builder for Circuit::End when defining the Activity's circuit.
+    def self.End(name, options={})
+      End.new(name, options)
+    end
+
+    class Signal;         end
+		class Right < Signal; end
+    class Left  < Signal; end
+  end
+end

data/lib/trailblazer/circuit/present.rb

@@ -0,0 +1,81 @@
+require "hirb"
+
+module Trailblazer
+  class Circuit
+    module Trace
+      # TODO:
+      # * Struct for debug_item
+      module Present
+        module_function
+
+        def tree(stack, level=1, tree=[])
+          tree_for(stack, level, tree)
+
+          Hirb::Console.format_output(tree, class: :tree, type: :directory)
+        end
+
+        # API HERE is: we only know the current element (e.g. task), input, output, and have an "introspection" object that tells us more about the element.
+        # TODO: the debug_item's "api" sucks, this should be a struct.
+        def tree_for(stack, level, tree)
+          stack.each do |debug_item|
+            task = debug_item[0][0]
+
+            if debug_item.size == 2 # flat
+              introspect = debug_item[0].last
+
+              name = (node = introspect[task]) ? node[:id] : task
+
+              tree << [ level,  name ]
+            else # nesting
+              tree << [ level, task ]
+
+              tree_for(debug_item[1..-2], level + 1, tree)
+
+              tree << [ level+1, debug_item[-1][0] ]
+            end
+
+            tree
+          end
+        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::Circuit::Start => :blue,
+            Trailblazer::Circuit::End   => :pink,
+            Trailblazer::Circuit::Right => :green,
+            Trailblazer::Circuit::Left  => :red
+          }
+        end
+
+        def color_table
+          {
+            red:    31,
+            green:  32,
+            yellow: 33,
+            blue:   34,
+            pink:   35
+          }
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/circuit/testing.rb

@@ -0,0 +1,42 @@
+module MiniTest::Assertions
+  def assert_activity_inspect(text, subject)
+    Trailblazer::Circuit::ActivityInspect(subject).must_equal text
+  end
+
+  def assert_event_inspect(text, subject)
+    Trailblazer::Circuit::EndInspect(subject).must_equal(text)
+  end
+end
+
+
+Trailblazer::Activity.infect_an_assertion :assert_activity_inspect, :must_inspect
+Trailblazer::Circuit::End.infect_an_assertion      :assert_event_inspect,    :must_inspect_end_fixme
+
+class Trailblazer::Circuit
+  def self.EndInspect(event)
+    event.instance_eval { "#<#{self.class.to_s.split("::").last}: #{@name} #{@options}>" }
+  end
+
+  def self.ActivityInspect(activity, strip: ["AlterTest::"])
+    strip += ["Trailblazer::Circuit::"]
+    stripped = ->(target) { strip_for(target, strip) }
+
+    map, _ = activity.circuit.to_fields
+
+    content = map.collect do |task, connections|
+      bla =
+      connections.collect do |direction, target|
+        target_str = target.kind_of?(End) ? EndInspect(target) : stripped.(target)
+        "#{stripped.(direction)}=>#{target_str}"
+      end.join(", ")
+      task_str = task.kind_of?(End) ? EndInspect(task) : stripped.(task)
+      "#{task_str}=>{#{bla}}"
+    end.join(", ")
+    "{#{content}}"
+  end
+
+  def self.strip_for(target, strings)
+    strings.each { |stripped| target = target.to_s.gsub(stripped, "") }
+    target
+  end
+end

data/lib/trailblazer/circuit/trace.rb

@@ -0,0 +1,86 @@
+module Trailblazer
+  class Circuit
+    # 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.
+    #
+    # Hooks into the TaskWrap.
+    module Trace
+      def self.call(activity, direction, options, flow_options={}, &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 )
+
+        return flow_options[:stack].to_a, direction, options, flow_options
+      end
+
+      # TODO: test alterations with any wrap_circuit.
+      def self.call_circuit(activity, *args, &block)
+        return activity.(*args) unless block
+        block.(activity, *args)
+      end
+
+      # Default tracing tasks to be plugged into the wrap circuit.
+      def self.wirings
+        [
+          [ :insert_before!, "task_wrap.call_task", node: [ Trace.method(:capture_args),   id: "task_wrap.capture_args" ], outgoing: [ Right, {} ], incoming: ->(*) { true } ],
+          [ :insert_before!, [:End, :default],      node: [ Trace.method(:capture_return), id: "task_wrap.capture_return" ], outgoing: [ Right, {} ], incoming: ->(*) { true } ],
+        ]
+      end
+
+      def self.capture_args(direction, options, flow_options, wrap_config, original_flow_options)
+        original_flow_options[:stack].indent!
+
+        original_flow_options[:stack] << [ wrap_config[:task], :args, nil, options.dup, original_flow_options[:introspection] ]
+
+        [ 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[:task], :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/wrap.rb

@@ -0,0 +1,88 @@
+class Trailblazer::Circuit
+  module Wrap
+    # The runner is passed into Circuit#call( runner: Runner ) and is called for every task in the circuit.
+    # Its primary job is to actually `call` the task.
+    #
+    # Here, we extend this, and wrap the task `call` into its own pipeline, so we can add external behavior per task.
+    module Runner
+      # @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")
+
+        task_wrap_activity = apply_wirings(task, static_wraps, runtime_wraps)
+
+        # 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.
+
+        # call the wrap for the task.
+        ret = task_wrap_activity.( nil, options, {}, wrap_config, flow_options )
+
+        [ *ret, static_wraps ] # return everything plus the static_wraps for the next task in the circuit.
+      end
+
+      private
+
+      # Compute the task's wrap by applying alterations both static and from runtime.
+      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.
+
+        # Apply runtime alterations.
+        # Grab the additional wirings for the particular `task` from `wrap_runtime` (returns default otherwise).
+        wrap_activity = Trailblazer::Activity.merge(wrap_activity, wrap_runtime[task])
+      end
+    end # Runner
+
+    # 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]
+
+      # 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_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
+
+    # Activity = Trailblazer::Circuit::Activity({ id: "task.wrap" }, end: { default: End.new(:default) }) do |act|
+    #   {
+    #     act[:Start] => { Right => Call }, # see Wrap::call_task
+    #     Call        => { Right => act[:End] },
+    #   }
+    # end # Activity
+
+    def self.initial_activity
+      Trailblazer::Activity.from_wirings(
+        [
+          [ :attach!, target: [ End.new(:default), type: :event, id: [:End, :default] ], edge: [ Right, {} ] ],
+          [ :insert_before!, [:End, :default], node: [ Call, id: "task_wrap.call_task" ], outgoing: [ Right, {} ], incoming: ->(*) { true } ]
+        ]
+      )
+    end
+  end
+end

data/lib/trailblazer/container_chain.rb

@@ -0,0 +1,45 @@
+# @private
+class Trailblazer::Context::ContainerChain # used to be called Resolver.
+  # Keeps a list of containers. When looking up a key/value, containers are traversed in
+  # the order they were added until key is found.
+  #
+  # Required Container interface: `#key?`, `#[]`.
+  #
+  # @note ContainerChain is an immutable data structure, it does not support writing.
+  # @param containers Array of <Container> objects (splatted)
+  def initialize(containers, to_hash: nil)
+    @containers = containers
+    @to_hash    = to_hash
+  end
+
+  # @param name Symbol or String to lookup a value stored in one of the containers.
+  def [](name)
+    self.class.find(@containers, name)
+  end
+
+  # @private
+  def key?(name)
+    @containers.find { |container| container.key?(name) }
+  end
+
+  def self.find(containers, name)
+    containers.find { |container| container.key?(name) && (return container[name]) }
+  end
+
+  def keys
+    @containers.collect(&:keys).flatten
+end
+
+  # @private
+  def to_hash
+    return @to_hash.(@containers) if @to_hash # FIXME: introduce pattern matching so we can have different "transformers" for each container type.
+    @containers.each_with_object({}) { |container, hash| hash.merge!(container.to_hash) }
+  end
+end
+
+# alternative implementation:
+# containers.reverse.each do |container| @mutable_options.merge!(container) end
+#
+# benchmark, merging in #initialize vs. this resolver.
+#                merge     39.678k (± 9.1%) i/s -    198.700k in   5.056653s
+#             resolver     68.928k (± 6.4%) i/s -    342.836k in   5.001610s

data/lib/trailblazer/context.rb

@@ -0,0 +1,100 @@
+# 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)
+      ContainerChain.find( [@mutable_options, @wrapped_options], name )
+    end
+
+    def key?(name)
+      @mutable_options.key?(name) || @wrapped_options.key?(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
+      [ @wrapped_options, @mutable_options ]
+    end
+
+    def key?(name)
+      ContainerChain.find( [@mutable_options, @wrapped_options], name )
+    end
+
+
+    def keys
+      @mutable_options.keys + @wrapped_options.keys # FIXME.
+    end
+
+
+
+    # TODO: maybe we shouldn't allow to_hash from context?
+    # TODO: massive performance bottleneck. also, we could already "know" here what keys the
+    # transformation wants.
+    # FIXME: ToKeywordArguments()
+    def to_hash
+      {}.tap do |hash|
+        # 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
+
+    # FIXME
+      # TODO: rename Context::Hash::Immutable
+      class Immutable
+        def initialize(hash)
+          @hash = hash
+        end
+
+        def [](key)
+          @hash[key]
+        end
+
+        def to_hash # DISCUSS: where do we call this?
+          @hash.to_hash # FIXME: should we do this?
+        end
+
+        def key?(key)
+          @hash.key?(key)
+        end
+
+        def merge(hash)
+          @hash.merge(hash)
+        end
+
+        def keys
+          @hash.keys
+        end
+
+        # DISCUSS: raise in #[]=
+        # each
+        # TODO: Skill could inherit
+      end
+  end
+
+  def self.Context(wrapped_options, mutable_options={})
+    Context.new(wrapped_options, mutable_options)
+  end
+end # Trailblazer

data/lib/trailblazer/option.rb

@@ -0,0 +1,78 @@
+module Trailblazer
+  # @note This might go to trailblazer-args along with `Context` at some point.
+  def self.Option(proc)
+    Option.build(Option, proc)
+  end
+
+  class Option
+    # Generic builder for a callable "option".
+    # @param call_implementation [Class, Module] implements the process of calling the proc
+    #   while passing arguments/options to it in a specific style (e.g. kw args, step interface).
+    # @return [Proc] when called, this proc will evaluate its option (at run-time).
+    def self.build(call_implementation, proc)
+      if proc.is_a? Symbol
+        ->(*args) { call_implementation.evaluate_method(proc, *args) }
+      else
+        ->(*args) { call_implementation.evaluate_callable(proc, *args) }
+      end
+    end
+
+    # A call implementation invoking `proc.(*args)` and plainly forwarding all arguments.
+    # Override this for your own step strategy (see KW#call!).
+    # @private
+    def self.call!(proc, *args)
+      proc.(*args)
+    end
+
+    # Note that both #evaluate_callable and #evaluate_method drop most of the args.
+    # If you need those, override this class.
+    # @private
+    def self.evaluate_callable(proc, *args, **flow_options)
+      call!(proc, *args)
+    end
+
+    # Make the context's instance method a "lambda" and reuse #call!.
+    # @private
+    def self.evaluate_method(proc, *args, exec_context:raise, **flow_options)
+      call!(exec_context.method(proc), *args)
+    end
+
+    # Returns a {Proc} that, when called, invokes the `proc` argument with keyword arguments.
+    # This is known as "step (call) interface".
+    #
+    # This is commonly used by `Operation::step` to wrap the argument and make it
+    # callable in the circuit.
+    #
+    #   my_proc = ->(options, **kws) { options["i got called"] = true }
+    #   task    = Trailblazer::Option::KW(my_proc)
+    #   task.(options = {})
+    #   options["i got called"] #=> true
+    #
+    # Alternatively, you can pass a symbol and an `:exec_context`.
+    #
+    #   my_proc = :some_method
+    #   task    = Trailblazer::Option::KW(my_proc)
+    #
+    #   class A
+    #     def some_method(options, **kws)
+    #       options["i got called"] = true
+    #     end
+    #   end
+    #
+    #   task.(options = {}, exec_context: A.new)
+    #   options["i got called"] #=> true
+    def self.KW(proc)
+      Option.build(KW, proc)
+    end
+
+    # TODO: It would be cool if call! was typed and had `options SymbolizedHash` or something.
+    class KW < Option
+      # A different call implementation that calls `proc` with a "step interface".
+      #   your_code.(options, **options)
+      # @private
+      def self.call!(proc, options, *)
+        proc.(options, **options.to_hash) # Step interface: (options, **)
+      end
+    end
+  end
+end

data/trailblazer-activity.gemspec

@@ -0,0 +1,29 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'trailblazer/activity/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "trailblazer-activity"
+  spec.version       = Trailblazer::Activity::VERSION
+  spec.authors       = ["Nick Sutterer"]
+  spec.email         = ["apotonick@gmail.com"]
+
+  spec.summary       = %q{The main element for Trailblazer's BPMN-compliant workflows.}
+  spec.description   = %q{The main element for Trailblazer's BPMN-compliant workflows. Used in Trailblazer's Operation to implement the Railway.}
+  spec.homepage      = "http://trailblazer.to/gems/workflow"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+
+  spec.add_dependency "hirb"
+
+  spec.required_ruby_version = '>= 2.0.0'
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: trailblazer-activity
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick Sutterer
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.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: The main element for Trailblazer's BPMN-compliant workflows. Used in
+  Trailblazer's Operation to implement the Railway.
+email:
+- apotonick@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CHANGES.md
+- Gemfile
+- README.md
+- Rakefile
+- lib/trailblazer-activity.rb
+- lib/trailblazer/activity.rb
+- lib/trailblazer/activity/graph.rb
+- lib/trailblazer/activity/nested.rb
+- lib/trailblazer/activity/version.rb
+- lib/trailblazer/circuit.rb
+- lib/trailblazer/circuit/present.rb
+- lib/trailblazer/circuit/testing.rb
+- lib/trailblazer/circuit/trace.rb
+- lib/trailblazer/circuit/wrap.rb
+- lib/trailblazer/container_chain.rb
+- lib/trailblazer/context.rb
+- lib/trailblazer/option.rb
+- trailblazer-activity.gemspec
+homepage: http://trailblazer.to/gems/workflow
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: The main element for Trailblazer's BPMN-compliant workflows.
+test_files: []