substation 0.0.10.beta2 → 0.0.10

data/lib/substation/chain/dsl/config.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+module Substation
+  class Chain
+    class DSL
+
+      # A configuration object used with a {DSL} instance
+      class Config
+
+        # Build a new config based on {registry} suitable for a {DSL} instance
+        #
+        # @param [Hash<Symbol, Processor::Builder>] registry
+        #   the registry of processor builders used in an {Environment}
+        #
+        # @return [Config]
+        #
+        # @api private
+        def self.build(registry)
+          new(registry, ModuleBuilder.call(registry))
+        end
+
+        include Equalizer.new(:registry)
+
+        # The registry of processor builders
+        #
+        # @return [Hash<Symbol, Processor::Builder>]
+        #
+        # @api private
+        attr_reader :registry
+
+        # A module exposing methods to build processors defined in {registry}
+        #
+        # @return [Module]
+        #
+        # @api private
+        attr_reader :dsl_module
+
+        # Initialize a new instance
+        #
+        # @param [Hash<Symbol, Processor::Builder>] registry
+        #   the registry of processor builder instances
+        #
+        # @param [Module] dsl_module
+        #   the module built by {Builder}, suitable for +registry+
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize(registry, dsl_module)
+          @registry, @dsl_module = registry, dsl_module
+        end
+      end # class Config
+    end # class DSL
+  end # class Chain
+end # module Substation

data/lib/substation/chain/dsl/module_builder.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+
+module Substation
+  class Chain
+    class DSL
+
+      # Builds a {Module} suitable for a {DSL} instance
+      class ModuleBuilder
+
+        # Builds a new {Module} targeted for a {DSL} instance
+        #
+        # @param [Hash<Symbol, Processor::Builder>] registry
+        #   the registry of processor builders used in an {Environment}
+        #
+        # @return [Module]
+        #
+        # @api private
+        def self.call(registry)
+          new(registry).dsl_module
+        end
+
+        include Adamantium::Flat
+
+        # A module suitable for inclusion in a {DSL} instance
+        #
+        # @return [Module]
+        #
+        # @api private
+        attr_reader :dsl_module
+
+        # Initialize a new instance
+        #
+        # @param [Hash<Symbol, Processor::Builder>] registry
+        #   the registry of processor builders to define methods for
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize(registry)
+          @registry   = registry
+          @dsl_module = Module.new
+          initialize_dsl_module
+        end
+
+        private
+
+        # Compile a new module for inclusion into a {DSL} instance
+        #
+        # @param [Hash<Symbol, Processor::Builder>] registry
+        #   the registry of processor builders to define methods for
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize_dsl_module
+          @registry.each { |pair| define_dsl_method(*pair) }
+        end
+
+        # Define a new instance method on the +dsl+ module
+        #
+        # @param [Symbol] name
+        #   the name of the method
+        #
+        # @param [Processor::Builder] builder
+        #   the processor builder to use within the chain
+        #
+        # @param [Module] dsl
+        #   the module to define the method on
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def define_dsl_method(name, builder)
+          @dsl_module.module_eval do
+            define_method(name) { |handler, failure_chain = EMPTY, observers = EMPTY_ARRAY|
+              use(builder.call(handler, failure_chain, observers))
+            }
+          end
+        end
+
+      end # class ModuleBuilder
+    end # class DSL
+  end # class Chain
+end # module Substation

data/lib/substation/dispatcher.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Substation
 
   # Encapsulates all registered actions and their observers
@@ -7,207 +9,20 @@ module Substation
   # application use case.
   class Dispatcher
 
-    # Encapsulates access to one registered action
-    class Action
-
-      # Raised when no action class name is configured
-      MissingHandlerError = Class.new(StandardError)
-
-      # Coerce the given +name+ and +config+ to an {Action} instance
-      #
-      # @param [#call, Hash<Symbol, Object>] config
-      #   the action configuration object
-      #
-      # @return [Action]
-      #   the coerced instance
-      #
-      # @raise [MissingHandlerError]
-      #   if no action handler is configured
-      #
-      # @raise [ArgumentError]
-      #   if action or observer handlers are not coercible
-      #
-      # @api private
-      def self.coerce(config)
-        if config.respond_to?(:fetch)
-          action   = config.fetch(:action) { raise(MissingHandlerError) }
-          observer = config[:observer]
-        else
-          action = config
-        end
-
-        action_handler   = Utils.coerce_callable(action)
-        observer_handler = Observer.coerce(observer)
-
-        new(action_handler, observer_handler)
-      end
-
-      include Concord.new(:handler, :observer)
-      include Adamantium::Flat
-
-      # Call the action
-      #
-      # @param [Substation::Request] request
-      #   the request passed to the registered action
-      #
-      # @return [Substation::Response]
-      #   the response returned when calling the action
-      #
-      # @api private
-      def call(request)
-        response = handler.call(request)
-        observer.call(response)
-        response
-      end
-
-    end # class Action
+    include Concord.new(:actions, :env)
+    include Adamantium::Flat
 
