cuprum 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5a329ab1299b862bc041a64a19da75c47101f902
-  data.tar.gz: 570f6b167f4b76570166a6293f81682b10197b59
+  metadata.gz: '0797c743296d8ae77c0cebf8db95ed48bb7701ac'
+  data.tar.gz: 78eef973b33c1ae167ac74f7e04169142ef69e45
 SHA512:
-  metadata.gz: 3bc9f429efab47bf5fcee2f843481afeae3e0709bafefd0810b7b4cb91038826ae0af00218b26f08d033f76fa7d90445ddc6f410a9a725741c3f43d0b8fcec02
-  data.tar.gz: 5aab1f5a727267c4b6cd95c037a987b36fdbc7c5c94fc2d03add97c996fcb1eabcbc36247bf2dddb89ae09ac252e4543ebd34d4f03cfcd984ab0d29726e30daf
+  metadata.gz: 356d580bea16226d831453bcb98cfe32bc6d38b264b53c6935cb91adccfc9f627ed416269374c42dc513187d34add5aa5a3298cfc8b4ef897dd785a58436bfdb
+  data.tar.gz: 0e181b037184bdd6e0ea774cc1861cea9997ba6d01bee5cba4b92e99ce5348d9a1b66f536b634e91269cc9dfc4a4b0c68172d7be76f32f33ff663d65eef008a9

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.0
+
+The "Halt And Catch Fire" Update.
+
+## Functions
+
+Can now call `#success!` or `#failure!` in a function block or `#process` method to override the default, error-based status for the result. This allows for a passing result that still has errors, or a failing result that does not have explicit errors.
+
+Can now call `#halt!` in a function block or `#process` method. If a function has been halted, then any subsequent chained functions will not be run unless they were chained with the `:on => :always` option.
+
+Can now generate results with custom error objects by overriding the `#build_errors` method.
+
+Fixed an inconsistency issue when a function block or `#process` method returned an instance of `Cuprum::Result`.
+
+## Operations
+
+Calling `#call` on an operation now returns the operation instance.
+
+## Results
+
+Can now call `#success!` or `#failure!` to override the default, error-based status.
+
+Can now call `#halt!` and check the `#halted?` status. A halted result will prevent subsequent chained functions from being run.
+
 ## 0.3.0
 
 The "Nothing To Lose But Your Chains" Update.

data/DEVELOPMENT.md

@@ -2,22 +2,17 @@
 
 ## Function
 
-- Handle when block or #process returns a Result instance.
 - #build_errors method
 - Predefined functions/operations:
   - NullFunction
   - IdentityFunction
   - MapFunction
+  - RetryFunction
 
 ## Operation
 
-- #reset! should return self
-
 ## Result
 
-- Abort chaining with #halt!, #halted? methods.
-- Force success or failure status with #success!, #failure! methods.
-
 ## Documentation
 
 Chaining Case Study: |

data/README.md

