trailblazer-circuit 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a7e34849fb98696e6c453bbe8177d90b3932ecd
+  data.tar.gz: 5c2d5ab3e575f380fda9f2976bddd77d2a5b9fb1
+SHA512:
+  metadata.gz: 9e64cefc10dfc6606ebe9be18cc918145ba4b1a4a62854b35a00e97b0dc26233a85d81e39b96f0534dc469f763c6796618b1350480bea30ec566f3c1a45ef1f1
+  data.tar.gz: c71327201a57cddb155d70c5cb6e1bbb67daf040a988be09045831c2e93900e05072689f564ad0de1a1a6eafc837d4f5a956a269259f5fe09f9fc1b08684fdf0

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,3 @@
+# 0.0.1
+
+* First release into an unsuspecting world. 🚀

data/Gemfile

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

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/circuit/activity.rb

@@ -0,0 +1,60 @@
+module Trailblazer
+  class Circuit
+    # This is a code structure to encapsulate the circuit execution behavior and the
+    # start, intermediate and end events, within a "physical" business process.
+    #
+    #   activity[:Start]
+    #   activity.()
+    #   activity.values
+    Activity = Struct.new(:circuit, :events) do
+      def [](*args)
+        events[*args]
+      end
+
+      def call(*args, &block)
+        circuit.(*args, &block)
+      end
+    end
+
+    # DSL
+    #  Conveniently build an Activity with Circuit instance and
+    # all its signals/events.
+    def self.Activity(name=:default, events={}, end_events=nil, implementation=false, &block)
+      # default events:
+      start   = events[:start] || { default: Start.new(:default) }
+      _end    = events[:end]   || { default: End.new(:default) }
+
+      events = { start: start }.merge(events)
+      events = { end:   _end  }.merge(events)
+
+      end_events ||= _end.values
+
+      evts = Events(events)
+      circuit = Circuit(name, evts, end_events, &block)
+
+      # DISCUSS: remove this!
+      circuit = implementation.(circuit) if implementation
+
+      Activity.new(circuit, evts)
+    end
+
+    def self.Circuit(name=:default, events, end_events)
+      Circuit.new(yield(events), end_events, name)
+    end
+
+    # DSL
+    #   events[:Start]
+    #
+    # :private:
+    def self.Events(events)
+      evts = Struct.new(*events.keys) do # [Start, End, Resume]
+        def [](event, name=:default)
+          cfg = super(event.downcase)
+          cfg[name] or raise "[Circuit] Event `#{event}.#{name} unknown."
+        end
+      end
+
+      evts.new(*events.values)
+    end
+  end
+end

data/lib/trailblazer/circuit/alter.rb

@@ -0,0 +1,49 @@
+module Trailblazer
+  class Circuit::Activity
+    # Find all `direction` connections TO <old_task> and rewire them to new_task,
+    # then connect new to old with `direction`.
+    def self.Before(activity, old_task, new_task, direction:raise, **kws)
+      Rewrite(activity, **kws) do |new_map|
+        cfg = new_map.find_all { |act, outputs| outputs[direction]==old_task }
+        # rewire old line to new task.
+        cfg.each { |(activity, outputs)| outputs[direction] = new_task }
+        # connect new_task --> old_task.
+        new_map[new_task] = { direction => old_task }
+      end
+    end
+
+    def self.Connect(activity, from, to, direction:raise)
+      Rewrite(activity) do |new_map|
+        new_map[from][direction] = to
+      end
+    end
+
+    # Deep-clones an Activity's circuit and allows to alter its map by yielding it.
+    #
+    #   activity = Circuit::Activity::Rewrite(activity) do |map, evt|
+    #     map[some_task] = { Circuit::Right => evt[:End] }
+    #   end
+    #
+    # You can only add events as they might already be in use in the existing map.
+    #
+    # :private:
+    def self.Rewrite(activity, debug:{}, events:{})
+      # decompose Activity and Circuit.
+      circuit, original_events = activity.values
+      map, end_events, original_debug  = circuit.to_fields
+
+      original_events = original_events.to_h
+      events.each { |k, v| original_events[k] = (original_events[k] || {}).merge(v) }
+
+      # events = events.to_h.merge(added_events) # add new events.
+      debug  = original_debug.to_h.merge(debug) # add new events.
+
+      new_map = {} # deep-dup.
+      map.each { |act, outputs| new_map[act] = outputs.dup }
+
+      # recompose to an Activity.
+      # new_map is mutable.
+      Circuit::Activity(debug, original_events) { |evts| yield(new_map, evts); new_map }
+    end
+  end
+end

