errgonomic 0.8.3 → 0.9.1

data/lib/errgonomic/result.rb

@@ -15,19 +15,30 @@ module Errgonomic
       end
 
       # Results order like Rust's: Ok sorts before any Err, and same variants
-      # order by their inner values. Follows Ruby's <=> convention of
-      # returning nil for incomparable operands, whether the other object is
-      # not a Result or the inner values do not themselves compare.
+      # order by their inner values. Two Results whose inner values do not
+      # themselves compare follow Ruby's convention and answer nil. A
+      # non-Result operand raises instead: Comparable turns a nil here into an
+      # ArgumentError that names the Result as the operand at fault, where
+      # what went wrong is that a wrapper was ordered against a bare value.
       #
       # @example
       #   (Ok(1) <=> Ok(2)) # => -1
       #   (Ok(1) <=> Err(:a)) # => -1
       #   (Err(:a) <=> Ok(1)) # => 1
       #   (Err(:a) <=> Err(:b)) # => -1
-      #   (Ok(1) <=> 1) # => nil
       #   [Err(:a), Ok(2), Ok(1)].sort # => [Ok(1), Ok(2), Err(:a)]
+      #
+      # @example a bare value is not ordered against a Result
+      #   Ok(1) <= 2 # => raise Errgonomic::TypeMismatchError, "cannot compare Ok(1) with Integer; test the inner value (ok_and? { |v| v <= other }) or reach for it (map, unwrap_or)"
+      #   Ok(1).ok_and? { |v| v <= 2 } # => true
+      #   Ok(1).map { |v| v <= 2 } # => Ok(true)
       def <=>(other)
-        return nil unless other.is_a?(Errgonomic::Result::Any)
+        unless other.is_a?(Errgonomic::Result::Any)
+          raise Errgonomic::TypeMismatchError,
+                "cannot compare #{inspect} with #{other.class}; test the inner value " \
+                '(ok_and? { |v| v <= other }) or reach for it (map, unwrap_or)'
+        end
+
         return ok? ? -1 : 1 if self.class != other.class
 
         value <=> other.value
@@ -87,7 +98,34 @@ module Errgonomic
       #   Ok(1).object_id == Ok(1).object_id # => false
       #   Ok(1) == 1 # => false
       #   Err() == nil # => false
+      #
+      # @example strict equality makes a cross-type comparison an error
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Ok(1) == 1
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.class
+      #     end
+      #   end # => Errgonomic::TypeMismatchError
+      #   Errgonomic.with_strict_equality { Ok(1) == Ok(1) } # => true
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Ok(1) != 1
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.message.include?("!=")
+      #     end
+      #   end # => true
+      #
+      # @example an Option is another container, not another Result
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Ok(1) == Some(1)
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.message.include?("different containers")
+      #     end
+      #   end # => true
       def ==(other)
+        strict_equality!(other, '==')
         return false if self.class != other.class
 
         value == other.value
@@ -103,7 +141,25 @@ module Errgonomic
       #   Ok(1).eql?(Err(1)) # => false
       #   { Ok(5) => 1 }[Ok(5)] # => 1
       #   [Err(:a), Err(:a)].uniq # => [Err(:a)]
+      #
+      # @example strict equality reaches eql?, and leaves hash alone
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Ok(5).eql?(5)
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.class
+      #     end
+      #   end # => Errgonomic::TypeMismatchError
+      #   Errgonomic.with_strict_equality { Ok(5).hash == Ok(5).hash } # => true
+      # Ruby derives != from ==, so a strict-equality message would name the
+      # operator the caller did not write.
+      def !=(other)
+        strict_equality!(other, '!=')
+        super
+      end
+
       def eql?(other)
+        strict_equality!(other, 'eql?')
         self.class == other.class && value.eql?(other.value)
       end
 
@@ -169,26 +225,32 @@ module Errgonomic
       end
 
       # Return the inner value of an Ok, else raise an exception with the given
-      # message when Err.
+      # message when Err. A block is called only on the Err branch, so a
+      # message that interpolates costs nothing on the path that succeeds.
       #
       # @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?
+      #   Err(:d).expect! { "no rate for #{7}" } # => raise Errgonomic::ExpectError, "no rate for 7"
+      def expect!(msg = nil, &block)
+        raise Errgonomic::ExpectError, block ? block.call : msg unless ok?
 
         @value
       end
 
       # Return the inner value of an Err, else raise an exception when Ok.
+      # The message is the Ok's value as inspect renders it, bounded, so an
+      # Ok holding an Option or a Result still has a message to print.
       #
       # @example
-      #   Ok(1).unwrap_err! # => raise Errgonomic::UnwrapError, 1
+      #   Ok(1).unwrap_err! # => raise Errgonomic::UnwrapError, "1"
+      #   Ok(Some(1)).unwrap_err! # => raise Errgonomic::UnwrapError, "Some(1)"
+      #   Ok("a" * 100).unwrap_err! # => raise Errgonomic::UnwrapError, "\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..."
       #   Err(:e).unwrap_err! # => :e
       def unwrap_err!
-        raise Errgonomic::UnwrapError, value unless err?
+        raise Errgonomic::UnwrapError.new(bounded_inspect(value), value) unless err?
 
         @value
       end
@@ -347,14 +409,22 @@ module Errgonomic
         Err(block.call(value))
       end
 
