trailblazer-activity 0.2.1 → 0.3.0

data/lib/trailblazer/activity/graph.rb

@@ -1,157 +0,0 @@
-module Trailblazer
-  # Note that Graph is a superset of a real directed graph. For instance, it might contain detached nodes.
-  # == Design
-  # * This class is designed to maintain a graph while building up a circuit step-wise.
-  # * It can be imperformant as this all happens at compile-time.
-  module Activity::Graph
-    # Task => { name: "Nested{Task}", type: :subprocess, boundary_events: { Circuit::Left => {} }  }
-
-    # Edge keeps references to its peer nodes via the `:source` and `:target` options.
-    class Edge
-      def initialize(data)
-        @data = data.freeze
-      end
-
-      def [](key)
-        @data[key]
-      end
-
-      def to_h
-        @data.to_h
-      end
-    end
-
-    # Node does only save meta data, and has *no* references to edges.
-    class Node < Edge
-    end
-
-    class Start < Node
-      def initialize(data)
-        yield self, data if block_given?
-        super
-      end
-
-      # Builds a node from the provided `:target` arguments and attaches it via `:edge` to `:source`.
-      # @param target: Array wrapped, options
-      def attach!(target:raise, edge:raise, source:self)
-        target = add!(target)
-
-        connect!(target: target, edge: edge, source: source)
-      end
-
-      def connect!(target:raise, edge:raise, source:self)
-        target = target.kind_of?(Node) ? target : (find_all(target)[0] || raise( "#{target} not found")) # FIXME: only needed for recompile_activity.
-        source = source.kind_of?(Node) ? source : (find_all(source)[0] || raise( "#{source} not found"))
-
-        connect_for!(source, edge, target)
-      end
-
-      def insert_before!(old_node, node:raise, outgoing:nil, incoming:raise)
-        old_node = find_all(old_node)[0] || raise( "#{old_node} not found") unless old_node.kind_of?(Node) # FIXME: do we really need this?
-        new_node = add!(node)
-
-        incoming_edges = predecessors(old_node)
-        rewired_edges  = incoming_edges.find_all { |(node, edge)| incoming.(edge) }
-
-        # rewire old_task's predecessors to new_task.
-        rewired_edges.each { |left_node, edge| reconnect!(left_node, edge, new_node) }
-
-        # connect new_task --> old_task.
-        if outgoing
-          node, edge = connect_for!(new_node, outgoing, old_node)
-        end
-
-        return new_node
-      end
-
-      def find_all(id=nil, &block)
-        nodes = self[:graph].keys + self[:graph].values.collect(&:values).flatten
-        nodes = nodes.uniq
-
-        nodes.find_all(& block || ->(node) { node[:id] == id })
-      end
-
-      def predecessors(target_node)
-        self[:graph].each_with_object([]) do |(node, connections), ary|
-          connections.each { |edge, target| target == target_node && ary << [node, edge] }
-        end
-      end
-
-      def successors(node)
-        ( self[:graph][node] || [] ).collect { |edge, target| [target, edge] }
-      end
-
-      def to_h(include_leafs:true)
-        hash = ::Hash[
-          self[:graph].collect do |node, connections|
-            connections = connections.collect { |edge, node| [ edge[:_wrapped], node[:_wrapped] ] }
-
-            [ node[:_wrapped], ::Hash[connections] ]
-          end
-        ]
-
-        if include_leafs == false
-          hash = hash.select { |node, connections| connections.any? }
-        end
-
-        hash
-      end
-
-      # @private
-      def Node(wrapped, id:raise("No ID was provided for #{wrapped}"), **options)
-        Node.new( options.merge( id: id, _wrapped: wrapped ) )
-      end
-
-    private
-
-      # Single entry point for adding nodes and edges to the graph.
-      # @private
-      # @return target Node
-      # @return edge Edge the edge created connecting source and target.
-      def connect_for!(source, edge_args, target)
-        edge = Edge(source, edge_args, target)
-
-        self[:graph][source][edge] = target
-
-        return target, edge
-      end
-
-      # Removes edge.
-      # @private
-      def unconnect!(node, edge)
-        self[:graph][node].delete(edge)
-      end
-
-      # @private
-      # Create a Node and add it to the graph, without connecting it.
-      def add!(node_args)
-        new_node = Node(*node_args)
-
-        raise IllegalNodeError.new("The ID `#{new_node[:id]}` has been added before.") if find_all( new_node[:id] ).any?
-
-        self[:graph][new_node] = {}
-        new_node
-      end
-
-      # @private
-      def reconnect!(left_node, edge, new_node)
-        unconnect!(left_node, edge) # dump the old edge.
-        connect_for!(left_node, [ edge[:_wrapped], edge.to_h ], new_node)
-      end
-
-      # @private
-      def Edge(source, (wrapped, options), target) # FIXME: test required id. test source and target
-        id   = "#{source[:id]}-#{wrapped}-#{target[:id]}"
-        edge = Edge.new(options.merge( _wrapped: wrapped, id: id, source: source, target: target ))
-      end
-    end
-
-    def self.Start(wrapped, graph:{}, **data, &block)
-      block ||= ->(node, data) { data[:graph][node] = {} }
-      Start.new( { _wrapped: wrapped, graph: graph }.merge(data), &block )
-    end
-
-    class IllegalNodeError < RuntimeError
-    end
-  end # Graph
-end

