cuprum 0.6.0 → 0.7.0.rc.0

data/lib/cuprum/utils/instance_spy.rb

@@ -2,19 +2,19 @@ require 'cuprum/utils'
 
 module Cuprum::Utils
   # Utility module for instrumenting calls to the #call method of any instance
-  # of a function class. This can be used to unobtrusively test the
-  # functionality of code that calls a function without providing a reference to
-  # the function instance, such as chained functions or methods that create and
-  # call a function instance.
+  # of a command class. This can be used to unobtrusively test the
+  # functionality of code that calls a command without providing a reference to
+  # the command instance, such as chained commands or methods that create and
+  # call a command instance.
   #
-  # @example Observing calls to instances of a function.
+  # @example Observing calls to instances of a command.
   #   spy = Cuprum::Utils::InstanceSpy.spy_on(CustomCommand)
   #
   #   expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
   #
   #   CustomCommand.new.call(1, 2, 3, :four => '4')
   #
-  # @example Observing calls to a chained function.
+  # @example Observing calls to a chained command.
   #   spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedCommand)
   #
   #   expect(spy).to receive(:call)
@@ -31,14 +31,14 @@ module Cuprum::Utils
   #   end # spy_on
   module InstanceSpy
     # Minimal class that implements a #call method to mirror method calls to
-    # instances of an instrumented function class.
+    # instances of an instrumented command class.
     class Spy
       # Empty method that accepts any arguments and an optional block.
       def call *_args, █ end
     end # class
 
     class << self
-      # Retires all spies. Subsequent calls to the #call method on function
+      # Retires all spies. Subsequent calls to the #call method on command
       # instances will not be mirrored to existing spy objects.
       def clear_spies
         Thread.current[:cuprum_instance_spies] = nil
@@ -50,7 +50,7 @@ module Cuprum::Utils
       # that the #call method is called for an object of the given type, the
       # spy's #call method will be invoked with the same arguments and block.
       #
-      # @param function_class [Class, Module] The type of function to spy on.
+      # @param command_class [Class, Module] The type of command to spy on.
       #   Must be either a Module, or a Class that extends Cuprum::Command.
       #
       # @raise [ArgumentError] If the argument is neither a Module nor a Class
@@ -59,54 +59,54 @@ module Cuprum::Utils
       # @note Calling this method for the first time will prepend the
       #   Cuprum::Utils::InstanceSpy module to Cuprum::Command.
       #
-      # @overload spy_on(function_class)
+      # @overload spy_on(command_class)
       #   @return [Cuprum::Utils::InstanceSpy::Spy] The instance spy.
       #
-      # @overload spy_on(function_class, &block)
+      # @overload spy_on(command_class, &block)
       #   Yields the instance spy to the block, and returns nil.
       #
       #   @yield [Cuprum::Utils::InstanceSpy::Spy] The instance spy.
       #
       #   @return [nil] nil.
-      def spy_on function_class
-        guard_spy_class!(function_class)
+      def spy_on command_class
+        guard_spy_class!(command_class)
 
         instrument_call!
 
         if block_given?
           begin
-            instance_spy = assign_spy(function_class)
+            instance_spy = assign_spy(command_class)
 
             yield instance_spy
           end # begin-ensure
         else
-          assign_spy(function_class)
+          assign_spy(command_class)
         end # if-else
       end # method spy_on
 
       private
 
-      def assign_spy function_class
-        existing_spy = spies[function_class]
+      def assign_spy command_class
+        existing_spy = spies[command_class]
 
         return existing_spy if existing_spy
 
-        spies[function_class] = build_spy
+        spies[command_class] = build_spy
       end # method assign_spy
 
       def build_spy
         Cuprum::Utils::InstanceSpy::Spy.new
       end # method build_spy
 
-      def call_spies_for function, *args, &block
-        spies_for(function).each { |spy| spy.call(*args, &block) }
+      def call_spies_for command, *args, &block
+        spies_for(command).each { |spy| spy.call(*args, &block) }
       end # method call_spies_for
 
-      def guard_spy_class! function_class
-        return if function_class.is_a?(Module) && !function_class.is_a?(Class)
+      def guard_spy_class! command_class
+        return if command_class.is_a?(Module) && !command_class.is_a?(Class)
 
-        return if function_class.is_a?(Class) &&
-                  function_class <= Cuprum::Command
+        return if command_class.is_a?(Class) &&
+                  command_class <= Cuprum::Command
 
         raise ArgumentError,
           'must be a class inheriting from Cuprum::Command',
@@ -123,8 +123,8 @@ module Cuprum::Utils
         Thread.current[:cuprum_instance_spies] ||= {}
       end # method spies
 
