rescuer 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cb1cf739c264df062124c8278d07ae5c5045b82c
-  data.tar.gz: 9202313bc83a069afc537d62a6c64074d969b8f0
+  metadata.gz: 4faa4200edef84a1567bb09eccfbbe6e1418867b
+  data.tar.gz: d7a26758830d969a3f828da1573164c1150b700e
 SHA512:
-  metadata.gz: e2092f82656031cce05dd6eee1a75d0b8c6a49fee76a649c2456528ab054ec910b8467bd3e42d3846a01d695358de487cfcbe44e370ff5347a60516bb0bcb235
-  data.tar.gz: 7d61b9f169eb50a91a2cdaf87a03d40b3ad3166ad2ff4a603e7d705eb3726410a590d10a62a5dbcc1ec60281479d928b7cf705233d0f03cb0103da59a7eb7673
+  metadata.gz: 32557bb01bd39b5b179bd00b9e168ad00142e3ba9e8a1280000976a210c959d3f0d73daf5794bd6be25bc9f89b214b7558e3f4720d803bc70c4af2a1cae0e5b1
+  data.tar.gz: 4e3fde18020cf6a940653e62a6d0d78d51c02f913b5e4da10dbc24abf823031b78d9c399e0f9d07a6f2d6219fc3a8f7cde99f5884cd27b5a278b813429a93b8e

data/.gitignore

@@ -2,6 +2,7 @@
 *.rbc
 /.config
 /.idea
