trailblazer-activity 0.7.1 → 0.8.0

data/.travis.yml

@@ -1,8 +1,9 @@
 sudo: false
 language: ruby
 rvm:
+  - 2.6.0
   - 2.5.1
   - 2.4.4
-  - 2.3.7
-  - 2.2.10
+  # - 2.3.7
+  # - 2.2.10
 before_install: gem install bundler

data/CHANGES.md

@@ -1,3 +1,13 @@
+# 0.8.0
+
+* Separate the [DSL](https://github.com/trailblazer/trailblazer-activity-dsl-linear) from the runtime code. The latter sits in this gem.
+* Separate the runtime {Activity} from its compilation, which happens through {Intermediate} (the structure) and {Implementation} (the runtime implementation) now.
+* Introduce {Pipeline} which is a simpler and much fast type of activity, mostly for the taskWrap.
+
+# 0.7.2
+
+* When recording DSL calls, use the `object_id` as key, so cloned methods are considered as different recordings.
+
 # 0.7.1
 
 * Alias `Trace.call` to `Trace.invoke` for consistency.

data/Gemfile

@@ -1,12 +1,13 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in workflow.gemspec
 gemspec
 
-gem "minitest-line"
 gem "benchmark-ips"
+gem "minitest-line"
 
 gem "rubocop", require: false
 
-gem "trailblazer-test", git: "https://github.com/trailblazer/trailblazer-test"
-
+# gem "trailblazer-context", path: "../trailblazer-context"
+gem "trailblazer-developer", path: "../trailblazer-developer"
+# gem "trailblazer-developer", github: "trailblazer/trailblazer-developer", branch: "exception-tracing"

data/README.md

@@ -1,5 +1,7 @@
 # Activity
 
+implements Intermediate, Implementation, compiler and `Activity::Implementation`, Activity::Interface
+
 The `activity` gem brings a light-weight DSL to define business processes, and the runtime logic to run those activities.
 
 A process is a set of arbitrary pieces of logic you define, chained together and put into a meaningful context by an activity. Activity lets you focus on the implementation of steps while Trailblazer takes care of the control flow.

data/Rakefile

@@ -5,7 +5,7 @@ require "rubocop/rake_task"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["**/*_test.rb"]
+  t.test_files = FileList["**/*_test.rb"] - FileList["test/docs/*"]
 end
 
 RuboCop::RakeTask.new

data/lib/trailblazer/activity.rb

@@ -1,123 +1,60 @@
 module Trailblazer
-  class Activity < Module
-    attr_reader :initial_state
+  # This is DSL-independent code, focusing only on run-time.
+  class Activity
+    # include Activity::Interface # TODO
 
-    def initialize(implementation, options)
-      builder, adds, circuit, outputs, options = BuildState.build_state_for( implementation.config, options)
-
-      @initial_state = State::Config.build(
-        builder: builder,
-        options: options,
-        adds:    adds,
-        circuit: circuit,
-        outputs: outputs,
-      )
-
-      include *options[:extend] # include the DSL methods.
-      include PublicAPI
-    end
-
-    # Injects the initial configuration into the module defining a new activity.
-    def extended(extended)
-      super
-      extended.instance_variable_set(:@state, initial_state)
-    end
-
-
-    module Inspect
-      def inspect
-        "#<Trailblazer::Activity: {#{name || self[:options][:name]}}>"
-      end
-
-      alias_method :to_s, :inspect
+    def initialize(schema)
+      @schema = schema
     end
 
-
-    require "trailblazer/activity/dsl/helper"
-    # Helpers such as Path, Output, End to be included into {Activity}.
-    module DSLHelper
-      extend Forwardable
-      def_delegators :@builder, :Path
-      def_delegators DSL, :Output, :End, :Subprocess, :Track
-
-      def Path(*args, &block)
-        self[:builder].Path(*args, &block)
-      end
+    def call(args, circuit_options={})
+      @schema[:circuit].(
+        args,
+        circuit_options.merge(activity: self)
+      )
     end
 
-    # Reader and writer method for DSL objects.
+    # Reader and writer method for an Activity.
     # The writer {dsl[:key] = "value"} exposes immutable behavior and will replace the old
     # @state with a new, modified copy.
     #
-    # Always use the DSL::Accessor accessors to avoid leaking state to other components
+    # Always use the accessors to avoid leaking state to other components
     # due to mutable write operations.
-    module Accessor
-      def []=(*args)
-        @state = State::Config.send(:[]=, @state, *args)
-      end
-
-      def [](*args)
-        State::Config[@state, *args]
-      end
+    def [](*key)
+      @schema[:config][*key]
     end
 
-    # FIXME: still to be decided
-    # By including those modules, we create instance methods.
-    # Later, this module is `extended` in Path, Railway and FastTrack, and
-    # imports the DSL methods as class methods.
-    module PublicAPI
-      include Accessor
-
-    require "trailblazer/activity/dsl/add_task"
-      include DSL::AddTask
-
-    require "trailblazer/activity/interface"
-      include Activity::Interface # DISCUSS
-
-      include DSLHelper # DISCUSS
-
-      include Activity::Inspect # DISCUSS
-
-    require "trailblazer/activity/dsl/magnetic/merge"
-      include Magnetic::Merge # Activity#merge!
-
-      # @private Note that {Activity.call} is considered private until the public API is stable.
-      def call(args, circuit_options={})
-        self[:circuit].( args, circuit_options.merge(activity: self) )
-      end
+    def to_h
+      @schema
     end
 
+    def inspect
+      %{#<Trailblazer::Activity:0x#{object_id}>}
+    end
   end # Activity
 end
 
-require "trailblazer/circuit"
+# require "trailblazer/activity/interface"
 require "trailblazer/activity/structures"
+require "trailblazer/activity/schema"
+require "trailblazer/activity/schema/implementation"
+require "trailblazer/activity/schema/intermediate"
+require "trailblazer/activity/circuit"
 require "trailblazer/activity/config"
 
-require "trailblazer/activity/dsl/strategy/build_state"
-require "trailblazer/activity/dsl/strategy/path"
-require "trailblazer/activity/dsl/strategy/plan"
-require "trailblazer/activity/dsl/strategy/railway"
-require "trailblazer/activity/dsl/strategy/fast_track"
-
 require "trailblazer/activity/task_wrap"
+require "trailblazer/activity/task_wrap/pipeline"
 require "trailblazer/activity/task_wrap/call_task"
-require "trailblazer/activity/task_wrap/trace"
 require "trailblazer/activity/task_wrap/runner"
-require "trailblazer/activity/task_wrap/merge"
 require "trailblazer/activity/task_wrap/variable_mapping"
+require "trailblazer/activity/task_wrap/inject"
 
 require "trailblazer/activity/trace"
 require "trailblazer/activity/present"
 
 require "trailblazer/activity/introspect"
+require "trailblazer/option"
+require "trailblazer/context"
+require "trailblazer/activity/task_builder"
 
-require "trailblazer/activity/dsl/magnetic/builder/state"
-require "trailblazer/activity/dsl/magnetic" # the "magnetic" DSL
-
-require "trailblazer/activity/dsl/schema/sequence"
-require "trailblazer/activity/dsl/schema/dependencies"
-
-require "trailblazer/activity/dsl/magnetic/builder/normalizer" # DISCUSS: name and location are odd. This one uses Activity ;)
 
-require "trailblazer/activity/dsl/record"

data/lib/trailblazer/activity/circuit.rb

@@ -0,0 +1,74 @@
+module Trailblazer
+  class Activity
+    # 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.
+    #
+    #   result = circuit.(start_at, *args)
+    #
+    # @see Activity
+    # @api semi-private
+    #
+    # This is the "pipeline operator"'s implementation.
+    class Circuit
+      def initialize(map, stop_events, start_task:, name: nil)
+        @map         = map
+        @stop_events = stop_events
+        @name        = name
+        @start_task  = start_task
+      end
+
+      # @param args [Array] all arguments to be passed to the task's `call`
+      # @param task [callable] task to call
+      Run = ->(task, args, **circuit_options) { task.(args, **circuit_options) }
+
+      # Runs the circuit until we hit a stop event.
+      #
+      # This method throws exceptions when the returned value of a task doesn't match
+      # any wiring.
+      #
+      # @param task An event or task of this circuit from where to start
+      # @param options anything you want to pass to the first task
+      # @param flow_options Library-specific flow control data
+      # @return [last_signal, options, flow_options, *args]
+      #
+      # NOTE: returned circuit_options are discarded when calling the runner.
+      def call(args, start_task: @start_task, runner: Run, **circuit_options)
+        circuit_options = circuit_options.merge( runner: runner ).freeze # TODO: set the :runner option via arguments_for_call to save the merge?
+        task            = start_task
+
+        loop do
+          last_signal, args, _discarded_circuit_options = runner.(
+            task,
+            args,
+            circuit_options
+          )
+
+          # Stop execution of the circuit when we hit a stop event (< End). This could be an task's End or Suspend.
+          return [ last_signal, args ] if @stop_events.include?(task) # DISCUSS: return circuit_options here?
+
+          task = next_for(task, last_signal) or raise IllegalSignalError.new("<#{@name}>[#{task}][ #{last_signal.inspect} ]")
+        end
+      end
+
+      # Returns the circuit's components.
+      def to_h
+        { map: @map, end_events: @stop_events, start_task: @start_task }
+      end
+
+      private
+
+      def next_for(last_task, signal)
+        outputs = @map[last_task]
+        outputs[signal]
+      end
+
+      class IllegalSignalError < RuntimeError
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/config.rb

@@ -3,12 +3,10 @@ module Trailblazer
     # Compile-time
     #
     # DISCUSS: we could replace parts with Hamster::Hash.
-    class Config
-      def self.build(variables={})
-        Hash[ variables.collect { |k,v| [k, v.freeze] } ].freeze
-      end
+    module Config
+      module_function
 
-      def self.[]=(state, *args)
+      def set(state, *args)
         if args.size == 2
           key, value = *args
 
@@ -25,7 +23,7 @@ module Trailblazer
         state
       end
 
-      def self.[](state, *args)
+      def get(state, *args)
         directive, key = *args
 
         return state[directive] if args.size == 1

data/lib/trailblazer/activity/introspect.rb

@@ -1,18 +1,22 @@
 module Trailblazer
-  class Activity < Module
-    # Compile-time.
-    # Introspection is not used at run-time except for rendering diagrams, tracing, and the like.
+  class Activity
+    # The Introspect API abstracts internals about circuits and provides a convenient API
+    # to third-parties such as tracing, rendering activities, etc.
     module Introspect
       def self.Graph(*args)
         Graph.new(*args)
       end
 
+      # TODO: order of step/fail/pass in Node would be cool to have
+
       # @private This API is still under construction.
       class Graph
         def initialize(activity)
           @activity = activity
-          @circuit  = activity.to_h[:circuit]
-          @adds     = activity.to_h[:adds].compact # FIXME: why are there nils in Adds?
+          @schema   = activity.to_h or raise
+          @circuit  = @schema[:circuit]
+          @map      = @circuit.to_h[:map]
+          @configs  = @schema[:nodes]
         end
 
         def find(id=nil, &block)
@@ -20,148 +24,48 @@ module Trailblazer
           find_with_block(&block)
         end
 
+        def collect(strategy: :circuit, &block)
+          @map.keys.each_with_index.collect { |task, i| yield find_with_block { |node| node.task==task }, i }
+        end
+
+        def stop_events
+          @circuit.to_h[:end_events]
+        end
+
         private
 
         def find_by_id(id)
-          (_, (id, triplett)) = @adds.find { |(op, (_id, triplett))| _id == id }
-
-          Node(triplett[1], id, triplett[0])
+          node = @configs.find { |node| node.id == id } or return
+          node_for(node)
         end
 
         def find_with_block(&block)
-          adds = @adds.find { |(op, (id, triplett))| yield( Node(triplett[1], id, triplett[0]) ) }
-          return nil unless adds
+          existing = @configs.find { |node| yield Node(node.task, node.id, node.outputs, node.data) } or return
 
-          (op, (id, triplett)) = adds
+          node_for(existing)
+        end
 
-          Node(triplett[1], id, triplett[0])
+        def node_for(node_attributes)
+          Node(node_attributes.task, node_attributes.id, node_attributes.outputs, outgoings_for(node_attributes), node_attributes.data)
         end
 
         def Node(*args)
           Node.new(*args).freeze
         end
 
-        Node = Struct.new(:task, :id, :magnetic_to)
-      end
-
+        Node     = Struct.new(:task, :id, :outputs, :outgoings, :data)
+        Outgoing = Struct.new(:output, :task)
 
-      # FIXME: remove this
-      # @private This will be removed shortly.
-      def self.collect(activity, options={}, &block)
-        circuit      = activity.to_h[:circuit]
-        circuit_hash = circuit.to_h[:map]
-
-        locals = circuit_hash.collect do |task, connections|
-          [
-            yield(task, connections),
-            *options[:recursive] && task.is_a?(Activity::Interface) ? collect(task, options, &block) : []
-          ]
-        end.flatten(1)
-      end
+        def outgoings_for(node)
+          outputs     = node.outputs
+          connections = @map[node.task]
 
-
-      def self.inspect_task_builder(task)
-        proc = task.instance_variable_get(:@user_proc)
-        match = proc.inspect.match(/(\w+)>$/)
-
-        %{#<TaskBuilder{.#{match[1]}}>}
-      end
-
-        # FIXME: clean up that shit below.
-
-# render
-      def self.Cct(circuit, **options)
-        circuit_hash( circuit.to_h[:map], **options )
-      end
-
-      def self.circuit_hash(circuit_hash, show_ids:false, **options)
-        content =
-          circuit_hash.collect do |task, connections|
-            conns = connections.collect do |signal, target|
-              " {#{signal}} => #{inspect_with_matcher(target, **options)}"
-            end
-
-            [ inspect_with_matcher(task, **options), conns.join("\n") ]
+          connections.collect do |signal, target|
+            output = outputs.find { |out| out.signal == signal }
+            Outgoing.new(output, target)
           end
-
-          content = content.join("\n")
-
-          return "\n#{content}" if show_ids
-          return "\n#{content}".gsub(/0x\w+/, "0x").gsub(/0.\d+/, "0.")
-      end
-
-      def self.Ends(activity)
-        end_events = activity.to_h[:end_events]
-        ends = end_events.collect { |evt| inspect_end(evt) }.join(",")
-        "[#{ends}]".gsub(/\d\d+/, "")
-      end
-
-
-      def self.Outputs(outputs)
-        outputs.collect { |semantic, output| "#{semantic}=> (#{output.signal}, #{output.semantic})" }.
-          join("\n").gsub(/0x\w+/, "").gsub(/\d\d+/, "")
-      end
-
-      # If Ruby had pattern matching, this function wasn't necessary.
-      def self.inspect_with_matcher(task, inspect_task: method(:inspect_task), inspect_end: method(:inspect_end))
-        return inspect_task.(task) unless task.kind_of?(Trailblazer::Activity::End)
-        inspect_end.(task)
-      end
-
-      def self.inspect_task(task)
-        task.inspect
-      end
-
-      def self.inspect_end(task)
-        class_name = strip(task.class)
-        options    = task.to_h
-
-        "#<#{class_name}/#{options[:semantic].inspect}>"
-      end
-
-      def self.strip(string)
-        string.to_s.sub("Trailblazer::Activity::", "")
+        end
       end
     end #Introspect
   end
-
-  module Activity::Magnetic
-    module Introspect
-      def self.seq(activity)
-        adds = activity.instance_variable_get(:@adds)
-        tripletts = Builder::Finalizer.adds_to_tripletts(adds)
-
-        Seq(tripletts)
-      end
-
-      def self.cct(builder)
-        adds = builder.instance_variable_get(:@adds)
-        circuit, _ = Builder::Finalizer.(adds)
-
-        Cct(circuit)
-      end
-
-      private
-
-      def self.Seq(sequence)
-        content =
-          sequence.collect do |(magnetic_to, task, plus_poles)|
-            pluses = plus_poles.collect { |plus_pole| PlusPole(plus_pole) }
-
-%{#{magnetic_to.inspect} ==> #{Activity::Introspect.inspect_with_matcher(task)}
-#{pluses.empty? ? " []" : pluses.join("\n")}}
-          end.join("\n")
-
-    "\n#{content}\n".gsub(/\d\d+/, "").gsub(/0x\w+/, "0x")
-      end
-
-      def self.PlusPole(plus_pole)
-        signal = plus_pole.signal.to_s.sub("Trailblazer::Activity::", "")
-        semantic = plus_pole.send(:output).semantic
-        " (#{semantic})/#{signal} ==> #{plus_pole.color.inspect}"
-      end
-
-
-    end
-  end
 end