cuprum 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bea85b3d71780b913660e164e106f5d996c36218
+  data.tar.gz: 256bcdf2ac7b383c060c812d004f8b45d491e907
+SHA512:
+  metadata.gz: a0dbaddff3b7672ee4dc4cfd4ce06f27d958b2f816643aa2db13ee3704b8717e28f93c446130a104476bcda2991ac9963b2fc768b983a2d468cdc7b883545841
+  data.tar.gz: 8a465d71bcb45eb32b7cfb60a26e09e91be3736b0346c7b60f786d99371c09d8fa913c6ae2c9ad817a62cb837b15fae4c24d1545a00f05cd0e9dfc6a697de4ff

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+Initial version.
+
+### Functions
+
+Implemented `Cuprum::Function`. A functional object that encapsulates a business logic operation with a consistent interface and tracking of result value and status.
+
+### Results
+
+Implemented `Cuprum::Result`. A data object that encapsulates the result of calling a Cuprum function.

data/DEVELOPMENT.md

@@ -0,0 +1,17 @@
+# Development
+
+## Errors
+
+- Dedicated errors object.
+
+## Function
+
+- 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/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2017 Rob Smith
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# Cuprum
+
+A lightweight, functional-lite toolkit for making business logic a first-class
+citizen of your application.
+
+## Support
+
+Cuprum is tested against Ruby 2.4.
+
+## Contribute
+
+### GitHub
+
+The canonical repository for this gem is located at https://github.com/sleepingkingstudios/cuprum.
+
+### A Note From The Developer
+
+Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use these tools every day, but they're not just written for me. If you find this project helpful in your own work, or if you have any questions, suggestions or critiques, please feel free to get in touch! I can be reached on GitHub (see above, and feel encouraged to submit bug reports or merge requests there) or via email at merlin@sleepingkingstudios.com. I look forward to hearing from you!
+
+## Features
+
+### Functions
+
+Functions are the core feature of Cuprum. In a nutshell, each Cuprum::Function is a functional object that encapsulates a business logic operation. A Function provides a consistent interface and tracking of result value and status. This minimizes boilerplate and allows for interchangeability between different implementations or strategies for managing your data and processes.
+
+Each Function implements a `#call` method that wraps your defined business logic and returns an instance of Cuprum::Result. The result wraps the returned data (with the `#value` method), any `#errors` generated when running the Function, and the overall status with the `#success?` and `#failure` methods. For more details about Cuprum::Result, see below.
+
+#### Defining With a Block
+
+Functions can be used right out of the box by passing a block to the Cuprum::Function constructor, as follows:
+
+    # A Function with a block
+    double_function = Function.new { |int| 2 * int }
+    result          = double_function.call(5)
+
+    result.value #=> 10
+
+The constructor block will be called each time `Function#call` is executed, and will be passed all of the arguments given to `#call`. You can even define a block parameter, which will be passed along to the constructor block when `#call` is called with a block argument.
+
+#### Defining With a Subclass
+
+Larger applications will want to create Function subclasses that encapsulate their business logic in a reusable, composable fashion. The implementation for each subclass is handled by the `#process` private method. If a subclass or its ancestors does not implement `#process`, a `Cuprum::Function::NotImplementedError` will be raised.
+
+    # A Function subclass
+    class MultiplyFunction
+      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
+
+As with the block syntax, a Function whose implementation is defined via the `#process` method will call `#process` each time that `#call` is executed, and will pass all arguments from `#call` on to `#process`. The value returned by `#process` will be assigned to the result `#value`.
+
+#### Success, Failure, and Errors
+
+Whether defined with a block or in the `#process` method, the Function implementation can access an `#errors` object while in the `#call` method. Any errors added to the errors object will be exposed by the `#errors` method on the result object.
+
+    # A Function with errors
+    class DivideFunction
+      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
+
+In addition, the result object defines `#success?` and `#failure?` predicates. If the result has no errors, then `#success?` will return true and `#failure?` will return false.
+
+    halve_function = DivideFunction.new(2)
+    result         = halve_function.call(10)
+
+    result.errors   #=> []
+    result.success? #=> true
+    result.failure? #=> false
+    result.value    #=> 5
+
+ If the result does have errors, `#success?` will return false and `#failure?` will return true.
+
+    function_with_errors = DivideFunction.new(0)
+    result               = function_with_errors.call(10)
+
+    result.errors   #=> ['errors.messages.divide_by_zero']
+    result.success? #=> false
+    result.failure? #=> true
+    result.value    #=> nil
+
+### 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:
+
+#### `#value`
+
+The value returned by the function. For example, for an increment function that added 1 to a given integer, the `#value` of the result object would be the incremented integer.
+
+#### `#errors`
+
+The errors generated by the function, or an empty array if no errors were generated.
+
+#### `#success?`
+
+True if the function did not generate any errors, otherwise false.
+
+#### `#failure?`
+
+True if the function generated one or more errors, otherwise false.

