substation 0.0.10.beta2 → 0.0.10

data/lib/substation/chain/definition.rb

@@ -0,0 +1,147 @@
+# encoding: utf-8
+
+module Substation
+  class Chain
+
+    # Encapsulates an ordered list of {Processor} instances to be used
+    # within an instance of {Chain}
+    class Definition
+
+      include Equalizer.new(:name, :processors)
+      include Enumerable
+
+      # The message for {UnknownProcessor} exceptions
+      UNKNOWN_PROCESSOR_MSG = 'No processor named %s is registered'.freeze
+
+      # The message for {DuplicateProcessorError} exceptions
+      DUPLICATE_PROCESSOR_MSG = 'The following processors already exist within this chain: %s'
+
+      # The name of the chain
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      attr_reader :name
+
+      # The processors used in this instance
+      #
+      # @return [Enumerable<#call>]
+      #
+      # @api private
+      attr_reader :processors
+      protected   :processors
+
+      # Initialize a new instance
+      #
+      # @param [Enumerable<#call>] processors
+      #   the processors to be used within this instance
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def initialize(name, processors)
+        @name, @processors = name, []
+        processors.each(&method(:<<))
+      end
+
+      # Append +processor+ to {#processors}
+      #
+      # @param [#call] processor
+      #   the processor to append
+      #
+      # @return [self]
+      #
+      # @api private
+      def <<(processor)
+        raise_duplicate_processor_error([processor]) if include?(processor)
+        processors << processor
+        self
+      end
+
+      # The following const MUST have #initialize and #<< defined already
+
+      # An empty instance
+      EMPTY = new(nil, EMPTY_ARRAY).freeze
+
+      # Replace the failure chain of the processor identified by +name+
+      #
+      # @param [Symbol] processor_name
+      #   the name of the processor
+      #
+      # @param [Chain] failure_chain
+      #   the failure chain to use in the replaced processor
+      #
+      # @return [self]
+      #
+      # @api private
+      def replace_failure_chain(processor_name, failure_chain)
+        idx = fetch(processor_name)
+        processors[idx] = processors.at(idx).with_failure_chain(failure_chain)
+        self
+      end
+
+      # Iterate over all processors
+      #
+      # @param [Proc] block
+      #   a block passed to #{processors} each method
+      #
+      # @yield [processor]
+      #
+      # @yieldparam [#call] processor
+      #   each processor in this instance
+      #
+      # @return [self]
+      #
+      # @api private
+      def each(&block)
+        return to_enum unless block
+        processors.each(&block)
+        self
+      end
+
+      # Returns a new instance with +other+'s processors prepended
+      #
+      # @param [Definition] other
+      #   the definition to prepend
+      #
+      # @return [Definition]
+      #
+      # @api private
+      def prepend(other)
+        duplicates = processors & other.processors
+        raise_duplicate_processor_error(duplicates) if duplicates.any?
+        self.class.new(name, other.processors | processors)
+      end
+
+      private
+
+      # Return the index for a processor with the given +name+
+      #
+      # @param [Symbol] name
+      #   the processor's name
+      #
+      # @return [Integer]
+      #
+      # @raise [UnknownProcessor]
+      #
+      # @api private
+      def fetch(processor_name)
+        processors.index {|processor| processor.name == processor_name} ||
+          raise(UnknownProcessor, UNKNOWN_PROCESSOR_MSG % processor_name.inspect)
+      end
+
+      # Raise {DuplicateProcessorError} with a message tailored for +dupes+
+      #
+      # @param [Processor, Array<Processor>] dupes
+      #   one or many duplicate processors
+      #
+      # @raise [DuplicateProcessorError]
+      #
+      # @api private
+      def raise_duplicate_processor_error(dupes)
+        raise DuplicateProcessorError, DUPLICATE_PROCESSOR_MSG % dupes.inspect
+      end
+
+    end # class Definition
+  end # class Chain
+end # module Substation

data/lib/substation/chain/dsl.rb

