errgonomic 0.9.3 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58963c6e1c1cfcf52d8fe4b065dd986acda616f4e55001d7d2bc13cbeab1eb28
-  data.tar.gz: 9d6f93fdd27c94525f2f2a2dc53010eb4f99760dae7514eaf4f035f5c9947869
+  metadata.gz: d39f466feedb411b53780fa853b509dc6a40db2f12aef63235a6817881ce2d95
+  data.tar.gz: bc81bba0f57ddaac60178b0319533feeb054be296614332b8a9744d72b0ae9d1
 SHA512:
-  metadata.gz: 2adf6eadd64c94629ba265ea9747d943314616f8c26943ad075ea5399bc86c4747e433946273989640b668e0841c337cdc6f3ecc873fed9006aa82eb439510d9
-  data.tar.gz: 475c6a42553b89700d4de4d0d7257bcbb71388c61d8b12da69a51ce4aa30a75f7074757a498bb20d5074539748b8e799bf8c78303ef3dc8ac33a74306d615aad
+  metadata.gz: 26b24e1089898ad573927824616829559a6c9fa5c169abf71addcad1284a345597ae12928f4a22153ce1d06f64db3572e7e4d0d6c596df2dffef4a1eb260e72e
+  data.tar.gz: 5f20b741f3feb1c4f5b84daee2f3934edc09f89f962a459c485dfed8356d63e84297f778b3b74f761ada2c1be2ea5c371c73b318a2ef5aa54c8ba635612ba450

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-10
+
+This release gives `deconstruct` the Rust shape and names the four variants at top level, so a pattern reads as `in Some(v)`.
+
+### Upgrading from 0.9.3
+
+`deconstruct` answers `[value]` for a `Some`, an `Ok` and an `Err` and `[]` for a `None`, so a pattern written against 0.9.x's `[self, value]` has to change shape: `in Errgonomic::Option::Some, v` becomes `in Some(v)`, `in Errgonomic::Result::Err, String => msg` becomes `in Err(String => msg)`, and `in Errgonomic::Option::None` stays as it is or becomes `in None`. `Some`, `None`, `Ok` and `Err` are now top-level names for the four variants, for patterns, as well as constructors. An application that defines its own constant under one of those names has to rename it: errgonomic refuses to load over one with a `NameError`, and a `class` or `module` of that name written after it loads raises `TypeError`.
+
+### Changes
+
+- [Behavior change] `deconstruct` answers `[value]` for a `Some`, an `Ok` and an `Err` and `[]` for a `None`, the one-payload shape `Data.define(:value)` and Rust's tuple variants share, where 0.9.x answered `[self, value]` and `[None]`. `in Some(v)` binds the value, `in Ok(Some(v))` nests, a two-branch `case/in` with no `else` is exhaustive, and a wrong type reaches `NoMatchingPatternError`. There is no `deconstruct_keys`: a one-payload sum type has no named field, and a `Some` around a Hash nests as `in Some({ id: })` through the Hash's own protocol
+- A value-less `Err()` deconstructs to `[]`, so `in Err` and `in Err()` match it and `in Err(e)` matches only an `Err` that carries a value. The sentinel `Err()` holds in place of a value is internal, and a pattern variable must never bind it
+- `Some`, `None`, `Ok` and `Err` are defined at top level beside the constructors of the same name, so a pattern reads as it does in Rust. Each is an `Errgonomic::VariantName` rather than the class it names: it matches as that class in a pattern and a `case/when`, and a bare one, written as Rust writes `return None`, refuses to stand in for a value. `to_s`, `to_json`, `as_json` and every ActiveRecord boundary that unwraps an Option raise `Errgonomic::SerializeError` on it, where the class would write `Errgonomic::Option::None` into a string, a column or a query, and a boolean column would store `true`. A constant of the same name that the application already defines stops the gem's load with a `NameError`, and a `class None` written after the gem loads raises `TypeError`, rather than one replacing or reopening the other. Rails defines none of the four
+
 ## [0.9.3] - 2026-09-10
 
 This release removes the public `value` slot from `Some`, `Ok` and `Err`, and freezes every instance as it is constructed, so an Option or a Result is the value the README already said it was.

data/README.md

@@ -111,17 +111,21 @@ Some(1).each.to_a                # => [1]
 
 `map` wraps whatever the block returns, as Rust's does, so a block that itself returns an Option gives `Some(Some(x))`. `and_then` is the spelling for that block.
 
