substation 0.0.10.beta2 → 0.0.10

data/lib/substation/dsl/registry.rb

@@ -0,0 +1,181 @@
+# encoding: utf-8
+
+module Substation
+  module DSL
+
+    # A mutable registry for objects collected with DSL classes
+    class Registry
+
+      include Equalizer.new(:guard, :entries)
+      include Enumerable
+
+      # Coerce +name+ into a Symbol
+      #
+      # @param [#to_sym] name
+      #   the name to coerce
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def self.coerce_name(name)
+        name.to_sym
+      end
+
+      # The guard responsible for rejecting invalid entries
+      #
+      # @return [Guard]
+      #
+      # @api private
+      attr_reader :guard
+      protected   :guard
+
+      # The entries this registry stores
+      #
+      # @return [Hash<Symbol, Object>]
+      #
+      # @api private
+      attr_reader :entries
+      protected   :entries
+
+      # Initialize a new instance
+      #
+      # @param [Guard] guard
+      #   the guard to use for rejecting invalid entries
+      #
+      # @param [Hash<Symbol, Object>] entires
+      #   the entries this registry stores
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def initialize(guard, entries = EMPTY_HASH)
+        @guard, @entries = guard, entries.dup
+      end
+
+      # Iterate over all entries
+      #
+      # @param [Proc] block
+      #   the block passed to #{entries}.each
+      #
+      # @yield [name, object]
+      #
+      # @yieldparam [Symbol] name
+      #   the name of the current entry
+      #
+      # @yieldparam [Object] object
+      #   the object registered by name
+      #
+      # @return [self]
+      #
+      # @api private
+      def each(&block)
+        return to_enum unless block
+        entries.each(&block)
+        self
+      end
+
+      # Return a new instance with +other+ merged in
+      #
+      # @param [Registry] other
+      #   the registry to merge
+      #
+      # @raise [AlreadyRegisteredError]
+      #   if any object in +other+ is already registered by the same
+      #   name in +self+
+      #
+      # @return [Registry]
+      #   the new, merged instance
+      #
+      # @api private
+      def merge(other)
+        other.each_with_object(new) { |(name, object), merged|
+          merged[name] = object
+        }
+      end
+
+      # Register +object+ by +name+
+      #
+      # @param [#to_sym] name
+      #   the name to register object with
+      #
+      # @param [Object] object
+      #   the object to register by +name+
+      #
+      # @raise [AlreadyRegisteredError]
+      #   if +object+ is already registered by the same +name+
+      #
+      # @raise [ReservedNameError]
+      #   if +object+ should be registered using a reserved +name+
+      #
+      # @return [Object]
+      #   the registered object
+      #
+      # @api private
+      def []=(name, object)
+        coerced_name = coerce_name(name)
+        guard.call(coerced_name, entries)
+        entries[coerced_name] = object
+      end
+
+      # Test wether an object is registered by +name+
+      #
+      # @param [#to_sym] name
+      #   the name to test
+      #
+      # @return [Boolean]
+      #   true if an object is registered, false otherwise
+      #
+      # @api private
+      def include?(name)
+        entries.include?(coerce_name(name))
+      end
+
+      # Return the object registered by +name+ or the value returned from +block+
+      #
+      # @param [#to_sym] name
+      #   the name of the object to fetch
+      #
+      # @param [Proc] block
+      #   the block to invoke if no object is registered by +name+
+      #
+      # @return [Object]
+      #
+      # @api private
+      def fetch(name, &block)
+        entries.fetch(coerce_name(name), &block)
+      end
+
+      # Return all names by which objects are registered
+      #
+      # @return [Array<Symbol>]
+      #
+      # @api private
+      def keys
+        entries.keys
+      end
+
+      private
+
+      # Coerce +name+ into a Symbol
+      #
+      # @param [#to_sym] name
+      #   the name to coerce
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def coerce_name(name)
+        self.class.coerce_name(name)
+      end
+
+      # Return a new instance with {#guard} and {#entries}
+      #
+      # @return [Registry]
+      #
+      # @api private
+      def new
+        self.class.new(guard, entries)
+      end
+    end # class Registry
+  end # module DSL
+end # module Substation