-    # Raised when trying to dispatch to an unregistered action
-    UnknownActionError = Class.new(StandardError)
+    GUARD = DSL::Guard.new(EMPTY_ARRAY)
 
-    # Coerce the given +config+ to a {Dispatcher} instance
-    #
-    # @example setup code for all the other examples
-    #
-    #   module App
-    #     class Environment
-    #       def initialize(storage, logger)
-    #         @storage, @logger = storage, logger
-    #       end
-    #     end
-    #
-    #     class SomeUseCase
-    #       def self.call(request)
-    #         data = perform_work
-    #         request.success(data)
-    #       end
-    #     end
-    #
-    #     class SomeObserver
-    #       def self.call(response)
-    #         # do something
-    #       end
-    #     end
-    #
-    #     class AnotherObserver
-    #       def self.call(response)
-    #         # do something
-    #       end
-    #     end
-    #   end
-    #
-    #   storage = SomeStorageAbstraction.new
-    #   env     = App::Environment.new(storage, Logger.new($stdout))
-    #
-    # @example without observers (short form, symbol keys)
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => App::SomeUseCase
-    #   }, env)
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => 'App::SomeUseCase'
-    #   }, env)
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => :App::SomeUseCase
-    #   }, env)
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => Proc.new { |request| request.success(:data) }
-    #   }, env)
-    #
-    # @example without observers (long form, string keys)
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     'some_use_case' => { 'action' => 'SomeUseCase' }
-    #   }, env)
-    #
-    # @example with a single observer
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     'some_use_case' => {
-    #       'action' => 'App::SomeUseCase',
-    #       'observer' => 'App::SomeObserver'
-    #     }
-    #   }, env)
-    #
-    # @example with multiple observers
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     'some_use_case' => {
-    #       'action' => 'App::SomeUseCase',
-    #       'observer' => [
-    #         'App::SomeObserver',
-    #         'App::AnotherObserver'
-    #       ]
-    #     }
-    #   }, env)
-    #
-    # @example with Symbol keys and const handlers
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => {
-    #       :action   => App::SomeUseCase,
-    #       :observer => App::SomeObserver
-    #     }
-    #   }, env)
+    # Return a new registry instance suitable for {Dispatcher}
     #
-    # @example with Symbol keys and proc handlers
-    #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => {
-    #       :action   => Proc.new { |request| request.success(:foo) },
-    #       :observer => Proc.new { |response| do_something }
-    #     }
-    #   }, env)
-    #
-    # @param [Hash<#to_sym, Object>] config
-    #   the action configuration
-    #
-    # @param [Object] env
-    #   the application environment
-    #
-    # @return [Dispatcher]
-    #   the coerced instance
-    #
-    # @raise [Action::MissingHandlerError]
-    #   if no action handler is configured
-    #
-    # @raise [ArgumentError]
-    #   if action or observer handlers are not coercible
-    #
-    # @api public
-    def self.coerce(config, env)
-      new(normalize_config(config), env)
-    end
-
-    # Normalize the given +config+
-    #
-    # @param [Hash<#to_sym, Object>] config
-    #   the action configuration
-    #
-    # @return [Hash<Symbol, Action>]
-    #   the normalized config hash
-    #
-    # @raise [Action::MissingHandlerError]
-    #   if no action handler is configured
-    #
-    # @raise [ArgumentError]
-    #   if action or observer handlers are not coercible
+    # @return [DSL::Registry]
     #
     # @api private
-    def self.normalize_config(config)
-      Utils.symbolize_keys(config).each_with_object({}) { |(name, action), actions|
-        actions[name] = Action.coerce(action)
-      }
+    def self.new_registry
+      DSL::Registry.new(GUARD)
     end
 
-    private_class_method :normalize_config
-
-    include Concord.new(:actions, :env)
-    include Adamantium::Flat
-
     # Invoke the action identified by +name+
     #
     # @example
@@ -249,45 +64,21 @@ module Substation
     #
     # @api public
     def call(name, input)
-      fetch(name).call(Request.new(env, input))
+      fetch(name).call(Request.new(name, env, input))
     end
 
-    # The names of all registered actions
+    # Test wether a chain with the given +name+ is registered
     #
-    # @example
-    #
-    #   module App
-    #     class Environment
-    #       def initialize(storage, logger)
-    #         @storage, @logger = storage, logger
-    #       end
-    #     end
-    #
-    #     class SomeUseCase
-    #       def self.call(request)
-    #         data = perform_work
-    #         request.success(data)
-    #       end
-    #     end
-    #   end
-    #
-    #   storage    = SomeStorageAbstraction.new
-    #   env        = App::Environment.new(storage, Logger.new($stdout))
-    #   config     = { :some_use_case => { :action => App::SomeUseCase } }
-    #   dispatcher = Substation::Dispatcher.coerce(config, env)
-    #
-    #   dispatcher.action_names # => #<Set: {:some_use_case}>
+    # @param [Symbol] name
+    #   the name of the chain to test for
     #
-    # @return [Set<Symbol>]
-    #   the set of registered action names
+    # @return [Boolean]
     #
-    # @api public
-    def action_names
-      Set.new(actions.keys)
+    # @api private
+    def include?(name)
+      actions.include?(name)
     end
 
-    memoize :action_names
-
     private
 
     # The action registered with +name+
@@ -295,10 +86,10 @@ module Substation
     # @param [Symbol] name
     #   a name for which an action is registered
     #
-    # @return [Action]
-    #   the action configuration registered for +name+
+    # @return [#call]
+    #   the callable registered for +name+
     #
-    # @raise [KeyError]
+    # @raise [UnknownActionError]
     #   if no action is registered with +name+
     #
     # @api private

data/lib/substation/dsl/guard.rb

@@ -0,0 +1,96 @@
+# encoding: utf-8
+
+module Substation
+  module DSL
+
+    # A guard used for rejecting invalid names in {DSL}
+    class Guard
+
+      include Equalizer.new(:reserved_names)
+      include Adamantium::Flat
+
+      # Message for ReservedNameError
+      RESERVED_NAME_MSG = '%s is a reserved name'.freeze
+
+      # Message for AlreadyRegisteredError
+      ALREADY_REGISTERED_MSG = '%s is already registered'.freeze
+
+      # The list of reserved names
+      #
+      # @return [Enumerable<Symbol>]
+      #
+      # @api private
+      attr_reader :reserved_names
+      private     :reserved_names
+
+      # Initialize a new instance
+      #
+      # @param [Enumerable<Symbol>] reserved_names
+      #   a list of reserved names
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def initialize(reserved_names = EMPTY_ARRAY)
+        @reserved_names = reserved_names
+      end
+
+      # Raise if {#name} is either reserved or already registered
+      #
+      # @param [Symbol] name
+      #   the name to test
+      #
+      # @param [#include?] registry
+      #   the registry to test
+      #
+      # @raise [AlreadyRegisteredError]
+      #   if +name+ is already registered
+      #
+      # @raise [ReservedNameError]
+      #   if +name+ is a reserved name
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def call(name, registry)
+        raise_if_already_registered(name, registry)
+        raise_if_reserved(name)
+      end
+
+      private
+
+      # Raise if +name+ is already included in {#names}
+      #
+      # @param [Symbol] name
+      #   the name to test
+      #
+      # @raise [AlreadyRegisteredError]
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def raise_if_already_registered(name, registry)
+        if registry.include?(name)
+          raise AlreadyRegisteredError, ALREADY_REGISTERED_MSG % name.inspect
+        end
+      end
+
+      # Raise if {Chain::DSL.methods} include +name+
+      #
+      # @param [Symbol] name
+      #   the name to test
+      #
+      # @raise [ReservedNameError]
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def raise_if_reserved(name)
+        if reserved_names.include?(name)
+          raise ReservedNameError, RESERVED_NAME_MSG % name.inspect
+        end
+      end
+
+    end # class Guard
+  end # module DSL
+end # module Substation