@@ -1,162 +1,200 @@
+# encoding: utf-8
+
 module Substation
   class Chain
 
     # The DSL class used to define chains in an {Environment}
     class DSL
 
-      # The class that builds a DSL class suitable for an {Environment}
-      class Builder
-        include Adamantium::Flat
-
-        # Build a new {DSL} subclass targeted for an {Environment}
-        #
-        # @param [Hash<Symbol, #call>] registry
-        #   the registry of processors used in an {Environment}
-        #
-        # @return [Class<DSL>]
-        #
-        # @api private
-        def self.call(registry)
-          new(registry).dsl
-        end
-
-        # The built DSL subclass
-        #
-        # @return [Class<DSL>]
-        #
-        # @api private
-        attr_reader :dsl
-
-        # Initialize a new instance
-        #
-        # @param [Hash<Symbol, #call>] registry
-        #   the registry of processors used in an {Environment}
-        #
-        # @return [undefined]
-        #
-        # @api private
-        def initialize(registry)
-          @registry = registry
-          @dsl      = compile_dsl
-        end
-
-        private
-
-        # Compile a new DSL class
-        #
-        # @return [Class<DSL>]
-        #
-        # @api private
-        def compile_dsl
-          @registry.each_with_object(Class.new(DSL)) { |(name, processor), dsl|
-            define_dsl_method(name, processor, dsl)
-          }
-        end
-
-
-        # Define a new instance method on the +dsl+ class
-        #
-        # @param [Symbol] name
-        #   the name of the method
-        #
-        # @param [#call] processor
-        #   the processor to use within the chain
-        #
-        # @param [Class<DSL>] dsl
-        #   the {DSL} subclass to define the method on
-        #
-        # @return [undefined]
-        #
-        # @api private
-        def define_dsl_method(name, processor, dsl)
-          dsl.class_eval do
-            define_method(name) do |*args, &block|
-              use(processor.new(env, *args, &block))
-            end
-          end
-        end
-
-      end # class Builder
-
-      # The processors to be used within a {Chain}
-      #
-      # @return [Array<#call>]
+      # Build a new instance suitable for +registry+
+      #
+      # @param [Hash<Symbol, Processor>] registry
+      #   the registry of processor builders to use in a {Chain}
+      #
+      # @param [Definition] definition
+      #   the collection of processors to use in a {Chain}
+      #
+      # @return [DSL]
       #
       # @api private
-      attr_reader :processors
+      def self.build(registry, definition = Definition::EMPTY)
+        new(Config.build(registry), definition)
+      end
 
-      # The processors to be used within a {Chain}
+      include Equalizer.new(:registry, :definition)
+
+      # The chain's name
       #
-      # @param [Environment] env
-      #   the substation environment used to build chains
+      # @return [#to_sym]
       #
-      # @param [Chain] chain
-      #   the chain to build on top of
+      # @api public
+      attr_reader :name
+
+      # The config for this instance
       #
-      # @param [Proc] block
-      #   a block to be instance_eval'ed
+      # @return [Config]
       #
-      # @return [Array<#call>]
+      # @api private
+      attr_reader :config
+
+      # The definition to be used within a {Chain}
+      #
+      # @return [Definition]
       #
       # @api private
-      def self.processors(env, chain, &block)
-        new(env, chain, &block).processors
-      end
+      attr_reader :definition
+
+      # The registry used to build processors
+      #
+      # @return [Hash<Symbol, Processor::Builder>]
+      #
+      # @api private
+      attr_reader :registry
 
       # Initialize a new instance
       #
-      # @param [Environment] env
-      #   the substation environment used to build chains
+      # Extends the new instance with methods defined in +config.dsl_module+.
+      # Only happens during boot, once for every instantiated {Environment}.
       #
-      # @param [#each<#call>] processors
-      #   an enumerable of processors to build on top of
+      # @param [Config] config
+      #   a config for this instance
       #
-      # @param [Proc] block
-      #   a block to be instance_eval'ed
+      # @param [Definition] definition
+      #   the definition to use within a {Chain}
       #
       # @return [undefined]
       #
       # @api private
