errgonomic 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f84b5db433f20f5b75dbfad878c881d7f536d6c169dd43a31527ca4e4380f54
-  data.tar.gz: 2415019deb923d5e5ba887786e457901883914039e23f2450ea7127c712c74da
+  metadata.gz: 0e21646c1a4fefc2d70df2089a912fce14df157b543f16b712c63d6dfdf5630c
+  data.tar.gz: 3732b419a1fbee854590a5fbdb700917c2a079880be10ff9b95520dc4102ef69
 SHA512:
-  metadata.gz: 1149999bdc13744158fbe5ddf5523528cccd32b8c0de1371d39da0d5cc0405f4be82c84b97ec74917bcd101dd3d8d6dbdc9d62ae6523dee5c6a101e507629c2d
-  data.tar.gz: ab8db80b9b3bec04a74ce464ab070c15ef6fcd8dd24af6fe8c4608f1ea256004c34806b07579deb5ca2626f5675c0eceb6818112f985cc9d904acc9e46de9962
+  metadata.gz: 1384fea58251177994a31855f6e99ebc15d8cbf173860063cb0d8b53b04f57ec6679e848d98bdd0c37a712f13e34540e4bc7f9908e6a8874bfe891d8f37e6db8
+  data.tar.gz: 229368094740e527915793df1d05b58c82b0da41e04c1fd47924abca7cf98dff7ea5de2dee4e28d3ef3ccf03d0d2950a648d000885813903b5aea9b5d9671ccc

data/.rubocop.yml

@@ -0,0 +1 @@
+require: rubocop-yard

data/.yardopts

@@ -0,0 +1 @@
+--plugin yard-doctest

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-03-28
+
+- Introduce (most of) Result and Option
+- Presence helpers which raise should have a bang on their name
+- [Dev, Test] - Replace rspec with yard-doctest
+
 ## [0.1.0] - 2025-02-27
 
-- Initial release
+- Initial release with some basic extensions for presence

data/Rakefile

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
 
+require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-require "standard/rake"
+require 'yard/doctest/rake'
+YARD::Doctest::RakeTask.new do |task|
+  task.doctest_opts = %w[-v]
+  task.pattern = 'lib/**/*.rb'
+end
 
-task default: %i[spec standard]
+task default: %i[spec yard:doctest]

data/doctest_helper.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'lib/errgonomic'

data/flake.nix

@@ -15,13 +15,6 @@
         "aarch64-darwin"
       ];
       overlays = [
-        (final: prev: {
-          gems = final.bundlerEnv {
-            name = "errgonomic";
-            gemdir = ./.;
-            # src = final.lib.cleanSource ../.;
-          };
-        })
       ];
       forAllSystems =
         f:
@@ -36,12 +29,25 @@
     {
       devShells = forAllSystems (
         { pkgs, ... }:
+        let
+          inherit (pkgs) ruby bundix;
+        in
         {
           default = pkgs.mkShell {
             buildInputs = [
-              pkgs.ruby
-              pkgs.bundix
-              pkgs.gems
+              ruby
+              bundix
+              (pkgs.bundlerEnv {
+                name = "errgonomic";
+                gemdir = ./.;
+                extraConfigPaths = [
+                  ./errgonomic.gemspec
+                  ./lib/errgonomic/version.rb
+                ];
+                postInstall = ''
+                  find . >&2
+                '';
+              })
             ];
           };
         }

data/gemset.nix

@@ -9,6 +9,26 @@
     };
     version = "2.4.2";
   };
+  backport = {
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "0xbzzjrgah0f8ifgd449kak2vyf30micpz6x2g82aipfv7ypsb4i";
+      type = "gem";
+    };
+    version = "1.2.0";
+  };
+  benchmark = {
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "0jl71qcgamm96dzyqk695j24qszhcc7liw74qc83fpjljp2gh4hg";
+      type = "gem";
+    };
+    version = "0.4.0";
+  };
   concurrent-ruby = {
     groups = ["default"];
     platforms = [];
@@ -37,7 +57,17 @@
       path = ./.;
       type = "path";
     };
