mona-result 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 170acae8e3dab4e7c9dec3b88b17cb8668a678290aafa5eb363da54261a5eab9
-  data.tar.gz: 0b327151acf8487019f87f5b859b1f940d766e67c84479c29ef1a70a4d26aeb1
+  metadata.gz: af436f63f473104b9dd2b4bffb0c379e15032c5eee00fbd7b76491f8d7dc3ba0
+  data.tar.gz: 0a198685c28efc6a3d72b87daf6563fb5ca6876e1990063b659a311ba5bd91a3
 SHA512:
-  metadata.gz: 45ca05476a2621a4d6e76a190b37852880b9c69d43470ec77ed5dc9dabf7ec9f6cbe9771777adc369f69ce421e8297f2e5c5ee66df8bf43b12c62d1e0ce3c53d
-  data.tar.gz: 59684cbea28ce2392a1755edb70c9756786b1bf730900e5aaf0829a3a4a068a0742c6db907e3720d4533ff17ff57a2c7b5a72e7dd5d1364c4acfd4f6a4bafd80
+  metadata.gz: 545a03866806626c22141209e8e5a5b828f5a686cfa54d40a90a3015b5efa3ea6ba404fdb77b2b0869fec30b2f8e035e551b8d836601710324ef3f3cccab5e6a
+  data.tar.gz: 6886883d884629a9de5fe769016fbb0b44c5a107e6f49bc1c6688c7fd6efab2800da4d47c252985ca8676d7f9d69ae87fbb80e6faeda001c2385447137d6bbef

data/.rubocop.yml

@@ -1,3 +1,7 @@
+require:
+  - rubocop-minitest
+  - rubocop-rake
+
 AllCops:
   TargetRubyVersion: 3.1
   NewCops: enable

data/CHANGELOG.md

@@ -1,4 +1,15 @@
-## [Unreleased]
+## [0.1.3] - 2022-08-09
+
+- Fix CHANGELOG rubygems link
+
+## [0.1.2] - 2022-08-09
+
+- Fix gemspec links
+- Improve documentation
+
+## [0.1.1] - 2022-08-09
+
+- Adds basic documentation
 
 ## [0.1.0] - 2022-08-04
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mona-result (0.1.0)
+    mona-result (0.1.3)
 
 GEM
   remote: https://rubygems.org/
@@ -33,14 +33,14 @@ GEM
     rbs (2.6.0)
     regexp_parser (2.5.0)
     rexml (3.2.5)
-    rubocop (1.33.0)
+    rubocop (1.34.0)
       json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.19.1, < 2.0)
+      rubocop-ast (>= 1.20.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.21.0)

data/README.md

@@ -1,8 +1,8 @@
 # Mona::Result
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/mona/result`. To experiment with that code, run `bin/console` for an interactive prompt.
+Provides a result monad, with OK holding a value, and Err holding a failure, with optional reason, and metadata.
 
-TODO: Delete this and the text above, and describe your gem
+Also provides a dict result monad, a hash-like result, which provides `#sequence` whose semantics mirror _do notation_
 
 ## Installation
 