-Options support pattern matching:
+Options pattern match in the Rust shape. `Some`, `None`, `Ok` and `Err` name the variants in a pattern as well as building them, so a pattern reads as it does in Rust:
 
 ```ruby
 case measurement
-in Errgonomic::Option::Some, value
+in Some(value)
   "Measurement is #{value}"
-in Errgonomic::Option::None
+in None
   "Measurement is not available"
 end
 ```
 
+Leave the `else` off: the two branches cover an Option, and a value that is not one raises `NoMatchingPatternError` where an `else` would take it quietly. When that value is a Result, the error's message refuses to print; see the `case/in` note below. `deconstruct` answers `[value]` for a `Some` and `[]` for a `None`, the one-payload shape `Data.define(:value)` and Rust's tuple variants share, and there is no `deconstruct_keys`, because a one-payload sum type has no named field. Patterns nest through the inner value's own protocol instead: `in Ok(Some(value))` reaches through a Result, and `in Some({ id: })` reaches into a Hash a `Some` wraps.
+
+A bare `Some`, `None`, `Ok` or `Err`, without parentheses, is that name and not a value, where Rust's `return None` is one. It matches as the class it names in a pattern or a `case/when`, and refuses to stand in for a value: interpolation, `to_s`, `join`, `to_json` and `as_json` raise `Errgonomic::SerializeError` (`bare None names a variant for a pattern, not a value; build one with parentheses`), and so does handing one to an ActiveRecord attribute, a bulk write or a `where`. It is not a class, so `is_a?`, `kind_of?` and `instance_of?` raise `TypeError` when given the bare name (`class or module required`), `Some.new`, `Some <= Errgonomic::Option::Any` and `Some.name` raise `NoMethodError`, and Minitest's `assert_kind_of Some, x` raises the same `TypeError` before it can assert anything. Each has a working spelling: check the variant with `x.some?`, `x.none?`, `x.ok?` or `x.err?`, or give the fully qualified class anywhere a class or module is required, as in `x.is_a?(Errgonomic::Option::Some)`, `assert_kind_of Errgonomic::Option::Some, x`, `Errgonomic::Option::Some.new(1)`, `Errgonomic::Option::Some <= Errgonomic::Option::Any` or `Errgonomic::Option::Some.name`. Build with the constructor, `Some(1)`, rather than `.new`. An application constant of the same name collides loudly: defined before errgonomic loads, it stops the load with a `NameError`, and a `class None` or `module Ok` written after raises `TypeError` where it is written. Two forms get past that. `None = …` assigned after the load replaces the name with only Ruby's `already initialized constant` warning, and in a Rails application Zeitwerk skips an autoloaded `app/models/ok.rb` because `Ok` is already defined, so the first call on `Ok` raises `NoMethodError`.
+
 An unhandled Option refuses to leak into your output: `to_s`, `to_json` and `as_json` raise `Errgonomic::SerializeError`, so you handle the inner value deliberately rather than shipping `Some("...")` to a user. The refusal names what it was carrying (`cannot serialize an unwrapped Some("cell-a1b2")`), so a payload built out of many values says which one went unhandled; the value's `inspect` is bounded to 60 characters, with an ellipsis past that. The refusal covers `as_json` because Hash and Array serialization recurses through that method, and an Option nested in a payload would otherwise serialize as `{"value": ...}`. A converted ActiveRecord model is the one exception, at the model boundary: it unwraps each attribute as it serializes, so a record's own `as_json` says what an unconverted record's says. See [Rails integration](#rails-integration).
 
 The `to_s` refusal is the loudest guard of the three, because a string is where a wrapper turns into data: string interpolation, `Array#join`, `format`, `String()`, a bare ERB `<%= %>` and the key of a Hash on its way to JSON all reach the value through `to_s`, and every one of them raises rather than writing `Some("...")` into a hostname, a column or a page. Rust gives `Option` a `Debug` and no `Display`, and `inspect` is the `Debug` here: it renders `Some(1)`, and it is what a log line or a `rescue` should call (`"got #{opt.inspect}"`). The refusal says so: `Some(1) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value`.
@@ -172,11 +176,11 @@ Results also pattern match, including against the kind of inner value:
 
 ```ruby
 case result
-in Errgonomic::Result::Ok, value
+in Ok(value)
   "Measurement is #{value}"
-in Errgonomic::Result::Err, String => msg
+in Err(String => msg)
   "Measurement failed with a message: #{msg}"
-in Errgonomic::Result::Err, Exception => e
+in Err(Exception => e)
   "Measurement produced an exception -- #{e.class}: #{e}"
 end
 ```