-    version = "0.1.0";
+    version = "0.2.0";
+  };
+  jaro_winkler = {
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "09645h5an19zc1i7wlmixszj8xxqb2zc8qlf8dmx39bxpas1l24b";
+      type = "gem";
+    };
+    version = "1.6.0";
   };
   json = {
     groups = ["default"];
@@ -49,6 +79,28 @@
     };
     version = "2.10.1";
   };
+  kramdown = {
+    dependencies = ["rexml"];
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "131nwypz8b4pq1hxs6gsz3k00i9b75y3cgpkq57vxknkv6mvdfw7";
+      type = "gem";
+    };
+    version = "2.5.1";
+  };
+  kramdown-parser-gfm = {
+    dependencies = ["kramdown"];
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "0a8pb3v951f4x7h968rqfsa19c8arz21zw1vaj42jza22rap8fgv";
+      type = "gem";
+    };
+    version = "1.1.0";
+  };
   language_server-protocol = {
     groups = ["default"];
     platforms = [];
@@ -59,15 +111,66 @@
     };
     version = "3.17.0.4";
   };
-  lint_roller = {
+  logger = {
     groups = ["default"];
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
-      sha256 = "11yc0d84hsnlvx8cpk4cbj6a4dz9pk0r1k29p0n1fz9acddq831c";
+      sha256 = "05s008w9vy7is3njblmavrbdzyrwwc1fsziffdr58w9pwqj8sqfx";
       type = "gem";
     };
-    version = "1.1.0";
+    version = "1.6.6";
+  };
+  mini_portile2 = {
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "0x8asxl83msn815lwmb2d7q5p29p7drhjv5va0byhk60v9n16iwf";
+      type = "gem";
+    };
+    version = "2.8.8";
+  };
+  minitest = {
+    groups = ["default" "development"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "0izrg03wn2yj3gd76ck7ifbm9h2kgy8kpg4fk06ckpy4bbicmwlw";
+      type = "gem";
+    };
+    version = "5.25.4";
+  };
+  nokogiri = {
+    dependencies = ["mini_portile2" "racc"];
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "0npx535cs8qc33n0lpbbwl0p9fi3a5bczn6ayqhxvknh9yqw77vb";
+      type = "gem";
+    };
+    version = "1.18.3";
+  };
+  observer = {
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "1b2h1642jy1xrgyakyzz6bkq43gwp8yvxrs8sww12rms65qi18yq";
+      type = "gem";
+    };
+    version = "0.1.2";
+  };
+  ostruct = {
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "05xqijcf80sza5pnlp1c8whdaay8x5dc13214ngh790zrizgp8q9";
+      type = "gem";
+    };
+    version = "0.6.1";
   };
   parallel = {
     groups = ["default"];
@@ -120,6 +223,17 @@
     };
     version = "13.2.1";
   };
+  rbs = {
+    dependencies = ["logger"];
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "07cwjkx7b3ssy8ccqq1s34sc5snwvgxan2ikmp9y2rz2a9wy6v1b";
+      type = "gem";
+    };
+    version = "3.8.1";
+  };
   regexp_parser = {
     groups = ["default"];
     platforms = [];
@@ -130,6 +244,27 @@
     };
     version = "2.10.0";
   };
+  reverse_markdown = {
+    dependencies = ["nokogiri"];
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "195c7yra7amggqj7rir0yr09r4v29c2hgkbkb21mj0jsfs3868mb";
+      type = "gem";
+    };
+    version = "3.0.0";
+  };
+  rexml = {
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "1jmbf6lf7pcyacpb939xjjpn1f84c3nw83dy3p1lwjx0l2ljfif7";
+      type = "gem";
+    };
+    version = "3.4.1";
+  };
   rspec = {
     dependencies = ["rspec-core" "rspec-expectations" "rspec-mocks"];
     groups = ["default"];
@@ -206,16 +341,16 @@
     };
     version = "1.38.1";
   };