data/lib/trailblazer/circuit/testing.rb

@@ -1,58 +0,0 @@
-# TODO: remove or move.
-
-module MiniTest::Assertions
-  def assert_activity_inspect(text, subject)
-    Trailblazer::Circuit::ActivityInspect(subject).must_equal text
-  end
-
-  def assert_event_inspect(text, subject)
-    Trailblazer::Circuit::EndInspect(subject).must_equal(text)
-  end
-end
-
-
-Trailblazer::Activity.infect_an_assertion :assert_activity_inspect, :must_inspect
-Trailblazer::Circuit::End.infect_an_assertion      :assert_event_inspect,    :must_inspect_end_fixme
-
-class Trailblazer::Circuit
-  def self.EndInspect(event)
-    event.instance_eval { "#<#{self.class.to_s.split("::").last}: #{@name} #{@options}>" }
-  end
-
-  def self.ActivityInspect(activity, strip: ["AlterTest::"])
-    strip += ["Trailblazer::Circuit::"]
-    stripped = ->(target) { strip_for(target, strip) }
-
-    map, _ = activity.circuit.to_fields
-
-    content = map.collect do |task, connections|
-      bla =
-      connections.collect do |direction, target|
-        target_str = target.kind_of?(End) ? EndInspect(target) : stripped.(target)
-        "#{stripped.(direction)}=>#{target_str}"
-      end.join(", ")
-      task_str = task.kind_of?(End) ? EndInspect(task) : stripped.(task)
-      "#{task_str}=>{#{bla}}"
-    end.join(", ")
-    "{#{content}}"
-  end
-
-  def self.strip_for(target, strings)
-    strings.each { |stripped| target = target.to_s.gsub(stripped, "") }
-    target
-  end
-end
-
-module Trailblazer::Activity::Inspect
-  # The "matcher":
-  # Finds out appropriate serializer and calls it.
-  def self.call(inspected)
-    Instance(inspected)
-  end
-
-  # Serializes an object instance with hex IDs.
-  #   <Trailblazer::Circuit::Start: @name=:default, @options={}>
-  def self.Instance(object)
-    object.inspect.gsub(/0x\w+/, "")
-  end
-end

data/lib/trailblazer/container_chain.rb