data/lib/errgonomic/option.rb

@@ -2,6 +2,7 @@
 
 require 'set'
 require 'stringio'
+require_relative 'variant_name'
 
 module Errgonomic
   module Option
@@ -174,20 +175,65 @@ module Errgonomic
         [self.class, value].hash
       end
 
+      # The Rust shape: a Some deconstructs to its one payload and a None to
+      # nothing, so `in Some(v)` binds the value and `in None` matches. There
+      # is no deconstruct_keys, because a one-payload sum type has no named
+      # field; a Some wrapping a Hash nests as `in Some({id:})` through the
+      # Hash's own protocol.
+      #
       # @example
-      #   measurement = Errgonomic::Option::Some.new(1)
+      #   Some(1).deconstruct # => [1]
+      #   None().deconstruct # => []
+      #   Some(1).respond_to?(:deconstruct_keys) # => false
+      #
+      # @example a two-branch case/in with no else is exhaustive
+      #   measurement = Some(1)
       #   case measurement
-      #   in Errgonomic::Option::Some, value
+      #   in Some(value)
       #     "Measurement is #{value}"
-      #   in Errgonomic::Option::None
+      #   in None
       #     "Measurement is not available"
-      #   else
-      #     "not matched"
       #   end # => "Measurement is 1"
+      #   case None()
+      #   in Some(value)
+      #     "Measurement is #{value}"
+      #   in None
+      #     "Measurement is not available"
+      #   end # => "Measurement is not available"
+      #
+      # @example the wrong type falls through to Ruby's own exhaustiveness check
+      #   begin
+      #     case 1
+      #     in Some(value) then value
+      #     in None then nil
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, e.message]
+      #   end # => [NoMatchingPatternError, "1"]
+      #
+      # @example a Result that falls through carries a message that refuses to print
+      #   begin
+      #     case Ok(1)
+      #     in Some(value) then value
+      #     in None then nil
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, (e.message rescue $!.class)]
+      #   end # => [NoMatchingPatternError, Errgonomic::SerializeError]
+      #
+      # @example patterns nest through the inner value's own protocol
+      #   case Ok(Some(1))
+      #   in Ok(Some(value)) then value
+      #   end # => 1
+      #   case Some({ id: 7, name: 'x' })
+      #   in Some({ id: }) then id
+      #   end # => 7
+      #   case Some(1)
+      #   in Errgonomic::Option::Some(value) then "bound #{value}"
+      #   else "not matched"
+      #   end # => "bound 1"
       def deconstruct
-        return [self, value] if some?
-
-        [Errgonomic::Option::None]
+        to_a
       end
 
       # Options order like Rust's: None sorts before any Some, and Somes
@@ -961,3 +1007,8 @@ end
 def None
   Errgonomic::Option::None.new
 end
+
+# The variants under their short names, so a pattern reads as it does in
+# Rust: `in Some(v)`, `in None`.
+Errgonomic::VariantName.define(:Some, Errgonomic::Option::Some)
+Errgonomic::VariantName.define(:None, Errgonomic::Option::None)

data/lib/errgonomic/rails/active_record_optional.rb

@@ -516,10 +516,10 @@ module Errgonomic
     #   Errgonomic::Rails.unwrap_options(1) # => 1
     def self.unwrap_options(value)
       case value
-      when Errgonomic::Option::Any
-        value.unwrap_or(nil)
+      when Errgonomic::Option::Any, Errgonomic::VariantName
+        unwrap_option(value)
       when Array
-        value.any? { |v| v.is_a?(Errgonomic::Option::Any) } ? value.map { |v| unwrap_options(v) } : value
+        value.any? { |v| unwrapped_at_boundary?(v) } ? value.map { |v| unwrap_options(v) } : value
       else
         value
       end
@@ -527,13 +527,16 @@ module Errgonomic
 
     # Take the value inside an Option, and a None as nil, where the boundary
     # takes one value: an attribute is a single typed field, so a collection