+/*.iml
 /coverage/
 /InstalledFiles
 /pkg/

data/README.md

@@ -5,4 +5,29 @@
 [![Code Climate](https://codeclimate.com/github/ms-ati/rescuer.png)](https://codeclimate.com/github/ms-ati/rescuer)
 [![Coverage Status](https://coveralls.io/repos/ms-ati/rescuer/badge.png)](https://coveralls.io/r/ms-ati/rescuer)
 
-A functional abstraction of rescuing exceptions inspired by Scala's Try class
+A functional abstraction of rescuing exceptions inspired by Scala's [Try][1] class (here's an [explanation][2]).
+
+[1]: http://www.scala-lang.org/api/2.10.3/index.html#scala.util.Try
+[2]: http://danielwestheide.com/blog/2012/12/26/the-neophytes-guide-to-scala-part-6-error-handling-with-try.html
+
+## Usage
+
+```ruby
+denominators = [0, 1]
+
+fractions = denominators.map { |d| Rescuer.new { 1 / d } }
+#=> [#<struct Rescuer::Failure exception=#<ZeroDivisionError: divided by 0>, exceptions_to_rescue=nil>,
+#    #<struct Rescuer::Success value=1, exceptions_to_rescue=nil>]
+```
+
+More coming soon...
+
+## TODO
+
+1.  Add any missing test to ensure exception rescuing matches all the same cases in Scala's `Try` class
+1.  Come up with output for `#to_s` and `#inspect` that I like
+1.  Document using yard
+1.  Release 0.9.0 and solicit comments
+1.  Incorporate suggested changes
+1.  Release 1.0.0
+1.  Potentially incorporate as a depedendency into [Rumonade](https://github.com/ms-ati/rumonade)

data/lib/rescuer.rb

@@ -1,16 +1,165 @@
 require 'rescuer/version'
 
 module Rescuer
-	DEFAULT_EXCEPTIONS = [StandardError]
+  DEFAULT_EXCEPTIONS_TO_RESCUE = [StandardError]
 
   def new(*exceptions)
-    exceptions = DEFAULT_EXCEPTIONS if exceptions.nil? || exceptions.empty?
-    Success.new(yield)
-	rescue *exceptions => ex
-    Failure.new(ex)
+    raise ArgumentError, 'no block given' unless block_given?
+
+    passed = exceptions && exceptions.flatten.compact
+    to_rescue, to_pass =
+      if passed.nil? || passed.empty? then [DEFAULT_EXCEPTIONS_TO_RESCUE, nil] else [passed, passed] end
+
+    begin
+      value = yield
+      Success.new(value, to_pass)
+	  rescue *to_rescue => error
+      Failure.new(error, to_pass)
+    end
   end
   module_function :new
 
-  Success = Struct.new(:value)
-  Failure = Struct.new(:cause)
+  Success = Struct.new(:value, :exceptions_to_rescue) do
+    def initialize(value, exceptions_to_rescue = nil)
+      super(value, exceptions_to_rescue)
+      freeze
+    end
+
+    def success?
+      true
+    end
+
+    def failure?
+      false
+    end
+
+    def get
+      value
+    end
+
+    def get_or_else(_)
+      value
+    end
+
+    def or_else(_)
+      self
+    end
+
+    def failed
+      Failure.new(TypeError.new('Success is not a Failure'))
+    end
+
+    def flat_map
+      Rescuer.new(exceptions_to_rescue) { yield value }.flatten(1)
+    end
+
+    def map
+      flat_map do |v|
+        new_value = yield v
+        Success.new(new_value)
+      end
+    end
+
+    def each
+      yield value
+      self
+    end
+
+    def select
+      flat_map do |v|
+        predicate = yield v
+        if predicate then self else Failure.new(IndexError.new("predicate does not hold for #{v}")) end
+      end
+    end
+    alias_method :find_all, :select
+
+    def transform(f_success, f_failure)
+      flat_map { |v| f_success.call(v) }
+    end
+
+    def recover
+      self
+    end
+
+    def recover_with
+      self
+    end
+
+    def flatten(depth = nil)
+      raise ArgumentError, 'invalid depth' unless depth.nil? || (depth.is_a?(Integer) && depth >= 0)
+      if depth && depth.zero?
+        self
+      else
+        case value
+        when Success, Failure then value.flatten(depth && depth - 1)
+        else self
+        end
+      end
+    end
+  end
+
+  Failure = Struct.new(:exception, :exceptions_to_rescue) do
+    def initialize(exception, exceptions_to_rescue = nil)
+      super(exception, exceptions_to_rescue)
+      raise ArgumentError, 'not an exception' unless exception.is_a? Exception
+      freeze
+    end
+
+    def success?
+      false
+    end
+
+    def failure?
+      true
+    end
+
+    def get
+      raise exception
+    end
+
+    def get_or_else(default)
+      default
+    end
+
+    def or_else(other)
+      other
+    end
+
+    def failed
+      Success.new(exception)
+    end
+
+    def flat_map
+      self
+    end
+
+    def map
+      self
+    end
+
+    def each
+      self
+    end
+
+    def select
+      self
+    end
+    alias_method :find_all, :select
+
+    def transform(f_success, f_failure)
+      failed.flat_map { |e| f_failure.call(e) }
+    end
+
+    def recover
+      failed.map { |e| yield e }
+    end
+
+    def recover_with
+      failed.flat_map { |e| yield e }
+    end
+
+    def flatten(depth = nil)
+      self
+    end
+  end
 end

data/lib/rescuer/version.rb

@@ -1,4 +1,4 @@
 module Rescuer
   # The current version of this gem
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/spec/rescuer_spec.rb

@@ -3,6 +3,9 @@ require 'rescuer'
 
 describe Rescuer do
 
+  ##
+  # Construct indirectly by wrapping a block which may raise an exception
+  ##
   describe '.new' do
 
     context 'when block does *not* raise' do
@@ -27,26 +30,476 @@ describe Rescuer do
       context 'when raise NoMemoryError' do
         let(:e) { NoMemoryError.new }
         subject { Rescuer.new(Exception) { raise e } }
-        it { is_expected.to eq(Rescuer::Failure.new(e)) }
+        it { is_expected.to eq(Rescuer::Failure.new(e, [Exception])) }
       end
     end
 
     context 'when block raises and two subclasses of Exception are arguments' do
-      exceptions = [NoMemoryError, SyntaxError]
+      let(:exceptions) { [NoMemoryError, SyntaxError] }
 
       context 'when raise StandardError' do
         subject { lambda { Rescuer.new(exceptions) { raise StandardError } } }
         it { is_expected.to raise_error(StandardError) }
       end
 
-      context 'when raise NoMemoryError' do
-        let(:e) { NoMemoryError.new }
-        subject { Rescuer.new(Exception) { raise e } }
-        it { is_expected.to eq(Rescuer::Failure.new(e)) }
+      context 'when raise SyntaxError' do
+        let(:e) { SyntaxError.new }
+        subject { Rescuer.new(exceptions) { raise e } }
+        it { is_expected.to eq(Rescuer::Failure.new(e, exceptions)) }
+      end
+
+    end
+
+    context 'when no block given' do
+      subject { lambda { Rescuer.new } }
+      it { is_expected.to raise_error(ArgumentError, 'no block given') }
+    end
+
+  end
+
+  ##
+  # Construct directly as Success
+  ##
+  describe Rescuer::Success do
+    context 'when given any object' do
+      let(:the_value) { 42 }
+      let(:a_success) { Rescuer::Success.new(the_value) }
+
+      describe '.new' do
+        subject { a_success }
+        it { is_expected.to     be_frozen }
+        it { is_expected.to     be_success }
+        it { is_expected.not_to be_failure }
+        it { is_expected.to     respond_to :value }
+        it { is_expected.not_to respond_to :exception }
+        it { is_expected.to     respond_to :exceptions_to_rescue }
+      end
+
+      describe '#==, #eql?, #equal?, #hash' do
+        subject { a_success }
+
+        context 'when same object' do
+          let(:another) { a_success }
+          it { is_expected.to          eq    another }
+          it { is_expected.to          eql   another }
+          it { is_expected.to          equal another }
+          it { expect(subject.hash).to eq    another.hash }
+        end
+
+        context 'when same class and equal values' do
+          let(:another) { Rescuer::Success.new(the_value) }
+          it { is_expected.to          eq    another }
+          it { is_expected.to          eql   another }
+          it { is_expected.not_to      equal another } # not the same object!
+          it { expect(subject.hash).to eq    another.hash }
+        end
+
+        context 'when same class and different values' do
+          let(:another) { Rescuer::Success.new('a different value') }
+          it { is_expected.not_to          eq    another }
+          it { is_expected.not_to          eql   another }
+          it { is_expected.not_to          equal another }
+          it { expect(subject.hash).not_to eq    another.hash }
+        end
+
+        context 'when different class and same values' do
+          let(:another_class) { Struct.new(*a_success.members) }
+          let(:another) { another_class.new(*a_success.values) }
+          it { is_expected.not_to          eq    another }
+          it { is_expected.not_to          eql   another }
+          it { is_expected.not_to          equal another }
+          #it { expect(subject.hash).not_to eq    another.hash } -- fails on rbx?
+        end
+      end
+
+      describe '#value' do
+        subject { a_success.value }
+        it { is_expected.to be the_value}
+      end
+
+      describe '#exceptions_to_rescue' do
+        context 'when not given' do
+          subject { a_success.exceptions_to_rescue }
+          it { is_expected.to be_nil }
+        end
+
+        context 'when given' do
+          let(:ex_to_rescue) { [ArgumentError, TypeError] }
+          subject { Rescuer::Success.new(the_value, ex_to_rescue).exceptions_to_rescue }
+          it { is_expected.to be ex_to_rescue }
+        end
+      end
+
+      describe '#get' do
+        subject { a_success.get }
+        it { is_expected.to be the_value }
+      end
+
+      describe '#get_or_else' do
+        subject { a_success.get_or_else(123) }
+        it { is_expected.to be the_value }
+      end
+
+      describe '#or_else' do
+        let(:another) { Rescuer::Success.new(123) }
+        subject { a_success.or_else(another) }
+        it { is_expected.to be a_success }
+      end
+
+      describe '#failed' do
+        subject { a_success.failed }
+        it { is_expected.to               be_instance_of Rescuer::Failure }
+        it { expect(subject.exception).to eq             TypeError.new('Success is not a Failure') }
+      end
+
+      describe '#each' do
+        context 'when block does *not* raise' do
+          let(:acc) { arr = []; a_success.each { |v| arr << v }; arr }
+          subject { dummy = []; a_success.each { |v| dummy << v } }
+          it { is_expected.to be a_success }
+          it { expect(acc).to eq [the_value] }
+        end
+
+        context 'when block raises' do
+          let(:the_error) { StandardError.new('a standard error') }
+          subject { lambda { a_success.each { |_| raise the_error } } }
+          it { is_expected.to raise_error(the_error) }
+        end
+      end
+
+      describe '#map' do
+        let(:to_rescue) { [ArgumentError] }
+        let(:a_success_rescuing_ae) { Rescuer::Success.new(the_value, to_rescue) }
+
+        context 'when block returns a value' do
+          subject { a_success.map { |v| v + 1 } }
+          it { is_expected.to eq Rescuer::Success.new(the_value + 1) }
+        end
+
+        context 'when block raises an exception that is to be rescued' do
+          let(:the_error) { ArgumentError.new('an error to be rescued') }
+          subject { a_success_rescuing_ae.map { |_| raise the_error } }
+          it { is_expected.to eq Rescuer::Failure.new(the_error, to_rescue) }
+        end
+
+        context 'when block raises an exception that is *not* to be rescued' do
+          let(:the_error) { StandardError.new('a standard error') }
+          subject { lambda { a_success_rescuing_ae.map { |_| raise the_error } } }
+          it { is_expected.to raise_error(the_error) }
+        end
+      end
+
+      describe '#flat_map' do
+        let(:to_rescue) { [ArgumentError] }
+        let(:a_success_rescuing_ae) { Rescuer::Success.new(the_value, to_rescue) }
+
+        context 'when block returns a Success' do
+          subject { a_success.flat_map { |v| Rescuer::Success.new(v + 1) } }
+          it { is_expected.to eq Rescuer::Success.new(the_value + 1) }
+        end
+
+        context 'when block raises an exception that is to be rescued' do
+          let(:the_error) { ArgumentError.new('an error to be rescued') }
+          subject { a_success_rescuing_ae.flat_map { |_| raise the_error } }
+          it { is_expected.to eq Rescuer::Failure.new(the_error, to_rescue) }
+        end
+
+        context 'when block raises an exception that is *not* to be rescued' do
+          let(:the_error) { StandardError.new('a standard error') }
+          subject { lambda { a_success_rescuing_ae.flat_map { |_| raise the_error } } }
+          it { is_expected.to raise_error(the_error) }
+        end
+      end
+
+      shared_examples 'select methods' do
+        context 'when predicate returns true' do
+          subject { select_method { |v| v == the_value } }
+          it { is_expected.to be a_success }
+        end
+
+        context 'when predicate returns false' do
+          let(:the_error) { IndexError.new('predicate does not hold for 42') }
+          subject { select_method { |v| v != the_value } }
+          it { is_expected.to eq Rescuer::Failure.new(the_error) }
+        end
+
+        context 'when predicate raises an exception that is to be rescued' do
+          let(:the_error) { StandardError.new('a standard error') }
+          subject { select_method { |_| raise the_error } }
+          it { is_expected.to eq Rescuer::Failure.new(the_error) }
+        end
+
+        context 'when predicate raises an exception that is *not* to be rescued' do
+          subject { lambda { select_method { |_| raise NoMemoryError } } }
+          it { is_expected.to raise_error(NoMemoryError) }
+        end
+      end
+
+      describe '#select' do
+        def select_method; a_success.select { |v| yield v }; end
+        it_behaves_like 'select methods'
+      end
+
+      describe '#find_all' do
+        def select_method; a_success.find_all { |v| yield v }; end
+        it_behaves_like 'select methods'
+      end
+
+      describe '#transform' do
+        subject { a_success.transform(lambda { |v| Rescuer::Success.new(v + 1) },
+                                      lambda { |e| Rescuer::Success.new(e.message.length) }) }
+        it { is_expected.to eq Rescuer::Success.new(the_value + 1) }
+      end
+
+      describe '#recover' do
+        subject { a_success.recover { |e| e.message.length } }
+        it { is_expected.to be a_success }
+      end
+
+      describe '#recover_with' do
+        subject { a_success.recover_with { |e| Rescuer::Success.new(e.message.length) } }
+        it { is_expected.to be a_success }
+      end
+
+      describe '#flatten' do
+        let(:nested_once)  { Rescuer::Success.new(a_success)   }
+        let(:nested_twice) { Rescuer::Success.new(nested_once) }
+        let(:nested_fail)  { Rescuer::Success.new(Rescuer::Failure.new(StandardError.new('a standard error'))) }
+
+        context 'given an invalid depth' do
+          let(:string_depth)   { lambda { a_success.flatten('hey!') } }
+          let(:negative_depth) { lambda { a_success.flatten(-1)     } }
+          let(:float_depth)    { lambda { a_success.flatten(1.23)   } }
+          it { expect(string_depth).to   raise_error(ArgumentError, 'invalid depth') }
+          it { expect(negative_depth).to raise_error(ArgumentError, 'invalid depth') }
+          it { expect(float_depth).to    raise_error(ArgumentError, 'invalid depth') }
+        end
+
+        context 'when *not* nested' do
+          context 'given depth is nil' do
+            subject { a_success.flatten }
+            it { is_expected.to be a_success }
+          end
+
+          context 'given depth = 1' do
+            subject { a_success.flatten(1) }
+            it { is_expected.to be a_success }
+          end
+        end
+
+        context 'when nested success containing success' do
+          context 'given depth is nil' do
+            subject { nested_once.flatten }
+            it { is_expected.to be a_success }
+          end
+
+          context 'given depth = 1' do
+            subject { nested_once.flatten(1) }
+            it { is_expected.to be a_success }
+          end
+        end
+
+        context 'when nested success containing success containing success' do
+          context 'given depth is nil' do
+            subject { nested_twice.flatten }
+            it { is_expected.to be a_success }
+          end
+
+          context 'given depth = 1' do
+            subject { nested_twice.flatten(1) }
+            it { is_expected.to be nested_once }
+          end
+        end
+
+        context 'when nested success containing failure' do
+          context 'given depth is nil' do
+            subject { nested_fail.flatten }
+            it { is_expected.to be nested_fail.value }
+          end
+
+          context 'given depth = 1' do
+            subject { nested_fail.flatten(1) }
+            it { is_expected.to be nested_fail.value }
+          end
+        end
+      end
+    end
+  end
+
+  ##
+  # Construct directly as Failure
+  ##
+  describe Rescuer::Failure do
+    context 'when given an exception' do
+      let(:the_error) { StandardError.new('a standard error') }
+      let(:a_failure) { Rescuer::Failure.new(the_error) }
+
+      describe '.new' do
+        subject { a_failure }
+        it { is_expected.to     be_frozen }
+        it { is_expected.not_to be_success }
+        it { is_expected.to     be_failure }
+        it { is_expected.not_to respond_to :value }
+        it { is_expected.to     respond_to :exception }
+        it { is_expected.to     respond_to :exceptions_to_rescue }
+      end
+
+      describe '#==, #eql?, #equal?, #hash' do
+        subject { a_failure }
+
+        context 'when same object' do
+          let(:another) { a_failure }
+          it { is_expected.to          eq    another }
+          it { is_expected.to          eql   another }
+          it { is_expected.to          equal another }
+          it { expect(subject.hash).to eq    another.hash }
+        end
+
+        context 'when same class and equal values' do
+          let(:another) { Rescuer::Failure.new(the_error) }
+          it { is_expected.to          eq    another }
+          it { is_expected.to          eql   another }
+          it { is_expected.not_to      equal another } # not the same object!
+          it { expect(subject.hash).to eq    another.hash }
+        end
+
+        context 'when same class and different values' do
+          let(:another) { Rescuer::Failure.new(StandardError.new('a different error')) }
+          it { is_expected.not_to          eq    another }
+          it { is_expected.not_to          eql   another }
+          it { is_expected.not_to          equal another }
+          it { expect(subject.hash).not_to eq    another.hash }
+        end
+
+        context 'when different class and same values' do
+          let(:another_class) { Struct.new(*a_failure.members) }
+          let(:another) { another_class.new(*a_failure.values) }
+          it { is_expected.not_to          eq    another }
+          it { is_expected.not_to          eql   another }
+          it { is_expected.not_to          equal another }
+          #it { expect(subject.hash).not_to eq    another.hash } -- fails on rbx?
+        end
+      end
+
+      describe '#exception' do
+        subject { a_failure.exception }
+        it { is_expected.to be the_error }
+      end
+
+      describe '#exceptions_to_rescue' do
+        context 'when not given' do
+          subject { a_failure.exceptions_to_rescue }
+          it { is_expected.to be_nil }
+        end
+
+        context 'when given' do
+          let(:ex_to_rescue) { [ArgumentError, TypeError] }
+          subject { Rescuer::Failure.new(the_error, ex_to_rescue).exceptions_to_rescue }
+          it { is_expected.to be ex_to_rescue }
+        end
+      end
+
+      describe '#get' do
+        subject { lambda { a_failure.get } }
+        it { is_expected.to raise_error(the_error) }
       end
 
+      describe '#get_or_else' do
+        subject { a_failure.get_or_else(123) }
+        it { is_expected.to be 123 }
+      end
+
+      describe '#or_else' do
+        let(:another) { Rescuer::Success.new(123) }
+        subject { a_failure.or_else(another) }
+        it { is_expected.to be another }
+      end
+
+      describe '#failed' do
+        subject { a_failure.failed }
+        it { is_expected.to           be_instance_of Rescuer::Success }
+        it { expect(subject.value).to be             the_error }
+      end
+
+      describe '#each' do
+        let(:acc) { arr = []; a_failure.each { |v| arr << v }; arr }
+        subject { dummy = []; a_failure.each { |v| dummy << v } }
+        it { is_expected.to be a_failure }
+        it { expect(acc).to eq [] }
+      end
+
+      describe '#map' do
+        subject { a_failure.map { |v| v + 1 } }
+        it { is_expected.to be a_failure }
+      end
+
+      describe '#flat_map' do
+        subject { a_failure.flat_map { |v| Rescuer::Success.new(v + 1) } }
+        it { is_expected.to be a_failure }
+      end
+
+      shared_examples 'select methods' do
+        context 'when predicate returns true' do
+          subject { select_method { |v| v == the_value } }
+          it { is_expected.to be a_failure }
+        end
+
+        context 'when predicate returns false' do
+          subject { select_method { |v| v != the_value } }
+          it { is_expected.to be a_failure }
+        end
+
+        context 'when predicate raises any exception' do
+          subject { select_method { |_| raise the_error } }
+          it { is_expected.to be a_failure }
+        end
+      end
+
+      describe '#select' do
+        def select_method; a_failure.select { |v| yield v }; end
+        it_behaves_like 'select methods'
+      end
+
+      describe '#find_all' do
+        def select_method; a_failure.find_all { |v| yield v }; end
+        it_behaves_like 'select methods'
+      end
+
+      describe '#transform' do
+        subject { a_failure.transform(lambda { |v| Rescuer::Success.new(v + 1) },
+                                      lambda { |e| Rescuer::Success.new(e.message.length) }) }
+        it { is_expected.to eq Rescuer::Success.new(the_error.message.length) }
+      end
+
+      describe '#recover' do
+        subject { a_failure.recover { |e| e.message.length } }
+        it { is_expected.to eq Rescuer::Success.new(the_error.message.length) }
+      end
+
+      describe '#recover_with' do
+        subject { a_failure.recover_with { |e| Rescuer::Success.new(e.message.length) } }
+        it { is_expected.to eq Rescuer::Success.new(the_error.message.length) }
+      end
+
+      describe '#flatten' do
+        context 'given depth is nil' do
+          subject { a_failure.flatten }
+          it { is_expected.to be a_failure }
+        end
+
+        context 'given depth = 1' do
+          subject { a_failure.flatten(1) }
+          it { is_expected.to be a_failure }
+        end
+      end
     end
 
+    context 'when given a *non*-exception' do
+      describe '.new' do
+        subject { lambda { Rescuer::Failure.new(42) } }
+        it { is_expected.to raise_error(ArgumentError, 'not an exception') }
+      end
+    end
   end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rescuer
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Marc Siegel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-16 00:00:00.000000000 Z
+date: 2014-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake