trailblazer-activity 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b95866eb764a602c8c23da32240f56751f5c5d0c
-  data.tar.gz: a12906e1f9767165094a8aec5d5e41602aab56de
+  metadata.gz: 767263f9c44b98ac587ae990b3feed3ac74f11ed
+  data.tar.gz: 0ef9c2e37f99170067b35ee8296705459bf9a9df
 SHA512:
-  metadata.gz: f3c00456958955cef5d4b9ee5f1368c6bf63a87ee43c20e379b6bccddd07d93658fbb748ba340c5ee511ffe6cee166bb4a171ced1f2fd15165d6cd42faa5053f
-  data.tar.gz: 3c4ea47c6520058588ba35763d0d49d9bd91cf8c52378e6f9fb0c7f65ffee53a80410eba2e1039480029c2192e832c5ea3e657f01d045849d05c253a21090ecc
+  metadata.gz: 7e6a9385a56bbbae8747836e5946c3d6fb8966fc50377ec4fc55c5ffb6324a8a435b8bdbbec3fa5f107f32d76410cc556a795885839b67e14fdef9b9e320e023
+  data.tar.gz: f6ffca410ecc638323d98ac4f2005491431faf3656f914984834ec1e14d4e12b8be516617404feb6b4fcf391cab4cb3849b6ac4f871b85fd15987ac7cf344c82

data/README.md

@@ -8,9 +8,7 @@ Circuit refrains from implementing deciders. The decisions are encoded in the ou
 
 `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 %}
+> 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.
 
 ## Installation
 
@@ -26,7 +24,7 @@ The `trailblazer-circuit` gem is often just called the `circuit` gem. It ships w
 
 The following diagram illustrates a common use-case for `circuit`, the task of publishing a blog post.
 
-<img src="/images/diagrams/blog-bpmn1.png">
+<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.
 
@@ -38,7 +36,17 @@ Your job is solely to implement the tasks and deciders put into this activity -
 
 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 }}
+```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 `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.
 
@@ -48,7 +56,14 @@ This defines the control flow - the next step is to actually implement the tasks
 
 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 }}
+```ruby
+module Blog
+  Write = ->(direction, options, *flow) do
+    options[:content] = options[:content].strip
+    [ Circuit::Right, options, *flow ]
+  end
+end
+```
 
 It receives all arguments returned from the task run before. This means a task should return everything it receives.
 
@@ -58,19 +73,27 @@ The first return value is crucial: it dictates what will be the next step when e
 
 For example, the `SpellCheck` task needs to decide which route to take.
 
-{{ "test/docs/activity_test.rb:spell:../trailblazer-circuit" | tsnippet }}
+```ruby
+SpellCheck = ->(direction, options, *flow) do
+  direction = SpellChecker.error_count(options[:content]) ? Circuit::Right : Circuit::Left
+  [ direction, options, *flow ]
+end
+```
 
 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 %}
+> You can use any object as a direction signal and return it, as long as it's defined in the circuit.
 
 ## 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 }}
+```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]`.
 
@@ -78,7 +101,10 @@ All options are passed straight to the first task, which in turn has to make sur
 
 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 }}
+```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.
 
@@ -86,25 +112,45 @@ As opposed to higher abstractions such as `Operation`, it is completely up to th
 
 For debugging or simply understanding the flows of circuits, you can use tracing.
 
-{{ "test/docs/activity_test.rb:trace-act:../trailblazer-circuit" | tsnippet }}
+```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 }
+  }
+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.
 
-{{ "test/docs/activity_test.rb:trace-call:../trailblazer-circuit" | tsnippet }}
+```ruby
+stack, _ = Circuit::Trace.( activity,
+  nil,
+  { content: "Let's start writing" }
+)
+```
 
 The `stack` can then be passed to a presenter.
 
-{{ "test/docs/activity_test.rb:trace-res:../trailblazer-circuit" | tsnippet }}
+```
+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.
 
-{% 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 %}
+> 🌅 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.
 
 ## Event
 
@@ -114,4 +160,4 @@ Also, more options will make debugging of complex, nested workflows easier.
 
 ## 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.
+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.

data/lib/trailblazer/activity.rb

