result_vault 1.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc62221bda4ff92f32af12135f1e99b44a85c0960494b3daad9d727dbc7f78f0
+  data.tar.gz: c2d5f53c3919a4eca97a89e1c11d1e89167eff80b5de6d5f94595d9e7d398b4c
+SHA512:
+  metadata.gz: 5a6028e1dbc8910a763ddc914f2261280d1d8371747ff480e028774048735620bdf695be5bd9d2c0067582c421b739a96e80d7332a5a4bc250b3ddb669a55ba1
+  data.tar.gz: dea5c853880da64aca0e40924960c7787b77c68f80c718a6f0f7875e50b574c3422cd526f2828ff5f038919d2632d674ed17bcaee0f368a0a7caecf2aa2ca7d0

data/lib/result_vault/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ResultVault
+  VERSION = "1.2.3"
+end

data/lib/result_vault.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require_relative "result_vault/version"
+
+##
+# A mechanism for returning a multi-factor result from any object call.
+#
+# @example
+#   result = ResultVault.new(error_message: "missing user", user_id: 123)
+#   result.user_name = 'Test User'
+#
+#   result.user_id        #=> 123
+#   result.user_name      #=> 'Test User'
+#   result.error_message  #=> "missing user"
+#
+class ResultVault
+
+  # ======================================================================
+  # = Public Methods
+  # ======================================================================
+
+  ##
+  # Returns the success value
+  #
+  # @return [boolean] success
+  #
+  def success?
+    !!@success
+  end
+  alias :ok?        :success?
+  alias :good?      :success?
+  alias :pass?      :success?
+  alias :passed?    :success?
+  alias :succeeded? :success?
+
+
+  ##
+  # Set success to true
+  #
+  def success=(val)
+    _update_vault(:success, val)
+  end
+  alias :ok=        :success=
+  alias :good=      :success=
+  alias :pass=      :success=
+  alias :passed=    :success=
+  alias :succeeded= :success=
+
+
+  ##
+  # Resturns the status or nil
+  #
+  # @return [Symbol, String, *, nil]
+  #
+  def status
+    @status
+  end
+
+
+  ##
+  # Sets the status
+  #
+  # @param [*] new_status
+  #   a description of the error
+  #
+  def status=(new_status)
+    _update_vault(:status, new_status)
+  end
+
+
+  ##
+  # Returns the stored exception
+  #
+  # @returns [Exception, nil]
+  #
+  def exception
+    @exception
+  end
+
+
+  ##
+  # Sets the stored exception
+  #
+  # @param [Exception] xcptn
+  #   an instance of the Exception class
+  #
+  def exception=(xcptn)
+    _update_vault(:exception, xcptn)
+  end
+
+
+  ##
+  # Resturns the stored error message or an empty string
+  #
+  # @return [String]
+  #
+  def error_message
+    @error_message
+  end
+
+
+  ##
+  # Sets the error message
+  #
+  # @param [String] err_msg
+  #   a description of the error
+  #
+  def error_message=(err_msg)
+    _update_vault(:error_message, err_msg)
+  end
+
+
+  ##
+  # Raise an exception if the user is setting data directly
+  #
+  def data=(*)
+    fail ArgumentError, ":data is a reserved keyword and may not be set directly."
+  end
+
+
+  ##
+  # Return a frozen copy of the stoted data
+  #
+  # @returns [Hash]
+  #
+  def data
+    result                  = @data.dup
+    result[:success]        = success?
+    result[:status]         = status
+    result[:error_message]  = error_message
+    result.freeze
+  end
+
+
+  ##
+  # Return an array of method names
+  #
+  # @retun [Array[Symbol]]
+  #
+  def methods(regular = true)
+    method_names  = super(regular)
+    method_names += _data_method_names
+    method_names -= _excluded_method_names
+
+    return method_names
+  end
+
+
+  ##
+  # Returns true if the vaul responds to the given methods
+  #
+  # @param [Symbol, String]
+  def respond_to?(name)
+    return false if _excluded_method_names.include?(name.to_sym)
+    return true  if _data_method_names.include?(name.to_sym)
+    super
+  end
+
+
+  # ======================================================================
+  # = Private
+  # ======================================================================
+  #
+  private
+
+  ##
+  # Initialize the response object's data-hash with the given arguments
+  #
+  # @param [Hash] args
+  #   a list of keyword parameters
+  #
+  def initialize(**args)
+    @data           = {}
+    @success        = false
+    @exception      = nil
+    @error_message  = ''
+
+    # add all arguments to the data hash
+    args.each { |key, val| _update_vault(key, val) }
+  end
+
+
+  ##
+  # Update the Vault's data
+  #
+  # @param [Symbol] key
+  #   the key to use for storage
+  #
+  # @param [*]
+  #   the value to be stored
+  #
+  def _update_vault(key, val)
+    _assert_symbolic_key(key)
+    _assert_not_frozen!
+
+    case key
+    when :data
+      fail ArgumentError, ":data is a reserved keyword and may not be set directly."
+
+    when :status
+      @status = val
+
+    when :exception
+      _assert_valid_exception(val)
+      @exception = val
+
+    when :success, :ok, :good, :pass, :passed, :succeeded
+      @success = !!val
+
+    when :error_message
+      @error_message = val
+
+    else
+      @data[key] = val
+    end
+  end
+
+
+  ##
+  # Return an array of the method names that should be excluded
+  # from the list of available methods.
+  #
+  # @note
+  #   This changes on whether the vault is frozen or not
+  #
+  def _excluded_method_names
+    excluded = [:data=]
+
+    if frozen?
+      excluded += [:success=, :ok=, :good=, :pass=, :succeeded=, :status=, :exception=, :error_messgae=]
+
+      @data.keys.each { |key| excluded << "#{key}=".to_sym }
+    end
+
+    return excluded
+  end
+
+
+  ##
+  # Return an array of the data keys for this vault,
+  # omitting the setter methods if the vault is frozen
+  #
+  def _data_method_names
+    data_methods = []
+
+    @data.keys.each do |key|
+      data_methods << key
+      data_methods << "#{key}=".to_sym unless frozen?
+    end
+
+    return data_methods
+  end
+
+
+  ##
+  # Test if an ancestor class has the method, otherwise test if
+  # it's a vault dynamic method
+  #
+  # @param [Symbol] method_sym
+  #   the name of the method
+  #
+  # @param [Array] arguments
+  #   the arguments for the method
+  #
+  # @block
+  #   an optional block
+  #
+  def method_missing(method_sym, *arguments, &block)
+    no_method_error = nil
+    catch :check_ancestors do
+      super
+    rescue => e
+      no_method_error = e
+      throw :check_ancestors
+    end
+
+    _dynamic_method_missing(method_sym, arguments.first, no_method_error)
+  end
+
+
+  ##
+  # If the missing method name ends in an '=' character, update the data.
+  # If the missing method name is already within the data hash, return the value
+  #
+  # @param [Symbol] method_sym
+  #   the name of the method
+  #
+  # @param * the value to set
+  #   the value for setting the method
+  #
+  # @param [NoMethodError]
+  #   the no methed exection to raise if there's no dynamic method
+  #
+  def _dynamic_method_missing(method_sym, val, no_method_error)
+    case
+    when @data.keys.include?(method_sym)
+      @data[method_sym]
+
+    when method_sym[-1].eql?('=')
+      _update_vault(method_sym[0..-2].to_sym, val)
+
+    else
+      raise no_method_error
+    end
+  end
+
+
+  ##
+  # @return [boolean]
+  #   true if the given method end with an '=' or the method exists
+  #
+  def respond_to_missing?(method_sym, include_private = false)
+    return true  if super
+    return true  if @data.keys.include?(method_sym)
+    return false if frozen?
+
+    method_sym[-1].eql?('=')
+  end
+
+
+  # = Assertions
+  # ======================================================================
+
+  ##
+  # Raise an exception if the provided key is not a Symbol
+  #
+  def _assert_symbolic_key(key)
+    return if key.is_a?(Symbol)
+    fail ArgumentError, "String key submitted: '#{key}'. Keys should be Symbols only."
+  end
+
+
+  ##
+  # Raise an error if the result is forzen
+  #
+  # @raise [RuntimeError]
+  #   if the result is frozen
+  #
+  def _assert_not_frozen!
+    fail 'This result vault may no longer be modified' if frozen?
+  end
+
+
+  ##
+  # Raise an exception if the provided value is not an Expection
+  #
+  def _assert_valid_exception(exception)
+    return if exception.is_a?(Exception)
+    fail ArgumentError, "The :exception= method will only accept an Exception instance, such as RuntimeError or AurgumentError"
+  end
+
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: result_vault
+version: !ruby/object:Gem::Version
+  version: 1.2.3
+platform: ruby
+authors:
+- CodeMeister
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-25 00:00:00.000000000 Z
+dependencies: []
+description: "     When your method needs to return more than a single value,     ResultVault
+  is a pure ruby solution that lets you add all     the extra bits you need while
+  still returning a single object.   "
+email:
+- result_vault@codemeister.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/result_vault.rb
+- lib/result_vault/version.rb
+homepage: https://github.com/Rubology/result_vault
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Rubology/result_vault
+  source_code_uri: https://github.com/Rubology/result_vault
+  changelog_uri: https://github.com/Rubology/result_vault/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.5
+signing_key:
+specification_version: 4
+summary: When your method needs to return more than a single value.
+test_files: []