-  rubocop-performance = {
-    dependencies = ["rubocop" "rubocop-ast"];
-    groups = ["default"];
+  rubocop-yard = {
+    dependencies = ["rubocop" "yard"];
+    groups = ["development"];
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
-      sha256 = "10hv0lz54q34dlwx6vld0qx1fjskfb0nyb5c18cadrpmjnkqcbzj";
+      sha256 = "03s8lwah6apkr1g25whhd9y2zrqq9dy56g5kwn0bxp0slakrpisz";
       type = "gem";
     };
-    version = "1.23.1";
+    version = "0.10.0";
   };
   ruby-progressbar = {
     groups = ["default"];
@@ -227,38 +362,36 @@
     };
     version = "1.13.0";
   };
-  standard = {
-    dependencies = ["language_server-protocol" "lint_roller" "rubocop" "standard-custom" "standard-performance"];
+  solargraph = {
+    dependencies = ["backport" "benchmark" "diff-lcs" "jaro_winkler" "kramdown" "kramdown-parser-gfm" "logger" "observer" "ostruct" "parser" "rbs" "reverse_markdown" "rubocop" "thor" "tilt" "yard" "yard-solargraph"];
     groups = ["default"];
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
-      sha256 = "13ijzq7r0v0rm1yyba1jfw2s9r3kfxljwypfhzpnkrsag64kk2b5";
+      sha256 = "0fqa486hfn6kdbqp3ppy3jvl9xyj8jz41a2dzgkhc6ny2pj31w92";
       type = "gem";
     };
-    version = "1.45.0";
+    version = "0.52.0";
   };
-  standard-custom = {
-    dependencies = ["lint_roller" "rubocop"];
+  thor = {
     groups = ["default"];
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
-      sha256 = "0av55ai0nv23z5mhrwj1clmxpgyngk7vk6rh58d4y1ws2y2dqjj2";
+      sha256 = "1nmymd86a0vb39pzj2cwv57avdrl6pl3lf5bsz58q594kqxjkw7f";
       type = "gem";
     };
-    version = "1.0.2";
+    version = "1.3.2";
   };
-  standard-performance = {
-    dependencies = ["lint_roller" "rubocop-performance"];
+  tilt = {
     groups = ["default"];
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
-      sha256 = "1x298w3wmq8cavbsg903wc3arxp3xh2x8263brvy128436m732rd";
+      sha256 = "0szpapi229v3scrvw1pgy0vpjm7z3qlf58m1198kxn70cs278g96";
       type = "gem";
     };
-    version = "1.6.0";
+    version = "2.6.0";
   };
   unicode-display_width = {
     dependencies = ["unicode-emoji"];
@@ -281,4 +414,36 @@
     };
     version = "4.0.4";
   };
+  yard = {
+    groups = ["development"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "14k9lb9a60r9z2zcqg08by9iljrrgjxdkbd91gw17rkqkqwi1sd6";
+      type = "gem";
+    };
+    version = "0.9.37";
+  };
+  yard-doctest = {
+    dependencies = ["minitest" "yard"];
+    groups = ["development"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "0zw4fa5ri58w76yawh0sc9xj69z26qm59lvjxr1gqn4zv5smmcvw";
+      type = "gem";
+    };
+    version = "0.1.17";
+  };
+  yard-solargraph = {
+    dependencies = ["yard"];
+    groups = ["default"];
+    platforms = [];
+    source = {
+      remotes = ["https://rubygems.org"];
+      sha256 = "03lklm47k6k294ww97x6zpvlqlyjm5q8jidrixhil622r4cld6m1";
+      type = "gem";
+    };
+    version = "0.1.0";
+  };
 }

data/lib/errgonomic/core_ext/blank.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "concurrent/map"
+require 'concurrent/map'
 
 class Object
   # An object is blank if it's false, empty, or a whitespace string.
@@ -99,7 +99,7 @@ class Array
   #   [1,2,3].blank? # => false
   #
   # @return [true, false]
-  alias_method :blank?, :empty?
+  alias blank? empty?
 
   def present? # :nodoc:
     !empty?
@@ -113,7 +113,7 @@ class Hash
   #   { key: 'value' }.blank?  # => false
   #
   # @return [true, false]
-  alias_method :blank?, :empty?
+  alias blank? empty?
 
   def present? # :nodoc:
     !empty?
@@ -125,7 +125,7 @@ class Symbol
   #
   #   :''.blank?     # => true
   #   :symbol.blank? # => false