-    # that happens to hold an Option is that collection.
+    # that happens to hold an Option is that collection. A bare variant name
+    # is refused here, since a boolean column would cast it to true.
     #
     # @example
     #   Errgonomic::Rails.unwrap_option(Some(1)) # => 1
     #   Errgonomic::Rails.unwrap_option(None()) # => nil
     #   Errgonomic::Rails.unwrap_option([Some(1)]) # => [Some(1)]
+    #   Errgonomic::Rails.unwrap_option(None) # => raise Errgonomic::SerializeError, "bare None names a variant for a pattern, not a value; build one with parentheses"
     def self.unwrap_option(value)
+      value.refuse! if value.is_a?(Errgonomic::VariantName)
       value.is_a?(Errgonomic::Option::Any) ? value.unwrap_or(nil) : value
     end
 
@@ -548,7 +551,7 @@ module Errgonomic
     #   plain = { title: 'x' }
     #   Errgonomic::Rails.unwrap_option_values(plain).equal?(plain) # => true
     def self.unwrap_option_values(hash)
-      return hash unless hash.each_value.any?(Errgonomic::Option::Any)
+      return hash unless hash.each_value.any? { |value| unwrapped_at_boundary?(value) }
 
       hash.transform_values { |value| unwrap_option(value) }
     end
@@ -561,11 +564,17 @@ module Errgonomic
     #   plain = [{ title: 'x' }]
     #   Errgonomic::Rails.unwrap_option_rows(plain).equal?(plain) # => true
     def self.unwrap_option_rows(rows)
-      return rows unless rows.any? { |row| row.is_a?(Hash) && row.each_value.any?(Errgonomic::Option::Any) }
+      return rows unless rows.any? { |row| row.is_a?(Hash) && row.each_value.any? { |v| unwrapped_at_boundary?(v) } }
 
       rows.map { |row| row.is_a?(Hash) ? unwrap_option_values(row) : row }
     end
 
+    # An Option, or a bare variant name, which a boundary refuses rather than
+    # let a column type cast it.
+    def self.unwrapped_at_boundary?(value)
+      value.is_a?(Errgonomic::Option::Any) || value.is_a?(Errgonomic::VariantName)
+    end
+
     # A declared default that is a Proc is not a value yet: ActiveModel calls
     # it with no arguments each time a record is built. Wrap it rather than
     # unwrap it, so what it returns meets the type where a literal default

data/lib/errgonomic/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'variant_name'
+
 module Errgonomic
   module Result
     # The base class for Result's Ok and Err class variants. We implement as
@@ -471,27 +473,79 @@ module Errgonomic
         pp.text(inspect)
       end
 
-      # @example simple pattern match with variable capture of the value
-      #   result = Errgonomic::Result::Ok.new(1)
-      #   case result
-      #   in Errgonomic::Result::Ok, value
+      # The Rust shape: each variant deconstructs to its one payload, so
+      # `in Ok(v)` binds the value and `in Err(e)` binds the error. A
+      # value-less Err deconstructs to nothing: the sentinel behind it is
+      # internal and must never bind to a pattern variable.
+      #
+      # @example
+      #   Ok(1).deconstruct # => [1]
+      #   Err(:e).deconstruct # => [:e]
+      #   Err().deconstruct # => []
+      #   Ok(1).respond_to?(:deconstruct_keys) # => false
+      #
+      # @example a value-less Err matches `in Err` and `in Err()`, never `in Err(e)`
+      #   case Err()
+      #   in Err(e) then e
+      #   in Err then :no_value
+      #   end # => :no_value
+      #   case Err()
+      #   in Err() then :no_value
+      #   end # => :no_value
+      #   case Err(:x)
+      #   in Err(e) then e
+      #   in Err then :no_value
+      #   end # => :x
+      #   begin
+      #     case Err()
+      #     in Err(e) then e
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     e.class
+      #   end # => NoMatchingPatternError
+      #
+      # @example a two-branch case/in with no else is exhaustive
+      #   case Ok(1)
+      #   in Ok(value)
       #     "Measurement is #{value}"
-      #   in Errgonomic::Result::Err, err
+      #   in Err(err)
       #     "Measurement is not available"
       #   end # => "Measurement is 1"
       #
