cuprum 0.9.1 → 0.11.0

data/lib/cuprum/currying/curried_command.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'cuprum/currying'
+
+module Cuprum::Currying
+  # A CurriedCommand wraps another command and passes preset args to #call.
+  #
+  # @example Currying Arguments
+  #   # Our base command takes two arguments.
+  #   say_command = Cuprum::Command.new do |greeting, person|
+  #     "#{greeting}, #{person}!"
+  #   end
+  #   say_command.call('Hello', 'world')
+  #   #=> returns a result with value 'Hello, world!'
+  #
+  #   # Next, we create a curried command. This sets the first argument to
+  #   # always be 'Greetings', so our curried command only takes one argument,
+  #   # namely the name of the person being greeted.
+  #   greet_command =
+  #     Cuprum::CurriedCommand.new(
+  #       arguments: ['Greetings'],
+  #       command:   say_command
+  #     )
+  #   greet_command.call('programs')
+  #   #=> returns a result with value 'Greetings, programs!'
+  #
+  #   # Here, we are creating a curried command that passes both arguments.
+  #   # Therefore, our curried command does not take any arguments.
+  #   recruit_command =
+  #     Cuprum::CurriedCommand.new(
+  #       arguments: ['Greetings', 'starfighter'],
+  #       command:   say_command
+  #     )
+  #   recruit_command.call
+  #   #=> returns a result with value 'Greetings, starfighter!'
+  #
+  # @example Currying Keywords
+  #   # Our base command takes two keywords: a math operation and an array of
+  #   # integers.
+  #   math_command = Cuprum::Command.new do |operands:, operation:|
+  #     operations.reduce(&operation)
+  #   end
+  #   math_command.call(operands: [2, 2], operation: :+)
+  #   #=> returns a result with value 4
+  #
+  #   # Our curried command still takes two keywords, but now the operation
+  #   # keyword is optional. It now defaults to :*, for multiplication.
+  #   multiply_command =
+  #     Cuprum::CurriedCommand.new(
+  #       command:  math_command,
+  #       keywords: { operation: :* }
+  #     )
+  #   multiply_command.call(operands: [3, 3])
+  #   #=> returns a result with value 9
+  class CurriedCommand < Cuprum::Command
+    # @param arguments [Array] The arguments to pass to the curried command.
+    # @param command [Cuprum::Command] The original command to curry.
+    # @param keywords [Hash] The keywords to pass to the curried command.
+    # @yield A block to pass to the curried command.
+    def initialize(command:, arguments: [], block: nil, keywords: {})
+      super()
+
+      @arguments = arguments
+      @block     = block
+      @command   = command
+      @keywords  = keywords
+    end
+
+    # @!method call(*args, **kwargs)
+    #   Merges the arguments and keywords and calls the wrapped command.
+    #
+    #   First, the arguments array is created starting with the :arguments
+    #   passed to #initialize. Any positional arguments passed directly to #call
+    #   are then appended.
+    #
+    #   Second, the keyword arguments are created by merging the keywords passed
+    #   directly into #call into the keywods passed to #initialize. This means
+    #   that if a key is passed in both places, the value passed into #call will
+    #   take precedence.
+    #
+    #   Finally, the merged arguments and keywords are passed into the original
+    #   command's #call method.
+    #
+    #   @param args [Array] Additional arguments to pass to the curried command.
+    #   @param kwargs [Hash] Additional keywords to pass to the curried command.
+    #
+    #   @return [Cuprum::Result]
+    #
+    #   @see Cuprum::Processing#call
+
+    # @return [Array] the arguments to pass to the curried command.
+    attr_reader :arguments
+
+    # @return [Proc, nil] a block to pass to the curried command.
+    attr_reader :block
+
+    # @return [Cuprum::Command] the original command to curry.
+    attr_reader :command
+
+    # @return [Hash] the keywords to pass to the curried command.
+    attr_reader :keywords
+
+    private
+
+    def process(*args, **kwargs, &override)
+      args   = [*arguments, *args]
+      kwargs = keywords.merge(kwargs)
+
+      if kwargs.empty?
+        command.call(*args, &(override || block))
+      else
+        command.call(*args, **kwargs, &(override || block))
+      end
+    end
+  end
+end

data/lib/cuprum/error.rb

@@ -4,34 +4,68 @@ require 'cuprum'
 
 module Cuprum
   # Wrapper class for encapsulating an error state for a failed Cuprum result.
+  #
   # Additional details can be passed by setting the #message or by using a
   # subclass of Cuprum::Error.
   class Error
-    COMPARABLE_PROPERTIES = %i[message].freeze
-    private_constant :COMPARABLE_PROPERTIES
+    # Short string used to identify the type of error.
+    #
+    # Primarily used for serialization. This value can be overriden by passing
+    # in the :type parameter to the constructor.
+    #
+    # Subclasses of Cuprum::Error should define their own default TYPE constant.
+    TYPE = 'cuprum.error'
 
     # @param message [String] Optional message describing the nature of the
     #   error.
