failure 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 222591a7509d0202f6c98d6ec6ed2158bbf225c8013f0b63bb325052233ee521
+  data.tar.gz: 987d4f4c9999e723d40af1ddf18ec5b518df1f23206e91e8d36aa58970076da4
+SHA512:
+  metadata.gz: c831346698f2c59a15a5b919a845c8873693f5db793f576c27c43161ebaf386c99e7a1897c9ad7fb340b789986d828e6e3262c85627db26ebde31eb6f4e910f6
+  data.tar.gz: bce4d0ddd8cb24d7ba242baf513825569d6491abe18062eee64ac0a664c9459e8c99e60d3afff7d0f565ec2a6a2c2f1a18e88de3436712b4f9cc7e1288d6ff5c

data/.gitignore

@@ -0,0 +1,50 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+ruby '2.5.0'
+
+# Specify your gem's dependencies in necklace.gemspec
+gemspec

data/README.md

@@ -0,0 +1,217 @@
+# Failure is always an option
+
+This library implements ruby-ified `Maybe` and `Either` types. Both capture
+`nil` and `Exception` and return an object that implements the functor and monad
+interfaces.
+
+## Usage
+
+### Maybe
+
+`Maybe.new` takes a block and returns `Just <value>` on success and `Nothing` if
+the block either returns `nil` or raises an exception.
+
+```ruby
+Maybe.new do
+  [1, 2, 3].first
+end
+
+#=> Just 1
+
+Maybe.new do
+  [].first
+end
+
+#=> Nothing
+```
+
+`#map` is implemented on `Just` and `Nothing`, and is the functor `fmap`:
+
+```haskell
+map :: Maybe a -> (a -> b) -> Maybe b
+```
+
+```ruby
+Maybe.new do
+  [1, 2, 3].first
+end.map do |i|
+  i * 100
+end
+
+#=> Just 100
+
+Maybe.new do
+  [].first
+end.map do |i|
+  i * 100
+end
+
+#=> Nothing
+```
+
+`#flat_map` is implemented on `Just` and `Nothing`, and is the monad `bind`:
+
+```haskell
+flat_map :: Maybe a -> (a -> Maybe b) -> Maybe b
+```
+
+```ruby
+Maybe.new do
+  [[1], [2], [3]].first
+end.flat_map do |i|
+  Maybe.new { i.first }
+end
+
+#=> Just 1
+
+Maybe.new do
+  [1, 2, 3].first
+end.flat_map do |i|
+  Maybe.new { i.first } # raises NoMethodError
+end
+
+#=> Nothing
+```
+
+`Maybe.match` takes the maybe, a proc for the `Just` and a proc of no arguments
+for the `Nothing` and returns the value of the associated variant. Because there
+is no value for `Nothing`, a default value may be provided instead of a proc.
+
+
+```haskell
+match :: Maybe a -> (a -> b) -> b -> b
+```
+
+```ruby
+just = Maybe.new do
+  [1, 2, 3].first
+end
+
+nothing = Maybe.new do
+  [].first
+end
+
+Maybe.match(just,
+  just: ->(i) { i + 1 },
+  nothing: 0
+)
+
+#=> 2
+
+Maybe.match(nothing,
+  just: ->(i) { i + 1 },
+  nothing: 0
+)
+
+#=> 0
+```
+
+### Either
+
+`Either` is similar to `Maybe` except that it preserves an error message from a
+captured exception, or (trivially) the `nil` returned from a failed function.
+
+`Either.new` takes a block and returns `Right <value>` if the block "succeeds",
+and `Left <err | nil>` if the block raises or returns `nil`.
+
+```ruby
+Either.new do
+  [1, 2, 3].first
+end
+
+#=> Right 1
+
+Either.new do
+  1.first
+end
+
+#=> Left NoMethodError
+```
+
+`#map` is implemented on `Right` and `Left` and is the functor `fmap`
+
+```haskell
+map :: Either a b -> (b -> c) -> Either a c
+```
+
+```ruby
+Either.new do
+  [1, 2, 3].first
+end.map do |i|
+  i * 100
+end
+
+#=> Right 100
+
+Either.new do
+  1.first
+end.map do |i|
+  i * 100
+end
+
+#=> Left NoMethodError
+```
+
+`#flat_map` is implemented on `Right` and `Left` and is the monad `bind`
+
+```haskell
+flat_map :: Either a b -> (b -> Either a c) -> Either a c
+```
+
+```ruby
+Either.new do
+  [[1], [2], [3]].first
+end.flat_map do |i|
+  Either.new { i.first }
+end
+
+#=> Right 1
+
+Either.new do
+  [1, 2, 3].first
+end.flat_map do |i|
+  Either.new { i.first }
+end
+
+#=> Left NoMethodError
+```
+
+`Either.match` takes an either, a proc for `Right` and a proc for `Left`,
+evaluates the proc corresponding to the variant, and returns the result.
+
+```haskell
+match :: Either a b -> (a -> c) (b -> c) -> c
+```
+
+```ruby
+right = Either.new do
+  [1, 2, 3].first
+end
+
+left = Either.new do
+  1.first
+end
+
+Either.match(right,
+  right: ->(i) { i * 100 },
+  left: ->(e) { e.message }
+)
+
+#=> 100
+
+Either.match(left,
+  right: ->(i) { i * 100 },
+  left: ->(e) { e.message }
+)
+
+#=> "NoMethodError (undefined method `first' for 1:Integer)"
+```
+
+## Type Safety
+
+There isn't any. Users are free to reach inside the classes using
+`instance_variable_get` or `send`, and users can use `flat_map` with a block
+that doesn't return an either to "unwrap" the value. And nothing constrains the
+two procs in `.match` to return the same type. If we wanted type safety, we'd
+use Haskell or Rust. But, just like everything else in ruby, this can be used to
+make programming nicer.

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run specs'
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Generate code coverage'
+RSpec::Core::RakeTask.new(:coverage)

data/failure.gemspec

@@ -0,0 +1,22 @@
+Gem::Specification.new do |s|
+  s.name        = 'failure'
+  s.version     = '0.1.0'
+  s.date        = '2018-04-18'
+  s.summary     = "Either and Option functor/applicative/monad"
+  s.description = "Implements Either and Option a la Haskell"
+  s.authors     = ["Stuart Terrett"]
+  s.email       = 'shterrett@gmail.com'
+  s.files       = ["lib/failure.rb"]
+  s.homepage    = 'http://github.com/shterrett/failure'
+  s.license     = 'MIT'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_development_dependency("rspec", "~> 3.7")
+  s.add_development_dependency("rake", "~> 12.3")
+  s.add_development_dependency("simplecov", "~> 0.16")
+  s.add_development_dependency("pry", "~> 0.11")
+end

data/lib/either.rb

@@ -0,0 +1,76 @@
+require_relative "./shared"
+
+module Either
+  def self.new(&block)
+    val = begin
+            block.call()
+          rescue Exception => e
+            e
+          end
+    if val.nil? || val.is_a?(Exception)
+      Left.new(val)
+    else
+      Right.new(val)
+    end
+  end
+
+  def self.match(e, left:, right:)
+    if e.right?
+      right.call(e.send(:val))
+    elsif e.left?
+      left.call(e.send(:val))
+    end
+  end
+
+  class Left
+    include Shared
+
+    def left?
+      true
+    end
+    def right?
+      false
+    end
+
+    def initialize(val)
+      @val = val
+    end
+
+    def map(&block)
+      self
+    end
+
+    def flat_map(&block)
+      self
+    end
+
+    private
+    attr_reader :val
+  end
+
+  class Right
+    include Shared
+
+    def left?
+      false
+    end
+    def right?
+      true
+    end
+
+    def initialize(val)
+      @val = val
+    end
+
+    def map
+      Either.new { yield val }
+    end
+
+    def flat_map
+      yield val
+    end
+
+    private
+    attr_reader :val
+  end
+end

data/lib/failure.rb

@@ -0,0 +1,2 @@
+require_relative "./either"
+require_relative "./maybe"

data/lib/maybe.rb

@@ -0,0 +1,79 @@
+require_relative "./shared"
+
+module Maybe
+  def self.new(&block)
+    val = begin
+            block.call()
+          rescue Exception => e
+            e
+          end
+    if val.nil? || val.is_a?(Exception)
+      Nothing.new
+    else
+      Just.new val
+    end
+  end
+
+  def self.match(m, just:, nothing:)
+    if m.is_just?
+      just.call(m.send(:val))
+    elsif m.is_nothing?
+      if nothing.is_a? Proc
+        nothing.call
+      else
+        nothing
+      end
+    end
+  end
+
+  class Just
+    include Shared
+
+    def is_just?
+      true
+    end
+    def is_nothing?
+      false
+    end
+
+    def initialize(val)
+      @val = val
+    end
+
+    def map
+      Maybe.new { yield val }
+    end
+
+    def flat_map
+      yield val
+    end
+
+    private
+    attr_reader :val
+  end
+
+  class Nothing
+    include Shared
+
+    def is_just?
+      false
+    end
+    def is_nothing?
+      true
+    end
+
+    def map(&block)
+      self
+    end
+
+    def flat_map(&block)
+      self
+    end
+
+    private
+
+    def val
+      nil
+    end
+  end
+end

data/lib/shared.rb

@@ -0,0 +1,10 @@
+module Shared
+  def ==(other)
+    self.class == other.class &&
+      other.val_eq?(val)
+  end
+
+  def val_eq?(other_val)
+    other_val == val
+  end
+end

data/spec/either_spec.rb

@@ -0,0 +1,131 @@
+require "spec_helper"
+
+describe Either do
+  describe "new" do
+    it "returns a Right when given a non-nil value" do
+      e = Either.new do
+        5
+      end
+
+      expect(e.left?).to be_falsey
+      expect(e.right?).to be_truthy
+      expect(e).to be_an_instance_of Either::Right
+    end
+
+    it "returns a Left when given a nil value" do
+      e = Either.new do
+        nil
+      end
+
+      expect(e.left?).to be_truthy
+      expect(e.right?).to be_falsey
+      expect(e).to be_an_instance_of Either::Left
+    end
+
+    it "returns a Left wrapping a returned exception" do
+      e = Either.new do
+        1 / 0
+      end
+
+      expect(e.left?).to be_truthy
+      expect(e.right?).to be_falsey
+      expect(e).to be_an_instance_of Either::Left
+    end
+  end
+
+  describe "==" do
+    it "is false if one side is Left and the other is Right" do
+      r = Either.new { 5 }
+      l = Either.new { nil }
+      fake = Either::Right.new(nil)
+
+      expect(r == l).to be_falsey
+      expect(l == r).to be_falsey
+      expect(r == fake).to be_falsey
+    end
+
+    it "delegates to the value equality when comparing the same variant" do
+      r_1 = Either.new { 5 }
+      r_2 = Either.new { 6 }
+      r_3 = Either.new { 5 }
+
+      expect(r_1).not_to eq r_2
+      expect(r_1).to eq r_3
+
+      l_1 = Either.new { nil }
+      l_2 = Either.new { 1 / 0 }
+      l_3 = Either.new { nil }
+
+      expect(l_1).not_to eq l_2
+      expect(l_1).to eq l_3
+    end
+  end
+
+  describe "match" do
+    it "runs the function given for Right and returns the result if the variant is a Right" do
+      e = Either::Right.new(5)
+      result = Either.match(
+        e,
+        left: ->(v){ v + 5 },
+        right: ->(v){ v * 5 }
+      )
+
+      expect(result).to eq 25
+    end
+
+    it "runs the function given for Left and returns the result if the variant is a Left" do
+      e = Either::Left.new(5)
+      result = Either.match(
+        e,
+        left: ->(v){ v + 5 },
+        right: ->(v){ v * 5 }
+      )
+
+      expect(result).to eq 10
+    end
+  end
+end
+
+describe Either::Left do
+  describe "map" do
+    it "returns itself, ignoring the function" do
+      l = Either::Left.new(nil).map do |v|
+        v * 5
+      end
+
+      expect(l).to eq Either::Left.new(nil)
+    end
+  end
+
+  describe "flat_map" do
+    it "returns itself, ignoring the function" do
+      l = Either::Left.new(nil).map do |v|
+        Either.new { v / 0 }
+      end
+
+      expect(l).to eq Either::Left.new(nil)
+    end
+  end
+end
+
+describe Either::Right do
+  describe "map" do
+    it "applies the function to the wrapped value and returns the wrapped result" do
+      r = Either::Right.new(5).map do |v|
+        v + 5
+      end
+
+      expect(r).to eq Either::Right.new(10)
+    end
+  end
+
+  describe "flat_map" do
+    it "applies the function to the wrapped value and returns the resulting Either" do
+      r = Either::Right.new(5).flat_map do |v|
+        Either.new { v / 0 }
+      end
+
+      expect(r.left?).to be_truthy
+    end
+  end
+end

data/spec/maybe_spec.rb

@@ -0,0 +1,135 @@
+require "spec_helper"
+
+describe Maybe do
+  describe "new" do
+    it "returns a Just when given a non-nil value" do
+      m = Maybe.new do
+        5
+      end
+
+      expect(m.is_just?).to be_truthy
+      expect(m.is_nothing?).to be_falsey
+      expect(m).to be_an_instance_of Maybe::Just
+    end
+
+    it "returns a Nothing when given a nil value"do
+      m = Maybe.new do
+        nil
+      end
+
+      expect(m.is_just?).to be_falsey
+      expect(m.is_nothing?).to be_truthy
+      expect(m).to be_an_instance_of Maybe::Nothing
+    end
+
+    it "returns a Nothing if the expression throws an exception" do
+      m = Maybe.new do
+        1 / 0
+      end
+
+      expect(m.is_just?).to be_falsey
+      expect(m.is_nothing?).to be_truthy
+      expect(m).to be_an_instance_of Maybe::Nothing
+    end
+  end
+
+  describe "==" do
+    it "is false if one side is Just and the other is Nothing" do
+      j = Maybe.new { 5 }
+      n = Maybe.new { nil }
+      fake = Maybe::Just.new(nil)
+
+      expect(j == n).to be_falsey
+      expect(n == j).to be_falsey
+      expect(j == fake).to be_falsey
+    end
+
+    it "delegates to the value when comparing Just values" do
+      j_1 = Maybe.new { 5 }
+      j_2 = Maybe.new { 6 }
+      j_3 = Maybe.new { 5 }
+
+      expect(j_1).not_to eq j_2
+      expect(j_1).to eq j_3
+    end
+  end
+
+  describe "match" do
+    it "runs the function given for Just and returns the result if the variant is Just" do
+      m = Maybe::Just.new(5)
+      result = Maybe.match(
+        m,
+        just: ->(v) { v + 5 },
+        nothing: -> { 0 }
+      )
+
+      expect(result).to eq 10
+    end
+
+    it "runs the function given for Nothing and returns the result if the variant is Nothing" do
+      m = Maybe::Nothing.new
+      result = Maybe.match(
+        m,
+        just: ->(v) { v + 5 },
+        nothing: -> { 0 }
+      )
+
+      expect(result).to eq 0
+    end
+
+    it "returns the static default given for Nothing if the variant is Nothing" do
+      m = Maybe::Nothing.new
+      result = Maybe.match(
+        m,
+        just: ->(v) { v + 5 },
+        nothing: 0
+      )
+
+      expect(result).to eq 0
+    end
+  end
+end
+
+describe Maybe::Nothing do
+  describe "map" do
+    it "returns itself, ignoring the function" do
+      n = Maybe::Nothing.new.map do |v|
+        v * 5
+      end
+
+      expect(n).to eq Maybe::Nothing.new
+    end
+  end
+
+  describe "flat_map" do
+    it "returns itself, ignoring the function" do
+      n = Maybe::Nothing.new.flat_map do |v|
+        Maybe.new { v * 5 }
+      end
+
+      expect(n).to eq Maybe::Nothing.new
+    end
+  end
+end
+
+describe Maybe::Just do
+  describe "map" do
+    it "applies the function to the wrapped value and returns the wrapped result" do
+      j = Maybe::Just.new(5).map do |v|
+        v * 5
+      end
+
+      expect(j).to eq Maybe::Just.new(25)
+    end
+  end
+
+  describe "flat_map" do
+    it "applies the function to the wrapped value and returns the resulting Maybe" do
+      m = Maybe::Just.new(5).flat_map do |v|
+        Maybe.new { v / 0 }
+      end
+
+      expect(m.is_nothing?).to be_truthy
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+require 'simplecov'
+require "pry"
+
+SimpleCov.start do
+  add_filter 'spec/'
+end
+
+# encoding: utf-8
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+Dir['./spec/shared/**/*.rb'].sort.each { |f| require f }
+require_relative '../lib/failure'
+
+require 'rspec'
+
+RSpec.configure do |config|
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: failure
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stuart Terrett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-04-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: Implements Either and Option a la Haskell
+email: shterrett@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- Rakefile
+- failure.gemspec
+- lib/either.rb
+- lib/failure.rb
+- lib/maybe.rb
+- lib/shared.rb
+- spec/either_spec.rb
+- spec/maybe_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/shterrett/failure
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: Either and Option functor/applicative/monad
+test_files:
+- spec/either_spec.rb
+- spec/maybe_spec.rb
+- spec/spec_helper.rb