@@ -1,45 +0,0 @@
-# @private
-class Trailblazer::Context::ContainerChain # used to be called Resolver.
-  # Keeps a list of containers. When looking up a key/value, containers are traversed in
-  # the order they were added until key is found.
-  #
-  # Required Container interface: `#key?`, `#[]`.
-  #
-  # @note ContainerChain is an immutable data structure, it does not support writing.
-  # @param containers Array of <Container> objects (splatted)
-  def initialize(containers, to_hash: nil)
-    @containers = containers
-    @to_hash    = to_hash
-  end
-
-  # @param name Symbol or String to lookup a value stored in one of the containers.
-  def [](name)
-    self.class.find(@containers, name)
-  end
-
-  # @private
-  def key?(name)
-    @containers.find { |container| container.key?(name) }
-  end
-
-  def self.find(containers, name)
-    containers.find { |container| container.key?(name) && (return container[name]) }
-  end
-
-  def keys
-    @containers.collect(&:keys).flatten
-end
-
-  # @private
-  def to_hash
-    return @to_hash.(@containers) if @to_hash # FIXME: introduce pattern matching so we can have different "transformers" for each container type.
-    @containers.each_with_object({}) { |container, hash| hash.merge!(container.to_hash) }
-  end
-end
-
-# alternative implementation:
-# containers.reverse.each do |container| @mutable_options.merge!(container) end
-#
-# benchmark, merging in #initialize vs. this resolver.
-#                merge     39.678k (± 9.1%) i/s -    198.700k in   5.056653s
-#             resolver     68.928k (± 6.4%) i/s -    342.836k in   5.001610s

data/lib/trailblazer/context.rb

@@ -1,68 +0,0 @@
-# TODO: mark/make all but mutable_options as frozen.
-# The idea of Skill is to have a generic, ordered read/write interface that
-# collects mutable runtime-computed data while providing access to compile-time
-# information.
-# The runtime-data takes precedence over the class data.
-module Trailblazer
-  # Holds local options (aka `mutable_options`) and "original" options from the "outer"
-  # activity (aka wrapped_options).
-
-  # only public creator: Build
-  class Context # :data object:
-    def initialize(wrapped_options, mutable_options)
-      @wrapped_options, @mutable_options = wrapped_options, mutable_options
-    end
-
-    def [](name)
-      ContainerChain.find( [@mutable_options, @wrapped_options], name )
-    end
-
-    def key?(name)
-      @mutable_options.key?(name) || @wrapped_options.key?(name)
-    end
-
-    def []=(name, value)
-      @mutable_options[name] = value
-    end
-
-    def merge(hash)
-      original, mutable_options = decompose
-
-      ctx = Trailblazer::Context( original, mutable_options.merge(hash) )
-    end
-
-    # Return the Context's two components. Used when computing the new output for
-    # the next activity.
-    def decompose
-      [ @wrapped_options, @mutable_options ]
-    end
-
-    def key?(name)
-      ContainerChain.find( [@mutable_options, @wrapped_options], name )
-    end
-
-
-    def keys
-      @mutable_options.keys + @wrapped_options.keys # FIXME.
-    end
-
-
-
-    # TODO: maybe we shouldn't allow to_hash from context?
-    # TODO: massive performance bottleneck. also, we could already "know" here what keys the
-    # transformation wants.
-    # FIXME: ToKeywordArguments()
-    def to_hash
-      {}.tap do |hash|
-        # the "key" here is to call to_hash on all containers.
-        [ @wrapped_options.to_hash, @mutable_options.to_hash ].each do |options|
-          options.each { |k, v| hash[k.to_sym] = v }
-        end
-      end
-    end
-  end
-
-  def self.Context(wrapped_options, mutable_options={})
-    Context.new(wrapped_options, mutable_options)
-  end
-end # Trailblazer

data/lib/trailblazer/option.rb

