trailblazer-activity 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81fa1b9e57d3f63ee5ee4b5caadea44250fcdbad
-  data.tar.gz: ba3e8fc06d51e146702ac7b6eb6765fe3af6e7ee
+  metadata.gz: 8acff4e1b4e5f3e922e9e368cf5885de56dcc2b5
+  data.tar.gz: 3a1a10d63d5cbe7236f0ffac21f4774add92954a
 SHA512:
-  metadata.gz: 62291d8bbb37376be5e1c6548c35d7df00a7edf654697ac26ed786d55a2bdf49de6130ad0bcfa3a221ff1dbf30935f9ae6d7f2fbe3d143bd4ae42c52d106b110
-  data.tar.gz: 3503a6d13258343169a5eddbcc99fa63a169f493dcde5e42962e03775b97c9f09bb9ed68aaa9891ee13a262539dda4051ac4b7e5895b3f01a93f3b4acdd08184
+  metadata.gz: 6e13c839f0ca6215fe069299de99ead0910557412fb24b40ecc4a1c9e25884108f105bdaa2cc6302a1ad96b83d425932d0cad0d1a2c5e016177eeb087e8278ea
+  data.tar.gz: f6a774594e754bb0c4ba4082b4a285421850e6d79450d00a5729d96c85c171627aa35dfc14fead7b47190069cebab893eb6ad57150cf10c186f63bd566842107

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.2.2
+
+* Remove `Activity#end_events`.
+
 # 0.2.1
 
 * Restructure all `Wrap`-specific tasks.

data/NOTES_

@@ -0,0 +1,36 @@
+  # NOT lowest level. if you need that, use your own proc.
+    # TODO: how do we track what goes into the callable?
+    #                 adjust what goes into it (e.g. without direction or with kw args)?
+    #                 pre contract -> step -> post contract (are these all just steps, in "mini nested pipe"?)
+    #
+    #
+    # aka "Atom".
+    def self.Task(instance: :context, method: :call, id:nil)
+
+
+      # * ingoing contract (could be implemented as a nested pipe with 3 steps. that would allow us
+      #   to compile it to native ruby method calls later)
+      ->(direction, options, **flow_options) {
+        instance = flow_options[:context] if instance==:context # TODO; implement different :context (e.g. :my_context).
+
+
+
+      # * incoming args
+        # step_args = [args] # TODO: overridable.
+        step_args = [ options, **options ]
+
+      # ** call the actual thing
+        res = instance.send(method, *step_args) # what goes in? kws?
+
+      # * interpret result (e.g. true=>Right) (should we keep doing that in the tie? so the op has it easier with success, etc?)
+      # * outgoing contract
+      # * outgoing args
+
+        [ *res, flow_options ]
+
+
+      # * tracing: incoming, outgoing, direction, etc. - do we want that in tasks, too?
+
+
+      }
+    end

data/README.md

@@ -67,12 +67,12 @@ Instead of using an operation, you can manually define activities by using the `
 ```ruby
 activity = Activity.from_hash do |start, _end|
   {
-    start            => { Trailblazer::Circuit::Right => Blog::Write },
-    Blog::Write      => { Trailblazer::Circuit::Right => Blog::SpellCheck },
-    Blog::SpellCheck => { Trailblazer::Circuit::Right => Blog::Publish,
-                          Trailblazer::Circuit::Left => Blog::Correct },
-    Blog::Correct    => { Trailblazer::Circuit::Right => Blog::SpellCheck },
-    Blog::Publish    => { Trailblazer::Circuit::Right => _end }
+    start            => { Trailblazer::Activity::Right => Blog::Write },
+    Blog::Write      => { Trailblazer::Activity::Right => Blog::SpellCheck },
+    Blog::SpellCheck => { Trailblazer::Activity::Right => Blog::Publish,
+                          Trailblazer::Activity::Left => Blog::Correct },
+    Blog::Correct    => { Trailblazer::Activity::Right => Blog::SpellCheck },
+    Blog::Publish    => { Trailblazer::Activity::Right => _end }
   }
 end
 ```
@@ -89,7 +89,7 @@ my_options = {}
 last_signal, options, flow_options, _ = activity.( nil, my_options, {} )
 ```
 
-1. The `start` event is `call`ed and per default returns the generic _signal_`Trailblazer::Circuit::Right`.
+1. The `start` event is `call`ed and per default returns the generic _signal_`Trailblazer::Activity::Right`.
 2. This emitted (or returned) signal is connected to the next task `Blog::Write`, which is now `call`ed.
 3. `Blog::Write` emits another `Right` signal that leads to `Blog::SpellCheck` being `call`ed.
 4. `Blog::SpellCheck` defines two outgoing signals and hence can decide what next task to call by emitting either `Right` if the spell check was ok, or `Left` if the post contains typos.

data/Rakefile

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

data/lib/trailblazer/activity.rb

@@ -1,136 +1,177 @@
 require "trailblazer/circuit"
 
-# TODO: move to separate gem.
-require "trailblazer/option"
-require "trailblazer/context"
-require "trailblazer/container_chain"
-
 module Trailblazer
   class Activity