-  alias_method :blank?, :empty?
+  alias blank? empty?
 
   def present? # :nodoc:
     !empty?

data/lib/errgonomic/option.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+module Errgonomic
+  module Option
+    # The base class for all options. Some and None are subclasses.
+    #
+    class Any
+      # An option of the same type with an equal inner value is equal.
+      #
+      # Because we're going to monkey patch this into other libraries Rails, we
+      # allow some "pass through" functionality into the inner value of a Some,
+      # such as comparability here.
+      #
+      # TODO: does None == null?
+      #
+      # strict:
+      #   Some(1) == 1 # => raise Errgonomic::NotComparableError, "Cannot compare Errgonomic::Option::Some with Integer"
+      #
+      # @example
+      #   Some(1) == Some(1) # => true
+      #   Some(1) == Some(2) # => false
+      #   Some(1) == None() # => false
+      #   None() == None() # => true
+      #   Some(1) == 1 # => false
+      #   None() == nil # => false
+      def ==(other)
+        return false if self.class != other.class
+        return true if none?
+
+        value == other.value
+      end
+
+      # @example
+      #   measurement = Errgonomic::Option::Some.new(1)
+      #   case measurement
+      #   in Errgonomic::Option::Some, value
+      #     "Measurement is #{measurement.value}"
+      #   in Errgonomic::Option::None
+      #     "Measurement is not available"
+      #   else
+      #     "not matched"
+      #   end # => "Measurement is 1"
+      def deconstruct
+        return [self, value] if some?
+
+        [Errgonomic::Option::None]
+      end
+
+      # return true if the contained value is Some and the block returns truthy
+      #
+      # @example
+      #   Some(1).some_and { |x| x > 0 } # => true
+      #   Some(0).some_and { |x| x > 0 } # => false
+      #   None().some_and { |x| x > 0 } # => false
+      def some_and(&block)
+        return false if none?
+
+        !!block.call(value)
+      end
+
+      alias some_and? some_and
+
+      # return true if the contained value is None or the block returns truthy
+      #
+      # @example
+      #   None().none_or { false } # => true
+      #   Some(1).none_or { |x| x > 0 } # => true
+      #   Some(1).none_or { |x| x < 0 } # => false
+      def none_or(&block)
+        return true if none?
+
+        !!block.call(value)
+      end
+
+      alias none_or? none_or
+
+      # return an Array with the contained value, if any
+      # @example
+      #   Some(1).to_a # => [1]
+      #   None().to_a # => []
+      def to_a
+        return [] if none?
+
+        [value]
+      end
+
+      # returns the inner value if present, else raises an error
+      # @example
+      #   Some(1).unwrap! # => 1
+      #   None().unwrap! # => raise Errgonomic::UnwrapError, "cannot unwrap None"
+      def unwrap!
+        raise Errgonomic::UnwrapError, 'cannot unwrap None' if none?
+
+        value
+      end
+
+      # returns the inner value if pressent, else raises an error with the given
+      # message
+      # @example
+      #   Some(1).expect!("msg") # => 1
+      #   None().expect!("msg") # => raise Errgonomic::ExpectError, "msg"
+      def expect!(msg)
+        raise Errgonomic::ExpectError, msg if none?
+
+        value
+      end
+
+      # returns the inner value if present, else returns the default value
+      # @example
+      #   Some(1).unwrap_or(2) # => 1
+      #   None().unwrap_or(2) # => 2
+      def unwrap_or(default)
+        return default if none?
+
+        value
+      end
+
+      # returns the inner value if present, else returns the result of the
+      # provided block
+      # @example
+      #   Some(1).unwrap_or_else { 2 } # => 1
+      #   None().unwrap_or_else { 2 } # => 2
+      def unwrap_or_else(&block)
+        return block.call if none?
+
+        value
+      end
+
+      # Calls a function with the inner value, if Some, but returns the original
+      # option. In Rust, this is "inspect" but that clashes with Ruby
+      # conventions. We call this "tap_some" to avoid further clashing with
+      # "tap."
+      #
+      # @example
+      #   tapped = false
+      #   Some(1).tap_some { |x| tapped = x } # => Some(1)
+      #   tapped # => 1
+      #   tapped = false
+      #   None().tap_some { tapped = true } # => None()
+      #   tapped # => false
+      def tap_some(&block)
+        block.call(value) if some?
+        self
+      end
+
+      # Maps the Option to another Option by applying a function to the
+      # contained value (if Some) or returns None. Raises a pedantic exception
+      # if the return value of the block is not an Option.
+      #
+      # @example
+      #   Some(1).map { |x| x + 1 } # => Some(2)
+      #   None().map { |x| x + 1 } # => None()
+      def map(&block)
+        return self if none?
+
+        Some(block.call(value))
+      end
+
+      # Returns the provided default (if none), or applies a function to the
+      # contained value (if some). If you want lazy evaluation for the provided
+      # value, use +map_or_else+.
+      #
+      # @example
+      #   None().map_or(1) { 100 } # => Some(1)
+      #   Some(1).map_or(100) { |x| x + 1 } # => Some(2)
+      #   Some("foo").map_or(0) { |str| str.length } # => Some(3)
+      def map_or(default, &block)
+        return Some(default) if none?
+
+        Some(block.call(value))
+      end
+
+      # Computes a default from the given Proc if None, or applies the block to
+      # the contained value (if Some).
+      #
+      # @example
+      #   None().map_or_else(-> { :foo }) { :bar } # => Some(:foo)
+      #   Some("str").map_or_else(-> { 100 }) { |str| str.length } # => Some(3)
+      #   None().map_or_else( -> { nil }) { |str| str.length } # => None()
+      def map_or_else(proc, &block)
+        if none?
+          val = proc.call
+          return val ? Some(val) : None()
+        end
+
+        Some(block.call(value))
+      end
+
+      # convert the option into a result where Some is Ok and None is Err
+      # @example
+      #   None().ok # => Err()
+      #   Some(1).ok # => Ok(1)
+      def ok
+        return Errgonomic::Result::Ok.new(value) if some?
+
+        Errgonomic::Result::Err.new
+      end
+
+      # Transforms the option into a result, mapping Some(v) to Ok(v) and None to Err(err)
+      #
+      # @example
+      #   None().ok_or("wow") # => Err("wow")
+      #   Some(1).ok_or("such err") # => Ok(1)
+      def ok_or(err)
+        return Errgonomic::Result::Ok.new(value) if some?
+
+        Errgonomic::Result::Err.new(err)
+      end
+
+      # Transforms the option into a result, mapping Some(v) to Ok(v) and None to Err(err).
+      # TODO: block or proc?
+      #
+      # @example
+      #   None().ok_or_else { "wow" } # => Err("wow")
+      #   Some("foo").ok_or_else { "such err" } # => Ok("foo")
+      def ok_or_else(&block)
+        return Errgonomic::Result::Ok.new(value) if some?
+
+        Errgonomic::Result::Err.new(block.call)
+      end
+
+      # Returns the option if it contains a value, otherwise returns the provided Option. Returns an Option.
+      #
+      # @example
+      #   None().or(Some(1)) # => Some(1)
+      #   Some(2).or(Some(3)) # => Some(2)
+      #   None().or(2) # => raise Errgonomic::ArgumentError.new, "other must be an Option, was Integer"
+      def or(other)
+        raise ArgumentError, "other must be an Option, was #{other.class.name}" unless other.is_a?(Any)
+
+        return self if some?
+
+        other
+      end
+
+      # Returns the option if it contains a value, otherwise calls the block and returns the result. Returns an Option.
+      #
+      # @example
+      #   None().or_else { Some(1) } # => Some(1)
+      #   Some(2).or_else { Some(3) } # => Some(2)
+      #   None().or_else { 2 } # => raise Errgonomic::ArgumentError.new, "block must return an Option, was Integer"
+      def or_else(&block)
+        return self if some?
+
+        val = block.call
+        if !val.is_a?(Errgonomic::Option::Any) && Errgonomic.give_me_ambiguous_downstream_errors?
+          raise Errgonomic::ArgumentError.new, "block must return an Option, was #{val.class.name}"
+        end
+
+        val
+      end
+
+      # If self is Some, return the provided other Option.
+      #
+      # @example
+      #   None().and(Some(1)) # => None()
+      #   Some(2).and(Some(3)) # => Some(3)
+      def and(other)
+        return self if none?
+
+        other
+      end
+
+      # If self is Some, call the given block and return its value. Block most return an Option.
+      #
+      # @example
+      #   None().and_then { Some(1) } # => None()
+      #   Some(2).and_then { Some(3) } # => Some(3)
+      def and_then(&block)
+        return self if none?
+
+        val = block.call
+        if Errgonomic.give_me_ambiguous_downstream_errors? && !val.is_a?(Errgonomic::Option::Any)
+          raise Errgonomic::ArgumentError.new, "block must return an Option, was #{val.class.name}"
+        end
+
+        val
+      end
+
+      # Zips self with another Option.
+      #
+      # If self is Some(s) and other is Some(o), this method returns
+      # Some([s, o]). Otherwise, None is returned.
+      #
+      # @example
+      #   None().zip(Some(1)) # => None()
+      #   Some(1).zip(None()) # => None()
+      #   Some(2).zip(Some(3)) # => Some([2, 3])
+      def zip(other)
+        return None() unless some? && other.some?
+
+        Some([value, other.value])
+      end
+
+      # Zip two options using the block passed. If self is Some and Other is
+      # some, yield both of their values to the block and return its value as
+      # Some. Else return None.
+      #
+      # @example
+      #   None().zip_with(Some(1)) { |a, b| a + b } # => None()
+      #   Some(1).zip_with(None()) { |a, b| a + b } # => None()
+      #   Some(2).zip_with(Some(3)) { |a, b| a + b } # => Some(5)
+      def zip_with(other, &block)
+        return None() unless some? && other.some?
+        other = block.call(value, other.value)
+        Some(other)
+      end
+
+      # filter
+      # xor
+      # insert
+      # get_or_insert
+      # get_or_insert_with
+      # take
+      # take_if
+      # replace
+      # zip
+      # zip_with
+    end
+
+    # Represent a value
+    class Some < Any
+      attr_accessor :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      def some?
+        true
+      end
+
+      def none?
+        false
+      end
+    end
+
+    class None < Any
+      def some?
+        false
+      end
+
+      def none?
+        true
+      end
+    end
+  end
+end
+
+# Global convenience for constructing a Some value.
+def Some(value)
+  Errgonomic::Option::Some.new(value)
+end
+
+# Global convenience for constructing a None value.
+def None
+  Errgonomic::Option::None.new
+end

