substation 0.0.10.beta2 → 0.0.10

data/TODO.md

@@ -0,0 +1 @@
+* Introduce DSL::Data and DSL::Data::Mutable to simplify DSL implementations

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
-threshold: 6
-total_score: 87
+threshold: 12 # TODO bring it back to 11 by collapsing the dsl registries
+total_score: 207

data/config/flog.yml

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

data/config/reek.yml

@@ -10,24 +10,32 @@ ClassVariable:
   exclude: []
 ControlParameter:
   enabled: true
-  exclude: []
+  exclude:
+  - Substation::DSL::Guard#raise_if_already_registered
 DataClump:
   enabled: true
-  exclude: []
+  exclude:
+  - Substation::Processor::Evaluator # FIXME
   max_copies: 2
   min_clump_size: 2
 DuplicateMethodCall:
   enabled: true
-  exclude: []
+  exclude:
+  - !ruby/regexp /^Substation::DSL::Registry#\[\]=$/ # reek won't emit this anymore soon
+  - Substation::Chain::Definition#prepend # reek won't emit this anymore soon
+  - Substation::Chain::Definition#replace_failure_chain # replaces object at given idx inside an array
+  - Substation::Processor::Nest::Incoming#call # calls a private method in a case expression
   max_calls: 1
   allow_calls: []
 FeatureEnvy:
   enabled: true
   exclude:
   - Substation::Chain#call # loops over instance state
-  - Substation::Chain::Incoming#result # defined in a module
-  - Substation::Chain::Outgoing#respond_with #defined in a module
+  - Substation::Processor::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
+  - Substation::Chain::DSL#__call__ # relies heavily on #new(other)
 IrresponsibleModule:
   enabled: true
   exclude: []
@@ -35,8 +43,7 @@ LongParameterList:
   enabled: true
   exclude:
   - Substation::Dispatcher#call
-  - Substation::Chain::DSL::Builder#define_dsl_method
-  max_params: 2
+  max_params: 3
 LongYieldList:
   enabled: true
   exclude: []
@@ -44,7 +51,7 @@ LongYieldList:
 NestedIterators:
   enabled: true
   exclude:
-  - Substation::Chain::DSL::Builder#define_dsl_method
+  - Substation::Chain::DSL::ModuleBuilder#define_dsl_method
   max_allowed_nesting: 1
   ignore_iterators: []
 NilCheck:
@@ -52,27 +59,41 @@ NilCheck:
   exclude: []
 RepeatedConditional:
   enabled: true
-  exclude: []
+  exclude:
+  - Substation::Chain::DSL
   max_ifs: 1
 TooManyInstanceVariables:
   enabled: true
   exclude:
   - Substation::Response
   - Substation::Processor::Evaluator
+  - Substation::Environment # 4
+  - Substation::Chain::Definition # 4
+  - Substation::Chain::DSL # 4
   max_instance_variables: 3
 TooManyMethods:
   enabled: true
-  exclude: []
+  exclude:
+  - Substation::Chain::DSL # 7
+  - Substation::Chain::Definition # 8
+  - Substation::Environment # 5
+  - Substation::DSL::Registry # 10
   max_methods: 4
 TooManyStatements:
   enabled: true
   exclude:
-  - Substation::Utils#self.const_get
-  - Substation::Utils#self.symbolize_keys
-  - Substation::Dispatcher::Action#self.coerce
   - Substation::Chain#call
-  - Substation::Utils#self.coerce_callable
   - Substation::Processor::Evaluator#call
+  - Substation::Dispatcher::DSL#dispatch
+  - Substation::Environment#self.build # ~5
+  - Substation::Environment::DSL#register # 4
+  - Substation::Chain::Definition#<< # 4
+  - Substation::Chain::Definition#initialize # 4
+  - Substation::Chain::DSL#initialize # 5
+  - Substation::Environment#initialize # 4
+  - Substation::Processor#initialize # 6
+  - Substation::Processor::Nest::Incoming#call # 4
+  - Substation::Response#initialize # 4
   max_statements: 3
 UncommunicativeMethodName:
   enabled: true
@@ -111,6 +132,10 @@ UnusedParameters:
 UtilityFunction:
   enabled: true
   exclude:
-  - Substation::Chain::Incoming#result # defined in a module
-  - Substation::Chain::Outgoing#respond_with # defined in a module
+  - Substation::Processor::Outgoing#respond_with # defined in a module
+  - Substation::Processor::Evaluator::Handler#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::Environment#action # DSL method
+  - Substation::Environment#dispatcher # DSL method
   max_helper_calls: 0

