errgonomic 0.1.0 → 0.3.0

data/lib/errgonomic/result.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Errgonomic
+  module Result
+    # The base class for Result's Ok and Err class variants. We implement as
+    # much logic as possible here, and let Ok and Err handle their
+    # initialization and self identification.
+    class Any
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      # Equality comparison for Result objects is based on value not reference.
+      #
+      # @param other [Object]
+      #
+      # @example
+      #   Ok(1) == Ok(1) # => true
+      #   Ok(1) == Err(1) # => false
+      #   Ok(1).object_id == Ok(1).object_id # => false
+      #   Ok(1) == 1 # => false
+      #   Err() == nil # => false
+      def ==(other)
+        return false if self.class != other.class
+
+        value == other.value
+      end
+
+      # Indicate that this is some kind of result object. Contrast to
+      # Object#result? which is false for all other types.
+      #
+      # @example
+      #   Ok("a").result? # => true
+      #   Err("a").result? # => true
+      #   "a".result? # => false
+      def result?
+        true
+      end
+
+      # Return true if the inner value is an Ok and the result of the block is
+      # truthy.
+      #
+      # @param [Proc] block The block to evaluate if the inner value is an Ok.
+      #
+      # @example
+      #   Ok(1).ok_and?(&:odd?) # => true
+      #   Ok(1).ok_and?(&:even?) # => false
+      #   Err(:a).ok_and? { |_| true } # => false
+      #   Err(:b).ok_and? { |_| false } # => false
+      def ok_and?(&block)
+        if ok?
+          !!block.call(value)
+        else
+          false
+        end
+      end
+
+      # Return true if the inner value is an Err and the result of the block is
+      # truthy.
+      #
+      # @example
+      #   Ok(1).err_and?(&:odd?) # => false
+      #   Ok(1).err_and?(&:even?) # => false
+      #   Err(:a).err_and? { |_| true } # => true
+      #   Err(:b).err_and? { |_| false } # => false
+      def err_and?(&block)
+        if err?
+          !!block.call(value)
+        else
+          false
+        end
+      end
+
+      # Return the inner value of an Ok, else raise an exception when Err.
+      #
+      # @example
+      #   Ok(1).unwrap! # => 1
+      #   Err(:c).unwrap! # => raise Errgonomic::UnwrapError, "value is an Err"
+      def unwrap!
+        raise Errgonomic::UnwrapError, 'value is an Err' unless ok?
+
+        @value
+      end
+
+      # Return the inner value of an Ok, else raise an exception with the given
+      # message when Err.
+      #
+      # @param msg [String]
+      #
+      # @example
+      #   Ok(1).expect!("should have worked") # => 1
+      #   Err(:d).expect!("should have worked") # => raise Errgonomic::ExpectError, "should have worked"
+      def expect!(msg)
+        raise Errgonomic::ExpectError, msg unless ok?
+
+        @value
+      end
+
+      # Return the inner value of an Err, else raise an exception when Ok.
+      #
+      # @example
+      #   Ok(1).unwrap_err! # => raise Errgonomic::UnwrapError, 1
+      #   Err(:e).unwrap_err! # => :e
+      def unwrap_err!
+        raise Errgonomic::UnwrapError, value unless err?
+
+        @value
+      end
+
+      # Given another result, return it if the inner result is Ok, else return
+      # the inner Err. Raise an exception if the other value is not a Result.
+      #
+      # @param other [Errgonomic::Result::Any]
+      #
+      # @example
+      #   Ok(1).and(Ok(2)) # => Ok(2)
+      #   Ok(1).and(Err(:f)) # => Err(:f)
+      #   Err(:g).and(Ok(1)) # => Err(:g)
+      #   Err(:h).and(Err(:i)) # => Err(:h)
+      #   Ok(1).and(2) # => raise Errgonomic::ArgumentError, "other must be a Result"
+      def and(other)
+        raise Errgonomic::ArgumentError, 'other must be a Result' unless other.is_a?(Errgonomic::Result::Any)
+        return self if err?
+
+        other
+      end
+
+      # Given a block, evaluate it and return its result if the inner result is
+      # Ok, else return the inner Err. This is lazy evaluated, and we
+      # pedantically check the type of the block's return value at runtime. This
+      # is annoying, sorry, but better than an "undefined method" error.
+      # Hopefully it gives your test suite a chance to detect incorrect usage.
+      #
+      # @param block [Proc]
+      #
+      # @example
+      #   Ok(1).and_then { |x| Ok(x + 1) } # => Ok(2)
+      #   Ok(1).and_then { |_| Err(:error) } # => Err(:error)
+      #   Err(:error).and_then { |x| Ok(x + 1) } # => Err(:error)
+      #   Err(:error).and_then { |x| Err(:error2) } # => Err(:error)
+      def and_then(&block)
+        return self if err?
+
+        res = block.call(value)
+        if !res.is_a?(Errgonomic::Result::Any) && Errgonomic.give_me_ambiguous_downstream_errors?
+          raise Errgonomic::ArgumentError, 'and_then block must return a Result'
+        end
+
+        res
+      end
+
+      # Return other if self is Err, else return the original Option. Raises a
+      # pedantic runtime exception if other is not a Result.
+      #
+      # @param other [Errgonomic::Result::Any]
+      #
+      # @example
+      #   Err(:j).or(Ok(1)) # => Ok(1)
+      #   Err(:k).or(Err(:l)) # => Err(:l)
+      #   Err(:m).or("oops") # => raise Errgonomic::ArgumentError, "other must be a Result; you might want unwrap_or"
+      def or(other)
+        unless other.is_a?(Errgonomic::Result::Any)
+          raise Errgonomic::ArgumentError,
+                'other must be a Result; you might want unwrap_or'
+        end
+        return other if err?
+
+        self
+      end
+
+      # Return self if it is Ok, else lazy evaluate the block and return its
+      # result. Raises a pedantic runtime check that the block returns a Result.
+      # Sorry about that, hopefully it helps your tests. Better than ambiguous
+      # downstream "undefined method" errors, probably.
+      #
+      # @param block [Proc]
+      #
+      # @example
+      #   Ok(1).or_else { Ok(2) } # => Ok(1)
+      #   Err(:o).or_else { Ok(1) } # => Ok(1)
+      #   Err(:q).or_else { Err(:r) } # => Err(:r)
+      #   Err(:s).or_else { "oops" } # => raise Errgonomic::ArgumentError, "or_else block must return a Result"
+      def or_else(&block)
+        return self if ok?
+
+        res = block.call(self)
+        if !res.is_a?(Errgonomic::Result::Any) && Errgonomic.give_me_ambiguous_downstream_errors?
+          raise Errgonomic::ArgumentError, 'or_else block must return a Result'
+        end
+
+        res
+      end
+
+      # Return the inner value if self is Ok, else return the provided default.
+      #
+      # @param other [Object]
+      #
+      # @example
+      #   Ok(1).unwrap_or(2) # => 1
+      #   Err(:t).unwrap_or(:u) # => :u
+      def unwrap_or(other)
+        return value if ok?
+
+        other
+      end
+
+      # Return the inner value if self is Ok, else lazy evaluate the block and
+      # return its result.
+      #
+      # @param block [Proc]
+      #
+      # @example
+      #   Ok(1).unwrap_or_else { 2 } # => 1
+      #   Err(:v).unwrap_or_else { :w } # => :w
+      def unwrap_or_else(&block)
+        return value if ok?
+
+        block.call(self)
+      end
+    end
+
+    # The Ok variant.
+    class Ok < Any
+      attr_accessor :value
+
+      # Ok is always ok
+      #
+      # @example
+      #   Ok(1).ok? # => true
+      def ok?
+        true
+      end
+
+      # Ok is never err
+      #
+      # @example
+      #   Ok(1).err? # => false
+      def err?
+        false
+      end
+    end
+
+    class Err < Any
+      class Arbitrary; end
+
+      attr_accessor :value
+
+      # Err may be constructed without a value, if you want.
+      #
+      # @example
+      #   Err(:y).value # => :y
+      #   Err().value # => Arbitrary
+      def initialize(value = Arbitrary)
+        super(value)
+      end
+
+      # Err is always err
+      #
+      # @example
+      #   Err(:z).err? # => true
+      def err?
+        true
+      end
+
+      # Err is never ok
+      #
+      # @example
+      #   Err(:A).ok? # => false
+      def ok?
+        false
+      end
+    end
+  end
+end
+
+# Introduce certain helper methods into the Object class.
+#
+# @example
+#   "foo".result? # => false
+#   "foo".assert_result! # => raise Errgonomic::ResultRequiredError
+class Object
+  # Convenience method to indicate whether we are working with a result.
+  # TBD whether we implement some stubs for the rest of the Result API; I want
+  # to think about how effectively these map to truthiness or presence.
+  #
+  # @example
+  #   "foo".result? # => false
+  #   Ok("foo").result? # => true
+  def result?
+    false
+  end
+
+  # Lacking static typing, we are going to want to make it easy to enforce at
+  # runtime that a given object is a Result.
+  #
+  # @example
+  #   "foo".assert_result! # => raise Errgonomic::ResultRequiredError
+  #   Ok("foo").assert_result! # => true
+  def assert_result!
+    return true if result?
+
+    raise Errgonomic::ResultRequiredError
+  end
+end
+
+# Global convenience method for constructing an Ok result.
+def Ok(value)
+  Errgonomic::Result::Ok.new(value)
+end
+
+# Global convenience method for constructing an Err result.
+def Err(value = Errgonomic::Result::Err::Arbitrary)
+  Errgonomic::Result::Err.new(value)
+end

