results 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 33039153c74e13756f5a15c64d552fc64e1f82be
-  data.tar.gz: d169c2ae7b34c76a40560b88a6cbd90a76615baf
+  metadata.gz: a7f5a6ff736c00051a79b53e0b228db6b051d37e
+  data.tar.gz: 7d0e3982b3422b2f9dd1d09918472019874136b9
 SHA512:
-  metadata.gz: 4ef21d48dd71bbabfd3aac219eebd0b217a526606e59125e3939500c678344f8e1356d8b961a9c384ee5da41a654b50fa71b073b4620496c3a5743b33a902d3b
-  data.tar.gz: 200415d4e0fd09f67ff95e3b8c58b2ebd26cb502fc2117e65fa852ff381f5aaed3275782115bd586e48fe553ab6f398c0f235efad2933babb31e3f158c821a1e
+  metadata.gz: 9582877f5ad6ef1716468e1f44f5c71195ec05622ade4ac061789f5da7e23dfe95b2583f2fa60d5ef85937d881797ef4ae8cf1f8e00e918a214bfa166f985b73
+  data.tar.gz: 53de975391c145a5dd6d22252a667ed87bbec00abc99e594ff292e4a712332c79669e923fff256bb676ef73d3ac53bcb7283a27347dd103ad23351148c84fb76

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/README.md

