cuprum 0.5.0 → 0.6.0

data/lib/cuprum/not_implemented_error.rb

@@ -0,0 +1,14 @@
+require 'cuprum'
+
+module Cuprum
+  # Error class for calling a Command that was not given a definition block
+  # or have a #process method defined.
+  class NotImplementedError < StandardError
+    # Error message for a NotImplementedError.
+    DEFAULT_MESSAGE = 'no implementation defined for command'.freeze
+
+    def initialize message = nil
+      super(message || DEFAULT_MESSAGE)
+    end # constructor
+  end # class
+end # module

data/lib/cuprum/operation.rb

@@ -1,4 +1,4 @@
-require 'cuprum/function'
+require 'cuprum/command'
 
 module Cuprum
   # Functional object that with syntactic sugar for tracking the last result.
@@ -32,13 +32,13 @@ module Cuprum
   # implementation block to the constructor or by creating a subclass that
   # overwrites the #process method.
   #
-  # @see Cuprum::Function
-  class Operation < Cuprum::Function
+  # @see Cuprum::Command
+  class Operation < Cuprum::Command
     # Module-based implementation of the Operation methods. Use this to convert
     # an already-defined function into an operation.
     #
     # @example
-    #   class CustomOperation < CustomFunction
+    #   class CustomOperation < CustomCommand
     #     include Cuprum::Operation::Mixin
     #   end # class
     module Mixin
@@ -60,11 +60,11 @@ module Cuprum
       #   @yield If a block argument is given, it will be passed to the
       #     implementation.
       #
-      #   @raise [NotImplementedError] Unless a block was passed to the
-      #     constructor or the #process method was overriden by a Function
+      #   @raise [Cuprum::NotImplementedError] Unless a block was passed to the
+      #     constructor or the #process method was overriden by a Command
       #     subclass.
       #
-      # @see Cuprum::Function#call
+      # @see Cuprum::Command#call
       def call *args, &block
         reset! if called? # Clear reference to most recent result.
 

data/lib/cuprum/utils/instance_spy.rb

@@ -1,4 +1,3 @@
-require 'cuprum/built_in/null_function'
 require 'cuprum/utils'
 
 module Cuprum::Utils
@@ -9,26 +8,26 @@ module Cuprum::Utils
   # call a function instance.
   #
   # @example Observing calls to instances of a function.
-  #   spy = Cuprum::Utils::InstanceSpy.spy_on(CustomFunction)
+  #   spy = Cuprum::Utils::InstanceSpy.spy_on(CustomCommand)
   #
   #   expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
   #
-  #   CustomFunction.new.call(1, 2, 3, :four => '4')
+  #   CustomCommand.new.call(1, 2, 3, :four => '4')
   #
   # @example Observing calls to a chained function.
-  #   spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedFunction)
+  #   spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedCommand)
   #
   #   expect(spy).to receive(:call)
   #
-  #   Cuprum::Function.new {}.
-  #     chain { |result| ChainedFunction.new.call(result) }.
+  #   Cuprum::Command.new {}.
+  #     chain { |result| ChainedCommand.new.call(result) }.
   #     call
   #
   # @example Block syntax
-  #   Cuprum::Utils::InstanceSpy.spy_on(CustomFunction) do |spy|
+  #   Cuprum::Utils::InstanceSpy.spy_on(CustomCommand) do |spy|
   #     expect(spy).to receive(:call)
   #
-  #     CustomFunction.new.call
+  #     CustomCommand.new.call
   #   end # spy_on
   module InstanceSpy
     # Minimal class that implements a #call method to mirror method calls to
@@ -52,13 +51,13 @@ module Cuprum::Utils
       # 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.
-      #   Must be either a Module, or a Class that extends Cuprum::Function.
+      #   Must be either a Module, or a Class that extends Cuprum::Command.
       #
       # @raise [ArgumentError] If the argument is neither a Module nor a Class
-      #   that extends Cuprum::Function.
+      #   that extends Cuprum::Command.
       #
       # @note Calling this method for the first time will prepend the