-      # @example more advanced pattern match against the kind of value
-      #   result = Errgonomic::Result::Err.new(StandardError.new("nope"))
+      # @example the wrong type falls through to Ruby's own exhaustiveness check
+      #   begin
+      #     case :done
+      #     in Ok(value) then value
+      #     in Err(err) then err
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, e.message]
+      #   end # => [NoMatchingPatternError, "done"]
+      #
+      # @example an Option that falls through carries a message that refuses to print
+      #   begin
+      #     case Some(1)
+      #     in Ok(value) then value
+      #     in Err(err) then err
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, (e.message rescue $!.class)]
+      #   end # => [NoMatchingPatternError, Errgonomic::SerializeError]
+      #
+      # @example a pattern reaches the kind of value inside the variant
+      #   result = Err(StandardError.new("nope"))
       #   case result
-      #   in Errgonomic::Result::Ok, value
+      #   in Ok(value)
       #     "Measurement is #{value}"
-      #   in Errgonomic::Result::Err, String => msg
+      #   in Err(String => msg)
       #     "Measurement failed with a message: #{msg}"
-      #   in Errgonomic::Result::Err, Exception => e
+      #   in Err(Exception => e)
       #     "Measurement produced an exception -- #{e.class}: #{e}"
       #   end # => "Measurement produced an exception -- StandardError: nope"
       def deconstruct
-        [self, value]
+        return [] if value.equal?(Err::Arbitrary)
+
+        [value]
       end
 
       protected
@@ -643,3 +697,8 @@ end
 def Err(value = Errgonomic::Result::Err::Arbitrary)
   Errgonomic::Result::Err.new(value)
 end
+
+# The variants under their short names, so a pattern reads as it does in
+# Rust: `in Ok(v)`, `in Err(e)`.
+Errgonomic::VariantName.define(:Ok, Errgonomic::Result::Ok)
+Errgonomic::VariantName.define(:Err, Errgonomic::Result::Err)

data/lib/errgonomic/variant_name.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Errgonomic
+  # What a bare `Some`, `None`, `Ok` or `Err` evaluates to. Rust writes a
+  # value as `return None`, where here the value is `None()`; the bare name
+  # is for patterns. It matches as the class it names, and refuses to become
+  # a string, so a missing pair of parentheses raises rather than writing a
+  # class name into a column. It is not a class, so an application's own
+  # `class None` fails where it is written instead of reopening the gem's.
+  #
+  # @example
+  #   case Some(1)
+  #   in Some(value) then value
+  #   end # => 1
+  #   None === None() # => true
+  #   None === Some(1) # => false
+  #   None.inspect # => "Errgonomic::Option::None"
+  #   "tier-#{None}" # => raise Errgonomic::SerializeError, "bare None names a variant for a pattern, not a value; build one with parentheses"
+  #   [Ok].join # => raise Errgonomic::SerializeError, "bare Ok names a variant for a pattern, not a value; build one with parentheses"
+  #   Some(1).is_a?(Some) # => raise TypeError, "class or module required"
+  #   Some(1).is_a?(Errgonomic::Option::Some) # => true
+  class VariantName
+    # Name a variant at top level, refusing a constant the application
+    # already holds there rather than replacing it.
+    def self.define(name, variant)
+      if Object.const_defined?(name, false)
+        existing = Object.const_get(name)
+        return if existing.is_a?(VariantName) && existing.names?(variant)
+
+        raise NameError.new("#{name} is already defined as #{existing.inspect}; errgonomic defines #{name} " \
+                            "at top level to name #{variant} in patterns, so rename the application's constant", name)
+      end
+      Object.const_set(name, new(name, variant))
+    end
+
+    def initialize(name, variant)
+      @name = name
+      @variant = variant
+      freeze
+    end
+
+    def names?(variant)
+      @variant.equal?(variant)
+    end
+
+    def ===(other)
+      @variant === other # rubocop:disable Style/CaseEquality
+    end
+
+    def inspect
+      @variant.inspect
+    end
+
+    # Refuse to stand in for a value.
+    def refuse!(*_args)
+      raise Errgonomic::SerializeError,
+            "bare #{@name} names a variant for a pattern, not a value; build one with parentheses"
+    end
+    alias to_s refuse!
+    alias to_json refuse!
+    alias as_json refuse!
+  end
+end

data/lib/errgonomic/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 0.10.0
 platform: ruby
 authors:
 - Nick Zadrozny
@@ -90,6 +90,7 @@ files:
 - lib/errgonomic/rails/active_record_optional.rb
 - lib/errgonomic/result.rb
 - lib/errgonomic/type.rb
+- lib/errgonomic/variant_name.rb
 - lib/errgonomic/version.rb
 - sig/errgonomic.rbs
 homepage: https://omc.io/