errgonomic 0.8.3 → 0.9.0

data/doctest_helper.rb

@@ -1,3 +1,156 @@
 # frozen_string_literal: true
 
+require 'active_record'
+require 'logger'
+
 require_relative 'lib/errgonomic'
+require_relative 'lib/errgonomic/rails'
+
+# The Rails integration patches ActiveRecord as it loads, so examples under
+# lib/errgonomic/rails need a live connection and a model to run against.
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Base.logger = Logger.new(File::NULL)
+
+# One nullable column per type the cast boundary has to map.
+ActiveRecord::Schema.verbose = false
+ActiveRecord::Schema.define do
+  create_table 'writers', force: :cascade do |t|
+    t.string :name
+    t.text :bio
+  end
+
+  create_table 'articles', force: :cascade do |t|
+    t.string :title
+    t.references :writer
+  end
+
+  create_table 'reports', force: :cascade do |t|
+    t.string :type, null: false
+    t.string :title
+    t.text :summary
+  end
+
+  create_table 'notes', force: :cascade do |t|
+    t.boolean :pinned
+    t.string :title
+    t.text :body
+    t.json :meta
+    t.integer :rank
+    t.float :score
+    t.decimal :price
+    t.date :due_on
+    t.datetime :read_at
+  end
+end
+
+Errgonomic::Rails.setup_before
+
+class Note < ActiveRecord::Base
+  include Errgonomic::Rails::ActiveRecordOptional
+end
+
+# ActionText and ActiveStorage declare singular associations of their own and
+# read them raw. A reflection names its class as a string, so a model can be
+# asked which readers it wrapped without either engine loaded.
+class Dispatch < ActiveRecord::Base
+  self.table_name = 'notes'
+  include Errgonomic::Rails::ActiveRecordOptional
+  has_one :rich_text_body, class_name: 'ActionText::RichText', as: :record
+end
+
+# A subclass wraps nothing of its own: an inherited reader is already an
+# Option, and wrapping it again would nest it.
+class Report < ActiveRecord::Base
+  include Errgonomic::Rails::ActiveRecordOptional
+end
+
+class Briefing < Report; end
+
+# An unconverted delegation target: its readers hand back plain values, and
+# two of its methods take an argument, a keyword and a block.
+class Writer < ActiveRecord::Base
+  def greeting(salutation, punctuation: '.')
+    "#{salutation}, #{name}#{punctuation}"
+  end
+
+  def styled_name
+    yield(name)
+  end
+end
+
+# A converted model reads its association as an Option.
+class Article < ActiveRecord::Base
+  include Errgonomic::Rails::ActiveRecordOptional
+  belongs_to :writer, optional: true
+  delegate_optional :name, to: :writer, prefix: true
+  delegate_optional :name, to: :writer, prefix: :author
+  delegate_optional :bio, to: :writer
+  delegate_optional :greeting, :styled_name, to: :writer, prefix: true
+  delegate_optional :table_name, to: :class
+end
+
+# The same records read through a converted model, so the target's own
+# reader is already an Option.
+class Byline < ActiveRecord::Base
+  self.table_name = 'writers'
+  include Errgonomic::Rails::ActiveRecordOptional
+end
+
+# Unconverted, so the association reader hands back a plain record or nil.
+class Draft < ActiveRecord::Base
+  self.table_name = 'articles'
+  belongs_to :writer, optional: true
+  belongs_to :byline, class_name: 'Byline', foreign_key: :writer_id, optional: true
+  delegate_optional :name, to: :writer, prefix: true
+  delegate_optional :name, to: :byline, prefix: true
+end
+
+# A mechanical swap from Rails' delegate carries allow_nil: true along, and
+# a delegation declared private stays off the public surface.
+class Reprint < ActiveRecord::Base
+  self.table_name = 'articles'
+  belongs_to :writer, optional: true
+  delegate_optional :name, to: :writer, prefix: true, allow_nil: true
+  delegate_optional :bio, to: :writer, private: true
+end
+
+# Two validators that answer differently for the same wrapped value.
+class Memo < ActiveRecord::Base
+  self.table_name = 'notes'
+  include Errgonomic::Rails::ActiveRecordOptional
+  validates :title, presence: true
+  validates :body, some: true
+end
+
+# yard-doctest sends any expectation that answers nil? to assert_nil, and
+# under the Rails integration None() answers it. Compare an expected Option by
+# value, so `# => None()` keeps meaning what it says.
+module DoctestOptionEquality
+  def assert_example(example, expected, actual, bind)
+    # An expectation is a literal in the example's own binding, so leaving
+    # the other branches to super costs nothing but evaluating it twice.
+    return super unless evaluate_with_assertion(expected, bind).is_a?(Errgonomic::Option::Any)
+
+    assert_equal(evaluate_with_assertion(expected, bind), evaluate_with_assertion(actual, bind))
+  rescue Minitest::Assertion => e
+    add_filepath_to_backtrace(e, example.filepath)
+    raise e
+  end
+end
+
+YARD::Doctest::Example.prepend(DoctestOptionEquality)
+
+# A declared default is cast on its way into a new record rather than assigned
+# through a writer.
+class DefaultedNote < ActiveRecord::Base
+  self.table_name = 'notes'
+  attribute :rank, :integer, default: Some(0)
+  attribute :title, :string, default: None()
+end
+
+# A Proc default is called when the record is built, so what it returns meets
+# the column type exactly where a literal default does.
+class ProcDefaultedNote < ActiveRecord::Base
+  self.table_name = 'notes'
+  attribute :title, :string, default: -> { Some('Wanderer') }
+end