-      #   Cuprum::Utils::InstanceSpy module to Cuprum::Function.
+      #   Cuprum::Utils::InstanceSpy module to Cuprum::Command.
       #
       # @overload spy_on(function_class)
       #   @return [Cuprum::Utils::InstanceSpy::Spy] The instance spy.
@@ -107,17 +106,17 @@ module Cuprum::Utils
         return if function_class.is_a?(Module) && !function_class.is_a?(Class)
 
         return if function_class.is_a?(Class) &&
-                  function_class <= Cuprum::Function
+                  function_class <= Cuprum::Command
 
         raise ArgumentError,
-          'must be a class inheriting from Cuprum::Function',
+          'must be a class inheriting from Cuprum::Command',
           caller(1..-1)
       end # method guard_spy_class!
 
       def instrument_call!
-        return if Cuprum::Function < Cuprum::Utils::InstanceSpy
+        return if Cuprum::Command < Cuprum::Utils::InstanceSpy
 
-        Cuprum::Function.prepend(Cuprum::Utils::InstanceSpy)
+        Cuprum::Command.prepend(Cuprum::Utils::InstanceSpy)
       end # method instrument_call!
 
       def spies
@@ -129,7 +128,7 @@ module Cuprum::Utils
       end # method spies_for
     end # eigenclass
 
-    # (see Cuprum::Function#call)
+    # (see Cuprum::Command#call)
     def call *args, &block
       Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &block)
 

data/lib/cuprum/version.rb

@@ -8,7 +8,7 @@ module Cuprum
     # Major version.
     MAJOR = 0
     # Minor version.
-    MINOR = 5
+    MINOR = 6
     # Patch version.
     PATCH = 0
     # Prerelease version.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-17 00:00:00.000000000 Z
+date: 2017-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -80,8 +80,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.15'
-description: A lightweight, functional-lite toolkit for making business logic a first-class
-  citizen of your application.
+description: An opinionated implementation of the Command pattern for Ruby applications.
+  Cuprum wraps your business logic in a consistent, object-oriented interface and
+  features status and error management, composability and control flow management.
 email:
 - merlin@sleepingkingstudios.com
 executables: []
@@ -93,12 +94,15 @@ files:
 - LICENSE
 - README.md
 - lib/cuprum.rb
+- lib/cuprum/basic_command.rb
 - lib/cuprum/built_in.rb
-- lib/cuprum/built_in/identity_function.rb
+- lib/cuprum/built_in/identity_command.rb
 - lib/cuprum/built_in/identity_operation.rb
-- lib/cuprum/built_in/null_function.rb
+- lib/cuprum/built_in/null_command.rb
 - lib/cuprum/built_in/null_operation.rb
-- lib/cuprum/function.rb
+- lib/cuprum/chaining.rb
+- lib/cuprum/command.rb
+- lib/cuprum/not_implemented_error.rb
 - lib/cuprum/operation.rb
 - lib/cuprum/result.rb
 - lib/cuprum/utils.rb
@@ -127,5 +131,5 @@ rubyforge_project:
 rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
-summary: A lightweight, functional-lite toolkit.
+summary: An opinionated implementation of the Command pattern.
 test_files: []

data/lib/cuprum/function.rb

