substation 0.0.9 → 0.0.10.beta2

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
-threshold: 9
-total_score: 134
+threshold: 6
+total_score: 87

data/config/flog.yml

@@ -1,2 +1,2 @@
 ---
-threshold: 13.3
+threshold: 16.4

data/config/mutant.yml

@@ -1,4 +1,3 @@
 ---
 name: substation
 namespace: Substation
-strategy: --rspec-dm2

data/config/reek.yml

@@ -25,10 +25,9 @@ FeatureEnvy:
   enabled: true
   exclude:
   - Substation::Chain#call # loops over instance state
-  - Substation::Processor::Outgoing#respond_with #defined in a module
+  - Substation::Chain::Incoming#result # defined in a module
+  - Substation::Chain::Outgoing#respond_with #defined in a module
   - Substation::Processor::Evaluator#call # method object
-  - Substation::Processor::Evaluator#on_success # method object
-  - Substation::Processor#success? # in a module to be included in a method object
 IrresponsibleModule:
   enabled: true
   exclude: []
@@ -37,8 +36,6 @@ LongParameterList:
   exclude:
   - Substation::Dispatcher#call
   - Substation::Chain::DSL::Builder#define_dsl_method
-  - Substation::Chain#self.failure_response
-  - Substation::Chain#on_failure
   max_params: 2
 LongYieldList:
   enabled: true
@@ -65,8 +62,7 @@ TooManyInstanceVariables:
   max_instance_variables: 3
 TooManyMethods:
   enabled: true
-  exclude:
-  - Substation::Chain::DSL
+  exclude: []
   max_methods: 4
 TooManyStatements:
   enabled: true
@@ -115,7 +111,6 @@ UnusedParameters:
 UtilityFunction:
   enabled: true
   exclude:
-  - Substation::Processor::Outgoing#respond_with # defined in a module
-  - Substation::Processor::Evaluator#on_success # inside a method object
-  - Substation::Processor#success? # in a module to be included in a method object
+  - Substation::Chain::Incoming#result # defined in a module
+  - Substation::Chain::Outgoing#respond_with # defined in a module
   max_helper_calls: 0

data/lib/substation.rb

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 require 'set'
 require 'forwardable'
 
@@ -34,11 +32,8 @@ require 'concord'
 
 module Substation
 
-  # An empty frozen array useful for (default) parameters
-  EMPTY_ARRAY = [].freeze
-
-  # Error raised when trying to access an unknown processor
-  UnknownProcessor = Class.new(StandardError)
+  # Represent an undefined argument
+  Undefined = Object.new.freeze
 
 end
 
@@ -50,8 +45,8 @@ require 'substation/chain'
 require 'substation/chain/dsl'
 require 'substation/processor'
 require 'substation/processor/evaluator'
+require 'substation/processor/pivot'
 require 'substation/processor/wrapper'
-require 'substation/processor/transformer'
 require 'substation/environment'
 require 'substation/environment/dsl'
 require 'substation/dispatcher'

data/lib/substation/chain.rb

@@ -1,19 +1,20 @@
-# encoding: utf-8
-
 module Substation
 
   # Implements a chain of responsibility for an action
   #
   # An instance of this class will typically contain (in that order)
-  # a few processors that process the incoming {Request} object, one
-  # processor that calls an action ({Processor::Pivot}), and some processors
+  # a few handlers that process the incoming {Request} object, one
+  # handler that calls an action ({Chain::Pivot}), and some handlers
   # that process the outgoing {Response} object.
   #
-  # @example chain processors (used in instance method examples)
+  # Both {Chain::Incoming} and {Chain::Outgoing} handlers must
+  # respond to `#call(response)` and `#result(response)`.
+  #
+  # @example chain handlers (used in instance method examples)
   #
   #   module App
   #
-  #     class Processor
+  #     class Handler
   #
   #       def initialize(handler = nil)
   #         @handler = handler
@@ -24,11 +25,11 @@ module Substation
   #       attr_reader :handler
   #
   #       class Incoming < self
-  #         include Substation::Processor::Incoming
+  #         include Substation::Chain::Incoming
   #       end
   #
   #       class Outgoing < self
-  #         include Substation::Processor::Outgoing
+  #         include Substation::Chain::Outgoing
   #
   #         private
   #
@@ -38,13 +39,13 @@ module Substation
   #       end
   #     end
   #
-  #     class Validator < Processor::Incoming
+  #     class Validator < Handler::Incoming
   #       def call(request)
   #         result = handler.call(request.input)
-  #         if result.success?
+  #         if result.valid?
   #           request.success(request.input)
   #         else
-  #           request.error(result.output)
+  #           request.error(result.violations)
   #         end
   #       end
   #     end