data/gem-groups.json

@@ -1 +1 @@
-{"errgonomic":["default"],"yard":["development"],"yard-doctest":["development"],"activerecord":["development"],"minitest":["development"],"rails":["development"],"rake":["development"],"rspec":["development"],"rubocop":["development"],"rubocop-yard":["development"],"solargraph":["development"],"sqlite3":["development"],"concurrent-ruby":["default","development"],"drb":["development"],"prism":["development"],"activemodel":["development"],"activesupport":["development"],"base64":["development"],"bigdecimal":["development"],"connection_pool":["development"],"i18n":["development"],"json":["development"],"logger":["development"],"securerandom":["development"],"timeout":["development"],"tzinfo":["development"],"uri":["development"],"action_text-trix":["development"],"actioncable":["development"],"actionmailbox":["development"],"actionmailer":["development"],"actionpack":["development"],"actiontext":["development"],"actionview":["development"],"activejob":["development"],"activestorage":["development"],"builder":["development"],"bundler":["development"],"crass":["development"],"date":["development"],"erb":["development"],"erubi":["development"],"globalid":["development"],"io-console":["development"],"irb":["development"],"loofah":["development"],"mail":["development"],"marcel":["development"],"mini_mime":["development"],"net-imap":["development"],"net-pop":["development"],"net-protocol":["development"],"net-smtp":["development"],"nio4r":["development"],"nokogiri":["development"],"pp":["development"],"prettyprint":["development"],"psych":["development"],"racc":["development"],"rack":["development"],"rack-session":["development"],"rack-test":["development"],"rackup":["development"],"rails-dom-testing":["development"],"rails-html-sanitizer":["development"],"railties":["development"],"rdoc":["development"],"reline":["development"],"stringio":["development"],"thor":["development"],"tsort":["development"],"useragent":["development"],"websocket-driver":["development"],"websocket-extensions":["development"],"zeitwerk":["development"],"diff-lcs":["development"],"rspec-core":["development"],"rspec-expectations":["development"],"rspec-mocks":["development"],"rspec-support":["development"],"ast":["development"],"language_server-protocol":["development"],"lint_roller":["development"],"parallel":["development"],"parser":["development"],"rainbow":["development"],"regexp_parser":["development"],"rubocop-ast":["development"],"ruby-progressbar":["development"],"unicode-display_width":["development"],"unicode-emoji":["development"],"backport":["development"],"benchmark":["development"],"commander":["development"],"highline":["development"],"jaro_winkler":["development"],"kramdown":["development"],"kramdown-parser-gfm":["development"],"observer":["development"],"open3":["development"],"ostruct":["development"],"parlour":["development"],"rbs":["development"],"reverse_markdown":["development"],"rexml":["development"],"sorbet-runtime":["development"],"sord":["development"],"tilt":["development"],"yard-activesupport-concern":["development"],"yard-solargraph":["development"]}
+{"errgonomic":["default"],"yard":["development"],"yard-doctest":["development"],"activerecord":["development"],"bcrypt":["development"],"minitest":["development"],"rails":["development"],"rake":["development"],"rspec":["development"],"rubocop":["development"],"rubocop-yard":["development"],"solargraph":["development"],"sqlite3":["development"],"concurrent-ruby":["default","development"],"drb":["development"],"prism":["development"],"activemodel":["development"],"activesupport":["development"],"base64":["development"],"bigdecimal":["development"],"connection_pool":["development"],"i18n":["development"],"json":["development"],"logger":["development"],"securerandom":["development"],"timeout":["development"],"tzinfo":["development"],"uri":["development"],"action_text-trix":["development"],"actioncable":["development"],"actionmailbox":["development"],"actionmailer":["development"],"actionpack":["development"],"actiontext":["development"],"actionview":["development"],"activejob":["development"],"activestorage":["development"],"builder":["development"],"bundler":["development"],"crass":["development"],"date":["development"],"erb":["development"],"erubi":["development"],"globalid":["development"],"io-console":["development"],"irb":["development"],"loofah":["development"],"mail":["development"],"marcel":["development"],"mini_mime":["development"],"net-imap":["development"],"net-pop":["development"],"net-protocol":["development"],"net-smtp":["development"],"nio4r":["development"],"nokogiri":["development"],"pp":["development"],"prettyprint":["development"],"psych":["development"],"racc":["development"],"rack":["development"],"rack-session":["development"],"rack-test":["development"],"rackup":["development"],"rails-dom-testing":["development"],"rails-html-sanitizer":["development"],"railties":["development"],"rdoc":["development"],"reline":["development"],"stringio":["development"],"thor":["development"],"tsort":["development"],"useragent":["development"],"websocket-driver":["development"],"websocket-extensions":["development"],"zeitwerk":["development"],"diff-lcs":["development"],"rspec-core":["development"],"rspec-expectations":["development"],"rspec-mocks":["development"],"rspec-support":["development"],"ast":["development"],"language_server-protocol":["development"],"lint_roller":["development"],"parallel":["development"],"parser":["development"],"rainbow":["development"],"regexp_parser":["development"],"rubocop-ast":["development"],"ruby-progressbar":["development"],"unicode-display_width":["development"],"unicode-emoji":["development"],"backport":["development"],"benchmark":["development"],"commander":["development"],"highline":["development"],"jaro_winkler":["development"],"kramdown":["development"],"kramdown-parser-gfm":["development"],"observer":["development"],"open3":["development"],"ostruct":["development"],"parlour":["development"],"rbs":["development"],"reverse_markdown":["development"],"rexml":["development"],"sorbet-runtime":["development"],"sord":["development"],"tilt":["development"],"yard-activesupport-concern":["development"],"yard-solargraph":["development"]}