data/lib/errgonomic/presence.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# 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.
+require_relative './core_ext/blank' unless Object.methods.include?(:blank?)
+
+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
+  end
+
+  alias_method :present_or_raise, :present_or_raise!
+
+  # 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
+  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
+  end
+
+  # Returns the receiver if it is blank, otherwise raises a NotPresentError.
+  # This method is helpful to enforce expectations where blank objects are required.
+  #
+  # @param message [String] The error message to raise if the receiver is not blank.
+  # @return [Object] The receiver if it is blank, otherwise raises a NotPresentError.
+  def blank_or_raise!(message)
+    raise Errgonomic::NotPresentError, message unless blank?
+
+    self
+  end
+
+  alias_method :blank_or_raise, :blank_or_raise!
+
+  # Returns the receiver if it is blank, otherwise returns the given value.
+  #
+  # @param value [Object] The value to return if the receiver is not blank.
+  # @return [Object] The receiver if it is blank, otherwise the given value.
+  def blank_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 blank?
+
+    value
+  end
+
+  # Returns the receiver if it is blank, otherwise returns the result of the
+  # block.
+  #
+  # @param block [Proc] The block to call if the receiver is not blank.
+  # @return [Object] The receiver if it is blank, otherwise the result of the block.
+  def blank_or_else(&block)
+    return block.call unless blank?
+
+    self
+  end
+end

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/version.rb

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

data/lib/errgonomic.rb

@@ -1,59 +1,58 @@
 # 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 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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nick Zadrozny
 autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-01 00:00:00.000000000 Z
+date: 2025-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -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,23 @@ 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/version.rb
 - sig/errgonomic.rbs
 homepage: https://omc.io/