@@ -57,7 +58,7 @@ module Substation
   #       end
   #     end
   #
-  #     class Presenter < Processor::Outgoing
+  #     class Presenter < Handler::Outgoing
   #       def call(response)
   #         respond_with(response, handler.new(response.output))
   #       end
@@ -66,97 +67,74 @@ module Substation
   #
   class Chain
 
-    include Enumerable
-    include Concord.new(:processors, :failure_chain)
-    include Adamantium::Flat
-
-    # Empty chain
-    EMPTY = Class.new(self).new(EMPTY_ARRAY, EMPTY_ARRAY)
-
-    # Wraps response data and an exception not caught from a handler
-    class FailureData
-      include Equalizer.new(:data)
+    # Supports chaining handlers processed before the {Pivot}
+    module Incoming
 
-      # Return the data available when +exception+ was raised
-      #
-      # @return [Object]
+      # The request passed on to the next handler in a {Chain}
       #
-      # @api private
-      attr_reader :data
-
-      # Return the exception instance
+      # @param [Response] response
+      #   the response returned from the previous handler in a {Chain}
       #
-      # @return [Class<StandardError>]
+      # @return [Request]
+      #   the request passed on to the next handler in a {Chain}
       #
       # @api private
-      attr_reader :exception
-
-      # Initialize a new instance
-      #
-      # @param [Object] data
-      #   the data available when +exception+ was raised
-      #
-      # @param [Class<StandardError>] exception
-      #   the exception instance raised from a handler
-      #
-      # @return [undefined]
-      #
-      # @api private
-      def initialize(data, exception)
-        @data, @exception = data, exception
+      def result(response)
+        Request.new(response.env, response.output)
       end
+    end
+
+    # Supports chaining the {Pivot} or handlers processed after the {Pivot}
+    module Outgoing
 
-      # Return the hash value
+      # The response passed on to the next handler in a {Chain}
       #
-      # @return [Fixnum]
+      # @param [Response] response
+      #   the response returned from the previous handler in a {Chain}
+      #
+      # @return [Response]
+      #   the response passed on to the next handler in a {Chain}
       #
       # @api private
-      def hash
-        super ^ exception.class.hash
+      def result(response)
+        response
       end
 
       private
 
-      # Tests wether +other+ is comparable using +comparator+
+      # Build a new {Response} based on +response+ and +output+
       #
-      # @param [Symbol] comparator
-      #   the operation used for comparison
+      # @param [Response] response
+      #   the original response
       #
-      # @param [Object] other
-      #   the object to test
+      # @param [Object] output
+      #   the data to be wrapped within the new {Response}
       #
-      # @return [Boolean]
+      # @return [Response]
       #
       # @api private
-      def cmp?(comparator, other)
-        super && exception.class.send(comparator, other.exception.class)
+      def respond_with(response, output)
+        response.class.new(response.request, output)
       end
     end
 
-    # Return a failure response
-    #
-    # @param [Request] request
-    #   the initial request passed into the chain
-    #
-    # @param [Object] data
-    #   the processed data available when the exception was raised
-    #
-    # @param [Class<StandardError>] exception
-    #   the exception instance that was raised
-    #
-    # @return [Response::Failure]
-    #
-    # @api private
-    def self.failure_response(request, data, exception)
-      Response::Failure.new(request, FailureData.new(data, exception))
-    end
+    # Supports chaining the {Pivot} handler
+    Pivot = Outgoing
+
+    include Enumerable
+    include Concord.new(:handlers)
+    include Adamantium::Flat
+    include Pivot # allow nesting of chains
+
+    # Empty chain
+    EMPTY = Class.new(self).new([])
 
     # Call the chain
     #
-    # Invokes all processors and returns either the first
+    # Invokes all handlers and returns either the first
     # {Response::Failure} that it encounters, or if all
     # goes well, the {Response::Success} returned from
-    # the last processor.
+    # the last handler.
     #
     # @example
     #
@@ -184,21 +162,20 @@ module Substation
     #   the request to handle
     #
     # @return [Response::Success]
-    #   the response returned from the last processor
+    #   the response returned from the last handler
     #
     # @return [Response::Failure]
-    #   the response returned from the failing processor's failure chain
+    #   the response returned from the failing handler
+    #
+    # @raise [Exception]
+    #   any exception that isn't explicitly rescued in client code
     #
     # @api public
     def call(request)