-      # Refuse to serialize an unwrapped Result as a String. Results must be
-      # correctly handled to access their inner value.
+      # Refuse to render as a String. Rust gives Result a Debug and no
+      # Display: a wrapper that reaches a string went unhandled, and a string
+      # is where it turns into data, a hostname, a hash key or a page. The
+      # refusal names the value and says how to log it or take it.
       #
       # @example
-      #   Ok("").to_s # => raise Errgonomic::SerializeError, "cannot serialize an unwrapped Result"
-      #   Err("").to_s # => raise Errgonomic::SerializeError, "cannot serialize an unwrapped Result"
+      #   Ok(1).to_s # => raise Errgonomic::SerializeError, "Ok(1) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      #   Err(:nope).to_s # => raise Errgonomic::SerializeError, "Err(:nope) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      #   "outcome: #{Ok(1)}" # => raise Errgonomic::SerializeError, "Ok(1) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      #   [Ok(1), Err(:x)].join(",") # => raise Errgonomic::SerializeError, "Ok(1) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      #   format("%s", Err(:x)) # => raise Errgonomic::SerializeError, "Err(:x) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      #   String(Ok(1)) # => raise Errgonomic::SerializeError, "Ok(1) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      #   Err("a" * 100).to_s # => raise Errgonomic::SerializeError, "Err(\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa... refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      #   Err(:nope).inspect # => "Err(:nope)"
       def to_s
-        raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Result'
+        raise Errgonomic::SerializeError, to_s_refusal
       end
 
       # Refuse to serialize an unwrapped Result as JSON. Not only should we
@@ -406,6 +476,38 @@ module Errgonomic
       def deconstruct
         [self, value]
       end
+
+      private
+
+      def to_s_refusal
+        "#{bounded_inspect} refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
+      end
+
+      # Name the value the caller failed to handle, bounded: an inspect of a
+      # record or a long payload would bury the message carrying it.
+      def bounded_inspect(object = self)
+        rendered = object.inspect
+        rendered.length > 60 ? "#{rendered[0, 57]}..." : rendered
+      end
+
+      def strict_equality!(other, operator)
+        return unless Errgonomic.strict_equality?
+        return if other.is_a?(Errgonomic::Result::Any)
+
+        raise Errgonomic::TypeMismatchError,
+              "#{self.class} #{operator} #{other.class}, which strict equality refuses.\n" \
+              "#{strict_equality_remedy(other)}"
+      end
+
+      def strict_equality_remedy(other)
+        return <<~MSG.chomp if other.is_a?(Errgonomic::Option::Any)
+          A Result and an Option are different containers, and neither is the other.
+          Unwrap the one you meant (res.unwrap_or(nil) == opt.unwrap_or(nil)).
+        MSG
+
+        "Compare Results (res == Ok(#{other.inspect})), test the inner value " \
+          "(res.ok_and? { |v| v == #{other.inspect} }), or unwrap_or a fallback first."
+      end
     end
 
     # The Ok variant.
@@ -474,8 +576,9 @@ module Errgonomic
       # @example
       #   Err(:nope).inspect # => "Err(:nope)"
       #   Err().inspect # => "Err()"
+      #   Errgonomic.with_strict_equality { Err(Some(1)).inspect } # => "Err(Some(1))"
       def inspect
-        return 'Err()' if value == Arbitrary
+        return 'Err()' if value.equal?(Arbitrary)
 
         "Err(#{value.inspect})"
       end

data/lib/errgonomic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Errgonomic
-  VERSION = '0.8.3'
+  VERSION = '0.9.1'
 end

data/lib/errgonomic.rb

@@ -19,6 +19,9 @@ require_relative 'errgonomic/core_ext/array'
 # Lift booleans into Option and Result.
 require_relative 'errgonomic/core_ext/bool'
 
+# All-or-nothing collection over an Enumerable of Options or Results.
+require_relative 'errgonomic/core_ext/enumerable'
+
 # Rails fu
 require_relative 'errgonomic/rails' if defined?(Rails::Railtie)
 
@@ -83,6 +86,33 @@ module Errgonomic
     @give_me_ambiguous_downstream_errors = original_value
   end
 
+  # Cross-type equality is quiet by default, as it is for every Ruby object.
+  # Strict equality turns it into an error instead, for a test suite or CI:
+  # `Some(5) == 5` is the comparison Rust rejects at compile time, and it is
+  # silently false here otherwise.
+  #
+  # @example
+  #   Errgonomic.strict_equality? # => false
+  #   Errgonomic.with_strict_equality { Errgonomic.strict_equality? } # => true
+  #   Errgonomic.strict_equality? # => false
+  def self.strict_equality?
+    !!@strict_equality
+  end
+
+  class << self
+    # Turn cross-type equality into an error for the rest of the process.
+    attr_writer :strict_equality
+  end
+
+  # Turn cross-type equality into an error for the duration of the block.
+  def self.with_strict_equality
+    original_value = @strict_equality
+    @strict_equality = true
+    yield
+  ensure
+    @strict_equality = original_value
+  end
+
   # 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?

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.9.1
 platform: ruby
 authors:
 - Nick Zadrozny
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -78,6 +78,7 @@ files:
 - lib/errgonomic/core_ext/array.rb
 - lib/errgonomic/core_ext/blank.rb
 - lib/errgonomic/core_ext/bool.rb
+- lib/errgonomic/core_ext/enumerable.rb
 - lib/errgonomic/core_ext/hash.rb
 - lib/errgonomic/option.rb
 - lib/errgonomic/optional_array.rb