cuprum 0.10.0 → 1.0.0.rc.1

data/lib/cuprum/built_in/identity_command.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in'
 require 'cuprum/command'
 
@@ -24,8 +26,8 @@ module Cuprum::BuiltIn
   class IdentityCommand < Cuprum::Command
     private
 
-    def process value = nil
+    def process(value = nil)
       value
-    end # method process
-  end # class
-end # module
+    end
+  end
+end

data/lib/cuprum/built_in/identity_operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in/identity_command'
 require 'cuprum/operation'
 
@@ -23,5 +25,5 @@ module Cuprum::BuiltIn
   #   #=> ['errors.messages.unknown']
   class IdentityOperation < Cuprum::BuiltIn::IdentityCommand
     include Cuprum::Operation::Mixin
-  end # class
-end # module
+  end
+end

data/lib/cuprum/built_in/null_command.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in'
 require 'cuprum/command'
 
@@ -13,6 +15,6 @@ module Cuprum::BuiltIn
   class NullCommand < Cuprum::Command
     private
 
-    def process *_args; end
-  end # class
-end # module
+    def process(*_args); end
+  end
+end

data/lib/cuprum/built_in/null_operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in/null_command'
 require 'cuprum/operation'
 
@@ -12,5 +14,5 @@ module Cuprum::BuiltIn
   #   #=> true
   class NullOperation < Cuprum::BuiltIn::NullCommand
     include Cuprum::Operation::Mixin
-  end # class
-end # module
+  end
+end

data/lib/cuprum/built_in.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 module Cuprum
   # Namespace for predefined command and operation classes.
   module BuiltIn; end
-end # module
+end

data/lib/cuprum/command.rb

@@ -1,4 +1,5 @@
-require 'cuprum/chaining'
+# frozen_string_literal: true
+
 require 'cuprum/currying'
 require 'cuprum/processing'
 require 'cuprum/steps'
@@ -20,14 +21,14 @@ module Cuprum
   #   class MultiplyCommand < Cuprum::Command
   #     def initialize multiplier
   #       @multiplier = multiplier
-  #     end # constructor
+  #     end
   #
   #     private
   #
   #     def process int
   #       int * @multiplier
-  #     end # method process
-  #   end # class
+  #     end
+  #   end
   #
   #   triple_command = MultiplyCommand.new(3)
   #   result         = command_command.call(5)
@@ -38,7 +39,7 @@ module Cuprum
   #   class DivideCommand < Cuprum::Command
   #     def initialize divisor
   #       @divisor = divisor
-  #     end # constructor
+  #     end
   #
   #     private
   #
@@ -48,8 +49,8 @@ module Cuprum
   #       end
   #
   #       int / @divisor
-  #     end # method process
-  #   end # class
+  #     end
+  #   end
   #
   #   halve_command = DivideCommand.new(2)
   #   result        = halve_command.call(10)
@@ -63,53 +64,6 @@ module Cuprum
   #   result.error #=> 'errors.messages.divide_by_zero'
   #   result.value #=> nil
   #
-  # @example Command Chaining
-  #   class AddCommand < Cuprum::Command
-  #     def initialize addend
-  #       @addend = addend
-  #     end # constructor
-  #
-  #     private
-  #
-  #     def process int
-  #       int + @addend
-  #     end # method process
-  #   end # class
-  #
-  #   double_and_add_one = MultiplyCommand.new(2).chain(AddCommand.new(1))
-  #   result             = double_and_add_one(5)
-  #
-  #   result.value #=> 5
-  #
-  # @example Conditional Chaining
-  #   class EvenCommand < Cuprum::Command
-  #     private
-  #
-  #     def process int
-  #       return int if int.even?
-  #
-  #       Cuprum::Errors.new(error: 'errors.messages.not_even')
-  #     end # method process
-  #   end # class
-  #
-  #   # The next step in a Collatz sequence is determined as follows:
-  #   # - If the number is even, divide it by 2.
-  #   # - If the number is odd, multiply it by 3 and add 1.
-  #   collatz_command =
-  #     EvenCommand.new.
-  #       chain(DivideCommand.new(2), :on => :success).
-  #       chain(
-  #         MultiplyCommand.new(3).chain(AddCommand.new(1),
-  #         :on => :failure
-  #       )
-  #
-  #   result = collatz_command.new(5)
-  #   result.value #=> 16
-  #
-  #   result = collatz_command.new(16)
-  #   result.value #=> 8
-  #
-  # @see Cuprum::Chaining
   # @see Cuprum::Processing
   class Command
     include Cuprum::Processing