data/lib/cuprum.rb

@@ -0,0 +1,8 @@
+# A lightweight, functional-lite toolkit for making business logic a first-class
+# citizen of your application.
+module Cuprum
+  # @return [String] The current version of the gem.
+  def self.version
+    VERSION
+  end # class method version
+end # module

data/lib/cuprum/function.rb

@@ -0,0 +1,122 @@
+# lib/cuprum/function.rb
+
+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 = Function.new { |int| 2 * int }
+  #   result          = double_function.call(5)
+  #
+  #   result.value #=> 10
+  #
+  # @example A Function subclass
+  #   class MultiplyFunction
+  #     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
+  #     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
+  class Function
+    # 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.
+    #
+    #   @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
+      Cuprum::Result.new.tap do |result|
+        @errors = result.errors
+
+        result.value = process(*args, &block)
+
+        @errors = nil
+      end # tap
+    end # method call
+
+    private
+
+    attr_reader :errors
+
+    def process *_args
+      raise NotImplementedError, nil, caller(1..-1)
+    end # method process
+  end # class
+end # module

data/lib/cuprum/result.rb

@@ -0,0 +1,30 @@
+require 'cuprum'
+
+module Cuprum
+  # Data object that encapsulates the result of calling a Cuprum function or
+  # operation.
+  class Result
+    # @return [Object] the value returned by calling the function.
+    attr_accessor :value
+
+    attr_writer :errors
+
+    # @return [Array] the errors (if any) generated when the function was
+    #   called.
+    def errors
+      @errors ||= []
+    end # method errors
+
+    # @return [Boolean] false if the function did not generate any errors,
+    #   otherwise true.
+    def failure?
+      !errors.empty?
+    end # method failure?
+
+    # @return [Boolean] true if the function did not generate any errors,
+    #   otherwise false.
+    def success?
+      errors.empty?
+    end # method success?
+  end # class
+end # module

data/lib/cuprum/version.rb

@@ -0,0 +1,54 @@
+module Cuprum
+  # @api private
+  #
+  # The current version of the gem.
+  #
+  # @see http://semver.org/
+  module Version
+    # Major version.
+    MAJOR = 0
+    # Minor version.
+    MINOR = 1
+    # Patch version.
+    PATCH = 0
+    # Prerelease version.
+    PRERELEASE = nil
+    # Build metadata.
+    BUILD = nil
+
+    class << self
+      # Generates the gem version string from the Version constants.
+      #
+      # Inlined here because dependencies may not be loaded when processing a
+      # gemspec, which results in the user being unable to install the gem for
+      # the first time.
+      #
+      # @see SleepingKingStudios::Tools::SemanticVersion#to_gem_version
+      def to_gem_version
+        str = "#{MAJOR}.#{MINOR}.#{PATCH}"
+
+        prerelease = value_of(:PRERELEASE)
+        str << ".#{prerelease}" if prerelease
+
+        build = value_of(:BUILD)
+        str << ".#{build}" if build
+
+        str
+      end # class method to_version
+
+      private
+
+      def value_of constant
+        return nil unless const_defined?(constant)
+
+        value = const_get(constant)
+
+        return nil if value.respond_to?(:empty?) && value.empty?
+
+        value
+      end # method value_of
+    end # eigenclass
+  end # module
+
+  VERSION = Version.to_gem_version
+end # module

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: cuprum
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rob "Merlin" Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-08-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: rspec-sleeping_king_studios
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.49.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.49.1
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+description: A lightweight, functional-lite toolkit for making business logic a first-class
+  citizen of your application.
+email:
+- merlin@sleepingkingstudios.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- DEVELOPMENT.md
+- LICENSE
+- README.md
+- lib/cuprum.rb
+- lib/cuprum/function.rb
+- lib/cuprum/result.rb
+- lib/cuprum/version.rb
+homepage: http://sleepingkingstudios.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: A lightweight, functional-lite toolkit.
+test_files: []