data/lib/errgonomic/core_ext/enumerable.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative '../option'
+require_relative '../result'
+
+# The all-or-nothing collection, which Rust spells as a collect into
+# Option<Vec<T>> or Result<Vec<T>, E>. On Enumerable rather than Array so it
+# composes with map, and so anything that yields wrappers can be sequenced.
+module Enumerable
+  # Collect an Enumerable of Options into an Option of an Array, stopping at
+  # the first None. A member that is not an Option raises unconditionally:
+  # with_ambiguous_downstream_errors relaxes what a block returned, not what
+  # a caller passed in.
+  #
+  # @return [Errgonomic::Option::Any]
+  #
+  # @example
+  #   [Some(1), Some(2)].sequence_options # => Some([1, 2])
+  #
+  # @example
+  #   [Some(1), None(), Some(3)].sequence_options # => None()
+  #
+  # @example
+  #   [].sequence_options # => Some([])
+  #
+  # @example a lazy enumerable is read only as far as the first None
+  #   seen = []
+  #   lazy = [Some(1), None(), Some(3)].lazy.map { |o| seen << o; o }
+  #   lazy.sequence_options # => None()
+  #   seen.size # => 2
+  #
+  # @example
+  #   [Some(1), 2].sequence_options # => raise Errgonomic::TypeMismatchError, "cannot sequence_options Integer; it is not an Option"
+  #
+  # @example a Hash yields pairs, which are Arrays
+  #   { a: Some(1) }.sequence_options # => raise Errgonomic::TypeMismatchError, "cannot sequence_options Array; it is not an Option"
+  #
+  # @example sequence a Hash by its values
+  #   { a: Some(1), b: Some(2) }.values.sequence_options # => Some([1, 2])
+  def sequence_options
+    values = []
+    each do |member|
+      unless member.is_a?(Errgonomic::Option::Any)
+        raise Errgonomic::TypeMismatchError,
+              "cannot sequence_options #{member.class}; it is not an Option"
+      end
+      return None() if member.none?
+
+      values << member.value
+    end
+    Some(values)
+  end
+
+  # Collect an Enumerable of Results into a Result of an Array, stopping at
+  # the first Err, which is returned as it stands so it keeps its error.
+  # A member that is not a Result raises on the same terms as
+  # sequence_options.
+  #
+  # @return [Errgonomic::Result::Any]
+  #
+  # @example
+  #   [Ok(1), Ok(2)].sequence_results # => Ok([1, 2])
+  #
+  # @example
+  #   [Ok(1), Err(:nope), Ok(3)].sequence_results # => Err(:nope)
+  #
+  # @example
+  #   [].sequence_results # => Ok([])
+  #
+  # @example a lazy enumerable is read only as far as the first Err
+  #   seen = []
+  #   lazy = [Ok(1), Err(:nope), Ok(3)].lazy.map { |r| seen << r; r }
+  #   lazy.sequence_results # => Err(:nope)
+  #   seen.size # => 2
+  #
+  # @example
+  #   [Ok(1), Some(2)].sequence_results # => raise Errgonomic::TypeMismatchError, "cannot sequence_results Errgonomic::Option::Some; it is not a Result"
+  #
+  # @example sequence a Hash by its values
+  #   { a: Ok(1), b: Ok(2) }.values.sequence_results # => Ok([1, 2])
+  def sequence_results
+    values = []
+    each do |member|
+      unless member.is_a?(Errgonomic::Result::Any)
+        raise Errgonomic::TypeMismatchError,
+              "cannot sequence_results #{member.class}; it is not a Result"
+      end
+      return member if member.err?
+
+      values << member.value
+    end
+    Ok(values)
+  end
+end