+    module Interface
+      def decompose # TODO: test me
+        @process.instance_variable_get(:@circuit).to_fields
+      end
+
+      def debug # TODO: TEST ME
+        @debug
+      end
+    end
 
-  require "trailblazer/activity/version"
-  require "trailblazer/activity/graph"
-  require "trailblazer/activity/subprocess"
+    extend Interface
 
-  require "trailblazer/activity/wrap"
-  require "trailblazer/wrap/variable_mapping"
-  require "trailblazer/wrap/call_task"
-  require "trailblazer/wrap/trace"
-  require "trailblazer/wrap/inject"
-  require "trailblazer/wrap/runner"
+    require "trailblazer/activity/version"
+    require "trailblazer/activity/structures"
 
-  require "trailblazer/activity/trace"
-  require "trailblazer/activity/present"
+    require "trailblazer/activity/subprocess"
 
-    # 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" } ]
+    require "trailblazer/activity/wrap"
+    require "trailblazer/wrap/call_task"
+    require "trailblazer/wrap/trace"
+    require "trailblazer/wrap/runner"
 
-      start      = block ? Graph::Start( *start_args, &block ) : Graph::Start(*start_args)
+    require "trailblazer/activity/trace"
+    require "trailblazer/activity/present"
 
-      wirings.each do |wiring|
-        start.send(*wiring)
-      end
 
-      new(start)
+    require "trailblazer/activity/magnetic" # the "magnetic" DSL
+    require "trailblazer/activity/schema/sequence"
+
+    require "trailblazer/activity/process"
+    require "trailblazer/activity/introspection"
+
+    require "trailblazer/activity/heritage"
+
+    def self.call(args, circuit_options={})
+      @process.( args, circuit_options )
     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
+    #- modelling
 
-      new(graph)
+    # @private
+    # DISCUSS: #each instead?
+    # FIXME: move to Introspection
+    def self.find(&block)
+      @process.instance_variable_get(:@circuit).instance_variable_get(:@map).find(&block)
+    end
+
+    def self.outputs
+      @outputs
     end
 
-    def self.merge(activity, wirings)
-      graph = activity.graph
+    #- DSL part
 
-      # 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?
+    def self.build(&block)
+      Class.new(self, &block)
+    end
 
-      from_wirings(wirings) do |start_node, data|
-        cloned_graph_ary.unshift [ start_node, old_start_connections ] # push new start node onto the graph.
+    private
 
-        data[:graph] = ::Hash[cloned_graph_ary]
-      end
+    def self.inherited(subclass)
+      super
+      subclass.initialize!(*subclass.config)
+      heritage.(subclass)
     end
 
-    def initialize(graph)
-      @graph               = graph
-      @default_start_event = graph[:_wrapped]
-      @circuit             = to_circuit( @graph ) # graph is an immutable object.
+    def self.initialize!(builder_class, normalizer)
+      initialize_activity_dsl!(builder_class, normalizer)
+      recompile_process!
     end
 
-    def end_events
-      outputs.keys
+    # builder is stateless, it's up to you to save @adds somewhere.
+    def self.initialize_activity_dsl!(builder_class, normalizer)
+      @builder, @adds = builder_class.for( normalizer ) # e.g. Path.for(...) which creates a Builder::Path instance.
+      @debug          = {} # only @adds and @debug are mutable
     end
 
-    # Returns a hash mapping the circuit {Event} to its meta data.
-    #
-    #   activity.outputs #=> { #<End ..> => { role: :success }, #<End ..> => { role: :failure } }
-    def outputs
-      # DISCUSS: add more meta data?
-      ::Hash[ graph.find_all { |node| graph.successors(node).size == 0 }.collect { |node| [ node[:_wrapped], { role: node[:role] } ] } ]
+    def self.recompile_process!
+      @process, @outputs = Recompile.( @adds )
     end
 
-    def call(args, start_event: default_start_event, **circuit_options)
-      @circuit.(
-        args,
-        circuit_options.merge( task: start_event) , # this passes :runner to the {Circuit}.
-      )
+    def self.config # FIXME: the normalizer is the same we have in Builder::plan.
+      return Magnetic::Builder::Path, Magnetic::Builder::DefaultNormalizer.new(plus_poles: Magnetic::Builder::Path.default_plus_poles)
     end
 
-    # @private
-    attr_reader :circuit
-    # @private
-    attr_reader :graph
+    # DSL part
 
-    private
+    # DISCUSS: make this functions and don't include?
+    module DSL
+
+      # Create a new method (e.g. Activity::step) that delegates to its builder, recompiles
+      # the process, etc. Method comes in a module so it can be overridden via modules.
+      #
+      # This approach assumes you maintain a @adds and a @debug instance variable. and #heritage
+      def self.def_dsl!(_name)
+        Module.new do
+          define_method(_name) do |*args, &block|
+            _task(_name, *args, &block)  # TODO: similar to Block.
+          end
+        end
+      end
+
+      private
+
+      def _task(name, *args, &block)
+        heritage.record(name, *args, &block)
+
+        adds, *returned_options = @builder.send(name, *args, &block)
+
+        @adds += adds
+        @adds.freeze
 
