monadic 0.0.7 → 0.1.0

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.1.0
+
+You can now chain Eithers with `+` without providing a block or a proc:
+
+    Success(1) + Failure(2)     == Failure(2)
+    Failure(1) + Failure(2)     == Failure(1)
+
+All monads now have the `#to_ary` and `#to_a` method, which coerces the inner value into an `Array`.
+
+I am considering the Api now almost stable, the only thing I am not so sure about, 
+is whether to apply the magic coercion or not.
+
+`Validation()` now returns the successfully validated values. See examples/validation.rb
+
 ## v0.0.7 
 
 Implements the #map method for all Monads. It works on value types and on Enumerable collections.  

data/README.md

@@ -216,7 +216,9 @@ Example:
       end
     end
 
-The above example, returns either `Success()` or `Failure(['Age must be > 0', 'No drunks allowed']) with a list of what went wrong during the validation.
+The above example, returns either `Success([32, :sober, :male])` or `Failure(['Age must be > 0', 'No drunks allowed'])` with a list of what went wrong during the validation.
+
+See also exmaples/validation.rb
 
 ### Monad 
 All Monads inherit from this class. Standalone it is an Identity monad. Not useful on its own. It's methods are usable on all its descendants.

data/examples/validation.rb

@@ -0,0 +1,31 @@
+require 'monadic'
+
+valid_age = ->(age_expr) {
+  age = age_expr.to_i
+  case 
+  when age <=  0; Failure('Age must be > 0')
+  when age > 130; Failure('Age must be < 130')
+  else Success(age)
+  end
+}
+
+valid_name = ->(name) {
+  case 
+  when name =~ /\w{3,99}/i; Success(name)
+  else Failure('Invalid name')
+  end
+}
+
+params = {age: 32, name: 'Andrzej', postcode: '50000'}
+
+Person = Struct.new(:name, :age)
+
+result = Validation() do
+  check { valid_age.(params[:age])   }
+  check { valid_name.(params[:name]) }
+end
+
+case result
+  when Failure; puts "Something went wrong: #{result.fetch}"
+  when Success; person = Person.new(*result.fetch); puts "We have a person #{person.inspect}"
+end

data/lib/monadic/either.rb

@@ -6,6 +6,7 @@ module Monadic
     end
 
     def self.unit(value)
+      return value if value.is_a? Either
       return Failure.new(value) if value.nil? || (value.respond_to?(:empty?) && value.empty?) || !value
       return Success.new(value)
     end
@@ -14,37 +15,46 @@ module Monadic
     # are required (Either is abstract).
     private_class_method :new
 
-    def success?
-      is_a? Success
-    end
+    # Allows privileged access to the +Either+'s inner value from within a block. 
+    # This block should return a +Success+ or +Failure+ itself. It will be coerced into #Either
+    # @return [Success, Failure]
+    def bind(proc=nil, &block)
+      return self if failure?
+      return concat(proc) if proc.is_a? Either
 
-    def failure?
-      is_a? Failure
+      begin
+        Either(call(proc, block))
+      rescue Exception => ex
+        Failure(ex)      
+      end
     end
+    alias :>=  :bind
+    alias :+   :bind
 
     def fetch(default=@value)
       return default if failure?
       return @value
     end
+
     alias :_     :fetch
+    def success?
+      is_a? Success
+    end
 
-    def bind(proc=nil, &block)
-      return self if failure?
+    def failure?
+      is_a? Failure
+    end
 
-      begin
-        result = if proc && proc.arity == 0 
-                   then proc.call
-                   else (proc || block).call(@value) 
-                 end
-        result ||= Failure(nil)
-        result = Either(result) unless result.is_a? Either
-        result    
-      rescue Exception => ex
-        Failure(ex)      
-      end
+    private 
+    def call(proc=nil, block)
+      func = (proc || block)
+      raise "No block or lambda given" unless func.is_a? Proc
+      (func.arity == 0 ? func.call : func.call(@value)) || Failure(nil)
+    end
+
+    def concat(other)
+      failure? ? self : other
     end
-    alias :>=  :bind
-    alias :+   :bind
   end
 
   class Either::Chain
@@ -64,7 +74,7 @@ module Monadic
     end
   end
 
-  # @private instance and class methods for Success and Failure
+  # @private instance and class methods for +Success+ and +Failure+
   module SuccessFailure
     def self.included(base)
       base.class_eval do
@@ -103,8 +113,8 @@ module Monadic
     Success.new(value)
   end
 
-  # Magic factory
-  # @return [Success, Failure] depending whether +value+ is falsey
+  # Coerces any value into either a +Success+ or a +Failure+.
+  # @return [Success, Failure] depending whether +value+ is falsey i.e. nil, false, Enumerable#empty? become +Failure+, all other `Success`
   def Either(value)
     Either.unit(value)
   end

data/lib/monadic/maybe.rb

@@ -9,16 +9,12 @@ module Monadic
     # are required (Maybe is abstract).
     private_class_method :new
 
+    # @return true if the underlying object responds to #empty?, false otherwise
     def empty?
       @value.respond_to?(:empty?) && @value.empty?
     end
 
-    def to_ary
-      return [@value].flatten if @value.respond_to? :flatten
-      return [@value]
-    end
-    alias :to_a :to_ary
-
+    # @return [Failure, Success] the Maybe Monad filtered with the block or proc expression
     def select(proc = nil, &block)
       return Maybe(@value.select(&block)) if @value.is_a?(::Enumerable)
       return Nothing unless (proc || block).call(@value)
@@ -30,6 +26,7 @@ module Monadic
     end
   end
 
+  # Represents an existing value
   class Just < Maybe
     public_class_method :new
 
@@ -43,6 +40,7 @@ module Monadic
     end
   end
 
+  # Represents a NullObject
   class Nothing < Maybe
     class << self
       def fetch(default=nil)

data/lib/monadic/monad.rb

@@ -8,6 +8,7 @@ module Monadic
       @value = join(value)
     end
 
+    # Allows priviledged access to the inner value of the Monad from within the block
     def bind(proc=nil, &block)
       (proc || block).call(@value)
     end
@@ -35,6 +36,12 @@ module Monadic
       return self.class.unit(func.call(@value))
     end
 
+    # @return [Array] a with the values inside the monad
+    def to_ary
+      Array(@value)
+    end
+    alias :to_a :to_ary
+    
     # Return the string representation of the Monad
     def to_s
       pretty_class_name = self.class.name.split('::')[-1]

data/lib/monadic/validation.rb

@@ -9,20 +9,25 @@ module Monadic
   # Validation is not a monad, but an deemed an applicative functor
   class Validation
     def initialize
-      @result = Success([])
+      @result = []
     end
 
     def call(&block)
       instance_eval(&block)
+
+      if @result.any?(&:failure?)
+        Failure(@result.select(&:failure?).map(&:fetch))
+      else
+        Success(@result.select(&:success?).map(&:fetch))
+      end
     end
 
     # 
     def check(proc=nil, &block)
       result = (proc || block).call
       raise NotEitherError, "Expected #{result.inspect} to be an Either" unless result.is_a? Either
-      @result = Failure(@result.fetch << result.fetch) if result.failure?
-
-      @result
+      # @failure.fetch << result.fetch) if result.failure?
+      @result << result
     end
   end
 end

data/lib/monadic/version.rb

@@ -1,3 +1,3 @@
 module Monadic
-  VERSION = "0.0.7"
+  VERSION = "0.1.0"
 end

data/spec/either_spec.rb

@@ -75,6 +75,12 @@ describe Monadic::Either do
     Failure.should === Either(nil)
   end
 
+  it 'Either on an either returns the Either self to allow coercion' do
+    Either(Success(1)).should == Success(1)
+    Success(Success(1)).should == Success(1)
+    Failure(Failure(1)).should == Failure(1)
+  end
+
   it 'Either with a non-falsey value returns success' do
     Success.should === Either(1)
     Success.should === Either(true)
@@ -166,6 +172,15 @@ describe Monadic::Either do
     either.should == Success(1)
   end
 
+  it 'allows to add Eithers without specifying a block or proc' do
+    (Failure(1) + Failure(2)).should  == Failure(1)
+    (Success(1) + Failure(2)).should  == Failure(2)
+    (Success(1) + Success(2)).should  == Success(2)
+    (Failure(1) >= Failure(2)).should == Failure(1)
+    (Success(1) >= Failure(2)).should == Failure(2)
+    (Success(1) >= Success(2)).should == Success(2)
+  end
+
   it 'allows to check whether the result was a success or failure' do
     Success(0).success?.should be_true
     Success(1).failure?.should be_false
@@ -174,7 +189,7 @@ describe Monadic::Either do
     Failure(3).failure?.should be_true
   end
 
-  it 'supprts Either.chain' do
+  it 'supports Either.chain' do
     Either.chain do 
       bind -> { Success(1) }
       bind -> { Success(2) }

data/spec/maybe_spec.rb

@@ -115,7 +115,7 @@ describe Monadic::Maybe do
     Maybe([1, 2]).select { |e| e == 1             }.should == Just([1])
   end
 
-  it 'acts as an array' do
+  it 'acts as an array (inherited from Monad)' do
     Maybe('foo').to_a.should == ['foo']
     Maybe(['foo', 'bar']).to_a.should == ['foo', 'bar']
     Maybe(nil).to_a.should == []

data/spec/monad_spec.rb

@@ -8,6 +8,10 @@ describe Monadic::Monad do
   it '#to_s shows the monad name and its value' do
     Monad.unit(1).to_s.should == 'Monad(1)'
     Monad.unit(nil).to_s.should == 'Monad(nil)'
+    Monad.unit([1, 2]).map(&:to_s).should == Monad.unit(["1", "2"])
+
+    # can be done also
+    Monad.unit([1, 2]).bind {|v| Monad.unit(v.map(&:to_s)) }.should == Monad.unit(["1", "2"])
   end
 
   describe '#map' do
@@ -21,4 +25,10 @@ describe Monadic::Monad do
       Monad.unit(['foo', 'bar']).map(&:upcase).should == Monad.unit(['FOO', 'BAR'])
     end
   end
+
+  describe '#to_ary #to_a' do
+    Monad.unit([1, 2]).to_a.should == [1, 2]
+    Monad.unit(nil).to_a.should == []
+    Monad.unit('foo').to_a.should == ['foo']
+  end
 end

data/spec/validation_spec.rb

@@ -42,6 +42,6 @@ describe Monadic::Validation do
 
     success = validate(Person.new(age = 30, gender = :male, sobriety = :sober, name = 'test'))
     success.should be_a Success
-    success.should == Success([])
+    success.should == Success([30, :sober, :male])
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-05 00:00:00.000000000 Z
+date: 2012-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -139,6 +139,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- examples/validation.rb
 - lib/monadic.rb
 - lib/monadic/core_ext/object.rb
 - lib/monadic/either.rb