@@ -16,7 +16,86 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-TODO: Write usage instructions here
+```ruby
+Result = Mona::Result
+
+# basic OK
+success = Result.ok(1) # => #<OK 1>
+success.ok? # => true
+success.err? # => false
+success.value # => 1
+success.and_tap { puts "it is #{_1}" }.and_then { _1 * 5 }.value_or { :nope }
+# OUT: it is 1
+# => 5
+
+# basic Err
+failure = Result.err(4, :not_prime) # => #<Err 4 reason: :not_prime>
+failure.ok? # => false
+failure.err? # => true
+failure.failure # => 4
+failure.reason # => :not_prime
+failure.and_tap { puts "it is #{_1}" }.and_then { _1 * 5 }.value_or { :nope } # => :nope
+
+# Dict with sequence, example using a fictional repository.
+# #set can take a [Symbol, Symbol] key argument where left is OK key, right is Err key
+result = Result.dict do |d|
+  d.set :user, UserRepo.find user_id
+  d.set :input, PostInput.valid(attributes)
+  d.set [:post, :input], PostRepo.create user_id: user_id, **d[:input]
+end
+# if find user fails:  # => #<Err {:user=>NotFoundError} reason: :not_found, key: :user>
+# if validation fails: # => #<Err {:user=>User, :input=>PostInput(invalid)} reason: :invalid, key: :input>
+# if create fails:     # => #<Err {:user=>User, :input=>PostInput(db err)} reason: :db_err, key: :input>
+# if all ok:           # => #<OK: {:user=>User, :post=>Post}>
+
+# Action - a callable sequence
+divide = Result.action do |x, y|
+  set :numerator, x
+  set :divisor, y.zero? ? Result.err(y, :is_zero) : y
+  puts "ready to calculate answer"
+  set :answer, numerator / divisor
+  puts "answer was: #{answer}"
+end
+
+divide.call(12, 4)
+# OUT: ready to calculate answer
+# OUT: answer was: 3
+# => #<OK {:numerator=>12, :divisor=>4, :answer=>3}>
+
+result = divide.call(12, 0) # => #<Err {:numerator=>12, :divisor=>0} reason: :is_zero, key: :divisor>
+result.err? # => true
+result.failure # => {:numerator=>12, :divisor=>0}
+result.reason # => :is_zero
+result.meta # => {:key=>:divisor}
+```
+
+Pattern matching is supported in the following way:
+
+```ruby
+case result
+in :ok, value
+in :err, failure, reason, { **meta }
+end
+
+case result
+in ok:
+in err:, reason:, **meta
+end
+```
+
+You can also match a result, using similar semantics, the difference from using case/pattern-match is that a
+`Mona::Result::NoMatchError` is raised, which keeps a reference to the result (which is useful for differentially
+handling errors in an enclosing scope - not currently possible with ruby's `NoMatchingPatternError` which does not
+contain any information about the failed match)
+
+```ruby
+Mona::Result.match(result) do |on|
+  on.ok            { |value| puts "ok" }
+  on.err(key: :x)  { |failure, reason, **meta| puts "error with meta :key => :x" }
+  on.err(:invalid) { |failure, reason, **meta| puts "error with reason :invalid" }
+  on.err           { |failure, reason, **meta| puts "error" }
+end
+```
 
 ## Development
 
@@ -26,7 +105,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mona-result.
+Bug reports and pull requests are welcome on GitHub at https://github.com/mona-rb/mona-result.
 
 ## License
 

data/Rakefile

@@ -3,6 +3,7 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+desc "Run steep check"
 task :steep do
   system "steep check" or raise "Steep type checking failed"
 end

data/lib/mona/result/version.rb

@@ -2,6 +2,6 @@
 
 module Mona
   module Result
-    VERSION = "0.1.0"
+    VERSION = "0.1.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mona-result
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - Ian White
@@ -10,7 +10,7 @@ bindir: exe
 cert_chain: []
 date: 2022-08-09 00:00:00.000000000 Z
 dependencies: []
-description: Mona::Result provides a result monad, and dict_result monad
+description: Mona::Result provides a result monad, and dict result monad with do-notation
 email:
 - ian.w.white@gmail.com
 executables: []
@@ -35,14 +35,14 @@ files:
 - lib/mona/result/sequence.rb
 - lib/mona/result/version.rb
 - sig/mona/result.rbs
-homepage: https://github.com/mona/mona-result
+homepage: https://github.com/mona-rb/mona-result
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  homepage_uri: https://github.com/mona/mona-result
-  source_code_uri: https://github.com/mona/mona-result
-  changelog_uri: https://github.com/mona/mona-result/CHANGELOG.md
+  homepage_uri: https://github.com/mona-rb/mona-result
+  source_code_uri: https://github.com/mona-rb/mona-result
+  changelog_uri: https://github.com/mona-rb/mona-result/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -61,5 +61,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Mona::Result is a result Monad for ruby
+summary: Mona::Result is a result monad for ruby
 test_files: []