data/config/rubocop.yml

@@ -0,0 +1,44 @@
+AllCops:
+  Includes:
+    - '../**/*.rake'
+  Excludes:
+    - '../spec/spec_helper.rb'
+
+# Avoid parameter lists longer than five parameters.
+ParameterLists:
+  Max: 3
+  CountKeywordArgs: true
+
+# Avoid more than `Max` levels of nesting.
+BlockNesting:
+  Max: 3
+
+HashSyntax:
+  Enabled: false
+
+Blocks:
+  Enabled: false
+
+SpaceInsideBrackets:
+  Enabled: false
+
+Documentation:
+  Enabled: false # reek already checks this and rubocop requires duplicate docs
+
+SingleLineMethods:
+  Enabled: false
+
+LineLength:
+  Max: 114 # the offending lines are in specs, sadly this means global disabling for now
+
+MethodLength:
+  Max: 12 # reek performs these checks anyway
+
+CaseIndentation:
+  Enabled: false
+
+Lambda:
+  Enabled: false # i personally like the look of multiline ->(arg) {} lambdas
+
+IfUnlessModifier:
+  Enabled: false # i have no strong opinion but i won't let it force me to go over the col limit

data/config/yardstick.yml

@@ -1,2 +1,2 @@
 ---
-threshold: 100.0
+threshold: 99.0

data/lib/substation.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 require 'set'
 require 'forwardable'
 
@@ -35,18 +37,52 @@ module Substation
   # Represent an undefined argument
   Undefined = Object.new.freeze
 
+  # An empty frozen array useful for (default) parameters
+  EMPTY_ARRAY = [].freeze
+
+  # An empty frozen hash useful for (default) parameters
+  EMPTY_HASH = {}.freeze
+
+  # Error raised when trying to access an unknown processor
+  UnknownProcessor = Class.new(StandardError)
+
+  # Raised when trying to dispatch to an unregistered action
+  UnknownActionError = Class.new(StandardError)
+
+  # Raised when an object is already registered under the a given name
+  AlreadyRegisteredError = Class.new(StandardError)
+
+  # Raised when a reserved method is being given
+  ReservedNameError = Class.new(StandardError)
+
+  # Raised when a duplicate {Processor} should be registered within a {Chain}
+  DuplicateProcessorError = Class.new(StandardError)
 end
 
-require 'substation/utils'
 require 'substation/request'
 require 'substation/response'
-require 'substation/observer'
-require 'substation/chain'
-require 'substation/chain/dsl'
+require 'substation/response/api'
+require 'substation/response/success'
+require 'substation/response/failure'
+require 'substation/response/exception'
+require 'substation/response/exception/output'
 require 'substation/processor'
+require 'substation/processor/builder'
+require 'substation/processor/config'
+require 'substation/processor/executor'
 require 'substation/processor/evaluator'
-require 'substation/processor/pivot'
+require 'substation/processor/evaluator/result'
+require 'substation/processor/evaluator/handler'
+require 'substation/processor/transformer'
 require 'substation/processor/wrapper'
+require 'substation/processor/nest'
+require 'substation/dsl/guard'
+require 'substation/dsl/registry'
+require 'substation/chain/definition'
+require 'substation/chain'
+require 'substation/chain/dsl'
+require 'substation/chain/dsl/config'
+require 'substation/chain/dsl/module_builder'
 require 'substation/environment'
 require 'substation/environment/dsl'
 require 'substation/dispatcher'

data/lib/substation/chain.rb

@@ -1,20 +1,19 @@
+# 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 handlers that process the incoming {Request} object, one
-  # handler that calls an action ({Chain::Pivot}), and some handlers
+  # a few processors that process the incoming {Request} object, one
+  # processor that calls an action ({Processor::Pivot}), and some processors
   # that process the outgoing {Response} object.
   #
-  # Both {Chain::Incoming} and {Chain::Outgoing} handlers must
-  # respond to `#call(response)` and `#result(response)`.
-  #
-  # @example chain handlers (used in instance method examples)
+  # @example chain processors (used in instance method examples)
   #
   #   module App
   #
-  #     class Handler
+  #     class Processor
   #
   #       def initialize(handler = nil)
   #         @handler = handler
@@ -25,11 +24,11 @@ module Substation
   #       attr_reader :handler
   #
   #       class Incoming < self
-  #         include Substation::Chain::Incoming
+  #         include Substation::Processor::Incoming
   #       end
   #
   #       class Outgoing < self