-    def initialize(message: nil)
-      @message = message
+    # @param properties [Hash] Additional properties used to compare errors.
+    # @param type [String] Short string used to identify the type of error.
+    def initialize(message: nil, type: nil, **properties)
+      @message               = message
+      @type                  = type || self.class::TYPE
+      @comparable_properties = properties.merge(message: message, type: type)
     end
 
-    # @return [String] Optional message describing the nature of the error.
+    # @return [String] optional message describing the nature of the error.
     attr_reader :message
 
+    # @return [String] short string used to identify the type of error.
+    attr_reader :type
+
     # @param other [Cuprum::Error] The other object to compare.
     #
-    # @return [Boolean] true if the other object has the same class and message;
-    #   otherwise false.
+    # @return [Boolean] true if the other object has the same class and
+    #   properties; otherwise false.
     def ==(other)
       other.instance_of?(self.class) &&
-        comparable_properties.all? { |prop| send(prop) == other.send(prop) }
+        other.comparable_properties == comparable_properties
+    end
+
+    # Generates a serializable representation of the error object.
+    #
+    # By default, contains the #type and #message properties and an empty :data
+    # Hash. This can be overriden in subclasses by overriding the private method
+    # #as_json_data; this should always return a Hash with String keys and whose
+    # values are basic objects or data structures of the same.
+    #
+    # @return [Hash<String, Object>] a serializable hash representation of the
+    #   error.
+    def as_json
+      {
+        'data'    => as_json_data,
+        'message' => message,
+        'type'    => type
+      }
     end
 
+    protected
+
+    attr_reader :comparable_properties
+
     private
 
-    def comparable_properties
-      self.class.const_get(:COMPARABLE_PROPERTIES)
+    def as_json_data
+      {}
     end
   end
 end

data/lib/cuprum/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 module Cuprum

data/lib/cuprum/errors/command_not_implemented.rb

@@ -13,6 +13,9 @@ module Cuprum::Errors
     # Format for generating error message.
     MESSAGE_FORMAT = 'no implementation defined for %s'
 
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.errors.command_not_implemented'
+
     # @param command [Cuprum::Command] The command called without a definition.
     def initialize(command:)
       @command = command
@@ -20,7 +23,7 @@ module Cuprum::Errors
       class_name = command&.class&.name || 'command'
       message    = MESSAGE_FORMAT % class_name
 
-      super(message: message)
+      super(command: command, message: message)
     end
 
     # @return [Cuprum::Command] The command called without a definition.
@@ -28,8 +31,8 @@ module Cuprum::Errors
 
     private
 
-    def comparable_properties
-      COMPARABLE_PROPERTIES
+    def as_json_data
+      command ? { 'class_name' => command.class.name } : {}
     end
   end
 end

data/lib/cuprum/errors/operation_not_called.rb

@@ -7,12 +7,12 @@ module Cuprum::Errors
   # Error class to be used when trying to access the result of an uncalled
   # Operation.
   class OperationNotCalled < Cuprum::Error
-    COMPARABLE_PROPERTIES = %i[operation].freeze
-    private_constant :COMPARABLE_PROPERTIES
-
     # Format for generating error message.
     MESSAGE_FORMAT = '%s was not called and does not have a result'
 
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.errors.operation_not_called'
+
     # @param operation [Cuprum::Operation] The uncalled operation.
     def initialize(operation:)
       @operation = operation
@@ -20,7 +20,7 @@ module Cuprum::Errors
       class_name = operation&.class&.name || 'operation'
       message    = MESSAGE_FORMAT % class_name
 
-      super(message: message)
+      super(message: message, operation: operation)
     end
 
     # @return [Cuprum::Operation] The uncalled operation.
@@ -28,8 +28,8 @@ module Cuprum::Errors
 
     private
 
-    def comparable_properties
-      COMPARABLE_PROPERTIES
+    def as_json_data
+      operation ? { 'class_name' => operation.class.name } : {}
     end
   end
 end

data/lib/cuprum/errors/uncaught_exception.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+require 'cuprum/errors'
+
+module Cuprum::Errors
+  # An error returned when a command encounters an unhandled exception.
+  class UncaughtException < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.uncaught_exception'
+
+    # @param exception [StandardError] The exception that was raised.
+    # @param message [String] A message to display. Will be annotated with
+    #   details on the exception and the exception's cause (if any).
+    def initialize(exception:, message: 'uncaught exception')
+      @exception = exception
+      @cause     = exception.cause
+
+      super(message: generate_message(message))
+    end
+
+    # @return [StandardError] the exception that was raised.
+    attr_reader :exception
+
+    private
+
+    attr_reader :cause
+
+    def as_json_data # rubocop:disable Metrics/MethodLength
+      data = {
+        'exception_backtrace' => exception.backtrace,
+        'exception_class'     => exception.class,
+        'exception_message'   => exception.message
+      }
+
+      return data unless cause
+
+      data.update(
+        {
+          'cause_backtrace' => cause.backtrace,
+          'cause_class'     => cause.class,
+          'cause_message'   => cause.message
+        }
+      )
+    end
+
+    def generate_message(message)
+      message = "#{message} #{exception.class}: #{exception.message}"
+
+      return message unless cause
+
+      message + " caused by #{cause.class}: #{cause.message}"
+    end
+  end
+end