-      def initialize(env, processors, &block)
-        @env, @processors = env, []
-        chain(processors)
-        instance_eval(&block) if block
+      def initialize(config, definition)
+        @config     = config
+        @definition = definition
+        @registry   = @config.registry
+        @name       = @definition.name
+
+        extend(@config.dsl_module)
       end
 
-      # Use the given +processor+ within a chain
+      # Build a new {Chain} based on +other+, a +failure_chain+ and a block
       #
-      # @param [#call] processor
-      #   a processor to use within a chain
+      # @param [#to_sym] name
+      #   the name of the chain to build
+      #
+      # @param [Enumerable<#call>] other
+      #   the processors to prepend
+      #
+      # @param [Chain] exception_chain
+      #   the chain to invoke in case of an uncaught exception
+      #
+      # @param [Proc] block
+      #   a block to be instance_eval'ed inside the new {DSL} instance
+      #
+      # @return [Chain]
+      #
+      # @api private
+      def build(name, other, exception_chain, &block)
+        Chain.new(__call__(Definition.new(name, other), &block), exception_chain)
+      end
+
+      # Append the given chain
+      #
+      # @param [Enumerable<#call>] processors
+      #   other processors to be nested within a {Definition}
       #
       # @return [self]
       #
       # @api private
-      def use(processor)
-        @processors << processor
+      def chain(processors, &block)
+        processors.each(&method(:use))
+        instance_eval(&block) if block
         self
       end
 
-      # Nest the given chain within another one
+      # Nest the given chain at the end of the current one
+      #
+      # @param [#to_sym] name
+      #   the name of the nested chain
+      #
+      # @param [Enumerable<#call>] chain
+      #   the chain to nest
+      #
+      # @param [Processor::Executor] executor
+      #   the executor used for nesting
+      #
+      # @return [Processor::Nest::Incoming]
+      #
+      # @api private
+      def nest(name, chain, executor)
+        config = Processor::Config.new(executor, EMPTY_ARRAY, EMPTY_ARRAY)
+        use(Processor::Nest::Incoming.new(name, chain, config))
+      end
+
+      # Use +chain+ as the failure chain for the processor identified by +name+
       #
-      # @param [#each<#call>] other
-      #   another chain to be nested within a chain
+      # @param [Symbol] name
+      #   the processor's name
+      #
+      # @param [Chain] failure_chain
+      #   the failure chain to use for the processor identified by +name+
       #
       # @return [self]
       #
       # @api private
-      def chain(other)
-        other.each { |handler| use(handler) }
+      def failure_chain(name, failure_chain)
+        definition.replace_failure_chain(name, failure_chain)
         self
       end
 
       private
 
-      # The substation environment used to build chains
+      # Use the given +processor+ within a chain
+      #
+      # @param [#call] processor
+      #   a processor to use within a chain
       #
-      # @return [Environment]
+      # @return [#call]
+      #   the added processor
       #
       # @api private
-      attr_reader :env
+      def use(processor)
+        definition << processor
+        processor
+      end
+
+      # Return a new definition
+      #
+      # @param [Definition] other
+      #   the definition to prepend
+      #
+      # @param [Proc] block
+      #   a block to be instance_eval'd inside a new {DSL} instance
+      #
+      # @return [Definition]
+      #   the definition to be used with a {Chain}
+      #
+      # @api private
+      def __call__(other, &block)
+        instance = new(other)
+        instance.instance_eval(&block) if block
+        instance.definition
+      end
+
+      # Instantiate a new instance
+      #
+      # @param [Definition] other
+      #   the definition to prepend
+      #
+      # @param [Proc] block
+      #   a block to be instance_eval'd inside a new {DSL} instance
+      #
+      # @return [DSL]
+      #
+      # @api private
+      def new(other)
+        self.class.new(config, other.prepend(definition))
+      end
+
+      # All methods defined in this class body
+      BASE_METHODS = methods.freeze
 
     end # class DSL
   end # class Chain