@@ -1,447 +0,0 @@
-require 'cuprum/result'
-
-module Cuprum
-  # Functional object that encapsulates a business logic operation with a
-  # consistent interface and tracking of result value and status.
-  #
-  # A Function can be defined either by passing a block to the constructor, or
-  # by defining a subclass of Function and implementing the #process method.
-  #
-  # @example A Function with a block
-  #   double_function = Cuprum::Function.new { |int| 2 * int }
-  #   result          = double_function.call(5)
-  #
-  #   result.value #=> 10
-  #
-  # @example A Function subclass
-  #   class MultiplyFunction < Cuprum::Function
-  #     def initialize multiplier
-  #       @multiplier = multiplier
-  #     end # constructor
-  #
-  #     private
-  #
-  #     def process int
-  #       int * @multiplier
-  #     end # method process
-  #   end # class
-  #
-  #   triple_function = MultiplyFunction.new(3)
-  #   result          = triple_function.call(5)
-  #
-  #   result.value #=> 15
-  #
-  # @example A Function with errors
-  #   class DivideFunction < Cuprum::Function
-  #     def initialize divisor
-  #       @divisor = divisor
-  #     end # constructor
-  #
-  #     private
-  #
-  #     def process int
-  #       if @divisor.zero?
-  #         errors << 'errors.messages.divide_by_zero'
-  #
-  #         return
-  #       end # if
-  #
-  #       int / @divisor
-  #     end # method process
-  #   end # class
-  #
-  #   halve_function = DivideFunction.new(2)
-  #   result         = halve_function.call(10)
-  #
-  #   result.errors #=> []
-  #   result.value  #=> 5
-  #
-  #   function_with_errors = DivideFunction.new(0)
-  #   result               = function_with_errors.call(10)
-  #
-  #   result.errors #=> ['errors.messages.divide_by_zero']
-  #   result.value  #=> nil
-  #
-  # @example Function Chaining
-  #   class AddFunction < Cuprum::Function
-  #     def initialize addend
-  #       @addend = addend
-  #     end # constructor
-  #
-  #     private
-  #
-  #     def process int
-  #       int + @addend
-  #     end # method process
-  #   end # class
-  #
-  #   double_and_add_one = MultiplyFunction.new(2).chain(AddFunction.new(1))
-  #   result             = double_and_add_one(5)
-  #
-  #   result.value #=> 5
-  #
-  # @example Conditional Chaining With #then And #else
-  #   class EvenFunction < Cuprum::Function
-  #     private
-  #
-  #     def process int
-  #       errors << 'errors.messages.not_even' unless int.even?
-  #
-  #       int
-  #     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_function =
-  #     EvenFunction.new.
-  #       then(DivideFunction.new(2)).
-  #       else(MultiplyFunction.new(3).chain(AddFunction.new(1)))
-  #
-  #   result = collatz_function.new(5)
-  #   result.value #=> 16
-  #
-  #   result = collatz_function.new(16)
-  #   result.value #=> 8
-  class Function # rubocop:disable Metrics/ClassLength
-    # Error class for calling a Function that was not given a definition block
-    # or have a #process method defined.
-    class NotImplementedError < StandardError
-      # Error message for a NotImplementedError.
-      DEFAULT_MESSAGE = 'no implementation defined for function'.freeze
-
-      def initialize message = nil
-        super(message || DEFAULT_MESSAGE)
-      end # constructor
-    end # class
-
-    # Returns a new instance of Cuprum::Function.
-    #
-    # @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 function.
-    #
-    #   @yield If a block argument is given, it will be passed to the
-    #     implementation.
-    #
-    #   @raise [NotImplementedError] Unless a block was passed to the
-    #     constructor or the #process method was overriden by a Function
-    #     subclass.
-    def call *args, &block
-      call_chained_functions do
-        wrap_result do |result|
-          merge_results(result, process(*args, &block))
-        end # method wrap_result
-      end # call_chained_functions
-    end # method call
-
-    # Registers a function or block to run after the current function, or after
-    # the last chained function if the current function already has one or more
-    # chained function(s). This creates and modifies a copy of the current
-    # function.
-    #
-    # @param on [Symbol] Sets a condition on when the chained function can run,
-    #   based on the status of the previous function. Valid values are :success,
-    #   :failure, and :always. A value of :success will constrain the function
-    #   to run only if the previous function succeeded. A value of :failure will
-    #   constrain the function to run only if the previous function failed. A
-    #   value of :always will ensure the function is always run, even if the
-    #   function chain has been halted. If no value is given, the function will
-    #   run whether the previous function was a success or a failure, but not if
-    #   the function chain has been halted.
-    #
-    # @overload chain(function, on: nil)
-    #   The function will be passed the #value of the previous function result
-    #   as its parameter, and the result of the chained function will be
-    #   returned (or passed to the next chained function, if any).
-    #
-    #   @param function [Cuprum::Function] The function to call after the
-    #     current or last chained function.
-    #
-    # @overload chain(on: :nil, &block)
-    #   The block will be passed the #result of the previous function as its
-    #   parameter. If your use case depends on the status of the previous
-    #   function or on any errors generated, use the block form of #chain.
-    #
-    #   If the block returns a Cuprum::Result (or an object responding to #value
-    #   and #success?), the block result will be returned (or passed to the next
-    #   chained function, if any). If the block returns any other value
-    #   (including nil), the #result of the previous function will be returned
-    #   or passed to the next function.
-    #
-    #   @yieldparam result [Cuprum::Result] The #result of the previous
-    #     function.
-    #
-    # @return [Cuprum::Function] The chained function.
-    def chain function = nil, on: nil, &block
-      clone.tap do |fn|
-        fn.chained_functions << build_chain_link(block || function, :on => on)
-      end # tap
-    end # method chain
-
-    # Shorthand for function.chain(:on => :failure). Registers a function or
-    # block to run after the current function. The chained function will only
-    # run if the previous function was unsuccessfully run.
-    #
-    # @overload else(function)
-    #
-    #   @param function [Cuprum::Function] The function to call after the
-    #     current or last chained function.
-    #
-    # @overload else(&block)
-    #
-    #   @yieldparam result [Cuprum::Result] The #result of the previous
-    #     function.
-    #
-    # @return [Cuprum::Function] The chained function.
-    #
-    # @see #chain
-    def else function = nil, &block
-      chain(function, :on => :failure, &block)
-    end # method else
-
-    # Shorthand for function.chain(:on => :success). Registers a function or
-    # block to run after the current function. The chained function will only
-    # run if the previous function was successfully run.
-    #
-    # @overload then(function)
-    #
-    #   @param function [Cuprum::Function] The function to call after the
-    #     current or last chained function.
-    #
-    # @overload then(&block)
-    #
-    #   @yieldparam result [Cuprum::Result] The #result of the previous
-    #     function.
-    #
-    # @return [Cuprum::Function] The chained function.
-    #
-    # @see #chain
-    def then function = nil, &block
-      chain(function, :on => :success, &block)
-    end # method then
-
-    protected
-
-    def chained_functions
-      @chained_functions ||= []
-    end # method chained_functions
-
-    private
-
-    def build_chain_link function_or_proc, on: nil
-      {
-        :proc => convert_function_or_proc_to_proc(function_or_proc),
-        :on   => on
-      } # end hash
-    end # method build_chain_link
-
-    # @!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 call_chained_functions
-      chained_functions.reduce(yield) do |result, hsh|
-        next result if skip_chained_function?(result, :on => hsh[:on])
-
-        value = hsh.fetch(:proc).call(result)
-
-        convert_value_to_result(value) || result
-      end # reduce
-    end # method call_chained_functions
-
-    def convert_function_or_proc_to_proc function_or_proc
-      return function_or_proc if function_or_proc.is_a?(Proc)
-
-      ->(result) { function_or_proc.call(result) }
-    end # method convert_function_or_proc_to_proc
-
-    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!
-
-    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 NotImplementedError
-    #
-    # @note This is a private method.
-    def process *_args
-      raise 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
-
-    def skip_chained_function? last_result, on:
-      return false if on == :always
-
-      return true if last_result.respond_to?(:halted?) && last_result.halted?
-
-      case on
-      when :success
-        !last_result.success?
-      when :failure
-        !last_result.failure?
-      end # case
-    end # method skip_chained_function?
-
-    # @!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
-      value = nil
-
-      Cuprum::Result.new(:errors => build_errors).tap do |result|
-        begin
-          @result = result
-
-          value = yield result
-        ensure
-          @result = nil
-        end # begin-ensure
-      end # tap
-
-      value
-    end # method wrap_result
-  end # class
-end # module