@@ -1,78 +0,0 @@
-module Trailblazer
-  # @note This might go to trailblazer-args along with `Context` at some point.
-  def self.Option(proc)
-    Option.build(Option, proc)
-  end
-
-  class Option
-    # Generic builder for a callable "option".
-    # @param call_implementation [Class, Module] implements the process of calling the proc
-    #   while passing arguments/options to it in a specific style (e.g. kw args, step interface).
-    # @return [Proc] when called, this proc will evaluate its option (at run-time).
-    def self.build(call_implementation, proc)
-      if proc.is_a? Symbol
-        ->(*args) { call_implementation.evaluate_method(proc, *args) }
-      else
-        ->(*args) { call_implementation.evaluate_callable(proc, *args) }
-      end
-    end
-
-    # A call implementation invoking `proc.(*args)` and plainly forwarding all arguments.
-    # Override this for your own step strategy (see KW#call!).
-    # @private
-    def self.call!(proc, *args)
-      proc.(*args)
-    end
-
-    # Note that both #evaluate_callable and #evaluate_method drop most of the args.
-    # If you need those, override this class.
-    # @private
-    def self.evaluate_callable(proc, *args, **flow_options)
-      call!(proc, *args)
-    end
-
-    # Make the context's instance method a "lambda" and reuse #call!.
-    # @private
-    def self.evaluate_method(proc, *args, exec_context:raise, **flow_options)
-      call!(exec_context.method(proc), *args)
-    end
-
-    # Returns a {Proc} that, when called, invokes the `proc` argument with keyword arguments.
-    # This is known as "step (call) interface".
-    #
-    # This is commonly used by `Operation::step` to wrap the argument and make it
-    # callable in the circuit.
-    #
-    #   my_proc = ->(options, **kws) { options["i got called"] = true }
-    #   task    = Trailblazer::Option::KW(my_proc)
-    #   task.(options = {})
-    #   options["i got called"] #=> true
-    #
-    # Alternatively, you can pass a symbol and an `:exec_context`.
-    #
-    #   my_proc = :some_method
-    #   task    = Trailblazer::Option::KW(my_proc)
-    #
-    #   class A
-    #     def some_method(options, **kws)
-    #       options["i got called"] = true
-    #     end
-    #   end
-    #
-    #   task.(options = {}, exec_context: A.new)
-    #   options["i got called"] #=> true
-    def self.KW(proc)
-      Option.build(KW, proc)
-    end
-
-    # TODO: It would be cool if call! was typed and had `options SymbolizedHash` or something.
-    class KW < Option
-      # A different call implementation that calls `proc` with a "step interface".
-      #   your_code.(options, **options)
-      # @private
-      def self.call!(proc, options, *)
-        proc.(options, **options.to_hash) # Step interface: (options, **)
-      end
-    end
-  end
-end

data/lib/trailblazer/wrap/inject.rb

@@ -1,32 +0,0 @@
-class Trailblazer::Activity
-  module Wrap
-    module Inject
-      # Returns an Alteration wirings that, when applied, inserts the {ReverseMergeDefaults} task
-      # before the {Wrap::Call} task. This is meant for macros and steps that accept a dependency
-      # injection but need a default parameter to be set if not injected.
-      # @returns Alteration
-      def self.Defaults(default_dependencies)
-        [
-          [ :insert_before!, "task_wrap.call_task", node: [ ReverseMergeDefaults.new( default_dependencies ), id: "ReverseMergeDefaults#{default_dependencies}" ], incoming: Proc.new{ true }, outgoing: [ Trailblazer::Circuit::Right, {} ] ]
-        ]
-      end
-
-      # @api private
-      # @returns Task
-      # @param Hash list of key/value that should be set if not already assigned/set before (or injected from the outside).
-      class ReverseMergeDefaults
-        def initialize(defaults)
-          @defaults = defaults
-        end
-
-        def call((wrap_ctx, original_args), **circuit_options)
-          ctx = original_args[0][0]
-
-          @defaults.each { |k, v| ctx[k] ||= v }
-
-          [ Trailblazer::Circuit::Right, [wrap_ctx, original_args] ]
-        end
-      end
-    end # Inject
-  end
-end