data/lib/substation/environment.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Substation
 
   # The environment holding all registered {Chain} processors
@@ -8,69 +10,170 @@ module Substation
 
     # Build a new {Environment} instance
     #
+    # @param [Object] app_env
+    #   the application environment
+    #
+    # @param [Dispatcher::Registry] actions
+    #   a mutable action registry
+    #
     # @param [Proc] block
     #   a block to be instance_eval'ed with {DSL}
     #
     # @return [Environment]
     #
     # @api private
-    def self.build(&block)
-      new(DSL.registry(&block))
+    def self.build(app_env, actions = Dispatcher.new_registry, &block)
+      new(app_env, actions, chain_dsl(&block))
+    end
+
+    # Build a new {Chain::DSL} instance
+    #
+    # @param [Proc] block
+    #   a block to be instance_eval'ed in {DSL}
+    #
+    # @return {Chain::DSL}
+    #
+    # @api private
+    def self.chain_dsl(&block)
+      Chain::DSL.build(DSL.registry(&block))
     end
 
+    private_class_method :chain_dsl
+
+    # The application environment
+    #
+    # @return [Object]
+    #
+    # @api private
+    attr_reader :app_env
+
+    # The mutable action registry
+    #
+    # @return [Dispatcher::Registry]
+    #
+    # @api private
+    attr_reader :actions
+
+    # The registry used by this {Environment}
+    #
+    # @return [Hash<Symbol, Processor::Builder>]
+    #
+    # @api private
+    attr_reader :registry
+    protected   :registry
+
     # Initialize a new instance
     #
-    # @param [Hash<Symbol, #call>] registry
-    #   the registry of processors
+    # @param [Chain::DSL] chain_dsl
+    #   the chain dsl tailored for the environment
     #
     # @return [undefined]
     #
     # @api private
-    def initialize(registry)
-      @registry  = registry
-      @chain_dsl = Chain::DSL::Builder.call(@registry)
+    def initialize(app_env, actions, chain_dsl)
+      @app_env   = app_env
+      @actions   = actions
+      @chain_dsl = chain_dsl
+      @registry  = chain_dsl.registry
+    end
+
+    # Inherit a new instance from self, merging the {Chain::DSL}
+    #
+    # @param [Dispatcher::Registry] actions
+    #   the mutable action registry
+    #
+    # @param [Proc] block
+    #   a block to instance_eval inside a {DSL} instance
+    #
+    # @return [Environment]
+    #
+    # @api private
+    def inherit(app_env = app_env, actions = Dispatcher.new_registry, &block)
+      self.class.new(app_env, actions, merged_chain_dsl(&block))
     end
 
     # Build a new {Chain} instance
     #
+    # @param [#to_sym] name
+    #   the new chain's name
+    #
     # @param [Chain] other
     #   the optional chain to build on top of
     #
+    # @param [Chain] exception_chain
+    #   the chain to invoke in case of an uncaught exceptions in handlers
+    #
     # @param [Proc] block
     #   a block to be instance_eval'ed in {Chain::DSL}
     #
     # @return [Chain]
     #
     # @api private
-    def chain(other = Chain::EMPTY, &block)
-      Chain.new(processors(other, &block))
+    def chain(name = nil, other = Chain::EMPTY, exception_chain = Chain::EMPTY, &block)
+      @chain_dsl.build(name, other, exception_chain, &block)
     end
 
-    protected
-
-    # The registry used by this {Environment}
+    # Register a new chain under the given +name+
+    #
+    # @param [#to_sym] name
+    #   the new chain's name
     #
-    # @return [Hash<Symbol, #call>]
+    # @param [Chain] other
+    #   the chain to build on top of
+    #
+    # @param [Chain] exception_chain
+    #   the chain to invoke in case of uncaught exceptions in handlers
+    #
+    # @return [Chain]
+    #   the registered chain
     #
     # @api private