-      def spies_for function
-        spies.select { |mod, _| function.is_a?(mod) }.map { |_, spy| spy }
+      def spies_for command
+        spies.select { |mod, _| command.is_a?(mod) }.map { |_, spy| spy }
       end # method spies_for
     end # eigenclass
 

data/lib/cuprum/utils/result_not_empty_warning.rb

@@ -0,0 +1,65 @@
+require 'cuprum/utils'
+
+module Cuprum::Utils
+  # Helper class for building a warning message when a command returns a result,
+  # but the command's current result already has errors, a set status, or is
+  # halted.
+  class ResultNotEmptyWarning
+    MESSAGE = '#process returned a result, but '.freeze
+    private_constant :MESSAGE
+
+    # @param result [Cuprum::Result] The result for which to generate the
+    #   warning message.
+    def initialize result
+      @result = result
+    end # constructor
+
+    # @return [String] The warning message for the given result.
+    def message
+      # byebug
+      MESSAGE + humanize_list(warnings).freeze
+    end # method message
+
+    private
+
+    attr_reader :result
+
+    def errors_not_empty_warning
+      return nil if result.errors.empty?
+
+      "there were already errors #{@result.errors.inspect}".freeze
+    end # method errors_not_empty_warning
+
+    def halted_warning
+      return nil unless result.halted?
+
+      'the command was halted'.freeze
+    end # method halted_warning
+
+    def humanize_list list, empty_value: ''
+      return empty_value if list.size.zero?
+
+      return list.first.to_s if list.size == 1
+
+      return "#{list.first} and #{list.last}" if list.size == 2
+
+      "#{list[0...-1].join ', '}, and #{list.last}"
+    end # method humanize_list
+
+    def status_set_warning
+      status = result.send(:status)
+
+      return nil if status.nil?
+
+      "the status was set to #{status.inspect}".freeze
+    end # method status_set_warning
+
+    def warnings
+      [
+        errors_not_empty_warning,
+        status_set_warning,
+        halted_warning
+      ].compact
+    end # method warnings
+  end # class
+end # module

data/lib/cuprum/version.rb

@@ -8,13 +8,13 @@ module Cuprum
     # Major version.
     MAJOR = 0
     # Minor version.
-    MINOR = 6
+    MINOR = 7
     # Patch version.
     PATCH = 0
     # Prerelease version.
-    PRERELEASE = nil
+    PRERELEASE = :rc
     # Build metadata.
-    BUILD = nil
+    BUILD = 0
 
     class << self
       # Generates the gem version string from the Version constants.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0.rc.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-30 00:00:00.000000000 Z
+date: 2018-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -94,7 +94,6 @@ files:
 - LICENSE
 - README.md
 - lib/cuprum.rb
-- lib/cuprum/basic_command.rb
 - lib/cuprum/built_in.rb
 - lib/cuprum/built_in/identity_command.rb
 - lib/cuprum/built_in/identity_operation.rb
@@ -104,9 +103,12 @@ files:
 - lib/cuprum/command.rb
 - lib/cuprum/not_implemented_error.rb
 - lib/cuprum/operation.rb
+- lib/cuprum/processing.rb
 - lib/cuprum/result.rb
+- lib/cuprum/result_helpers.rb
 - lib/cuprum/utils.rb
 - lib/cuprum/utils/instance_spy.rb
+- lib/cuprum/utils/result_not_empty_warning.rb
 - lib/cuprum/version.rb
 homepage: http://sleepingkingstudios.com
 licenses:
@@ -123,9 +125,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.13

data/lib/cuprum/basic_command.rb