data/lib/trailblazer/wrap/variable_mapping.rb

@@ -1,92 +0,0 @@
-class Trailblazer::Activity
-  module Wrap
-    # TaskWrap step to compute the incoming {Context} for the wrapped task.
-    # This allows renaming, filtering, hiding, of the options passed into the wrapped task.
-    #
-    # Both Input and Output are typically to be added before and after task_wrap.call_task.
-    #
-    # @note Assumption: we always have :input _and_ :output, where :input produces a Context and :output decomposes it.
-    class Input
-      def initialize(filter)
-        @filter = Trailblazer::Option(filter)
-      end
-
-      # `original_args` are the actual args passed to the wrapped task: [ [options, ..], circuit_options ]
-      #
-      def call((wrap_ctx, original_args), **circuit_options)
-        # let user compute new ctx for the wrapped task.
-        input_ctx = apply_filter(*original_args)
-
-        # TODO: make this unnecessary.
-        # wrap user's hash in Context if it's not one, already (in case user used options.merge).
-        # DISCUSS: should we restrict user to .merge and options.Context?
-        input_ctx = Trailblazer.Context({}, input_ctx) unless input_ctx.instance_of?(Trailblazer::Context)
-
-        wrap_ctx = wrap_ctx.merge( vm_original_args: original_args )
-
-        # decompose the original_args since we want to modify them.
-        (original_ctx, original_flow_options), original_circuit_options = original_args
-
-        # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
-        return Trailblazer::Circuit::Right, [ wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options] ]
-      end
-
-      private
-
-      def apply_filter((original_ctx, original_flow_options), original_circuit_options)
-        @filter.( original_ctx, **original_circuit_options )
-      end
-    end
-
-    # TaskWrap step to compute the outgoing {Context} from the wrapped task.
-    # This allows renaming, filtering, hiding, of the options returned from the wrapped task.
-    class Output
-      def initialize(filter, strategy=CopyMutableToOriginal)
-        @filter   = Trailblazer::Option(filter)
-        @strategy = strategy
-      end
-
-      # Runs the user filter and replaces the ctx in `wrap_ctx[:result_args]` with the filtered one.
-      def call((wrap_ctx, original_args), **circuit_options)
-        (original_ctx, original_flow_options), original_circuit_options = original_args
-
-        returned_ctx, _ = wrap_ctx[:result_args] # this is the context returned from `call`ing the task.
-
-        # returned_ctx is the Context object from the nested operation. In <=2.1, this might be a completely different one
-        # than "ours" we created in Input. We now need to compile a list of all added values. This is time-intensive and should
-        # be optimized by removing as many Context creations as possible (e.g. the one adding self[] stuff in Operation.__call__).
-        _, mutable_data = returned_ctx.decompose # FIXME: this is a weak assumption. What if the task returns a deeply nested Context?
-
-        # let user compute the output.
-        output = apply_filter(mutable_data, original_flow_options, original_circuit_options)
-
-        original_ctx = wrap_ctx[:vm_original_args][0][0]
-
-        new_ctx = @strategy.( original_ctx, output ) # here, we compute the "new" options {Context}.
-
-        wrap_ctx = wrap_ctx.merge( result_args: [new_ctx, original_flow_options] )
-
-        # and then pass on the "new" context.
-        return Trailblazer::Circuit::Right, [ wrap_ctx, original_args ]
-      end
-
-      private
-
-      # @note API not stable
-      def apply_filter(mutable_data, original_flow_options, original_circuit_options)
-        @filter.(mutable_data, **original_circuit_options)
-      end
-
-      # "merge" Strategy
-      class CopyMutableToOriginal
-        # @param original Context
-        # @param options  Context The object returned from a (nested) {Activity}.
-        def self.call(original, mutable)
-          mutable.each { |k,v| original[k] = v }
-
-          original
-        end
-      end
-    end
-  end # Wrap
-end