data/lib/errgonomic/type.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class Object
+  # Returns the receiver if it matches the expected type, otherwise raises a TypeMismatchError.
+  # This is useful for enforcing type expectations in method arguments.
+  #
+  # @param type [Class] The expected type or module the receiver should be.
+  # @param message [String] Optional error message to raise if type doesn't match.
+  # @return [Object] The receiver if it is of the expected type.
+  # @example
+  #   'hello'.type_or_raise!(String) #=> "hello"
+  #   123.type_or_raise!(String, "We need a string!") #=> raise Errgonomic::TypeMismatchError, "We need a string!"
+  #   123.type_or_raise!(String) #=> raise Errgonomic::TypeMismatchError, "Expected String but got Integer"
+  def type_or_raise!(type, message = nil)
+    message ||= "Expected #{type} but got #{self.class}"
+    raise Errgonomic::TypeMismatchError, message unless is_a?(type)
+
+    self
+  end
+
+  alias type_or_raise type_or_raise!
+
+  # Returns the receiver if it matches the expected type, otherwise returns the default value.
+  #
+  # @param type [Class] The expected type or module the receiver should be.
+  # @param default [Object] The value to return if type doesn't match.
+  # @return [Object] The receiver if it is of the expected type, otherwise the default value.
+  # @example
+  #   'hello'.type_or(String, 'default')  # => "hello"
+  #   123.type_or(String, 'default')      # => "default"
+  def type_or(type, default)
+    return self if is_a?(type)
+
+    default
+  end
+
+  # Returns the receiver if it matches the expected type, otherwise returns the result of the block.
+  # Useful when constructing the default value is expensive.
+  #
+  # @param type [Class] The expected type or module the receiver should be.
+  # @param block [Proc] The block to call if type doesn't match.
+  # @return [Object] The receiver if it is of the expected type, otherwise the block result.
+  # @example
+  #   'hello'.type_or_else(String) { 'default' }  # => "hello"
+  #   123.type_or_else(String) { 'default' }      # => "default"
+  def type_or_else(type, &block)
+    return self if is_a?(type)
+
+    block.call
+  end
+
+  # Returns the receiver if it does not match the expected type, otherwise raises a TypeMismatchError.
+  #
+  # @param type [Class] The type or module the receiver should not be.
+  # @param message [String] Optional error message to raise if type matches.
+  # @return [Object] The receiver if it is not of the specified type.
+  # @example
+  #   'hello'.not_type_or_raise!(Integer) #=> "hello"
+  #   123.not_type_or_raise!(Integer, "We dont want an integer!") #=> raise Errgonomic::TypeMismatchError, "We dont want an integer!"
+  #   123.not_type_or_raise!(Integer) #=> raise Errgonomic::TypeMismatchError, "Expected anything but Integer but got Integer"
+  def not_type_or_raise!(type, message = nil)
+    message ||= "Expected anything but #{type} but got #{self.class}"
+    raise Errgonomic::TypeMismatchError, message if is_a?(type)
+
+    self
+  end
+end