@@ -1,10 +1,6 @@
-require "trailblazer/activity/version"
-
 require "trailblazer/circuit"
-require "trailblazer/circuit/trace"
-require "trailblazer/circuit/present"
-require "trailblazer/circuit/wrap"
 
+# TODO: move to separate gem.
 require "trailblazer/option"
 require "trailblazer/context"
 require "trailblazer/container_chain"
@@ -12,8 +8,12 @@ require "trailblazer/container_chain"
 module Trailblazer
   class Activity
 
+  require "trailblazer/activity/version"
   require "trailblazer/activity/graph"
   require "trailblazer/activity/nested"
+  require "trailblazer/activity/trace"
+  require "trailblazer/activity/present"
+  require "trailblazer/activity/wrap"
 
     # Only way to build an Activity.
     def self.from_wirings(wirings, &block)

data/lib/trailblazer/activity/graph.rb

@@ -1,5 +1,3 @@
-require "forwardable"
-
 module Trailblazer
   # Note that Graph is a superset of a real directed graph. For instance, it might contain detached nodes.
   # == Design

data/lib/trailblazer/{circuit → activity}/present.rb

@@ -1,7 +1,7 @@
 require "hirb"
 
 module Trailblazer
-  class Circuit
+  class Activity
     module Trace
       # TODO:
       # * Struct for debug_item

data/lib/trailblazer/{circuit → activity}/trace.rb

@@ -1,10 +1,10 @@
 module Trailblazer
-  class Circuit
+  class Activity
     # 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.
+    #   stack, _ = Trailblazer::Activity::Trace.(activity, activity[:Start], { id: 1 })
+    #   puts Trailblazer::Activity::Present.tree(stack) # renders the trail.
     #
     # Hooks into the TaskWrap.
     module Trace
@@ -31,8 +31,8 @@ module Trailblazer
       # 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 } ],
+          [ :insert_before!, "task_wrap.call_task", node: [ Trace.method(:capture_args),   id: "task_wrap.capture_args" ], outgoing: [ Circuit::Right, {} ], incoming: ->(*) { true } ],
+          [ :insert_before!, "End.default",      node: [ Trace.method(:capture_return), id: "task_wrap.capture_return" ], outgoing: [ Circuit::Right, {} ], incoming: ->(*) { true } ],
         ]
       end
 

data/lib/trailblazer/activity/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Activity
-    VERSION = "0.1.4"
+    VERSION = "0.1.5"
   end
 end

data/lib/trailblazer/{circuit → activity}/wrap.rb

@@ -1,6 +1,6 @@
-class Trailblazer::Circuit
+class Trailblazer::Activity
   module Wrap
-    # The runner is passed into Circuit#call( runner: Runner ) and is called for every task in the circuit.
+    # The runner is passed into Activity#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.
@@ -69,7 +69,7 @@ class Trailblazer::Circuit
     #   |-- Trace.capture_return [optional]
     #   |-- End
 
-    # Activity = Trailblazer::Circuit::Activity({ id: "task.wrap" }, end: { default: End.new(:default) }) do |act|
+    # Activity = Trailblazer::Activity::Activity({ id: "task.wrap" }, end: { default: End.new(:default) }) do |act|
     #   {
     #     act[:Start] => { Right => Call }, # see Wrap::call_task
     #     Call        => { Right => act[:End] },
@@ -79,8 +79,8 @@ class Trailblazer::Circuit
     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 } ]
+          [ :attach!, target: [ 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 } ]
         ]
       )
     end

data/lib/trailblazer/circuit/testing.rb

@@ -1,3 +1,5 @@
+# TODO: remove or move.
+
 module MiniTest::Assertions
   def assert_activity_inspect(text, subject)
     Trailblazer::Circuit::ActivityInspect(subject).must_equal text

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-03 00:00:00.000000000 Z
+date: 2017-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hirb
@@ -98,12 +98,12 @@ files:
 - lib/trailblazer/activity.rb
 - lib/trailblazer/activity/graph.rb
 - lib/trailblazer/activity/nested.rb
+- lib/trailblazer/activity/present.rb
+- lib/trailblazer/activity/trace.rb
 - lib/trailblazer/activity/version.rb
+- lib/trailblazer/activity/wrap.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