data/lib/trailblazer/circuit/present.rb

@@ -0,0 +1,70 @@
+module Trailblazer
+  class Circuit
+    class Trace
+      # TODO:
+      # * Struct for debug_item
+      module Present
+        FREE_SPACE = (' ' * 3).freeze
+        module_function
+
+        def tree(stack, level = 1)
+          stack.each do |debug_item|
+            puts FREE_SPACE * level + delimeter(stack, debug_item) + '--' + '> ' + to_name(debug_item) + to_options(debug_item)
+
+            if debug_item.last.is_a?(Array)
+              tree(debug_item.last, level + 1)
+            end
+          end
+        end
+
+        # private
+
+        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
+
+        def delimeter(stack, debug_item)
+          if stack.last == debug_item || debug_item.last.is_a?(Array)
+            '`'
+          else
+            '|'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/circuit/task.rb

@@ -0,0 +1,47 @@
+class Trailblazer::Circuit
+  module Task
+    module_function
+    # Convenience functions for tasks. Totally optional.
+
+    # Task::Binary aka "step"
+    # Step is binary task: true=> Right, false=>Left.
+    # Step call proc.(options, flow_options)
+    # Step is supposed to run Option::KW, so `step` should be Option::KW.
+    #
+    # Returns task to call the proc with (options, flow_options), omitting `direction`.
+    # When called, the task always returns a direction signal.
+    def Binary(step, on_true=Right, on_false=Left)
+      ->(direction, *args) do # Activity/Task interface.
+        [ step.(direction, *args) ? on_true : on_false, *args ] # <=> Activity/Task interface
+      end
+    end
+
+    module Args
+      module_function
+      # :private:
+      # Return task to call the proc with keyword arguments. Ruby >= 2.0.
+      # This is used by `Operation::step` to wrap the argument and make it
+      # callable in the circuit.
+      def KW(proc)
+        if proc.is_a? Symbol
+          ->(*args) { meth!(proc, *args) } # Activity interface
+        else
+          ->(*args) { call!(proc, *args) } # Activity interface
+        end
+      end
+
+      # DISCUSS: standardize tmp_options.
+      # Calls `proc` with a step interface.
+      def call!(proc, direction, options, flow_options, tmp_options={})
+        # proc.(options, **options.to_hash(tmp_options))
+        proc.(options, **options.to_hash)
+      end
+
+      # 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)
+      end
+    end
+  end
+end

data/lib/trailblazer/circuit/trace.rb

@@ -0,0 +1,19 @@
+module Trailblazer
+  class Circuit
+    #   direction, result = circuit.( circuit[:Start], options, runner: Circuit::Trace.new, stack: [] )
+
+    # Every `activity.call` is considered nested
+    class Trace
+      def call(activity, direction, args, debug:raise, stack:raise, **flow_options)
+        activity_name, _ = debug[activity]
+        activity_name ||= activity
+
+        Run.(activity, direction, args, stack:[], **flow_options).tap do |direction, outgoing_options, **flow_options| # TODO: USE KW ARG FOR :stack
+          # raise activity_name.inspect if flow_options[:stack].nil? # TODO: remove this.
+          # TODO: fix the inspect, we need a snapshot, deep-nested.
+          stack << [activity_name, activity, direction, outgoing_options, outgoing_options.inspect, flow_options[:stack].any? ? flow_options[:stack] : nil ]
+        end
+      end
+    end # Trace
+  end
+end

data/lib/trailblazer/circuit/version.rb

@@ -0,0 +1,5 @@
+module Trailblazer
+  class Circuit
+    VERSION = "0.0.1"
+  end
+end

data/lib/trailblazer/circuit.rb