data/lib/errgonomic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Errgonomic
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/errgonomic.rb

@@ -1,59 +1,61 @@
 # frozen_string_literal: true
 
-require_relative "errgonomic/version"
+require_relative 'errgonomic/version' unless defined?(Errgonomic::VERSION)
 
-# The semantics here borrow heavily from ActiveSupport. Let's prefer that if
-# loaded, otherwise just copypasta the bits we like. Or convince me to make that
-# gem a dependency.
-if !Object.methods.include?(:blank?)
-  require_relative "errgonomic/core_ext/blank"
-end
+# A more opinionated blend with Rails presence.
+require_relative 'errgonomic/presence'
+
+# Bring in a subtle and manual type checker.
+require_relative 'errgonomic/type'
+
+# Bring in our Option and Result.
+require_relative 'errgonomic/option'
+require_relative 'errgonomic/result'
 
+# Errgonomic adds opinionated abstractions to handle errors in a way that blends
+# Rust and Ruby ergonomics. This library leans on Rails conventions for some
+# presence-related methods; when in doubt, make those feel like Rails. It also
+# has an implementation of Option and Result; when in doubt, make those feel
+# more like Rust.
 module Errgonomic
   class Error < StandardError; end
 
   class NotPresentError < Error; end
 
   class TypeMismatchError < Error; end