@@ -99,6 +99,59 @@ If the block returns a Cuprum::Result (or an object responding to #value and #su
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#else-instance_method)
 
+#### `#build_errors`
+
+*Private method*. 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.
+
+    build_errors() #=> Array
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#build_errors-instance_method)
+
+### Implementation Hooks
+
+These methods are only available while the Function is being called, and allow the implementation to update the errors of and override the results of the result object.
+
+#### `#errors`
+
+Only available while the Function is being called. Provides access to the errors object of the generated Cuprum::Result, which is by default an instance of Array.
+
+    errors() #=> Array
+
+Inside of the Function block or the `#process` method, you can add errors to the result.
+
+    function =
+      Cuprum::Function.new do
+        errors << "I'm sorry, something went wrong."
+
+        nil
+      end # function
+
+    result = function.call
+    result.failure?
+    #=> true
+    result.errors
+    #=> ["I'm sorry, something went wrong."]
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#errors-instance_method)
+
+#### `#success!`
+
+Only available while the Function is being called. If called, marks the result object as passing, even if the result has errors.
+
+    success!() #=> NilClass
+
+#### `#failure!`
+
+Only available while the Function is being called. If called, marks the result object as failing, even if the result does not have errors.
+
+    failure!() #=> NilClass
+
+#### `#halt!`
+
+Only available while the Function is being called. If called, halts the function chain (see Chaining Functions, below). Subsequent chained functions will not be called unless they were chained with the `:on => :always` option.
+
+    halt!() #=> NilClass
+
 ### Defining With a Block
 
 Functions can be used right out of the box by passing a block to the Cuprum::Function constructor, as follows:
@@ -246,11 +299,35 @@ The methods `#then` and `#else` serve as shortcuts for `#chain` with `:on => :su
     result = collatz_function.new(16)
     result.value #=> 8
 
+#### Halting A Function Chain
+
+If the `#halt` method is called as part of a Function block or `#process` method, the function chain is halted. Any subsequent chained functions will not be called unless they were chained with the `:on => :always` option. This allows you to terminate a Function chain early without having to raise and rescue an exception.
+
+    panic_function =
+      Cuprum::Function.new do |value|
+        halt!
+
+        value
+      end # function
+
+    result =
+      double_function.
+        then(panic_function).
+        then(AddFunction.new(1)). #=> This is never executed.
+        chain(:on => :always) { |count| puts "There are #{count} lights!" }.
+        call(2)
+    #=> Writes "There are 4 lights!" to STDOUT.
+
+    result.value   #= 4
+    result.halted? #=> true
+
 ## Operations
 
 [Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
 
-An Operation is like a Function, but with an additional trick of tracking its own most recent execution result. This allows us to simplify some conditional logic, especially boilerplate code used to interact with frameworks.
+An Operation is like a Function, but with two key differences. First, an Operation retains a reference to the result object from the most recent time the operation was called and delegates the methods defined by `Cuprum::Result` to the most recent result. This allows a called Operation to replace a `Cuprum::Result` in any code that expects or returns a result. Second, the `#call` method returns the operation instance, rather than the result itself.
+
+These two features allow developers to simplify logic around calling and using the results of operations, and reduce the need for boilerplate code (particularly when using an operation as part of an existing framework, such as inside of an asynchronous worker or a Rails controller action).
 
     class CreateBookOperation < Cuprum::Operation
       def process

data/lib/cuprum/function.rb

@@ -128,7 +128,9 @@ module Cuprum
 
     # @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.
+    #   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.
     #
@@ -144,12 +146,12 @@ module Cuprum
     #     subclass.
     def call *args, &block
       call_chained_functions do
-        Cuprum::Result.new.tap do |result|
-          @errors = result.errors
+        Cuprum::Result.new(:errors => build_errors).tap do |result|
+          @result = result
 
-          result.value = process(*args, &block)
+          merge_results(result, process(*args, &block))
 
-          @errors = nil
+          @result = nil
         end # tap
       end # call_chained_functions
     end # method call
@@ -160,11 +162,14 @@ module Cuprum
     # 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
-    #   and :failure, and will constrain the function to run only if the
-    #   previous function succeeded or failed, respectively. If no value is
-    #   given, the function will run whether the previous function was a success
-    #   or a failure.
+    #   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
@@ -243,16 +248,6 @@ module Cuprum
 
     protected
 
-    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)
-
-        value_is_result?(value) ? value : result
-      end # reduce
-    end # method call_chained_functions
-
     def chain_function proc, on: nil
       hsh = { :proc => proc }
       hsh[:on] = on if on
@@ -268,7 +263,27 @@ module Cuprum
 
     private
 
-    attr_reader :errors
+    # @!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)
@@ -276,11 +291,97 @@ module Cuprum
       ->(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!
+
+    def merge_errors result, other
+      return unless other.respond_to?(:errors)
+
+      result.errors += other.errors
+    end # method merge_errors
+
+    def merge_results result, other
+      if value_is_result?(other)
+        result.value = other.value
+
+        merge_errors(result, other)
+      else
+        result.value = other
+      end # if-else
+
+      result
+    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 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?
@@ -289,6 +390,21 @@ module Cuprum
       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

data/lib/cuprum/operation.rb

@@ -3,10 +3,17 @@ require 'cuprum/function'
 module Cuprum
   # Functional object that with syntactic sugar for tracking the last result.
   #
-  # An Operation is like a Function, but with an additional trick of tracking
-  # its own most recent execution result. This allows us to simplify some
-  # conditional logic, especially boilerplate code used to interact with
-  # frameworks.
+  # An Operation is like a Function, but with two key differences. First, an
+  # Operation retains a reference to the result object from the most recent time
+  # the operation was called and delegates the methods defined by Cuprum::Result
+  # to the most recent result. This allows a called Operation to replace a
+  # Cuprum::Result in any code that expects or returns a result. Second, the
+  # #call method returns the operation instance, rather than the result itself.
+  #
+  # These two features allow developers to simplify logic around calling and
+  # using the results of operations, and reduce the need for boilerplate code
+  # (particularly when using an operation as part of an existing framework,
+  # such as inside of an asynchronous worker or a Rails controller action).
   #
   # @example
   #   def create
@@ -31,11 +38,31 @@ module Cuprum
     #   operation.
     attr_reader :result
 
-    # (see Cuprum::Function#call)
+    # @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 the
+    #   operation object.
+    #
+    #   @param arguments [Array] Arguments to be passed to the implementation.
+    #
+    #   @param keywords [Hash] Keywords to be passed to the implementation.
+    #
+    #   @return [Cuprum::Operation] the called operation.
+    #
+    #   @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.
+    #
+    # @see Cuprum::Function#call
     def call *args, &block
       reset! if called? # Clear reference to most recent result.
 
       @result = super
+
+      self
     end # method call
 
     # @return [Boolean] true if the operation has been called and has a
@@ -57,6 +84,11 @@ module Cuprum
       called? ? result.failure? : false
     end # method success?
 
+    # @return [Boolean] true if the most recent was halted, otherwise false.
+    def halted?
+      called? ? result.halted? : false
+    end # method halted?
+
     # Clears the reference to the most recent call of the operation, if any.
     # This allows the result and any referenced data to be garbage collected.
     # Use this method to clear any instance variables or state internal to the

data/lib/cuprum/result.rb

@@ -10,6 +10,8 @@ module Cuprum
     def initialize value = nil, errors: []
       @value  = value
       @errors = errors
+      @status = nil
+      @halted = false
     end # constructor
 
     # @return [Object] the value returned by calling the function.
@@ -19,16 +21,52 @@ module Cuprum
     #   called.
     attr_accessor :errors
 
+    # Marks the result as a failure, whether or not the function generated any
+    # errors.
+    #
+    # @return [Cuprum::Result] The result.
+    def failure!
+      @status = :failure
+
+      self
+    end # method failure!
+
     # @return [Boolean] false if the function did not generate any errors,
     #   otherwise true.
     def failure?
-      !errors.empty?
+      @status == :failure || (@status.nil? && !errors.empty?)
     end # method failure?
 
+    # Marks the result as halted. Any subsequent chained functions will not be
+    #   run.
+    #
+    # @return [Cuprum::Result] The result.
+    def halt!
+      @halted = true
+
+      self
+    end # method halt!
+
+    # @return [Boolean] true if the function has been halted, and will not run
+    #   any subsequent chained functions.
+    def halted?
+      @halted
+    end # method halted?
+
+    # Marks the result as a success, whether or not the function generated any
+    # errors.
+    #
+    # @return [Cuprum::Result] The result.
+    def success!
+      @status = :success
+
+      self
+    end # method success!
+
     # @return [Boolean] true if the function did not generate any errors,
     #   otherwise false.
     def success?
-      errors.empty?
+      @status == :success || (@status.nil? && errors.empty?)
     end # method success?
   end # class
 end # module

data/lib/cuprum/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-29 00:00:00.000000000 Z
+date: 2017-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -117,7 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: A lightweight, functional-lite toolkit.