@@ -122,16 +76,33 @@ module Cuprum
     #   #call method will wrap the block and set the result #value to the return
     #   value of the block. This overrides the implementation in #process, if
     #   any.
-    def initialize &implementation
+    def initialize(&implementation)
       return unless implementation
 
       define_singleton_method :process, &implementation
 
       singleton_class.send(:private, :process)
-    end # method initialize
+    end
 
+    # (see Cuprum::Processing#call)
     def call(*args, **kwargs, &block)
       steps { super }
     end
-  end # class
-end # module
+
+    # Wraps the command in a proc.
+    #
+    # Calling the proc will call the command with the given arguments, keywords,
+    # and block.
+    #
+    # @return [Proc] the wrapping proc.
+    def to_proc
+      @to_proc ||= lambda do |*args, **kwargs, &block|
+        if kwargs.empty?
+          call(*args, &block)
+        else
+          call(*args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/command_factory.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 require 'sleeping_king_studios/tools/toolbelt'
@@ -147,7 +149,7 @@ module Cuprum
       def command_class(name, **metadata, &defn)
         guard_abstract_factory!
 
-        raise ArgumentError, 'must provide a block'.freeze unless block_given?
+        raise ArgumentError, 'must provide a block' unless block_given?
 
         method_name = normalize_command_name(name)
 
@@ -227,13 +229,13 @@ module Cuprum
 
         raise NotImplementedError,
           'Cuprum::CommandFactory is an abstract class. Create a subclass to ' \
-          'define commands for a factory.'.freeze
+          'define commands for a factory.'
       end
 
       def guard_invalid_definition!(command_class)
         return if command_class.is_a?(Class) && command_class < Cuprum::Command
 
-        raise ArgumentError, 'definition must be a command class'.freeze
+        raise ArgumentError, 'definition must be a command class'
       end
 
       def normalize_command_name(command_name)
@@ -241,7 +243,7 @@ module Cuprum
       end
 
       def require_definition!
-        raise ArgumentError, 'must provide a command class or a block'.freeze
+        raise ArgumentError, 'must provide a command class or a block'
       end
 
       def tools
@@ -263,7 +265,7 @@ module Cuprum
     end
 
     # @private
-    def const_defined?(const_name, inherit = true)
+    def const_defined?(const_name, inherit = true) # rubocop:disable Style/OptionalBooleanParameter
       command?(const_name) || super
     end
 

data/lib/cuprum/currying/curried_command.rb

@@ -56,8 +56,12 @@ module Cuprum::Currying
     # @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.
-    def initialize(arguments: [], command:, keywords: {})
+    # @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
@@ -87,6 +91,9 @@ module Cuprum::Currying
     # @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
 
@@ -95,14 +102,14 @@ module Cuprum::Currying
 
     private
 
-    def process(*args, **kwargs, &block)
+    def process(*args, **kwargs, &override)
       args   = [*arguments, *args]
       kwargs = keywords.merge(kwargs)
 
       if kwargs.empty?
-        command.call(*args, &block)
+        command.call(*args, &(override || block))
       else
-        command.call(*args, **kwargs, &block)
+        command.call(*args, **kwargs, &(override || block))
       end
     end
   end

data/lib/cuprum/currying.rb

@@ -65,11 +65,12 @@ module Cuprum
     # @return [Cuprum::Currying::CurriedCommand] the curried command.
     #
     # @see Cuprum::Currying::CurriedCommand#call
-    def curry(*arguments, **keywords)
-      return self if arguments.empty? && keywords.empty?
+    def curry(*arguments, **keywords, &block)
+      return self if arguments.empty? && keywords.empty? && block.nil?
 
       Cuprum::Currying::CurriedCommand.new(
         arguments: arguments,
+        block:     block,
         command:   self,
         keywords:  keywords
       )

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/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/errors.rb

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

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