-end
 
-class Object
-  # Returns the receiver if it is present, otherwise raises a NotPresentError.
-  # This method is useful to enforce strong expectations, where it is preferable
-  # to fail early rather than risk causing an ambiguous error somewhere else.
-  #
-  # @param message [String] The error message to raise if the receiver is not present.
-  # @return [Object] The receiver if it is present, otherwise raises a NotPresentError.
-  def present_or_raise(message)
-    raise Errgonomic::NotPresentError, message if blank?
-    self
+  class UnwrapError < Error; end
+
+  class ExpectError < Error; end
+
+  class ArgumentError < Error; end
+
+  class ResultRequiredError < Error; end
+
+  class NotComparableError < StandardError; end
+
+  # A little bit of control over how pedantic we are in our runtime type checks.
+  def self.give_me_ambiguous_downstream_errors?
+    @give_me_ambiguous_downstream_errors || true
+  end
+
+  # You can opt out of the pedantic runtime checks for lazy block evaluation,
+  # but not quietly.
+  def self.with_ambiguous_downstream_errors
+    original_value = @give_me_ambiguous_downstream_errors
+    @give_me_ambiguous_downstream_errors = true
+    yield
+  ensure
+    @give_me_ambiguous_downstream_errors = original_value
   end
 
-  # Returns the receiver if it is present, otherwise returns the given value. If
-  # constructing the default value is expensive, consider using
-  # +present_or_else+.
-  #
-  # @param value [Object] The value to return if the receiver is not present.
-  # @return [Object] The receiver if it is present, otherwise the given value.
-  def present_or(value)
-    # TBD whether this is *too* strict
-    if value.class != self.class && self.class != NilClass
-      raise Errgonomic::TypeMismatchError, "Type mismatch: default value is a #{value.class} but original was a #{self.class}"
-    end
-
-    return self if present?
-
-    value
+  # Lenient inner value comparison means the inner value of a Some or Ok can be
+  # compared to some other non-Result or non-Option value.
+  def self.lenient_inner_value_comparison?
+    @lenient_inner_value_comparison ||= true
   end
 
-  # Returns the receiver if it is present, otherwise returns the result of the
-  # block. Invoking a block may be preferable to returning a default value with
-  # +present_or+, if constructing the default value is expensive.
-  #
-  # @param block [Proc] The block to call if the receiver is not present.
-  # @return [Object] The receiver if it is present, otherwise the result of the block.
-  def present_or_else(&block)
-    return block.call if blank?
-    self
+  def self.give_me_lenient_inner_value_comparison=(value)
+    @lenient_inner_value_comparison = value
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nick Zadrozny
@@ -24,6 +24,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: yard-doctest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: Let's blend the Rails 'present' and 'blank' conventions with a few patterns
   from Rust Option types.
 email:
@@ -34,17 +62,24 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".rspec"
+- ".rubocop.yml"
 - ".standard.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- doctest_helper.rb
 - flake.lock
 - flake.nix
 - gemset.nix
 - lib/errgonomic.rb
 - lib/errgonomic/core_ext/blank.rb
+- lib/errgonomic/option.rb
+- lib/errgonomic/presence.rb
+- lib/errgonomic/result.rb
+- lib/errgonomic/type.rb
 - lib/errgonomic/version.rb
 - sig/errgonomic.rbs
 homepage: https://omc.io/