cuprum 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bea85b3d71780b913660e164e106f5d996c36218
-  data.tar.gz: 256bcdf2ac7b383c060c812d004f8b45d491e907
+  metadata.gz: 457807ef9d8b39d6980467ad264972081f01b9ec
+  data.tar.gz: 92fedf44dfd331ef25e1429c8f35c2af7ede6180
 SHA512:
-  metadata.gz: a0dbaddff3b7672ee4dc4cfd4ce06f27d958b2f816643aa2db13ee3704b8717e28f93c446130a104476bcda2991ac9963b2fc768b983a2d468cdc7b883545841
-  data.tar.gz: 8a465d71bcb45eb32b7cfb60a26e09e91be3736b0346c7b60f786d99371c09d8fa913c6ae2c9ad817a62cb837b15fae4c24d1545a00f05cd0e9dfc6a697de4ff
+  metadata.gz: ef543f82ad31ce828f01d4bfea7805da392ea524f4477af24ca77cb80b77ad623d9439af35ef2f8f5ef6d25b119e03dec104b73db966e287f2ebfc8141ab70de
+  data.tar.gz: 73c642f2383e11273184ec3145ab61808cd80646bdf1687ca9abb94a439d3f9bfbc12fceb4806845c49ac7b91eda570997a2e2d669a2c566da5dbca88a9e4df4

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0
+
+The "Fully Armed and Operational" Update.
+
+### Operations
+
+Implemented `Cuprum::Operation`. As a Function, but with an additional trick of tracking its own most recent execution result.
+
 ## 0.1.0
 
 Initial version.

data/DEVELOPMENT.md

@@ -8,10 +8,6 @@
 
 - Chaining with #then, #else, etc.
 
-## Operation
-
-- Wraps a function and tracks the last result object.
-
 ## Result
 
 - Force success or failure status with #success!, #failure! methods.

data/README.md

@@ -104,6 +104,46 @@ In addition, the result object defines `#success?` and `#failure?` predicates. I
     result.failure? #=> true
     result.value    #=> nil
 
+### Operations
+
+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.
+
+    class CreateBookOperation < Cuprum::Operation
+      def process
+        # Implementation here.
+      end # method process
+    end # class
+
+    def create
+      operation = CreateBookOperation.new.call(book_params)
+
+      if operation.success?
+        redirect_to(operation.value)
+      else
+        @book = operation.value
+
+        render :new
+      end # if-else
+    end # create
+
+Like a Function, an Operation can be defined directly by passing an implementation block to the constructor or by creating a subclass that overwrites the #process method.
+
+An operation inherits the `#call` method from Cuprum::Function (see above), and delegates the `#value`, `#errors`, `#success?`, and `#failure` methods to the most recent result (see below). If the operation has not been called, the operation will return default values.
+
+In addition, an operation defines the following methods:
+
+#### `#result`
+
+The most recent result, from the previous time `#call` was executed for the operation.
+
+#### `#called?`
+
+True if the operation has been called and there is a result available by calling `#result` or one of the delegated methods, otherwise false.
+
+#### `#reset!`
+
+Clears the most recent result and resets `#called?` to false. This frees the result and any linked data for garbage collection. It also clears any internal state from the operation.
+
 ### Results
 
 A Cuprum::Result is a data object that encapsulates the result of calling a Cuprum function - the returned value, the success or failure status, and any errors generated by the function. It defines the following methods:

data/lib/cuprum.rb

@@ -1,6 +1,10 @@
 # A lightweight, functional-lite toolkit for making business logic a first-class
 # citizen of your application.
 module Cuprum
+  autoload :Function,  'cuprum/function'
+  autoload :Operation, 'cuprum/operation'
+  autoload :Result,    'cuprum/result'
+
   # @return [String] The current version of the gem.
   def self.version
     VERSION

data/lib/cuprum/function.rb

@@ -1,5 +1,3 @@
-# lib/cuprum/function.rb
-
 require 'cuprum/result'
 
 module Cuprum

data/lib/cuprum/operation.rb

@@ -0,0 +1,85 @@
+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.
+  #
+  # @example
+  #   def create
+  #     operation = CreateBookOperation.new.call(book_params)
+  #
+  #     if operation.success?
+  #       redirect_to(operation.value)
+  #     else
+  #       @book = operation.value
+  #
+  #       render :new
+  #     end # if-else
+  #   end # create
+  #
+  # Like a Function, an Operation can be defined directly by passing an
+  # implementation block to the constructor or by creating a subclass that
+  # overwrites the #process method.
+  #
+  # @see Cuprum::Function
+  class Operation < Cuprum::Function
+    # @return [Cuprum::Result] The result from the most recent call of the
+    #   operation.
+    attr_reader :result
+
+    # (see Cuprum::Function#call)
+    def call *args, &block
+      reset! if called? # Clear reference to most recent result.
+
+      @result = super
+    end # method call
+
+    # @return [Boolean] true if the operation has been called and has a
+    #   reference to the most recent result; otherwise false.
+    def called?
+      !result.nil?
+    end # method called?
+
+    # @return [Array] the errors from the most recent result, or nil if the
+    #   operation has not been called.
+    def errors
+      super || (called? ? result.errors : nil)
+    end # method errors
+
+    # @return [Boolean] true if the most recent result had errors, or false if
+    #   the most recent result had no errors or if the operation has not been
+    #   called.
+    def failure?
+      called? ? result.failure? : false
+    end # method success?
+
+    # 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
+    # operation (an operation should never have external state apart from the
+    # last result).
+    #
+    # If the operation cannot be run more than once, this method should raise an
+    # error.
+    def reset!
+      @result = nil
+    end # method reset
+
+    # @return [Boolean] true if the most recent result had no errors, or false
+    #   if the most recent result had errors or if the operation has not been
+    #   called.
+    def success?
+      called? ? result.success? : false
+    end # method success?
+
+    # @return [Object] the value of the most recent result, or nil if the
+    #   operation has not been called.
+    def value
+      called? ? result.value : nil
+    end # method value
+  end # class
+end # module

data/lib/cuprum/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-17 00:00:00.000000000 Z
+date: 2017-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -28,16 +28,16 @@ dependencies:
   name: rspec-sleeping_king_studios
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.15.1
+        version: '1.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.15.1
+        version: '1.15'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +94,7 @@ files:
 - README.md
 - lib/cuprum.rb
 - lib/cuprum/function.rb
+- lib/cuprum/operation.rb
 - lib/cuprum/result.rb
 - lib/cuprum/version.rb
 homepage: http://sleepingkingstudios.com