trailblazer-activity-dsl-linear 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b19b59ebf1ee26717edb3a9d5e797eec4a4796bc567bdc21ee92ba13fd4a04
-  data.tar.gz: 782a283ddf31bdebc6575323c7fcdae0958f301802793c5d193b2c42494f1076
+  metadata.gz: fb92b49935156ee66dcf347cfe7b803cc3be0222ebf84ee676923e48bfb20ea2
+  data.tar.gz: 802be96cb11290483f4b326d9251933b7783f230dbf8cf6f6bf6781b64bb6a4e
 SHA512:
-  metadata.gz: bc097663260f945545c68f4f7f9c8e6023631b5ff67552ec0baf0ee39acdf3b6c8517c31b31aecadcaf8d61b09e04ee31c033d0ae80b5019f5cc0b3392da64b1
-  data.tar.gz: cafc5c1e5dd50768986066988efac3b4fcbc37a5da13e10b2ca542fec63eb7193dee59a6379437bdd3ac69ea3a2e492065c4c076755e58432b11461e215fb01b
+  metadata.gz: 3b408a672b9ad2ccbd09352ede7f47938f3506c687a7204ac762da44abd949a9788f61fd7dce096e41c222dafcbc6ee67c4ee304aede850f7f7ffcae90b42137
+  data.tar.gz: 4f13684ec5f770e321f713747460b095033ff39e2c1e9b67f9afc82ac69bec057d4f5e32f4342d88fb763344be9f710aa42e04026fcc44dd824d66a7517e4c69

data/CHANGES.md

