substation 0.0.10.beta2 → 0.0.10

data/lib/substation/processor/evaluator/handler.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+module Substation
+  module Processor
+    class Evaluator
+
+      # Helps returning an api compatible result from custom Evaluator handlers
+      module Handler
+
+        # Return a successful result
+        #
+        # @param [Object] output
+        #   the data associated with the result
+        #
+        # @return [Result::Success]
+        #
+        # @api private
+        def success(output)
+          respond_with(Result::Success, output)
+        end
+
+        # Return an errorneous result
+        #
+        # @param [Object] output
+        #   the data associated with the result
+        #
+        # @return [Result::Failure]
+        #
+        # @api private
+        def error(output)
+          respond_with(Result::Failure, output)
+        end
+
+        private
+
+        # Return a new result subclass instance
+        #
+        # @param [Result::Success, Result::Failure] klass
+        #   the result class
+        #
+        # @param [Object] output
+        #   the data associated with the result
+        #
+        # @return [Response]
+        #
+        # @api private
+        def respond_with(klass, output)
+          klass.new(output)
+        end
+
+      end # module Handler
+    end # class Evaluator
+  end # module Processor
+end # module Substation

data/lib/substation/processor/evaluator/result.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+module Substation
+  module Processor
+    class Evaluator
+
+      # A result object compatible with the {Evaluator} api contract
+      class Result
+        include AbstractType
+        include Concord::Public.new(:output)
+
+        # A successful evaluation result
+        class Success < self
+          include Response::API::Success
+        end # class Success
+
+        # An errorneous evaluation result
+        class Failure < self
+          include Response::API::Failure
+        end # class Failure
+      end # class Result
+    end # class Evaluator
+  end # module Processor
+end # module Substation

data/lib/substation/processor/executor.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Substation
+  module Processor
+
+    # Supports executing new {Processor} handler instances
+    class Executor
+
+      include Concord.new(:decomposer, :composer)
+      include Adamantium::Flat
+
+      decompose = ->(input)         { input  }
+      compose   = ->(input, output) { output }
+
+      NULL = new(decompose, compose)
+
+      # Decompose input
+      #
+      # @param [Object] input
+      #   the input to decompose
+      #
+      # @return [Object]
+      #
+      # @api private
+      def decompose(input)
+        decomposer.call(input)
+      end
+
+      # Compose input and output
+      #
+      # @param [Object] input
+      #   the input to compose from
+      #
+      # @param [Object] output
+      #   the output to compose with
+      #
+      # @return [Object]
+      #
+      # @api private
+      def compose(input, output)
+        composer.call(input, output)
+      end
+
+    end # class Executor
+  end # module Processor
+end # module Substation

data/lib/substation/processor/nest.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+module Substation
+  module Processor
+
+    # Namespace for processor that call a nested chain
+    module Nest
+
+      # An incoming processor that calls a nested chain
+      class Incoming
+
+        include Processor::Incoming
+
+        # Call the processor
+        #
+        # @param [Request] request
+        #   the request to process
+        #
+        # @return [Response::Success]
+        #
+        # @api private
+        def call(request)
+          state = invoke(decompose(request))
+
+          case state
+          when Request
+            request.success(compose(request, request.success(state.data)))
+          when Response::Success
+            request.success(compose(request, state))
+          when Response::Failure
+            request.error(compose(request, state))
+          else
+            raise 'Illegal state returned from the invoked handler'
+          end
+        end
+
+      end # class Incoming
+    end # module Nest
+  end # module Processor
+end # module Substation

data/lib/substation/processor/transformer.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Substation
+  module Processor
+
+    # A processor that transforms output data into something else
+    module Transformer
+
+      # A transformer used to transform an incoming request
+      class Incoming
+        include Processor::Incoming
+
+        # Call the processor
+        #
+        # @param [Request] request
+        #   the request to process
+        #
+        # @return [Response::Success]
+        #
+        # @api private
+        def call(request)
+          request.success(execute(request))
+        end
+      end
+
+      # A transformer used to transform an outgoing response
+      class Outgoing
+        include Processor::Outgoing
+
+        # Call the processor
+        #
+        # @param [Response] response
+        #   the response to process
+        #
+        # @return [Response]
+        #   a new instance of the same class as +response+
+        #
+        # @api private
+        def call(response)
+          respond_with(response, execute(response))
+        end
+      end
+
+    end # class Transformer
+  end # module Processor
+end # module Substation

data/lib/substation/processor/wrapper.rb

@@ -1,11 +1,22 @@
+# encoding: utf-8
+
 module Substation
   module Processor
 
     # A processor that wraps output data in a new handler instance