-    attr_reader :registry
+    def register(name, other = Chain::EMPTY, exception_chain = Chain::EMPTY, &block)
+      actions[name] = chain(name, other, exception_chain, &block)
+      self
+    end
 
-    private
+    # Return the chain identified by +name+ or raise an error
+    #
+    # @param [name]
+    #   the name of the chain to retrieve
+    #
+    # @return [Chain]
+    #
+    # @raise [UnknownActionError]
+    #   if no chain is registered under +name+
+    #
+    # @api private
+    def [](name)
+      actions.fetch(name)
+    end
 
-    # The processors collected via the chain dsl instance
+    # Build a new {Dispatcher} instance
     #
-    # @param [Chain] other
-    #   another chain to build upon
+    # @see Dispatcher.new
     #
-    # @param [Proc] block
-    #   the block to pass to {Chain::DSL#processors}
+    # @param [Object] env
+    #   the application environment
     #
-    # @return [Hash<Symbol, #call>]
+    # @return [Dispatcher]
     #
     # @api private
-    def processors(other, &block)
-      @chain_dsl.processors(self, other, &block)
+    def dispatcher
+      Dispatcher.new(actions, app_env)
     end
 
+    private
+
+    # Return a new {Chain::DSL} by merging in +other.registry+
+    #
+    # @param [Environment] other
+    #   the other environment providing the registry to merge
+    #
+    # @return [Chain::DSL]
+    #
+    # @api private
+    def merged_chain_dsl(&block)
+      Chain::DSL.build(registry.merge(DSL.registry(&block)))
+    end
   end # class Environment
 end # module Substation

data/lib/substation/environment/dsl.rb

@@ -1,27 +1,39 @@
+# encoding: utf-8
+
 module Substation
   class Environment
 
-    # The DSL class used to define register processors
+    # The DSL class used to register processor builders
     class DSL
 
-      # The registry of processors
+      # Rejects already registered and reserved names
+      GUARD = Substation::DSL::Guard.new(Chain::DSL::BASE_METHODS)
+
+      # The registry of processor builders
       #
-      # @return [Hash<Symbol, #call>]
+      # @return [Hash<Symbol, Processor::Builder>]
       #
       # @api private
       attr_reader :registry
 
+      # The guard to use for rejecting invalid names
+      #
+      # @return [Guard]
+      #
+      # @api private
+      attr_reader :guard
+      private     :guard
 
-      # The registry of processors
+      # The registry of processor builders
       #
       # @param [Proc] block
       #   a block to be instance_eval'ed
       #
-      # @return [Hash<Symbol, #call>]
+      # @return [Hash<Symbol, Processor::Builder>]
       #
       # @api private
-      def self.registry(&block)
-        new(&block).registry
+      def self.registry(guard = GUARD, &block)
+        new(Substation::DSL::Registry.new(guard), &block).registry
       end
 
       # Initialize a new instance
@@ -32,12 +44,12 @@ module Substation
       # @return [undefined]
       #
       # @api private
-      def initialize(&block)
-        @registry = {}
+      def initialize(registry, &block)
+        @registry = registry
         instance_eval(&block) if block
       end
 
-      # Register a new +processor+ using the given +name+
+      # Register a new +processor+ using the given +name+ and +executor+
       #
       # @param [#to_sym] name
       #   the name to register the +processor+ for
@@ -45,11 +57,18 @@ module Substation
       # @param [#call] processor
       #   the processor to register for +name+
       #
+      # @param [Processor::Executor] executor
+      #   the executor for +processor+
+      #
       # @return [self]
       #
       # @api private
-      def register(name, processor)
-        @registry[name] = processor
+      def register(name, processor, executor = Processor::Executor::NULL)
+        coerced_name = name.to_sym
+
+        registry[coerced_name] =
+          Processor::Builder.new(coerced_name, processor, executor)
+
         self
       end