@@ -1,3 +1,30 @@
+# 0.3.0
+
+* Fix circuit interface callable to make `step task: :instance_method` use circuit signature.
+
+# 0.2.9
+
+* The `Path()` helper, when used with `:end_task` will now automatically _append_ the end task (or terminus) to `End.success`.
+  It used to be placed straight after the last path's element, which made it hard to later insert more steps into that very path.
+
+# 0.2.8
+
+* Add `:inherit` option so `step` can override an existing step while inheriting the original `:extensions` and `:connections` (which are the `Outputs`). This is great to customize "template" activities.
+* Add `Track(:color, wrap_around: true)` option and `Search::WrapAround` so you can find a certain track color (or the beginning of a Path) even when the path was positioned before the actual step in the `Sequence`.
+  Note that this feature is still experimental and might get removed.
+
+# 0.2.7
+
+* `Did you mean ?` suggestions on Linear::Sequence::IndexError.
+* Introduce `Linear::Helper` module for strategy extensions in third-party gems.
+* Convenient way to patch Subprocess itself using `patch` option.
+* Allow multiple `Path()` macro per step.
+* Small fix for defining instance methods as steps using circuit interface.
+
+# 0.2.6
+
+* Added `@fields` to `Linear::State` to save arbitrary data on the activity/strategy level.
+
 # 0.2.5
 
 * Patching now requires the [`:patch` option for `Subprocess`](http://2019.trailblazer.to/2.1/docs/activity.html#activity-dsl-options-patching

data/Gemfile

@@ -10,3 +10,4 @@ gem "rubocop", require: false
 # gem "trailblazer-context", path: "../trailblazer-context"
 # gem "trailblazer-developer", path: "../trailblazer-developer"
 # gem "trailblazer-activity", path: "../trailblazer-activity"
+# gem "trailblazer-activity", path: "../circuit"

data/README.md

@@ -1,29 +1,93 @@
-# Trailblazer-Activity-DSL-Linear
+# Activity-DSL-Linear
 
-_The popular Railway/Fasttrack DSL for building activities._
+The `activity-dsl-linear` gem brings:
+- [Path](https://2019.trailblazer.to/2.1/docs/activity.html#activity-strategy-path)
+- [Railway](https://2019.trailblazer.to/2.1/docs/activity.html#activity-strategy-railway)
+- [Fasttrack](https://2019.trailblazer.to/2.1/docs/activity.html#activity-strategy-fasttrack)
+  
+DSLs strategies for buildig activities. It is build around [`activity`](https://github.com/trailblazer/trailblazer-activity) gem.
 
+Please find the [full documentation on the Trailblazer website](https://2019.trailblazer.to/2.1/docs/activity.html#activity-strategy). [Note that the docs are WIP.]
 
-# Overview
+## Example
 
-This gem allows creating activities by leveraging a handy DSL. Built-in are the strategies `Path`, the popular `Railway` and `FastTrack`. The latter is used for `Trailblazer::Operation`.
+The `activity-dsl-linear` gem provides three default patterns to model processes: `Path`, `Railway` and `FastTrack`. Here's an example of what a railway activity could look like, along with some more complex connections (you can read more about Railway strategy in the [docs](https://2019.trailblazer.to/2.1/docs/activity.html#activity-strategy-railway)).
 
-Note that you don't need to use the DSL. You can simply create a InIm structure yourself, or use our online editor.
+```ruby
+require "trailblazer-activity"
+require "trailblazer-activity-dsl-linear"
 
-Full documentation can be found here: trailblazer.to/2.1/#dsl-linear
+class Memo::Update < Trailblazer::Activity::Railway
+  # here goes your business logic
+  #
+  def find_model(ctx, id:, **)
+    ctx[:model] = Memo.find_by(id: id)
+  end
 
-## Normalizer
+  def validate(ctx, params:, **)
+    return true if params[:body].is_a?(String) && params[:body].size > 10
+    ctx[:errors] = "body not long enough"
+    false
+  end
 
-Normalizers are itself linear activities (or "pipelines") that compute all options necessary for `DSL.insert_task`.
-For example, `FailFast.normalizer` will process your options such as `fast_track: true` and add necessary connections and outputs.
+  def save(ctx, model:, params:, **)
+    model.update_attributes(params)
+  end
 
-The different "step types" (think of `step`, `fail`, and `pass`) are again implemented as different normalizers that "inherit" generic steps.
+  def log_error(ctx, params:, **)
+    ctx[:log] = "Some idiot wrote #{params.inspect}"
+  end
 
+  # here comes the DSL describing the layout of the activity
+  #
+  step :find_model
+  step :validate, Output(:failure) => End(:validation_error)
+  step :save
+  fail :log_error
+end
+```
 
-`:sequence_insert`
-`:connections` are callables to find the connecting tasks
+Visually, this would translate to the following circuit.
+
+<img src="http://trailblazer.to/images/2.1/activity-readme-example.png">
+
+You can run the activity by invoking its `call` method.
+
+```ruby
+ctx = { id: 1, params: { body: "Awesome!" } }
+
+signal, (ctx, *) = Update.( [ctx, {}] )
+
+pp ctx #=>
+{:id=>1,
+ :params=>{:body=>"Awesome!"},
+ :model=>#<Memo body=nil>,
+ :errors=>"body not long enough"}
+
+pp signal #=> #<struct Trailblazer::Activity::End semantic=:validation_error>
+```
+
+With Activity, modeling business processes turns out to be ridiculously simple: You define what should happen and when, and Trailblazer makes sure _that_ it happens.
+
+## Features
+
+* Activities can model any process with arbitrary flow and connections.
+* Nesting and compositions are allowed and encouraged (via Trailblazer's [`dsl-linear`](https://github.com/trailblazer/trailblazer-activity-dsl-linear) gem).
+* Different step interfaces, manual processing of DSL options, etc is all possible.
+* Steps can be any kind of callable objects.
+* Tracing! (via Trailblazer's [`developer`](https://github.com/trailblazer/trailblazer-developer) gem)
+
+## Operation
+
+Trailblazer's [`Operation`](https://2019.trailblazer.to/2.1/docs/operation.html#operation-overview) internally uses an activity to model the processes.
+
+## Workflow
+Activities can be formed into bigger compounds and using workflow, you can build long-running processes such as a moderated blog post or a parcel delivery. Also, you don't have to use the DSL but can use the [`editor`](https://2019.trailblazer.to/2.1/docs/pro.html#pro-editor)instead(cool for more complex, long-running flows). Here comes a sample screenshot.
+
+<img src="http://2019.trailblazer.to/2.1/dist/img/flow.png">
 
 ## License
 
 © Copyright 2018, Trailblazer GmbH
 
-Licensed under the LGPLv3 license. We also offer a [commercial-friendly license](http://trailblazer.to/pro).
+Licensed under the LGPLv3 license. We also offer a commercial-friendly [license](https://2019.trailblazer.to/2.1/docs/pro.html#pro-license).

data/lib/trailblazer/activity/dsl/linear.rb

@@ -37,7 +37,17 @@ class Trailblazer::Activity
           sequence
         end
 
-        class IndexError < IndexError; end
+        class IndexError < IndexError
+          attr_reader :step_id
+
+          def initialize(sequence, step_id)
+            @step_id  = step_id
+            valid_ids = sequence.collect{ |row| row[3][:id].inspect }
+
+            message = %{#{@step_id.inspect} is not a valid step ID. Did you mean any of these ?\n#{valid_ids.join("\n")}}
+            super(message)
+          end
+        end
       end
 
       # Sequence
@@ -48,7 +58,21 @@ class Trailblazer::Activity
         # Note that we only go forward, no back-references are done here.
         def Forward(output, target_color)
           ->(sequence, me) do
-            target_seq_row = sequence[sequence.index(me)+1..-1].find { |seq_row| seq_row[0] == target_color }
+            target_seq_row = find_in_range(sequence[sequence.index(me)+1..-1], target_color)
+
+            return output, target_seq_row
+          end
+        end
+
+        # Tries to find a track colored step by doing a Forward-search, first, then wraps around going
+        # through all steps from sequence start to self.
+        def WrapAround(output, target_color)
+          ->(sequence, me) do
+            my_index      = sequence.index(me)
+            # First, try all elements after me, then go through the elements preceding myself.
+            wrapped_range = sequence[my_index+1..-1] + sequence[0..my_index-1]
+
+            target_seq_row = find_in_range(wrapped_range, target_color)
 
             return output, target_seq_row
           end
@@ -69,6 +93,11 @@ class Trailblazer::Activity
             return output, target_seq_row
           end
         end
+
+        # @private
+        def find_in_range(range, target_color)
+          target_seq_row = range.find { |seq_row| seq_row[0] == target_color }
+        end
       end # Search
 
       # Sequence
@@ -111,7 +140,7 @@ class Trailblazer::Activity
         end
 
         def find(sequence, insert_id)
-          index = find_index(sequence, insert_id) or raise Sequence::IndexError.new(insert_id.inspect)
+          index = find_index(sequence, insert_id) or raise Sequence::IndexError.new(sequence, insert_id)
 
           return index, sequence.clone # Ruby doesn't have an easy way to avoid mutating arrays :(
         end
@@ -157,10 +186,10 @@ end
 
 require "trailblazer/activity/dsl/linear/normalizer"
 require "trailblazer/activity/dsl/linear/state"
+require "trailblazer/activity/dsl/linear/helper"
 require "trailblazer/activity/dsl/linear/strategy"
 require "trailblazer/activity/dsl/linear/compiler"
 require "trailblazer/activity/path"
 require "trailblazer/activity/railway"
 require "trailblazer/activity/fast_track"
-require "trailblazer/activity/dsl/linear/helper" # FIXME
 require "trailblazer/activity/dsl/linear/variable_mapping"

data/lib/trailblazer/activity/dsl/linear/helper.rb

@@ -1,125 +1,150 @@
 module Trailblazer
   class Activity
-    module DSL::Linear # TODO: rename!
-      # @api private
-      OutputSemantic = Struct.new(:value)
-      Id             = Struct.new(:value)
-      Track          = Struct.new(:color, :adds)
-      Extension      = Struct.new(:callable) do
-        def call(*args, &block)
-          callable.(*args, &block)
-        end
-      end
-
-      # Shortcut functions for the DSL.
-      module_function
-
-      #   Output( Left, :failure )
-      #   Output( :failure ) #=> Output::Semantic
-      def Output(signal, semantic=nil)
-        return OutputSemantic.new(signal) if semantic.nil?
-
-        Activity.Output(signal, semantic)
-      end
-
-      def End(semantic)
-        Activity.End(semantic)
-      end
-
-      def end_id(_end)
-        "End.#{_end.to_h[:semantic]}" # TODO: use everywhere
-      end
-
-      def Track(color)
-        Track.new(color, []).freeze
-      end
-
-      def Id(id)
-        Id.new(id).freeze
-      end
-
-      def Path(track_color: "track_#{rand}", end_id:"path_end_#{rand}", connect_to:nil, **options, &block)
-        # DISCUSS: here, we use the global normalizer and don't allow injection.
-        state = Activity::Path::DSL::State.new(Activity::Path::DSL.OptionsForState(track_name: track_color, end_id: end_id, **options)) # TODO: test injecting {:normalizers}.
-
-        # seq = block.call(state) # state changes.
-        state.instance_exec(&block)
-
-        seq = state.to_h[:sequence]
-
-        _end_id =
-          if connect_to
-            end_id
-          else
-            nil
+    module DSL
+      module Linear
+        module Helper
+          # @api private
+          OutputSemantic = Struct.new(:value)
+          Id             = Struct.new(:value)
+          Track          = Struct.new(:color, :adds, :options)
+          Extension      = Struct.new(:callable) do
+            def call(*args, &block)
+              callable.(*args, &block)
+            end
+          end
+
+          def self.included(base)
+            base.extend ClassMethods
           end
 
-        seq = strip_start_and_ends(seq, end_id: _end_id) # don't cut off end unless {:connect_to} is set.
+          # Shortcut functions for the DSL.
+          module ClassMethods
+            #   Output( Left, :failure )
+            #   Output( :failure ) #=> Output::Semantic
+            def Output(signal, semantic=nil)
+              return OutputSemantic.new(signal) if semantic.nil?
+
+              Activity.Output(signal, semantic)
+            end
+
+            def End(semantic)
+              Activity.End(semantic)
+            end
+
+            def end_id(_end)
+              "End.#{_end.to_h[:semantic]}" # TODO: use everywhere
+            end
+
+            def Track(color, wrap_around: false)
+              Track.new(color, [], wrap_around: wrap_around).freeze
+            end
+
+            def Id(id)
+              Id.new(id).freeze
+            end
+
+            def Path(track_color: "track_#{rand}", end_id:"path_end_#{rand}", connect_to:nil, **options, &block)
+              # DISCUSS: here, we use the global normalizer and don't allow injection.
+              state = Activity::Path::DSL::State.new(Activity::Path::DSL.OptionsForState(track_name: track_color, end_id: end_id, **options)) # TODO: test injecting {:normalizers}.
 
-        if connect_to
-          output, _ = seq[-1][2][0].(seq, seq[-1]) # FIXME: the Forward() proc contains the row's Output, and the only current way to retrieve it is calling the search strategy. It should be Forward#to_h
+              # seq = block.call(state) # state changes.
+              state.instance_exec(&block)
 
-          searches = [Search.ById(output, connect_to.value)]
+              seq = state.to_h[:sequence]
 
-          row = seq[-1]
-          row = row[0..1] + [searches] + [row[3]] # FIXME: not mutating an array is so hard: we only want to replace the "searches" element, index 2
+              _end_id =
+                if connect_to
+                  end_id
+                else
+                  nil
+                end
 
-          seq = seq[0..-2] + [row]
-        end
+              seq = strip_start_and_ends(seq, end_id: _end_id) # don't cut off end unless {:connect_to} is set.
 
-        # Add the path before End.success - not sure this is bullet-proof.
-        adds = seq.collect do |row|
-          {
-            row:    row,
-            insert: [Insert.method(:Prepend), "End.success"]
-          }
-        end
+              if connect_to
+                output, _ = seq[-1][2][0].(seq, seq[-1]) # FIXME: the Forward() proc contains the row's Output, and the only current way to retrieve it is calling the search strategy. It should be Forward#to_h
 
-        # Connect the Output() => Track(path_track)
-        return Track.new(track_color, adds)
-      end
+                searches = [Search.ById(output, connect_to.value)]
 
-      # Computes the {:outputs} options for {activity}.
-      def Subprocess(activity, patch: {})
-        patch.each do |path, patch|
-          activity = Patch.(activity, path, patch) # TODO: test if multiple patches works!
-        end
+                row = seq[-1]
+                row = row[0..1] + [searches] + [row[3]] # FIXME: not mutating an array is so hard: we only want to replace the "searches" element, index 2
 
-        {
-          task:    activity,
-          outputs: Hash[activity.to_h[:outputs].collect { |output| [output.semantic, output] }]
-        }
-      end
+                seq = seq[0..-2] + [row]
+              end
 
-      module Patch
-        module_function
+              # Add the path elements before {End.success}.
+              # Termini (or :stop_event) are to be placed after {End.success}.
+              adds = seq.collect do |row|
+                options = row[3]
 
-        def call(activity, path, customization)
-          task_id, *path = path
+                # the terminus of the path goes _after_ {End.success} into the "end group".
+                insert_method = options[:stop_event] ? Insert.method(:Append) : Insert.method(:Prepend)
 
+                {
+                  row:    row,
+                  insert: [insert_method, "End.success"]
+                }
+              end
 
-          patch =
-            if task_id
-              segment_activity = Introspect::Graph(activity).find(task_id).task
-              patched_segment_activity = call(segment_activity, path, customization)
+              # Connect the Output() => Track(path_track)
+              return Track.new(track_color, adds, {})
+            end
+
+            # Computes the {:outputs} options for {activity}.
+            def Subprocess(activity, patch: {})
+              activity = Patch.customize(activity, options: patch)
+
+              {
+                task:    activity,
+                outputs: Hash[activity.to_h[:outputs].collect { |output| [output.semantic, output] }]
+              }
+            end
+
+            module Patch
+              module_function
+
+              def customize(activity, options:)
+                options = options.is_a?(Proc) ?
+                  { [] => options } : # hash-wrapping with empty path, for patching given activity itself
+                  options
+
+                options.each do |path, patch|
+                  activity = call(activity, path, patch) # TODO: test if multiple patches works!
+                end
 
-              # Replace the patched subprocess.
-              -> { step Subprocess(patched_segment_activity), replace: task_id, id: task_id }
-            else
-              customization # apply the *actual* patch from the Subprocess() call.
+                activity
+              end
+
+              def call(activity, path, customization)
+                task_id, *path = path
+
+                patch =
+                  if task_id
+                    segment_activity = Introspect::Graph(activity).find(task_id).task
+                    patched_segment_activity = call(segment_activity, path, customization)
+
+                    # Replace the patched subprocess.
+                    -> { step Subprocess(patched_segment_activity), replace: task_id, id: task_id }
+                  else
+                    customization # apply the *actual* patch from the Subprocess() call.
+                  end
+
+                patched_activity = Class.new(activity)
+                patched_activity.class_exec(&patch)
+                patched_activity
+              end
             end
 
-          patched_activity = Class.new(activity)
-          patched_activity.class_exec(&patch)
-          patched_activity
-        end
-      end
-
-      def normalize(options, local_keys) # TODO: test me.
-        locals  = options.reject { |key, value| ! local_keys.include?(key) }
-        foreign = options.reject { |key, value| local_keys.include?(key) }
-        return foreign, locals
-      end
-    end
-  end
+            def normalize(options, local_keys) # TODO: test me.
+              locals  = options.reject { |key, value| ! local_keys.include?(key) }
+              foreign = options.reject { |key, value| local_keys.include?(key) }
+              return foreign, locals
+            end
+          end
+        end # Helper
+
+        include Helper # Introduce Helper constants in DSL::Linear scope
+      end # Linear
+    end # DSL
+  end # Activity
 end

data/lib/trailblazer/activity/dsl/linear/normalizer.rb

@@ -20,6 +20,7 @@ module Trailblazer
               "activity.normalize_id"                   => method(:normalize_id),
               "activity.normalize_override"             => method(:normalize_override),
               "activity.wrap_task_with_step_interface"  => method(:wrap_task_with_step_interface), # last
+              "activity.inherit_option"               => method(:inherit_option),
               },
 
               Linear::Insert.method(:Append), "Start.default"
@@ -53,16 +54,26 @@ module Trailblazer
           # Specific to the "step DSL": if the first argument is a callable, wrap it in a {step_interface_builder}
           # since its interface expects the step interface, but the circuit will call it with circuit interface.
           def normalize_step_interface((ctx, flow_options), *)
-            options = ctx[:options] # either a <#task> or {} from macro
-
-            unless options.is_a?(::Hash)
-              # task = wrap_with_step_interface(task: options, step_interface_builder: ctx[:user_options][:step_interface_builder]) # TODO: make this optional with appropriate wiring.
-              task = options
-
-              ctx = ctx.merge(options: {task: task, wrap_task: true})
-            end
-
-            return Trailblazer::Activity::Right, [ctx, flow_options]
+            options = case ctx[:options]
+                      when Hash
+                        # Circuit Interface
+                        task = ctx[:options].fetch(:task)
+
+                        if task.is_a?(Symbol)
+                          # step task: :find
+                          { options: { task: Trailblazer::Option( task ) } }
+                        else
+                          # step task: Callable, ... (Subprocess, Proc, macros etc)
+                          { task: task }
+                        end
+                      else
+                        # Step Interface
+                        # step :find, ...
+                        # step Callable, ... (Method, Proc etc)
+                        { options: { task: ctx[:options], wrap_task: true } }
+                      end
+
+            return Trailblazer::Activity::Right, [ctx.merge(options), flow_options]
           end
 
           def wrap_task_with_step_interface((ctx, flow_options), **)
@@ -122,7 +133,7 @@ module Trailblazer
 
             ctx[:wirings] =
               connections.collect do |semantic, (search_strategy_builder, *search_args)|
-                output = outputs[semantic] || raise("No `#{semantic}` output found for #{outputs.inspect}")
+                output = outputs[semantic] || raise("No `#{semantic}` output found for #{ctx[:id].inspect} and outputs #{outputs.inspect}")
 
                 search_strategy_builder.( # return proc to be called when compiling Seq, e.g. {ById(output, :id)}
                   output,
@@ -157,6 +168,8 @@ module Trailblazer
                   _adds      = [add_end(cfg, magnetic_to: end_id, id: end_id)] unless end_exists
 
                   [output_to_id(ctx, output, end_id), _adds]
+                else
+                  raise cfg.inspect
                 end
 
               connections = connections.merge(new_connections)
@@ -168,8 +181,10 @@ module Trailblazer
             return Trailblazer::Activity::Right, [new_ctx, flow_options]
           end
 
-          def output_to_track(ctx, output, target)
-            {output.value => [Linear::Search.method(:Forward), target.color]}
+          def output_to_track(ctx, output, track)
+            search_strategy = track.options[:wrap_around] ? :WrapAround : :Forward
+
+            {output.value => [Linear::Search.method(search_strategy), track.color]}
           end
 
           def output_to_id(ctx, output, target)
@@ -219,9 +234,28 @@ module Trailblazer
             return Trailblazer::Activity::Right, [ctx.merge(new_ctx), flow_options]
           end
 
+          # Currently, the {:inherit} option copies over {:connections} from the original step
+          # and merges them with the (prolly) connections passed from the user.
+          def inherit_option((ctx, flow_options), *)
+            return Trailblazer::Activity::Right, [ctx, flow_options] unless ctx[:inherit]
+
+            sequence = ctx[:sequence]
+            id = ctx[:id]
+
+            index = Linear::Insert.find_index(sequence, id)
+            row   = sequence[index] # from this row we're inheriting options.
+
+            extensions = (row[3][:extensions]||[]) + (ctx[:extensions]||[]) # FIXME: DEFAULTING, FOR FUCK'S SAKE
+
+            ctx = ctx.merge(connections: row[3][:connections], extensions: extensions) # "inherit"
+
+            return Trailblazer::Activity::Right, [ctx, flow_options]
+          end
+
           # TODO: make this extendable!
           def cleanup_options((ctx, flow_options), *)
-            new_ctx = ctx.reject { |k, v| [:connections, :outputs, :end_id, :step_interface_builder, :failure_end, :track_name, :sequence].include?(k) }
+            # new_ctx = ctx.reject { |k, v| [:connections, :outputs, :end_id, :step_interface_builder, :failure_end, :track_name, :sequence].include?(k) }
+            new_ctx = ctx.reject { |k, v| [:outputs, :end_id, :step_interface_builder, :failure_end, :track_name, :sequence].include?(k) }
 
             return Trailblazer::Activity::Right, [new_ctx, flow_options]
           end

data/lib/trailblazer/activity/dsl/linear/state.rb

@@ -3,28 +3,40 @@ module Trailblazer
     module DSL
       module Linear
         # A {State} instance is kept per DSL client, which usually is a subclass of {Path}, {Railway}, etc.
+        # State doesn't have any immutable features - all write operations to it must guarantee they only replace
+        # instance variables.
+        #
+        # @private
+        #
+        # DISCUSS: why do we have this structure? It doesn't cover "immutable copying", that has to be done by its clients.
+        #          also, copy with to_h
         class State
             # remembers how to call normalizers (e.g. track_color), TaskBuilder
             # remembers sequence
-          def initialize(normalizers:, initial_sequence:, **normalizer_options)
+          def initialize(normalizers:, initial_sequence:, fields: {}.freeze, **normalizer_options)
             @normalizer         = normalizers # compiled normalizers.
             @sequence           = initial_sequence
             @normalizer_options = normalizer_options
+            @fields             = fields
           end
 
           # Called to "inherit" a state.
           def copy
-            self.class.new(normalizers: @normalizer, initial_sequence: @sequence, **@normalizer_options)
+            self.class.new(normalizers: @normalizer, initial_sequence: @sequence, fields: @fields, **@normalizer_options)
           end
 
           def to_h
-            {sequence: @sequence, normalizers: @normalizer, normalizer_options: @normalizer_options} # FIXME.
+            {sequence: @sequence, normalizers: @normalizer, normalizer_options: @normalizer_options, fields: @fields} # FIXME.
           end
 
           def update_sequence(&block)
             @sequence = yield(to_h)
           end
 
+          def update_options(fields)
+            @fields = fields
+          end
+
           # Compiles and maintains all final normalizers for a specific DSL.
           class Normalizer
             def compile_normalizer(normalizer_sequence)

data/lib/trailblazer/activity/dsl/linear/strategy.rb

@@ -1,5 +1,3 @@
-require "forwardable"
-
 module Trailblazer
   class Activity
     module DSL
@@ -29,7 +27,7 @@ module Trailblazer
             options = options.merge(dsl_track: type)
 
             # {#update_sequence} is the only way to mutate the state instance.
-            state.update_sequence do |sequence:, normalizers:, normalizer_options:|
+            state.update_sequence do |sequence:, normalizers:, normalizer_options:, fields:|
               # Compute the sequence rows.
               options = normalizers.(type, normalizer_options: normalizer_options, options: task, user_options: options.merge(sequence: sequence))
 
@@ -58,23 +56,29 @@ module Trailblazer
 
           private def forward_block(args, block)
             options = args[1]
-            if options.is_a?(Hash) # FIXME: doesn't account {task: <>} and repeats logic from Normalizer.
-              output, proxy = (options.find { |k,v| v.is_a?(BlockProxy) } or return args)
+
+            return args unless options.is_a?(Hash)
+
+              # FIXME: doesn't account {task: <>} and repeats logic from Normalizer.
+
+            # DISCUSS: THIS SHOULD BE DONE IN DSL.Path() which is stateful! the block forwarding should be the only thing happening here!
+            evaluated_options =
+            options.find_all { |k,v| v.is_a?(BlockProxy) }.collect do |output, proxy|
               shared_options = {step_interface_builder: @state.instance_variable_get(:@normalizer_options)[:step_interface_builder]} # FIXME: how do we know what to pass on and what not?
-              return args[0], options.merge(output => Linear.Path(**shared_options, **proxy.options, &block))
+
+              [output, Linear.Path(**shared_options, **proxy.options, &(proxy.block || block))] # FIXME: the || sucks.
             end
 
-            args
-          end
+            evaluated_options = Hash[evaluated_options]
 
-          extend Forwardable
-          def_delegators Linear, :Output, :End, :Track, :Id, :Subprocess
+            return args[0], options.merge(evaluated_options)
+          end
 
-          def Path(options) # we can't access {block} here, syntactically.
-            BlockProxy.new(options)
+          def Path(options, &block) # syntactically, we can't access the {do ... end} block here.
+            BlockProxy.new(options, block)
           end
 
-          BlockProxy = Struct.new(:options)
+          BlockProxy = Struct.new(:options, :block)
 
           private def merge!(activity)
             old_seq = @state.instance_variable_get(:@sequence) # TODO: fixme

data/lib/trailblazer/activity/dsl/linear/version.rb

@@ -3,7 +3,7 @@ module Trailblazer
     module Activity
       module DSL
         module Linear
-          VERSION = "0.2.5"
+          VERSION = "0.3.0"
         end
       end
     end

data/lib/trailblazer/activity/fast_track.rb

@@ -154,6 +154,7 @@ module Trailblazer
         end
       end
 
+      include Activity::DSL::Linear::Helper
       extend Activity::DSL::Linear::Strategy
 
       initialize!(Railway::DSL::State.new(DSL.OptionsForState()))

data/lib/trailblazer/activity/path.rb

@@ -177,6 +177,7 @@ module Trailblazer
 
       end # DSL
 
+      include DSL::Linear::Helper
       extend DSL::Linear::Strategy
 
       initialize!(Path::DSL::State.new(DSL.OptionsForState()))

data/lib/trailblazer/activity/railway.rb

@@ -90,6 +90,8 @@ module Trailblazer
           )
         end
 
+        # Add {:failure} output to {:outputs}.
+        # TODO: assert that failure_outputs doesn't override existing {:outputs}
         def normalize_path_outputs((ctx, flow_options), *)
           outputs = failure_outputs.merge(ctx[:outputs])
           ctx     = ctx.merge(outputs: outputs)
@@ -132,7 +134,6 @@ module Trailblazer
           pass:  Linear::Normalizer.activity_normalizer( Railway::DSL.normalizer_for_pass ),
         )
 
-
         def self.OptionsForState(normalizers: Normalizers, failure_end: Activity::End.new(semantic: :failure), **options)
           options = Path::DSL.OptionsForState(options).
             merge(normalizers: normalizers, failure_end: failure_end)
@@ -157,6 +158,7 @@ module Trailblazer
         end
       end
 
+      include DSL::Linear::Helper
       extend DSL::Linear::Strategy
 
       initialize!(Railway::DSL::State.new(DSL.OptionsForState()))

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity-dsl-linear
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-08 00:00:00.000000000 Z
+date: 2020-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trailblazer-activity
@@ -135,8 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Simple DSL to define Trailblazer activities.