@@ -1,212 +0,0 @@
-require 'cuprum/not_implemented_error'
-
-module Cuprum
-  # Functional object that encapsulates a business logic operation with a
-  # standardized interface and returns a result object.
-  class BasicCommand
-    # Returns a new instance of Cuprum::BasicCommand.
-    #
-    # @yield [*arguments, **keywords, &block] If a block is given, the
-    #   #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
-      define_singleton_method :process, &implementation if implementation
-    end # method initialize
-
-    # @overload call(*arguments, **keywords, &block)
-    #   Executes the logic encoded in the constructor block, or the #process
-    #   method if no block was passed to the constructor, and returns a
-    #   Cuprum::Result object with the return value of the block or #process,
-    #   the success or failure status, and any errors generated.
-    #
-    #   @param arguments [Array] Arguments to be passed to the implementation.
-    #
-    #   @param keywords [Hash] Keywords to be passed to the implementation.
-    #
-    #   @return [Cuprum::Result] The result object for the command.
-    #
-    #   @yield If a block argument is given, it will be passed to the
-    #     implementation.
-    #
-    #   @raise [Cuprum::NotImplementedError] Unless a block was passed to the
-    #     constructor or the #process method was overriden by a Command
-    #     subclass.
-    def call *args, &block
-      wrap_result { |result| merge_results(result, process(*args, &block)) }
-    end # method call
-
-    private
-
-    # @!visibility public
-    #
-    # Generates an empty errors object. When the function is called, the result
-    # will have its #errors property initialized to the value returned by
-    # #build_errors. By default, this is an array. If you want to use a custom
-    # errors object type, override this method in a subclass.
-    #
-    # @return [Array] An empty errors object.
-    def build_errors
-      []
-    end # method build_errors
-
-    def convert_value_to_result value
-      return nil unless value_is_result?(value)
-
-      if value.respond_to?(:result) && value_is_result?(value.result)
-        return value.result
-      end # if
-
-      value
-    end # method convert_value_to_result
-
-    # @!visibility public
-    #
-    # Provides a reference to the current result's errors object. Messages or
-    # error objects added to this will be included in the #errors method of the
-    # returned result object.
-    #
-    # @return [Array, Object] The errors object.
-    #
-    # @see Cuprum::Result#errors.
-    #
-    # @note This is a private method, and only available when executing the
-    #   function implementation as defined in the constructor block or the
-    #   #process method.
-    def errors
-      @result&.errors
-    end # method errors
-
-    # @!visibility public
-    #
-    # Marks the current result as failed. Calling #failure? on the returned
-    # result object will evaluate to true, whether or not the result has any
-    # errors.
-    #
-    # @see Cuprum::Result#failure!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   function implementation as defined in the constructor block or the
-    #   #process method.
-    def failure!
-      @result&.failure!
-    end # method failure!
-
-    # @!visibility public
-    #
-    # Marks the current result as halted.
-    #
-    # @see Cuprum::Result#halt!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   function implementation as defined in the constructor block or the
-    #   #process method.
-    def halt!
-      @result&.halt!
-    end # method halt!
-
-    # :nocov:
-    def humanize_list list, empty_value: ''
-      return empty_value if list.size.zero?
-
-      return list.first.to_s if list.size == 1
-
-      return "#{list.first} and #{list.last}" if list.size == 2
-
-      "#{list[0...-1].join ', '}, and #{list.last}"
-    end # method humanize_list
-    # :nocov:
-
-    def merge_results result, other
-      if value_is_result?(other)
-        Cuprum.warn(result_not_empty_warning) unless result.empty?
-
-        convert_value_to_result(other)
-      else
-        result.value = other
-
-        result
-      end # if-else
-    end # method merge_results
-
-    # @!visibility public
-    # @overload process(*arguments, **keywords, &block)
-    #   The implementation of the function, to be executed when the #call method
-    #   is called. Can add errors to or set the status of the result, and the
-    #   value of the result will be set to the value returned by #process. Do
-    #   not call this method directly.
-    #
-    #   @param arguments [Array] The arguments, if any, passed from #call.
-    #
-    #   @param keywords [Hash] The keywords, if any, passed from #call.
-    #
-    #   @yield The block, if any, passed from #call.
-    #
-    #   @return [Object] the value of the result object to be returned by #call.
-    #
-    #   @raise [Cuprum::NotImplementedError] Unless a block was passed to the
-    #     constructor or the #process method was overriden by a Command
-    #     subclass.
-    #
-    # @note This is a private method.
-    def process *_args
-      raise Cuprum::NotImplementedError, nil, caller(1..-1)
-    end # method process
-
-    def result_not_empty_warning # rubocop:disable Metrics/MethodLength
-      warnings = []
-
-      unless @result.errors.empty?
-        warnings << "there were already errors #{@result.errors.inspect}"
-      end # unless
-
-      status = @result.send(:status)
-      unless status.nil?
-        warnings << "the status was set to #{status.inspect}"
-      end # unless
-
-      if @result.halted?
-        warnings << 'the function was halted'
-      end # if
-
-      message = '#process returned a result, but '
-      message <<
-        humanize_list(warnings, :empty_value => 'the result was not empty')
-
-      message
-    end # method result_not_empty_warning
-
-    # @!visibility public
-    #
-    # Marks the current result as passing. Calling #success? on the returned
-    # result object will evaluate to true, whether or not the result has any
-    # errors.
-    #
-    # @see Cuprum::Result#success!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   function implementation as defined in the constructor block or the
-    #   #process method.
-    def success!
-      @result&.success!
-    end # method success!
-
-    def value_is_result? value
-      value.respond_to?(:value) && value.respond_to?(:success?)
-    end # method value
-
-    def wrap_result
-      result = Cuprum::Result.new(:errors => build_errors)
-
-      begin
-        @result = result
-
-        result = yield result
-      ensure
-        @result = nil
-      end # begin-ensure
-
-      result
-    end # method wrap_result
-  end # class
-end # module