data/lib/cuprum/exception_handling.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'cuprum/errors/uncaught_exception'
+
+module Cuprum
+  # Utility class for handling uncaught exceptions in commands.
+  #
+  # @example
+  #   class UnsafeCommand < Cuprum::Command
+  #     private
+  #
+  #     def process
+  #       raise 'Something went wrong.'
+  #     end
+  #   end
+  #
+  #   class SafeCommand < UnsafeCommand
+  #     include Cuprum::ExceptionHandling
+  #   end
+  #
+  #   UnsafeCommand.new.call
+  #   #=> raises a StandardError
+  #
+  #   result = SafeCommand.new.call
+  #   #=> a Cuprum::Result
+  #   result.error
+  #   #=> a Cuprum::Errors::UncaughtException error.
+  #   result.error.message
+  #   #=> 'uncaught exception in SafeCommand -' \
+  #       ' StandardError: Something went wrong.'
+  module ExceptionHandling
+    # Wraps the #call method with a rescue clause matching any StandardError.
+    #
+    # If a StandardError or subclass thereof is raised and not caught by #call,
+    # then ExceptionHandling will rescue the exception and return a failing
+    # Cuprum::Result with a Cuprum::Errors::UncaughtException error.
+    #
+    # @return [Cuprum::Result] the result of calling the superclass method, or
+    #   a failing result if a StandardError is raised.
+    def call(*args, **kwargs, &block)
+      super
+    rescue StandardError => exception
+      error = Cuprum::Errors::UncaughtException.new(
+        exception: exception,
+        message:   "uncaught exception in #{self.class.name} - "
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/matcher.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+require 'cuprum/matching'
+
+module Cuprum
+  # Provides result matching based on result status, error, and value.
+  #
+  # First, define match clauses using the .match DSL. Each match clause has a
+  # status and optionally a value class and/or error class. A result will only
+  # match the clause if the result status is the same as the clause's status.
+  # If the clause sets a value class, then the result value must be an instance
+  # of that class (or an instance of a subclass). If the clause sets an error
+  # class, then the result error must be an instance of that class (or an
+  # instance of a subclass).
+  #
+  # Once the matcher defines one or more match clauses, call #call with a result
+  # to match the result. The matcher will determine the best match with the same
+  # status (value and error match the result, only value or error match, or just
+  # status matches) and then call the match clause with the result. If no match
+  # clauses match the result, the matcher will instead raise a
+  # Cuprum::Matching::NoMatchError.
+  #
+  # @example Matching A Status
+  #   matcher = Cuprum::Matcher.new do
+  #     match(:failure) { 'Something went wrong' }
+  #
+  #     match(:success) { 'Ok' }
+  #   end
+  #
+  #   matcher.call(Cuprum::Result.new(status: :failure))
+  #   #=> 'Something went wrong'
+  #
+  #   matcher.call(Cuprum::Result.new(status: :success))
+  #   #=> 'Ok'
+  #
+  # @example Matching An Error
+  #   matcher = Cuprum::Matcher.new do
+  #     match(:failure) { 'Something went wrong' }
+  #
+  #     match(:failure, error: CustomError) { |result| result.error.message }
+  #
+  #     match(:success) { 'Ok' }
+  #   end
+  #
+  #   matcher.call(Cuprum::Result.new(status: :failure))
+  #   #=> 'Something went wrong'
+  #
+  #   error = CustomError.new(message: 'The magic smoke is escaping.')
+  #   matcher.call(Cuprum::Result.new(error: error))
+  #   #=> 'The magic smoke is escaping.'
+  #
+  # @example Using A Match Context
+  #   context = Struct.new(:name).new('programs')
+  #   matcher = Cuprum::Matcher.new(context) do
+  #     match(:failure) { 'Something went wrong' }
+  #
+  #     match(:success) { "Greetings, #{name}!" }
+  #   end
+  #
+  #   matcher.call(Cuprum::Result.new(status: :success)
+  #   #=> 'Greetings, programs!'
+  class Matcher
+    include Cuprum::Matching
+
+    # @param match_context [Object] the execution context for a matching clause.
+    #
+    # @yield Executes the block in the context of the singleton class. This is
+    #   used to define match clauses when instantiating a Matcher instance.
+    def initialize(match_context = nil, &block)
+      @match_context = match_context
+
+      singleton_class.instance_exec(&block) if block_given?
+    end
+
+    # Returns a copy of the matcher with the given execution context.
+    #
+    # @param match_context [Object] the execution context for a matching clause.
+    #
+    # @return [Cuprum::Matcher] the copied matcher.
+    def with_context(match_context)
+      clone.tap { |copy| copy.match_context = match_context }
+    end
+    alias_method :using_context, :with_context
+
+    protected
+
+    attr_writer :match_context
+  end
+end