-    attr_reader :default_start_event
+        recompile_process!
+
+        add_introspection!(adds, *returned_options)
+
+        return adds, returned_options
+      end
+
+      def add_introspection!(adds, task, local_options, *)
+        @debug[task] = { id: local_options[:id] }.freeze
+      end
+    end
 
-    def to_circuit(graph)
-      Circuit.new(graph.to_h( include_leafs: false ), end_events, {})
+    # delegate as much as possible to Builder
+    # let us process options and e.g. do :id
+    class << self
+      extend Forwardable # TODO: test those helpers
+      def_delegators :@builder, :Path#, :task
     end
 
-    class Introspection
-      # @param activity Activity
-      def initialize(activity)
-        @activity = activity
-        @graph    = activity.graph
-        @circuit  = activity.circuit
+    extend DSL                  # _task, :add_introspection
+    extend DSL.def_dsl!(:task)  # define Activity::task.
+
+    extend Heritage::Accessor
+
+
+    # MOVE ME TO ADDS
+    module Recompile
+      # Recompile the process and outputs from the {ADDS} instance that collects circuit tasks and connections.
+      def self.call(adds)
+        process, end_events = Magnetic::Builder::Finalizer.(adds)
+        outputs             = recompile_outputs(end_events)
+
+        return process, outputs
       end
 
-      # Find the node that wraps `task` or return nil.
-      def [](task)
-        @graph.find_all { |node| node[:_wrapped] == task  }.first
+      private
+
+      def self.recompile_outputs(end_events)
+        ary = end_events.collect do |evt|
+          [
+            semantic = evt.instance_variable_get(:@options)[:semantic], # DISCUSS: better API here?
+            Activity::Output(evt, semantic)
+          ]
+        end
+
+        ::Hash[ ary ]
       end
     end
+
+    # TODO: hm
+    class Railway < Activity
+      def self.config # FIXME: the normalizer is the same we have in Builder::plan.
+        return Magnetic::Builder::Railway, Magnetic::Builder::DefaultNormalizer.new(plus_poles: Magnetic::Builder::Railway.default_plus_poles)
+      end
+
+      extend DSL
+      extend DSL.def_dsl!(:step)
+      extend DSL.def_dsl!(:fail)
+      extend DSL.def_dsl!(:pass)
+    end
   end
 end

data/lib/trailblazer/activity/heritage.rb

@@ -0,0 +1,30 @@
+module Trailblazer
+  # This is copied from the Declarative gem. This might get removed in favor of a real heritage gem.
+  class Activity
+    class Heritage < Array
+      # Record inheritable assignments for replay in an inheriting class.
+      def record(method, *args, &block)
+        self << { method: method, args: args, block: block }
+      end
+
+      # Replay the recorded assignments on inheritor.
+      # Accepts a block that will allow processing the arguments for every recorded statement.
+      def call(inheritor, &block)
+        each { |cfg| call!(inheritor, cfg, &block) }
+      end
+
+    private
+      def call!(inheritor, cfg)
+        yield cfg if block_given? # allow messing around with recorded arguments.
+
+        inheritor.send(cfg[:method], *cfg[:args], &cfg[:block])
+      end
+
+      module Accessor
+        def heritage
+          @heritage ||= Heritage.new
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/introspection.rb

@@ -0,0 +1,105 @@
+module Trailblazer
+  class Activity
+    # Introspection is not used at run-time except for rendering diagrams, tracing, and the like.
+    module Introspect
+
+      def self.collect(activity, options={}, &block)
+        circuit_hash, _ = activity.decompose
+
+        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
+
+
+# render
+      def self.Cct(process, **options)
+        circuit_hash( process.instance_variable_get(:@circuit).to_fields[0], **options )
+      end
+
+      def self.circuit_hash(circuit_hash, show_ids:false)
+        content =
+          circuit_hash.collect do |task, connections|
+            conns = connections.collect do |signal, target|
+              " {#{signal}} => #{Task(target)}"
+            end
+
+            [ Task(task), conns.join("\n") ]
+          end
+
+          content = content.join("\n")
+
+          return "\n#{content}" if show_ids
+          return "\n#{content}".gsub(/\d\d+/, "")
+      end
+
+      def self.Ends(process)
+        end_events = process.instance_variable_get(:@circuit).to_fields[1]
+        ends = end_events.collect { |evt| Task(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
+
+      def self.Task(task)
+        return task.inspect unless task.kind_of?(Trailblazer::Activity::End)
+
+        class_name = strip(task.class)
+        name     = task.instance_variable_get(:@name)
+        semantic = task.instance_variable_get(:@options)[:semantic]
+        "#<#{class_name}:#{name}/#{semantic.inspect}>"
+      end
+
+      def self.strip(string)
+        string.to_s.sub("Trailblazer::Activity::", "")
+      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)
+        process, _ = Builder::Finalizer.(adds)
+
+        Cct(process)
+      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.Task(task)}
+#{pluses.empty? ? " []" : pluses.join("\n")}}
+          end.join("\n")
+
+    "\n#{content}\n".gsub(/\d\d+/, "")
+      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