-    class Wrapper
+    module Wrapper
+
+      # A wrapper used to wrap incoming request data
+      class Incoming < Transformer::Incoming
+        include Wrapper
+      end
+
+      # A wrapper used to wrap outgoing response data
+      class Outgoing < Transformer::Outgoing
+        include Wrapper
+      end
 
-      include Outgoing
-      include Concord.new(:env, :handler)
+      private
 
       # Wrap response data in an instance of {#handler}
       #
@@ -15,8 +26,8 @@ module Substation
       # @return [Response]
       #
       # @api private
-      def call(response)
-        respond_with(response, handler.new(response.data))
+      def invoke(state)
+        handler.new(state)
       end
 
     end # class Wrapper

data/lib/substation/request.rb

@@ -1,41 +1,27 @@
+# encoding: utf-8
+
 module Substation
 
   # Encapsulates the application environment and an input model instance
   class Request
 
-    include Concord.new(:env, :input)
+    include Concord::Public.new(:name, :env, :input)
     include Adamantium::Flat
 
-    # The application environment
-    #
-    # @example
-    #
-    #   class SomeUseCase
-    #     def self.call(request)
-    #       request.env
-    #     end
-    #   end
-    #
-    # @return [Object]
-    #
-    # @api public
-    attr_reader :env
+    # @!attribute [r] name
+    #   @return [Symbol] the name of the request
 
-    # The input passed to an action
-    #
-    # @example
-    #
-    #   class SomeUseCase
-    #     def self.call(request)
-    #       request.input
-    #     end
-    #   end
+    # @!attribute [r] env
+    #   @return [Object] the application environment
+
+    # @!attribute [r] input
+    #   @return [Object] the input data
+
+    # An alias for {#input}
     #
     # @return [Object]
     #
-    # @api public
-    attr_reader :input
-
+    # @api private
     alias_method :data, :input
 
     # Create a new successful response
@@ -80,6 +66,22 @@ module Substation
       respond_with(Response::Failure, output)
     end
 
+    # Return self or a new instance with +input+
+    #
+    # @param [Object] input
+    #   the input for the new instance
+    #
+    # @return [self]
+    #   if +input+ is {Undefined}
+    #
+    # @return [Request]
+    #   a new instance with +input+
+    #
+    # @api private
+    def to_request(new_input = Undefined)
+      new_input.equal?(Undefined) ? self : self.class.new(name, env, new_input)
+    end
+
     private
 
     # Instantiate an instance of +klass+ and pass +output+

data/lib/substation/response.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Substation
 
   # Base class for action responses
@@ -129,40 +131,23 @@ module Substation
     # @api public
     abstract_method :success?
 
-    # An errorneous {Response}
-    class Failure < self
-
-      # Tests wether this response was successful
-      #
-      # @example
-      #
-      #   response = dispatcher.call(:failing_action, :some_input)
-      #   response.success? # => false
-      #
-      # @return [false]
-      #
-      # @api public
-      def success?
-        false
-      end
+    # Test wether processing raised an exception
+    #
+    # @return [true]
+    #
+    # @api private
+    def exception?
+      false
     end
 
-    # A successful {Response}
-    class Success < self
-
-      # Tests wether this response was successful
-      #
-      # @example
-      #
-      #   response = dispatcher.call(:successful_action, :some_input)
-      #   response.success? # => true
-      #
-      # @return [true]
-      #
-      # @api public
-      def success?
-        true
-      end
+    # Return a {Request} instance built upon this response
+    #
+    # @return [Request]
+    #
+    # @api private
+    def to_request(new_input = output)
+      Request.new(request.name, env, new_input)
     end
-  end
-end
+
+  end # class Response
+end # module Substation

data/lib/substation/response/api.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+module Substation
+  class Response
+
+    # Namespace for modules that help with processor result compatibility
+    module API
+
+      # Indicate successful processing
+      module Success
+
+        # Test wether processing was successful
+        #
+        # @return [true]
+        #
+        # @api private
+        def success?
+          true
+        end
+      end
+
+      # Indicate errorneous processing
+      module Failure
+
+        # Test wether processing was successful
+        #
+        # @return [false]
+        #
+        # @api private
+        def success?
+          false
+        end
+      end
+
+    end # module API
+  end # class Response
+end # module Substation

data/lib/substation/response/exception.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module Substation
+  class Response
+
+    # An exception {Response}
+    class Exception < self
+      include API::Failure
+
+      # Test wether processing raised an exception
+      #
+      # @return [true]
+      #
+      # @api private
+      def exception?
+        true
+      end
+    end # class Exception
+  end # class Response
+end # module Substation