-      processors.reduce(request) { |result, processor|
-        begin
-          response = processor.call(result)
-          return response unless processor.success?(response)
-          processor.result(response)
-        rescue => exception
-          return on_failure(request, result, exception)
-        end
+      handlers.inject(request) { |result, handler|
+        response = handler.call(result)
+        return response unless response.success?
+        handler.result(response)
       }
     end
 
@@ -217,29 +194,8 @@ module Substation
     # @api private
     def each(&block)
       return to_enum unless block
-      processors.each(&block)
+      handlers.each(&block)
       self
     end
-
-    private
-
-    # Call the failure chain in case of an uncaught exception
-    #
-    # @param [Request] request
-    #   the initial request passed into the chain
-    #
-    # @param [Object] data
-    #   the processed data available when the exception was raised
-    #
-    # @param [Class<StandardError>] exception
-    #   the exception instance that was raised
-    #
-    # @return [Response::Failure]
-    #
-    # @api private
-    def on_failure(request, data, exception)
-      failure_chain.call(self.class.failure_response(request, data, exception))
-    end
-
   end # class Chain
 end # module Substation

data/lib/substation/chain/dsl.rb

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 module Substation
   class Chain
 
@@ -55,6 +53,7 @@ module Substation
           }
         end
 
+
         # Define a new instance method on the +dsl+ class
         #
         # @param [Symbol] name
@@ -71,36 +70,46 @@ module Substation
         # @api private
         def define_dsl_method(name, processor, dsl)
           dsl.class_eval do
-            define_method(name) { |*args| use(processor.new(name, *args)) }
+            define_method(name) do |*args, &block|
+              use(processor.new(env, *args, &block))
+            end
           end
         end
 
       end # class Builder
 
-      # Build a new {Chain} based on +other+, a +failure_chain+ and a block
+      # The processors to be used within a {Chain}
       #
-      # @param [#each<#call>] other
-      #   the processors to build on top of
+      # @return [Array<#call>]
+      #
+      # @api private
+      attr_reader :processors
+
+      # The processors to be used within a {Chain}
+      #
+      # @param [Environment] env
+      #   the substation environment used to build chains
       #
-      # @param [Chain] failure_chain
-      #   the failure chain to invoke in case of an uncaught exception
+      # @param [Chain] chain
+      #   the chain to build on top of
       #
       # @param [Proc] block
       #   a block to be instance_eval'ed
       #
-      # @return [Chain]
+      # @return [Array<#call>]
       #
       # @api private
-      def self.build(other, failure_chain, &block)
-        Chain.new(new(other, &block).processors, failure_chain)
+      def self.processors(env, chain, &block)
+        new(env, chain, &block).processors
       end
 
-      include Equalizer.new(:processors)
-
       # Initialize a new instance
       #
+      # @param [Environment] env
+      #   the substation environment used to build chains
+      #
       # @param [#each<#call>] processors
-      #   the processors to build on top of
+      #   an enumerable of processors to build on top of
       #
       # @param [Proc] block
       #   a block to be instance_eval'ed
@@ -108,21 +117,12 @@ module Substation
       # @return [undefined]
       #
       # @api private
-      def initialize(processors, &block)
-        @processors = {}
+      def initialize(env, processors, &block)
+        @env, @processors = env, []
         chain(processors)
         instance_eval(&block) if block
       end
 
-      # The processors to be used within a {Chain}
-      #
-      # @return [Array<#call>]
-      #
-      # @api private
-      def processors
-        @processors.values
-      end
-
       # Use the given +processor+ within a chain
       #
       # @param [#call] processor
@@ -132,7 +132,7 @@ module Substation
       #
       # @api private
       def use(processor)
-        @processors[processor.name] = processor
+        @processors << processor
         self
       end
 
@@ -145,45 +145,18 @@ module Substation
       #
       # @api private
       def chain(other)
-        other.each { |processor| use(processor) }
-        self
-      end
-
-      # Use +chain+ as the failure chain for the processor identified by +name+
-      #
-      # @param [Symbol] name
-      #   the processor's name
-      #
-      # @param [#call] chain
-      #   the failure chain to use for the processor identified by +name+
-      #
-      # @return [self]
-      #
-      # @api private
-      def failure_chain(name, chain)
-        @processors[name] = processor(name).with_failure_chain(chain)
+        other.each { |handler| use(handler) }
         self
       end
 
       private
 
-      # Return the processor identified by +name+
-      #
-      # @param [Symbol] name
-      #   the processor's name
+      # The substation environment used to build chains
       #
-      # @return [#call]
-      #   the processor identified by +name+
-      #
-      # @raise [UnknownProcessor]
-      #   if no processor identified by +name+ is registered
+      # @return [Environment]
       #
       # @api private
-      def processor(name)
-        @processors.fetch(name) {
-          raise UnknownProcessor, "No processor named #{name.inspect} is registered"
-        }
-      end
+      attr_reader :env
 
     end # class DSL
   end # class Chain