@@ -0,0 +1,125 @@
+require "trailblazer/circuit/version"
+
+# Start, Suspend, Resume, End can return something other than the next symbol?
+# Nested could replace options with local options
+
+
+module Trailblazer
+  # Circuit executes ties, finds next step and stops when reaching a Stop signal (or derived from).
+  #
+  #   circuit.()
+  #
+  # Cicuit doesn't know anything about contexts, options, etc. tasks: what steps follows? call it!
+	class Circuit
+    def initialize(map, stop_events, name)
+      @name        = name
+      @map         = map
+      @stop_events = stop_events
+    end
+
+        # the idea is to always have a breakpoint state that has only one outgoing edge. we then start from
+    # that vertix. it's up to the caller to test if the "persisted" state == requested state.
+    # activity: where to start
+    Run = ->(activity, direction, *args) { activity.(direction, *args) }
+
+    def call(activity, args, runner: Run, **o) # DISCUSS: should start activity be @activity and we omit it here?
+      # TODO: args
+      direction = nil
+
+      loop do
+        # puts "[#{@name}]. #{activity}"
+        direction, args  = runner.(activity, direction, args, runner: runner, debug: @name, **o)
+
+        # last task in a process is always either its Stop or its Suspend.
+        return [ direction, args, **o ] if @stop_events.include?(activity)
+
+        activity = next_for(activity, direction) do |next_activity, in_map|
+          # puts "[#{@name}]...`#{activity}`[#{direction}] => #{next_activity}"
+
+          raise IllegalInputError.new("#{@name} #{activity}") unless in_map
+          # last activity didn't emit knowns signal, it's not connected.
+          raise IllegalOutputSignalError.new("from #{@name};;#{activity}"+ direction.inspect) unless next_activity
+        end
+      end
+    end
+
+    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
+
+    def Right
+      Right
+    end
+
+    def Left
+      Left
+    end
+
+    class End
+      def initialize(name, options={})
+        @name    = name
+        @options = options
+      end
+
+      def to_s
+        %{#<End: #{@name} #{@options.inspect}>}
+      end
+
+      def inspect
+        to_s
+      end
+
+      def call(direction, *args)
+        [ self, *args ]
+      end
+    end
+
+    class Start < End
+      def call(direction, *args)
+        [Right, *args]
+      end
+
+      def to_s
+        %{#<Start: #{@name} #{@options.inspect}>}
+      end
+    end
+
+    # # run a nested process.
+    def self.Nested(activity, start_with=activity[:Start])
+      # TODO: currently, we only support only 1 start event. you can use multiple in BPMN.
+      # "The BPMN standard allows for multiple start and end events to be used at the same process level. "
+      ->(start_at, options, *args) {
+         # puts "@@@@@ #{options.inspect}"
+        activity.(start_with, options, *args)
+      }
+    end
+
+    class Direction; end
+		class Right < Direction; end
+    class Left < Direction;  end
+  end
+end
+
+require "trailblazer/circuit/activity"
+require "trailblazer/circuit/task"
+require "trailblazer/circuit/alter"
+require "trailblazer/circuit/trace"

data/lib/trailblazer-circuit.rb

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

data/trailblazer-circuit.gemspec

@@ -0,0 +1,28 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'trailblazer/circuit/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "trailblazer-circuit"
+  spec.version       = Trailblazer::Circuit::VERSION
+  spec.authors       = ["Nick Sutterer"]
+  spec.email         = ["apotonick@gmail.com"]
+
+  spec.summary       = %q{BPMN-compliant workflows or state machines.}
+  spec.description   = %q{BPMN-compliant workflows or state machines. 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_development_dependency "pry"
+
+  spec.required_ruby_version = '>= 2.0.0'
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: trailblazer-circuit
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nick Sutterer
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-04-27 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: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  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:
+- apotonick@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CHANGES.md
+- Gemfile
+- README.md
+- Rakefile
+- lib/trailblazer-circuit.rb
+- lib/trailblazer/circuit.rb
+- lib/trailblazer/circuit/activity.rb
+- lib/trailblazer/circuit/alter.rb
+- lib/trailblazer/circuit/present.rb
+- lib/trailblazer/circuit/task.rb
+- lib/trailblazer/circuit/trace.rb
+- lib/trailblazer/circuit/version.rb
+- trailblazer-circuit.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.5.2
+signing_key: 
+specification_version: 4
+summary: BPMN-compliant workflows or state machines.
+test_files: []