-  #         include Substation::Chain::Outgoing
+  #         include Substation::Processor::Outgoing
   #
   #         private
   #
@@ -39,13 +38,13 @@ module Substation
   #       end
   #     end
   #
-  #     class Validator < Handler::Incoming
+  #     class Validator < Processor::Incoming
   #       def call(request)
   #         result = handler.call(request.input)
-  #         if result.valid?
+  #         if result.success?
   #           request.success(request.input)
   #         else
-  #           request.error(result.violations)
+  #           request.error(result.output)
   #         end
   #       end
   #     end
@@ -58,7 +57,7 @@ module Substation
   #       end
   #     end
   #
-  #     class Presenter < Handler::Outgoing
+  #     class Presenter < Processor::Outgoing
   #       def call(response)
   #         respond_with(response, handler.new(response.output))
   #       end
@@ -67,74 +66,38 @@ module Substation
   #
   class Chain
 
-    # Supports chaining handlers processed before the {Pivot}
-    module Incoming
-
-      # The request passed on to the next handler in a {Chain}
-      #
-      # @param [Response] response
-      #   the response returned from the previous handler in a {Chain}
-      #
-      # @return [Request]
-      #   the request passed on to the next handler in a {Chain}
-      #
-      # @api private
-      def result(response)
-        Request.new(response.env, response.output)
-      end
-    end
-
-    # Supports chaining the {Pivot} or handlers processed after the {Pivot}
-    module Outgoing
-
-      # The response passed on to the next handler in a {Chain}
-      #
-      # @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 result(response)
-        response
-      end
-
-      private
-
-      # Build a new {Response} based on +response+ and +output+
-      #
-      # @param [Response] response
-      #   the original response
-      #
-      # @param [Object] output
-      #   the data to be wrapped within the new {Response}
-      #
-      # @return [Response]
-      #
-      # @api private
-      def respond_with(response, output)
-        response.class.new(response.request, output)
-      end
-    end
-
-    # Supports chaining the {Pivot} handler
-    Pivot = Outgoing
-
     include Enumerable
-    include Concord.new(:handlers)
+    include Concord.new(:processors, :exception_chain)
     include Adamantium::Flat
-    include Pivot # allow nesting of chains
 
     # Empty chain
-    EMPTY = Class.new(self).new([])
+    EMPTY = new(Definition::EMPTY, EMPTY_ARRAY)
+
+    # Return an exception response
+    #
+    # @param [Request, Response] state
+    #   the initial state 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::Exception]
+    #
+    # @api private
+    def self.exception_response(state, data, exception)
+      output = Response::Exception::Output.new(data, exception)
+      Response::Exception.new(state.to_request(data), output)
+    end
 
     # Call the chain
     #
-    # Invokes all handlers and returns either the first
+    # Invokes all processors and returns either the first
     # {Response::Failure} that it encounters, or if all
     # goes well, the {Response::Success} returned from
-    # the last handler.
+    # the last processor.
     #
     # @example
     #
@@ -162,20 +125,24 @@ module Substation
     #   the request to handle
     #
     # @return [Response::Success]
-    #   the response returned from the last handler
+    #   the response returned from the last processor
     #
     # @return [Response::Failure]
-    #   the response returned from the failing handler
+    #   the response returned from the failing processor's failure chain
     #
-    # @raise [Exception]
-    #   any exception that isn't explicitly rescued in client code
+    # @return [Response::Exception]
+    #   the response returned from invoking the {#exception_chain}
     #
     # @api public
     def call(request)
-      handlers.inject(request) { |result, handler|
-        response = handler.call(result)
-        return response unless response.success?
-        handler.result(response)
+      reduce(request) { |result, processor|
+        begin
+          response = processor.call(result)
+          return response unless processor.success?(response)
+          processor.result(response)
+        rescue => exception
+          return on_exception(request, result.data, exception)
+        end
       }
     end
 
@@ -184,18 +151,40 @@ module Substation
     # @param [Proc] block
     #   a block passed to {#handlers} each method
     #
-    # @yield [handler]
+    # @yield [processor]
     #
-    # @yieldparam [#call] handler
-    #   each handler in the chain
+    # @yieldparam [#call] processor
+    #   each processor in the chain
     #
     # @return [self]
     #
     # @api private
     def each(&block)
       return to_enum unless block
-      handlers.each(&block)
+      processors.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::Exception]
+    #
+    # @api private
+    def on_exception(state, data, exception)
+      response = self.class.exception_response(state, data, exception)
+      exception_chain.call(response)
+    end
+
   end # class Chain
 end # module Substation