@@ -1,22 +1,215 @@
-= Results =
+# Results
 [![Gem Version](https://badge.fury.io/rb/results.png)](http://badge.fury.io/rb/results)
 [![Build Status](https://travis-ci.org/ms-ati/results.png)](https://travis-ci.org/ms-ati/results)
 [![Dependency Status](https://gemnasium.com/ms-ati/results.png)](https://gemnasium.com/ms-ati/results)
 [![Code Climate](https://codeclimate.com/github/ms-ati/results.png)](https://codeclimate.com/github/ms-ati/results)
 [![Coverage Status](https://coveralls.io/repos/ms-ati/results/badge.png)](https://coveralls.io/r/ms-ati/results)
 
-A functional combinator of results which are either Good or Bad inspired by the [ScalaUtils][1] [Or and Every][1] classes.
+A functional combinator of results which are either {Results::Good Good} or {Results::Bad Bad}.
+
+Inspired by the [ScalaUtils][1] library's [Or and Every][2] classes, whose APIs are documented
+[here][3] and [here][4].
 
 [1]: http://www.scalautils.org
 [2]: http://www.scalautils.org/user_guide/OrAndEvery
+[3]: http://doc.scalatest.org/2.1.3/index.html#org.scalautils.Or
+[4]: http://doc.scalatest.org/2.1.3/index.html#org.scalautils.Every
+
+## Table of Contents
+
+* [Usage](#usage)
+  * [Basic validation](#basic-validation)
+  * [Chained filters and validations](#chained-filters-and-validations)
+  * [Accumulating multiple bad results](#accumulating-multiple-bad-results)
+    * [Multiple filters and validations of a single input](#multiple-filters-and-validations-of-a-single-input)
+    * [Combine results of multiple inputs](#combine-results-of-multiple-inputs)
+* [TODO](#todo)
 
 ## Usage
 
+### Basic validation
+
+By default, `Results` will transform an `ArgumentError` into a `Bad`, allowing built-in
+numeric conversions to work directly as validations.
+
 ```ruby
-# Coming soon...
+def parseAge(str)
+  Results.new(str) { |v| Integer(v) }
+end
+
+parseAge('1')   # => #<struct Results::Good value=1>
+parseAge('abc') # => #<struct Results::Bad why=[#<struct Results::Because error="invalid value for integer", input="abc">]>
+```
+
+### Chained filters and validations
+
+Once you have a `Good` or `Bad`, you can chain additional boolean filters using `#when` and `#when_not`.
+
+```ruby
+def parseAge21To45(str)
+  # Syntax workaround due to no chaining on blocks - Open to suggestions!
+  _ = parseAge(str)
+  _ = _.when    ('under 45') { |v| v < 45 }
+  _ = _.when_not('under 21') { |v| v < 21 }
+end
+
+parseAge21To45('29') # => #<struct Results::Good value=29>
+parseAge21To45('65') # => #<struct Results::Bad why=[#<struct Results::Because error="not under 45", input=65>]>
+parseAge21To45('1')  # => #<struct Results::Bad why=[#<struct Results::Because error="under 21", input=1>]>
+```
+
+Want to save your favorite filters? You can use the provided class `Filter`,
+or any object with the same duck-type, meaning it responds to `#call` and `#message`.
+
+```ruby
+# You can use the provided class Filter
+under_45 = Results::Filter.new('under 45') { |v| v < 45 }
+
+# ...or do something funky like this...
+under_21 = lambda { |v| v < 21 }.tap { |l| l.define_singleton_method(:message) { 'under 21' } }
+
+# Both work the same way
+parseAge('65')
+  .when(under_45)
+  .when_not(under_21) # => #<struct Results::Bad why=[#<struct Results::Because error="not under 45", input=65>]>
+```
+
+You can also chain validation functions (returning `Good` or `Bad` instead of `Boolean`) using `#validate`.
+
+```ruby
+def parseAgeRange(str)
+  parseAge(str).validate do |v|
+    case v
+    when 21...45 then Results::Good.new(v)
+    else              Results::Bad.new('not between 21 and 45', v)
+    end
+  end
+end
+
+parseAgeRange('29') # => #<struct Results::Good value=29>
+parseAgeRange('65') # => #<struct Results::Bad why=[#<struct Results::Because error="not between 21 and 45", input=65>]>
+```
+
+For convenience, the `#when` and `#when_not` methods can also accept a lambda for
+the error message, to format the error message based on the input value.
+
+```ruby
+parseAge('65').when(lambda { |v| "#{v} is not under 45" }) { |v| v < 45 } 
+# => #<struct Results::Bad why=[#<struct Results::Because error="65 is not under 45", input=65>]>
+```
+
+In a similar vein, if you already have a `Filter` or compatible duck-type
+(see above), it's easy turn it into a basic validation function returning
+`Good` or `Bad` via convenience functions `Results.when` and `Results.when_not`.
+
+```ruby
+Results.when_not(under_21).call(16) 
+# => #<struct Results::Bad why=[#<struct Results::Because error="under 21", input=16>]>
+```
+
+Note that this is equivalent to:
+
+```ruby
+Results.new(16).when_not(under_21)
+```
+
+The benefit of `Results.when` is for cases where the value (here, 16) is not yet known.
+
+Experience has shown that many filters that are written are simply
+predicates called on value objects, such as `Numeric#zero?` or `String#empty?` or
+even `Object#nil?`.
+
+For these cases, you can use the convenience function `Results.predicate`.
+
+```ruby
+# validates non-nil, non-empty
+def valid?(str)
+  Results.new(str)
+    .when_not(Results.predicate :nil?)
+    .when_not(Results.predicate :empty?)
+end
+```
+
+Or even simpler, just pass the symbol of the predicate name directly to `#when` or `#when_not`.
+
+```ruby
+# same as above
+def valid_short?(str)
+  Results.new(str).when_not(:nil?).when_not(:empty?)
+end
+```
+
+### Accumulating multiple bad results
+
+So, now the interesting parts (Yes, the earlier sections were a bit slow,
+but it picks up a bit here):
+
+#### Multiple filters and validations of a single input
+
+The way we've done things so far, even if you chained multiple filters and validations
+together, if more than one would fail for some input, you would only see the first
+`Bad`, and none of the the later filters would be run.
+
+Now, instead, we're going to accumulate all the failures for a single input.
+
+One simple way is to intersperse the `#and` method between your chained `#when` calls.
+
+```ruby
+# Good still works as before
+Results.new(0).when(:integer?).and.when(:zero?)    # => #<struct Results::Good value=0>
+
+# Bad accumulates multiple failures
+Results.new(1.23).when(:integer?).and.when(:zero?) # => #<struct Results::Bad why=[
+                                                   #      #<struct Results::Because error="not integer", input=1.23>,
+                                                   #      #<struct Results::Because error="not zero", input=1.23>]>
+```
+
+You can also call `#when_all` and`#when_all_not` with a collection of filters.
+
+```ruby
+filters = [:integer?, :zero?, Results::Filter.new('greater than 2') { |n| n > 2 }]
+r = Results.new(1.23).when_all(filters) # => #<struct Results::Bad why=[
+                                        #      #<struct Results::Because error="not integer", input=1.23>,
+                                        #      #<struct Results::Because error="not zero", input=1.23>,
+                                        #      #<struct Results::Because error="not greater than 2", input=1.23>]>
+```
+
+For a collection of validation functions, you can use `#validate_all` in a similar fashion.
+
+#### Combine results of multiple inputs
+
+If you have two results, the simplest way to combine them is with `#zip`. If both results
+are good, it returns a `Good` containing an array of both values. However, if any results
+are bad, it returns a `Bad` containing all the failures.
+
+```ruby
+good = Results::Good.new(1)
+bad1 = Results::Bad.new('not nonzero', 0)
+bad2 = Results::Bad.new('not integer', 1.23)
+
+good.zip(good)           # => #<struct Results::Good value=[1, 1]>
+
+good.zip(bad1).zip(bad2) # => #<struct Results::Bad why=[
+                         #      #<struct Results::Because error="not nonzero", input=0>,
+                         #      #<struct Results::Because error="not integer", input=1.23>]>
+```
+
+If you have a collection of results, you can combine them with `Results.combine`. If all
+results are good, it returns a single `Good` containing a collection of all the values.
+However, if any results are bad, it returns a single `Bad` containing all the failures.
+
+```ruby
+all_good_results = [good, good, good]
+some_bad_results = [bad1, good, bad2]
+
+Results.combine(all_good_results) # => #<struct Results::Good value=[1, 1, 1]>
+
+Results.combine(some_bad_results) # => #<struct Results::Bad why=[
+                                  #      #<struct Results::Because error="not nonzero", input=0>,
+                                  #      #<struct Results::Because error="not integer", input=1.23>]>
 ```
 
-More coming soon...
+NOTE: this section is under construction...
 
 ## TODO
 

data/lib/results.rb

@@ -1,4 +1,236 @@
+require 'rescuer'
+
 module Results
-  Good = Struct.new(:value)
-  Bad  = Struct.new(:error)
+  DEFAULT_EXCEPTIONS_TO_RESCUE_AS_BADS = [ArgumentError]
+  DEFAULT_EXCEPTION_MESSAGE_TRANSFORMS = {
+    ArgumentError => lambda do |m|
+      r = /\Ainvalid (value|string) for ([A-Z][a-z]+)(\(\))?(: ".*")?\Z/
+      m.gsub(r) { |_| "invalid value for #{$2}".downcase }
+    end
+  }
+
+  def new(input_or_proc)
+    exceptions_as_bad = DEFAULT_EXCEPTIONS_TO_RESCUE_AS_BADS
+    exceptions_xforms = DEFAULT_EXCEPTION_MESSAGE_TRANSFORMS
+
+    rescued = Rescuer.new(*exceptions_as_bad) do
+      call_or_yield_or_return(input_or_proc) { |input| block_given? ? yield(input) : input }
+    end
+
+    from_rescuer(rescued, input_or_proc, exceptions_xforms)
+  end
+  module_function :new
+
+  def from_rescuer(success_or_failure, input, exception_message_transforms = DEFAULT_EXCEPTION_MESSAGE_TRANSFORMS)
+    success_or_failure.transform(
+      lambda { |v| Good.new(v) },
+      lambda { |e| Bad.new(transform_exception_message(e, exception_message_transforms), input) }
+    ).get
+  end
+  module_function :from_rescuer
+
+  def transform_exception_message(exception, exception_message_transforms = DEFAULT_EXCEPTION_MESSAGE_TRANSFORMS)
+    _, f = exception_message_transforms.find { |klass, _| klass === exception }
+    message = exception && exception.message
+    f && f.call(message) || message
+  end
+  module_function :transform_exception_message
+
+  def when(*args)
+    lambda { |v| Results.new(v).when(*args) }
+  end
+  module_function :when
+
+  def when_not(*args)
+    lambda { |v| Results.new(v).when_not(*args) }
+  end
+  module_function :when_not
+
+  # TODO: Extract this simple util somewhere else
+  HeadCombiner = Struct.new(:elements) do
+    def initialize(*args)
+      head, *tail = args
+      super(head.is_a?(HeadCombiner) ? head.elements + tail : args)
+    end
+  end
+
+  def combine(*args)
+    flat_args = (args.size == 1 && args.first.is_a?(Enumerable)) ? args.first : args
+    raise ArgumentError, 'no results to combine' if flat_args.empty?
+    flat_args.inject { |res, nxt| res.zip(nxt).map { |vs| HeadCombiner.new(*vs) } }.map { |hc| hc.elements }
+  end
+  module_function :combine
+
+  def predicate(method_name)
+    Filter.new(method_name.to_s.gsub(/\?\Z/, '')) { |v| v.send(method_name) }
+  end
+  module_function :predicate
+
+  class Filter
+    def initialize(msg_or_proc, &filter_block)
+      raise ArgumentError, 'invalid message' if msg_or_proc.nil?
+      raise ArgumentError, 'no block given' if filter_block.nil?
+      @msg_or_proc, @filter_block = msg_or_proc, filter_block
+    end
+
+    def call(value)
+      @filter_block.call(value)
+    end
+
+    def message
+      @msg_or_proc
+    end
+  end
+
+  Good = Struct.new(:value) do
+    def map
+      flat_map { |v| Good.new(yield v) }
+    end
+
+    def flat_map
+      yield(value)
+    end
+
+    alias_method :validate, :flat_map
+
+    def when(msg_or_proc_or_filter)
+      validate do |v|
+        predicate, msg_or_proc = extract_predicate_and_message(msg_or_proc_or_filter, v) { yield v }
+        predicate ? self : Bad.new(Results.call_or_yield_or_return(msg_or_proc, v) { |msg| 'not ' + msg }, v)
+      end
+    end
+
+    def when_not(msg_or_proc_or_filter)
+      validate do |v|
+        predicate, msg_or_proc = extract_predicate_and_message(msg_or_proc_or_filter, v) { yield v }
+        !predicate ? self : Bad.new(Results.call_or_yield_or_return(msg_or_proc, v), v)
+      end
+    end
+
+    def and
+      self
+    end
+
+    def when_all(*filters)
+      filters.flatten.inject(self) { |prev_result, filter| prev_result.and.when(filter) }
+    end
+
+    def when_all_not(*filters)
+      filters.flatten.inject(self) { |prev_result, filter| prev_result.and.when_not(filter) }
+    end
+
+    def validate_all(*validations)
+      validations.flatten.inject(self) { |prev_result, validation| prev_result.and.validate(&validation) }
+    end
+
+    def zip(other)
+      case other
+      when Good then Good.new([value, other.value])
+      when Bad  then other
+      end
+    end
+
+    private
+
+    def extract_predicate_and_message(msg_or_proc_or_filter, v)
+      if msg_or_proc_or_filter.is_a? Symbol
+        p = Results.predicate(msg_or_proc_or_filter)
+        [p.call(v), p.message]
+      elsif msg_or_proc_or_filter.respond_to?(:call) && msg_or_proc_or_filter.respond_to?(:message)
+        [msg_or_proc_or_filter.call(v), msg_or_proc_or_filter.message]
+      else
+        [yield, msg_or_proc_or_filter]
+      end
+    end
+
+  end
+
+  Bad = Struct.new(:why) do
+    def initialize(*args)
+      flat_args = args.flatten
+      super( flat_args.all? { |a| a.is_a? Because } ? flat_args : [Because.new(*flat_args)] )
+    end
+
+    def map
+      self
+    end
+
+    def flat_map
+      self
+    end
+
+    alias_method :validate, :flat_map
+
+    def when(msg_or_proc)
+      self
+    end
+
+    def when_not(msg_or_proc)
+      self
+    end
+
+    def and
+      And.new(self)
+    end
+
+    And = Struct.new(:prev_bad) do
+      def when(*args, &blk)
+        accumulate(:when, *args, &blk)
+      end
+
+      def when_not(*args, &blk)
+        accumulate(:when_not, *args, &blk)
+      end
+
+      def validate(*args, &blk)
+        accumulate(:validate, *args, &blk)
+      end
+
+      private
+
+      def accumulate(method, *args, &blk)
+        next_result = Good.new(input).send(method, *args, &blk)
+        case next_result
+        when Good then prev_bad
+        when Bad  then Bad.new(prev_bad.why + next_result.why)
+        end
+      end
+
+      def input
+        prev_bad.why.last.input
+      end
+    end
+
+    def when_all(*filters)
+      filters.flatten.inject(self) { |prev_result, filter| prev_result.and.when(filter) }
+    end
+
+    def when_all_not(*filters)
+      filters.flatten.inject(self) { |prev_result, filter| prev_result.and.when_not(filter) }
+    end
+
+    def validate_all(*validations)
+      validations.flatten.inject(self) { |prev_result, validation| prev_result.and.validate(&validation) }
+    end
+
+    def zip(other)
+      case other
+      when Good then self
+      when Bad  then Bad.new(why + other.why)
+      end
+    end
+  end
+
+  Because = Struct.new(:error, :input)
+
+  # Helper which will call its argument, or yield it to a block, or simply return it,
+  #   depending on what is possible with the given input
+  def self.call_or_yield_or_return(proc_or_value, *args)
+    if proc_or_value.respond_to?(:call)
+      proc_or_value.call(*args)
+    else
+      block_given? ? yield(proc_or_value) : proc_or_value
+    end
+  end
+
 end

data/lib/results/version.rb

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

data/spec/example_usages_spec.rb

@@ -0,0 +1,182 @@
+require 'spec_helper'
+require 'results'
+
+##
+# These specs ensure that published usage examples continue to work.
+##
+describe 'Example usages' do
+
+  def parseAge(str)
+    Results.new(str) { |v| Integer(v) }
+  end
+
+  describe 'Basic validation' do
+
+    context 'parseAge("1")' do
+      subject { parseAge('1').inspect }
+      it { is_expected.to eq '#<struct Results::Good value=1>' }
+    end
+
+    context 'parseAge("abc")' do
+      subject { parseAge('abc').inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="invalid value for integer", input="abc">]>' }
+    end
+
+  end
+
+  def parseAge21To45(str)
+    # Syntax workaround due to lack of support for chaining on blocks
+    _ = parseAge(str)
+    _ = _.when    ('under 45') { |v| v < 45 }
+    _ = _.when_not('under 21') { |v| v < 21 }
+  end
+
+  under_45 = Results::Filter.new('under 45') { |v| v < 45 }
+
+  under_21 = lambda { |v| v < 21 }.tap { |l| l.define_singleton_method(:message) { 'under 21' } }
+
+  def parseAgeRange(str)
+    parseAge(str).validate do |v|
+      case v
+      when 21...45 then Results::Good.new(v)
+      else              Results::Bad.new('not between 21 and 45', v)
+      end
+    end
+  end
+
+  def valid?(str)
+    Results.new(str)
+      .when_not(Results.predicate :nil?)
+      .when_not(Results.predicate :empty?)
+  end
+
+  def valid_short?(str)
+    Results.new(str)
+      .when_not(:nil?)
+      .when_not(:empty?)
+  end
+
+  describe 'Chained filters and validations' do
+
+    context 'parseAge21To45("29")' do
+      subject { parseAge21To45('29').inspect }
+      it { is_expected.to eq '#<struct Results::Good value=29>' }
+    end
+
+    context 'parseAge21To45("65")' do
+      subject { parseAge21To45('65').inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="not under 45", input=65>]>' }
+    end
+
+    context 'parseAge21To45("1")' do
+      subject { parseAge21To45('1').inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="under 21", input=1>]>' }
+    end
+
+    context 'parseAgeRange("29")' do
+      subject { parseAgeRange('29').inspect }
+      it { is_expected.to eq '#<struct Results::Good value=29>' }
+    end
+
+    context 'parseAgeRange("65")' do
+      subject { parseAgeRange('65').inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="not between 21 and 45", input=65>]>' }
+    end
+
+    context 'parseAge("65").when(under_45).when_not(under_21)' do
+      subject { parseAge('65').when(under_45).when_not(under_21).inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="not under 45", input=65>]>' }
+    end
+
+    context 'parseAge("16").when(under_45).when_not(under_21)' do
+      subject {
+        parseAge('16')
+          .when(under_45)
+          .when_not(under_21).inspect
+      }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="under 21", input=16>]>' }
+    end
+
+    context 'parseAge("65").when(lambda { |v| "#{v} is not under 45" }) { |v| v < 45 }' do
+      subject { parseAge('65').when(lambda { |v| "#{v} is not under 45" }) { |v| v < 45 }.inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="65 is not under 45", input=65>]>' }
+    end
+
+    context 'Results.when_not(under_21).call(16)' do
+      subject { Results.when_not(under_21).call(16).inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="under 21", input=16>]>' }
+    end
+
+    context 'valid?(nil)' do
+      subject { valid?(nil).inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="nil", input=nil>]>' }
+    end
+
+    context 'valid?("")' do
+      subject { valid?('').inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="empty", input="">]>' }
+    end
+
+    context 'valid_short?(nil)' do
+      subject { valid_short?(nil).inspect }
+      it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="nil", input=nil>]>' }
+    end
+
+  end
+
+  describe 'Accumulating multiple bad results' do
+
+    describe 'Multiple filters and validations of a single input' do
+
+      context 'Results.new(1.23).when(:integer?).and.when(:zero?)' do
+        subject { Results.new(1.23).when(:integer?).and.when(:zero?).inspect }
+        it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="not integer", input=1.23>, ' +
+                                                          '#<struct Results::Because error="not zero", input=1.23>]>' }
+      end
+
+      let(:filters) { [:integer?, :zero?, Results::Filter.new('greater than 2') { |n| n > 2 }] }
+
+      context 'Results.new(1.23).when_all(filters)' do
+        subject { Results.new(1.23).when_all(filters).inspect }
+        it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="not integer", input=1.23>, ' +
+                                                          '#<struct Results::Because error="not zero", input=1.23>, ' +
+                                                          '#<struct Results::Because error="not greater than 2", input=1.23>]>' }
+      end
+
+    end
+
+    describe 'Combine results of multiple inputs' do
+      let(:good) { Results::Good.new(1) }
+      let(:bad1) { Results::Bad.new('not nonzero', 0) }
+      let(:bad2) { Results::Bad.new('not integer', 1.23) }
+
+      context 'good.zip(good)' do
+        subject { good.zip(good).inspect }
+        it { is_expected.to eq '#<struct Results::Good value=[1, 1]>' }
+      end
+
+      context 'good.zip(bad1).zip(bad2)' do
+        subject { good.zip(bad1).zip(bad2).inspect }
+        it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="not nonzero", input=0>, ' +
+                                                          '#<struct Results::Because error="not integer", input=1.23>]>' }
+      end
+
+      let(:all_good_results) { [good, good, good] }
+      let(:some_bad_results) { [bad1, good, bad2] }
+
+      context 'Results.combine(all_good_results)' do
+        subject { Results.combine(all_good_results).inspect }
+        it { is_expected.to eq '#<struct Results::Good value=[1, 1, 1]>' }
+      end
+
+      context 'Results.combine(some_bad_results)' do
+        subject { Results.combine(some_bad_results).inspect }
+        it { is_expected.to eq '#<struct Results::Bad why=[#<struct Results::Because error="not nonzero", input=0>, ' +
+                                                          '#<struct Results::Because error="not integer", input=1.23>]>' }
+      end
+
+    end
+
+  end
+
+end

data/spec/results_unit_spec.rb

@@ -0,0 +1,618 @@
+require 'spec_helper'
+require 'results'
+
+describe Results do
+
+  ##
+  # Construct indirectly with a value or block which may raise an exception
+  ##
+  describe '.new' do
+
+    context 'with non-callable value and no block' do
+      subject { Results.new(1) }
+      it { is_expected.to eq Results::Good.new(1) }
+    end
+
+    shared_examples 'exception handler' do
+      context 'when does *not* raise' do
+        subject { when_does_not_raise }
+        it { is_expected.to eq Results::Good.new(1) }
+      end
+
+      context 'when *does* raise' do
+        let(:std_err) { StandardError.new('abc') }
+
+        context 'with defaults' do
+          context 'when raises ArgumentError' do
+            subject { when_raises_arg_err }
+            it { is_expected.to eq Results::Bad.new('invalid value for integer', input_raises_arg_err) }
+          end
+
+          context 'when raises StandardError' do
+            subject { lambda { when_raises_std_err } }
+            it { is_expected.to raise_error(StandardError, 'abc') }
+          end
+        end
+      end
+    end
+
+    context 'with callable value' do
+      let(:input_does_not_raise) { lambda { 1 } }
+      let(:input_raises_arg_err) { lambda { Integer('abc') } }
+      let(:input_raises_std_err) { lambda { raise std_err } }
+
+      let(:when_does_not_raise) { Results.new(input_does_not_raise) }
+      let(:when_raises_arg_err) { Results.new(input_raises_arg_err) }
+      let(:when_raises_std_err) { Results.new(input_raises_std_err) }
+
+      it_behaves_like 'exception handler'
+    end
+
+    context 'with block' do
+      let(:input_does_not_raise) { 1 }
+      let(:input_raises_arg_err) { 'abc' }
+      let(:input_raises_std_err) { 'dummy' }
+
+      let(:when_does_not_raise) { Results.new(input_does_not_raise) { |v| v } }
+      let(:when_raises_arg_err) { Results.new(input_raises_arg_err) { |v| Integer(v) } }
+      let(:when_raises_std_err) { Results.new(input_raises_std_err) { |_| raise std_err } }
+
+      it_behaves_like 'exception handler'
+    end
+
+  end
+
+  ##
+  # Construct directly by wrapping an existing Rescuer::Success or Rescuer::Failure
+  ##
+  describe '.from_rescuer' do
+
+    context 'when success' do
+      let(:success) { Rescuer::Success.new(1) }
+      subject { Results.from_rescuer(success, 1) }
+      it { is_expected.to eq Results::Good.new(1) }
+    end
+
+    context 'when failure' do
+      let(:input) { 'abc' }
+      let(:failure) { Rescuer::Failure.new(StandardError.new('failure message')) }
+      subject { Results.from_rescuer(failure, input) }
+      it { is_expected.to eq Results::Bad.new('failure message', 'abc') }
+    end
+
+  end
+
+  ##
+  # Make a validation function from a filter using .when
+  ##
+  describe '.when' do
+
+    shared_examples 'validation from a filter' do
+      context 'when passes' do
+        subject { Results.when(is_zero).call(0) }
+        it { is_expected.to eq Results::Good.new(0) }
+      end
+
+      context 'when fails' do
+        subject { Results.when(is_zero).call(1) }
+        it { is_expected.to eq Results::Bad.new('not zero', 1) }
+      end
+    end
+
+    context 'when instance of Results::Filter' do
+      let(:is_zero) { Results::Filter.new('zero') { |n| n.zero? } }
+      it_behaves_like 'validation from a filter'
+    end
+
+    context 'when a duck-type of #call and #message' do
+      let(:is_zero) { lambda { |n| n.zero? }.tap { |l| l.define_singleton_method(:message) { 'zero' } } }
+      it_behaves_like 'validation from a filter'
+    end
+
+  end
+
+  ##
+  # Make a validation function from a filter using .when_not
+  ##
+  describe '.when_not' do
+
+    shared_examples 'validation from a filter' do
+      context 'when passes' do
+        subject { Results.when_not(is_zero).call(1) }
+        it { is_expected.to eq Results::Good.new(1) }
+      end
+
+      context 'when fails' do
+        subject { Results.when_not(is_zero).call(0) }
+        it { is_expected.to eq Results::Bad.new('zero', 0) }
+      end
+    end
+
+    context 'when instance of Results::Filter' do
+      let(:is_zero) { Results::Filter.new('zero') { |n| n.zero? } }
+      it_behaves_like 'validation from a filter'
+    end
+
+    context 'when a duck-type of #call and #message' do
+      let(:is_zero) { lambda { |n| n.zero? }.tap { |l| l.define_singleton_method(:message) { 'zero' } } }
+      it_behaves_like 'validation from a filter'
+    end
+
+  end
+
+  ##
+  # Combine a collection of multiple results
+  ##
+  describe '.combine' do
+    let(:all_goods) { Array.new(4) { |n| Results::Good.new(n) } }
+    let(:some_bads) { all_goods.map { |r| r.when('even') { |v| v % 2 == 0 } } }
+
+    context 'when all good results' do
+      subject { Results.combine(all_goods) }
+      it { is_expected.to eq Results::Good.new([0, 1, 2, 3]) }
+    end
+
+    context 'when some bad results' do
+      subject { Results.combine(some_bads) }
+      it { is_expected.to eq Results::Bad.new([1, 3].map { |v| Results::Because.new('not even', v) }) }
+    end
+
+    context 'when splatted all good results' do
+      subject { Results.combine(*all_goods) }
+      it { is_expected.to eq Results::Good.new([0, 1, 2, 3]) }
+    end
+
+    context 'when good results are arrays' do
+      subject { Results.combine(all_goods.map { |r| r.map { |n| [n] } }) }
+      it { is_expected.to eq Results::Good.new([[0], [1], [2], [3]]) }
+    end
+
+    context 'when empty' do
+      subject { lambda { Results.combine([]) } }
+      it { is_expected.to raise_error(ArgumentError, 'no results to combine') }
+    end
+  end
+
+  ##
+  # Make a filter from the symbol name of a predicate method using .predicate
+  ##
+  describe '.predicate' do
+    context 'when symbol ends in ?, message strips the ?' do
+      subject { Results.predicate(:zero?).message }
+      it { is_expected.to eq 'zero' }
+    end
+
+    context 'when passes' do
+      subject { Results.predicate(:zero?).call(0) }
+      it { is_expected.to eq true }
+    end
+
+    context 'when fails' do
+      subject { Results.predicate(:zero?).call(1) }
+      it { is_expected.to eq false }
+    end
+  end
+
+  ##
+  # Transform exception message formatting via configured lambdas
+  ##
+  describe '.transform_exception_message' do
+
+    context 'with defaults' do
+      context 'when argument error due to invalid integer' do
+        subject { Results.transform_exception_message(begin; Integer('abc'); rescue => e; e; end) }
+        it { is_expected.to eq 'invalid value for integer' }
+      end
+
+      context 'when argument error due to invalid float' do
+        subject { Results.transform_exception_message(begin; Float('abc'); rescue => e; e; end) }
+        it { is_expected.to eq 'invalid value for float' }
+      end
+    end
+
+  end
+
+  ##
+  # Construct directly as Good
+  ##
+  describe Results::Good do
+    let(:value) { 1 }
+    let(:good) { Results::Good.new(value) }
+
+    describe '#map' do
+      context 'with a function' do
+        subject { good.map { |v| v + 1 } }
+        it { is_expected.to eq Results::Good.new(2) }
+      end
+    end
+
+    describe '#flat_map' do
+      context 'with a function' do
+        subject { good.flat_map { |v| Results::Good.new(v + 1) } }
+        it { is_expected.to eq Results::Good.new(2) }
+      end
+    end
+
+    describe '#when' do
+      context 'with true predicate' do
+        subject { good.when('dummy') { |_| true } }
+        it { is_expected.to be good }
+      end
+
+      context 'with false predicate and string error message, prepends "not"' do
+        subject { good.when('true') { |_| false } }
+        it { is_expected.to eq Results::Bad.new('not true', value) }
+      end
+
+      context 'with false predicate and callable error message' do
+        subject { good.when(lambda { |v| "#{v} was not true" }) { |_| false } }
+        it { is_expected.to eq Results::Bad.new('1 was not true', value) }
+      end
+
+      context 'with true predicate given by name' do
+        subject { good.when(:nonzero?) }
+        it { is_expected.to be good }
+      end
+
+      context 'with false predicate given by name' do
+        subject { good.when(:zero?) }
+        it { is_expected.to eq Results::Bad.new('not zero', value) }
+      end
+    end
+
+    describe '#when_not' do
+      context 'with false predicate' do
+        subject { good.when_not('dummy') { |_| false } }
+        it { is_expected.to be good }
+      end
+
+      context 'with true predicate and string error message' do
+        subject { good.when_not('evaluated as true') { |_| true } }
+        it { is_expected.to eq Results::Bad.new('evaluated as true', value) }
+      end
+
+      context 'with failing predicate and callable error message' do
+        subject { good.when_not(lambda { |v| "#{v} evaluated as true" }) { |_| true } }
+        it { is_expected.to eq Results::Bad.new('1 evaluated as true', value) }
+      end
+
+      context 'with true predicate given by name' do
+        subject { good.when_not(:nonzero?) }
+        it { is_expected.to eq Results::Bad.new('nonzero', value) }
+      end
+
+      context 'with false predicate given by name' do
+        subject { good.when_not(:zero?) }
+        it { is_expected.to be good }
+      end
+    end
+
+    describe '#validate' do
+      context 'with return of good' do
+        subject { good.validate { |_| good } }
+        it { is_expected.to be good }
+      end
+
+      context 'with return of bad' do
+        subject { good.validate { |v| Results::Bad.new("no good: #{v}", v) } }
+        it { is_expected.to eq Results::Bad.new('no good: 1', value) }
+      end
+    end
+
+    describe '#and' do
+      subject { good.and }
+      it { is_expected.to be good }
+    end
+
+    describe '#when_all' do
+      context 'with filters which are all true' do
+        let(:filters_true) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| true } } }
+
+        context 'passed as array' do
+          subject { good.when_all(filters_true) }
+          it { is_expected.to be good }
+        end
+
+        context 'passed splatted' do
+          subject { good.when_all(*filters_true) }
+          it { is_expected.to be good }
+        end
+      end
+
+      context 'with filters which are all false' do
+        let(:filters_false) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| false } } }
+        let(:expected_bad) { Results::Bad.new(
+          Results::Because.new('not f0', value),
+          Results::Because.new('not f1', value)) }
+
+        context 'passed as array' do
+          subject { good.when_all(filters_false) }
+          it { is_expected.to eq expected_bad }
+        end
+
+        context 'passed splatted' do
+          subject { good.when_all(*filters_false) }
+          it { is_expected.to eq expected_bad }
+        end
+      end
+    end
+
+    describe '#when_all_not' do
+      context 'with filters which are all true' do
+        let(:filters_true) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| true } } }
+        let(:expected_bad) { Results::Bad.new(
+          Results::Because.new('f0', value),
+          Results::Because.new('f1', value)) }
+
+        context 'passed as array' do
+          subject { good.when_all_not(filters_true) }
+          it { is_expected.to eq expected_bad }
+        end
+
+        context 'passed splatted' do
+          subject { good.when_all_not(*filters_true) }
+          it { is_expected.to eq expected_bad }
+        end
+      end
+
+      context 'with filters which are all false' do
+        let(:filters_false) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| false } } }
+
+        context 'passed as array' do
+          subject { good.when_all_not(filters_false) }
+          it { is_expected.to be good }
+        end
+
+        context 'passed splatted' do
+          subject { good.when_all_not(*filters_false) }
+          it { is_expected.to be good }
+        end
+      end
+    end
+
+    describe '#validate_all' do
+      context 'with validations all returning good' do
+        let(:validations_good) { Array.new(2) { |n| lambda { |_| Results::Good.new(n) } } }
+        subject { good.validate_all(validations_good) }
+        it { is_expected.to eq good }
+      end
+
+      context 'with validations all returning bad' do
+        let(:validations_bad) { Array.new(2) { |n| lambda { |i| Results::Bad.new("v#{n}", i) } } }
+        let(:expected_bad) { Results::Bad.new(
+          Results::Because.new('v0', value),
+          Results::Because.new('v1', value)) }
+
+        subject { good.validate_all(validations_bad) }
+        it { is_expected.to eq expected_bad }
+      end
+    end
+
+    describe '#zip' do
+      context 'when other is good' do
+        subject { good.zip(good) }
+        it { is_expected.to eq Results::Good.new([value, value]) }
+      end
+
+      context 'when other is bad' do
+        let(:bad) { Results::Bad.new('not ok', value) }
+        subject { good.zip(bad) }
+        it { is_expected.to be bad }
+      end
+    end
+  end
+
+  ##
+  # Construct directly as Bad
+  ##
+  describe Results::Bad do
+    let(:msg) { 'epic fail' }
+    let(:input) { 'abc' }
+    let(:bad) { Results::Bad.new(msg, input) }
+
+    describe '#map' do
+      context 'with any function' do
+        subject { bad.map { |_| 'dummy' } }
+        it { is_expected.to be bad }
+      end
+    end
+
+    describe '#flat_map' do
+      context 'with any function' do
+        subject { bad.flat_map { |_| Results::Bad.new('dummy', 0) } }
+        it { is_expected.to be bad }
+      end
+    end
+
+    describe '#when' do
+      context 'with any predicate' do
+        subject { bad.when('dummy') { |_| true } }
+        it { is_expected.to be bad }
+      end
+    end
+
+    describe '#when_not' do
+      context 'with any predicate' do
+        subject { bad.when_not('dummy') { |_| true } }
+        it { is_expected.to be bad }
+      end
+    end
+
+    describe '#validate' do
+      context 'with any function' do
+        subject { bad.validate { |_| Results::Good.new(2) } }
+        it { is_expected.to be bad }
+      end
+    end
+
+    describe '#and' do
+      describe '#when' do
+        context 'filter is true' do
+          subject { bad.and.when('filter') { |_| true } }
+          it { is_expected.to be bad }
+        end
+
+        context 'filter is false' do
+          subject { bad.and.when('filter') { |_| false } }
+          it { is_expected.to eq Results::Bad.new(Results::Because.new(msg, input),
+                                                  Results::Because.new('not filter', input)) }
+        end
+      end
+
+      describe '#when_not' do
+        context 'filter is true' do
+          subject { bad.and.when_not('filter') { |_| true } }
+          it { is_expected.to eq Results::Bad.new(Results::Because.new(msg, input),
+                                                  Results::Because.new('filter', input)) }
+        end
+
+        context 'filter is false' do
+          subject { bad.and.when_not('filter') { |_| false } }
+          it { is_expected.to be bad }
+        end
+      end
+    end
+
+    describe '#when_all' do
+      context 'with filters which are all true' do
+        let(:filters_true) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| true } } }
+
+        context 'passed as array' do
+          subject { bad.when_all(filters_true) }
+          it { is_expected.to be bad }
+        end
+
+        context 'passed splatted' do
+          subject { bad.when_all(*filters_true) }
+          it { is_expected.to be bad }
+        end
+      end
+
+      context 'with filters which are all false' do
+        let(:filters_false) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| false } } }
+        let(:expected_bad) { Results::Bad.new(
+                               Results::Because.new(msg, input),
+                               Results::Because.new('not f0', input),
+                               Results::Because.new('not f1', input)) }
+
+        context 'passed as array' do
+          subject { bad.when_all(filters_false) }
+          it { is_expected.to eq expected_bad }
+        end
+
+        context 'passed splatted' do
+          subject { bad.when_all(*filters_false) }
+          it { is_expected.to eq expected_bad }
+        end
+      end
+    end
+
+    describe '#when_all_not' do
+      context 'with filters which are all true' do
+        let(:filters_true) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| true } } }
+        let(:expected_bad) { Results::Bad.new(
+                               Results::Because.new(msg, input),
+                               Results::Because.new('f0', input),
+                               Results::Because.new('f1', input)) }
+
+        context 'passed as array' do
+          subject { bad.when_all_not(filters_true) }
+          it { is_expected.to eq expected_bad }
+        end
+
+        context 'passed splatted' do
+          subject { bad.when_all_not(*filters_true) }
+          it { is_expected.to eq expected_bad }
+        end
+      end
+
+      context 'with filters which are all false' do
+        let(:filters_false) { Array.new(2) { |n| Results::Filter.new("f#{n}") { |_| false } } }
+
+        context 'passed as array' do
+          subject { bad.when_all_not(filters_false) }
+          it { is_expected.to be bad }
+        end
+
+        context 'passed splatted' do
+          subject { bad.when_all_not(*filters_false) }
+          it { is_expected.to be bad }
+        end
+      end
+    end
+
+    describe '#validate_all' do
+      context 'with validations all returning good' do
+        let(:validations_good) { Array.new(2) { |n| lambda { |_| Results::Good.new(n) } } }
+        subject { bad.validate_all(validations_good) }
+        it { is_expected.to be bad }
+      end
+
+      context 'with validations all returning bad' do
+        let(:validations_bad) { Array.new(2) { |n| lambda { |i| Results::Bad.new("v#{n}", i) } } }
+        let(:expected_bad) { Results::Bad.new(
+          Results::Because.new(msg, input),
+          Results::Because.new('v0', input),
+          Results::Because.new('v1', input)) }
+
+        subject { bad.validate_all(validations_bad) }
+        it { is_expected.to eq expected_bad }
+      end
+    end
+
+    describe '#zip' do
+      context 'when other is good' do
+        subject { bad.zip(Results::Good.new(2)) }
+        it { is_expected.to be bad }
+      end
+
+      context 'when other is bad' do
+        subject { bad.zip(bad) }
+        it { is_expected.to eq Results::Bad.new(bad.why + bad.why) }
+      end
+    end
+  end
+
+  ##
+  # Helper class Filter for use with #when and #when_not
+  ##
+  describe Results::Filter do
+
+    context 'with string message and block' do
+      let(:filter_under_45) { Results::Filter.new('under 45') { |v| v < 45 } }
+
+      context '#call when block returns false' do
+        subject { filter_under_45.call(45) }
+        it { is_expected.to be false }
+      end
+
+      context '#call when block returns true' do
+        subject { filter_under_45.call(44) }
+        it { is_expected.to be true }
+      end
+
+      context '#message' do
+        subject { filter_under_45.message }
+        it { is_expected.to eq 'under 45' }
+      end
+    end
+
+    context 'with callable message' do
+      let(:filter_callable_msg) { Results::Filter.new(lambda { |v| "value: #{v}" }) { |v| v } }
+      subject { filter_callable_msg.message.call(1) }
+      it { is_expected.to eq 'value: 1' }
+    end
+
+    context 'with nil message' do
+      subject { lambda { Results::Filter.new(nil) { |v| v } } }
+      it { is_expected.to raise_error(ArgumentError, 'invalid message') }
+    end
+
+    context 'with *no* block' do
+      subject { lambda { Results::Filter.new('dummy') } }
+      it { is_expected.to raise_error(ArgumentError, 'no block given') }
+    end
+
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: results
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Marc Siegel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-22 00:00:00.000000000 Z
+date: 2014-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rescuer
@@ -116,6 +116,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - ".ruby-gemset"
 - ".ruby-version"
 - ".travis.yml"
@@ -126,7 +127,8 @@ files:
 - lib/results.rb
 - lib/results/version.rb
 - results.gemspec
-- spec/results_spec.rb
+- spec/example_usages_spec.rb
+- spec/results_unit_spec.rb
 - spec/spec_helper.rb
 homepage: http://ms-ati.github.com/results/
 licenses:

data/spec/results_spec.rb

@@ -1,24 +0,0 @@
-require 'spec_helper'
-require 'results'
-
-describe Results do
-
-  ##
-  # Construct indirectly by wrapping a block which may raise an exception
-  ##
-  describe '.new' do
-  end
-
-  ##
-  # Construct directly as Good
-  ##
-  describe Results::Good do
-  end
-
-  ##
-  # Construct directly as Bad
-  ##
-  describe Results::Bad do
-  end
-
-end