monadic 0.0.4 → 0.0.5

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.0.5 
+
+Removed the `#chain` method alias for bind in `Either`.
+
+Moar examples with instance variables in an `Either.chain`.
+
+Add monadic `Validation`, which is a special application (an applicative functor) of the Either Monad e.g.
+
+    Validation() do
+      check { check_age.(person.age);          }
+      check { check_sobriety.(person.sobriety) }
+    end
+
+It returns a Success([]) with an empty list, or a Failure([..]) with a list of all Failures.
+
 ## v0.0.4
 
 To be more idiomatic rubyuesque, rename `#value` to `#fetch`, which throws now an `NoValueError`.  

data/README.md

@@ -1,17 +1,22 @@
 # Monadic
 
-helps dealing with exceptional situations, it comes from the sphere of functional programming and bringing the goodies I have come to love in Scala to my ruby projects (hence I will be using more Scala like constructs than Haskell).
+helps dealing with exceptional situations, it comes from the sphere of functional programming and bringing the goodies I have come to love in [Scala](http://www.scala-lang.org/) to my ruby projects (hence I will be using more [Scala](http://www.scala-lang.org/) like constructs than Haskell).
 
 My motivation to create this gem was that I often work with nested Hashes and need to reach deeply inside of them so my code is sprinkled with things like some_hash.fetch(:one, {}).fetch(:two, {}).fetch(:three, "unknown"). 
 
-We have the following monadics:
+We have the following monadics (monads, functors, applicatives and variations):
 
-- Option (Maybe in Haskell) - Scala like with a rubyesque flavour
+- Option (Maybe in Haskell) - [Scala](http://www.scala-lang.org/) like with a rubyesque flavour
 - Either - more Haskell like
+- Validation 
 
 What's the point of using monads in ruby? To me it started with having a safe way to deal with nil objects and other exceptions.
 Thus you contain the erroneous behaviour within a monad - an indivisible, impenetrable unit.
 
+Monad purists might complain that there is no unit method to get the zero monad, I didn't include them, as I didn't find this idiomatic to the ruby language. I prefer to focus on the pragmatic uses of monads. If you want to learn moar about monads, see the references section at the bottom.  
+
+A monad is most effectively described as a computation that eventually returns a value. -- Wolfgang De Meuter
+
 ## Usage
 
 ### Option
@@ -105,14 +110,15 @@ Slug example
 
 ### Either
 Its main purpose here to handle errors gracefully, by chaining multiple calls in a functional way and stop evaluating them as soon as the first fails.
-Assume you need several calls to construct some object in order to be useful, after each you need to check for success. Also you want to catch exceptions and not let them bubble upwards.
+Assume you need several calls to construct some object in order to be useful, after each you need to check for success. Also you want to catch exceptions and not let them bubble upwards.  
+What is specific to this implementation is that exceptions are caught within the execution blocks. This way I have all error conditions wrapped in one place.
 
 `Success` represents a successfull execution of an operation (Right in Scala, Haskell).  
 `Failure` represents a failure to execute an operation (Left in Scala, Haskell).  
 
-The `Either()` wrapper will treat `nil`, `false` or `empty?` as a `Failure` and all others as `Success`.
+The `Either()` wrapper will treat all falsey values `nil`, `false` or `empty?` as a `Failure` and all others as `Success`. If that does not suit you, use `Success` or `Failure` only.
 
-    result = parse_and_validate_params(params).
+    result = parse_and_validate_params(params).                 # must return a Success or Failure inside
                 bind ->(user_id) { User.find(user_id) }.        # if #find returns null it will become a Failure
                 bind ->(user)    { authorized?(user); user }.   # if authorized? raises an Exception, it will be a Failure 
                 bind ->(user)    { UserDecorator(user) }
@@ -154,15 +160,62 @@ Exceptions are wrapped into a Failure:
 Another example:
 
     Success(params).
-      bind ->(params)   { Either(params.fetch(:path)) }
-      bind ->(path)     { load_stuff(params) }
+      bind ->(params)   { Either(params.fetch(:path)) }        # fails if params does not contain :path
+      bind ->(path)     { load_stuff(params)          }        # 
+
+Storing intermediate results in instance variables is possible, although it is not very elegant:
+
+    result = Either.chain do
+      bind { @map = { one: 1, two: 2 } }
+      bind { @map.fetch(:one) }
+      bind { |p| Success(p + 100) }
+    end
+
+    result == Success(101)
+
+
+### Validation 
+The Validation applicative functor, takes a list of checks within a block. Each check must return either Success of Failure.  
+If Successful, it will return Success, if not a Failure monad, containing a list of failures.  
+Within the Failure() provide the reason why the check failed.
+
+Example:
+
+    def validate(person)
+      check_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
+      }
+
+      check_sobriety = ->(sobriety) {
+        case sobriety
+        when :sober, :tipsy; Success(sobriety)
+        when :drunk        ; Failure('No drunks allowed')
+        else Failure("Sobriety state '#{sobriety}' is not allowed")
+        end 
+      }
+
+      check_gender = ->(gender) {
+        gender == :male || gender == :female ? Success(gender) : Failure("Invalid gender #{gender}")
+      }
+        
+      Validation() do
+        check { check_age.(person.age);          }
+        check { check_sobriety.(person.sobriety) }
+        check { check_gender.(person.gender)     }
+      end
+    end
 
 
 ## References
 
  * [Wikipedia Monad](See also http://en.wikipedia.org/wiki/Monad)
  * [Learn You a Haskell - for a few monads more](http://learnyouahaskell.com/for-a-few-monads-more)
- * [Monad equivalend in Ruby](http://stackoverflow.com/questions/2709361/monad-equivalent-in-ruby)
+ * [Monad equivalent in Ruby](http://stackoverflow.com/questions/2709361/monad-equivalent-in-ruby)
  * [Option Type ](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/)
  * [NullObject and Falsiness by @avdi](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/)
  * [andand](https://github.com/raganwald/andand/blob/master/README.textile)
@@ -172,8 +225,10 @@ Another example:
  * [Monads in Ruby with nice syntax](http://www.valuedlessons.com/2008/01/monads-in-ruby-with-nice-syntax.html)
  * [Maybe in Ruby](https://github.com/bhb/maybe)
  * [Monads on the Cheap](http://osteele.com/archives/2007/12/cheap-monads)
- * [Rumonade](https://github.com/ms-ati/rumonade)
+ * [Rumonade - another excellent (more scala-like) monad implementation](https://github.com/ms-ati/rumonade)
  * [Monads for functional programming](http://homepages.inf.ed.ac.uk/wadler/papers/marktoberdorf/baastad.pdf)
+ * [Monads as a theoretical foundation for AOP](http://soft.vub.ac.be/Publications/1997/vub-prog-tr-97-10.pdf)
+ * [What is an applicative functor?](http://applicative-errors-scala.googlecode.com/svn/artifacts/0.6/html/index.html)
 
 ## Installation
 

data/lib/monadic/either.rb

@@ -1,7 +1,5 @@
-# Chain various method calls 
+# Chain various method calls
 module Either
-  class NoEitherError < StandardError; end
-
   def self.chain(initial=nil, &block)
     Either::Chain.new(&block).call(initial)
   end
@@ -35,9 +33,8 @@ module Either
       Failure(ex)      
     end
   end
-  alias :>=     :bind
-  alias :+      :bind
-  alias :chain  :bind
+  alias :>=  :bind
+  alias :+   :bind
 
   def to_s
     "#{self.class.name}(#{@value.nil? ? 'nil' : @value.to_s})"
@@ -65,7 +62,6 @@ class Either::Chain
   def bind(proc=nil, &block)
     @chain << (proc || block)
   end
-  alias :chain :bind
 
 end
 

data/lib/monadic/errors.rb

@@ -1,4 +1,7 @@
 module Monadic
   # thrown by Option#fetch if it has no value and no default was provided
   class NoValueError < StandardError; end
+
+  # thrown when a Success or Failure was expected, but anything else was returned
+  class NotEitherError < StandardError; end 
 end

data/lib/monadic/validation.rb

@@ -0,0 +1,24 @@
+def Validation(&block)
+  Validation.new.call(&block)
+end
+
+# Conducts several function calls which do checks, of which each must return Success or Failure
+# and returns a list of all failures. 
+# Validation is not a monad, but an deemed an applicative functor
+class Validation
+  def initialize
+    @result = Success([])
+  end
+
+  def call(&block)
+    instance_eval(&block)
+  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
+  end
+end

data/lib/monadic/version.rb

@@ -1,3 +1,3 @@
 module Monadic
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/lib/monadic.rb

@@ -3,6 +3,7 @@ require 'monadic/version'
 require 'monadic/errors'
 require 'monadic/option'
 require 'monadic/either'
+require 'monadic/validation'
 
 module Monadic
 end

data/spec/either_spec.rb

@@ -34,6 +34,7 @@ describe 'Either' do
   end
 
   class User
+    attr :age, :gender, :sobriety
     def self.find(id)
       case id 
       when -1; raise 'invalid user id'
@@ -62,7 +63,7 @@ describe 'Either' do
 
   it 'works' do
     either = Either(true).
-              chain -> { User.find(-1) }
+              bind -> { User.find(-1) }
     either.failure?.should be_true
     RuntimeError.should === either.fetch
   end
@@ -191,4 +192,15 @@ describe 'Either' do
     either.should be_a_failure
     KeyError.should === either.fetch
   end
+
+  it 'instance variables' do
+    result = Either.chain do
+      bind { @map = { one: 1, two: 2 } }
+      bind { Success(100) }
+      bind { @map.fetch(:one) }
+      bind { |p| Success(p + 100) }
+    end
+
+    result.should == Success(101)
+  end
 end

data/spec/validation_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe 'Validation' do
+  Person = Struct.new(:age, :gender, :sobriety, :name)
+
+  it 'a projection of Success and Failure' do
+
+    def validate(person)
+      check_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
+      }
+
+      check_sobriety = ->(sobriety) {
+        case sobriety
+        when :sober, :tipsy; Success(sobriety)
+        when :drunk        ; Failure('No drunks allowed')
+        else Failure("Sobriety state '#{sobriety}' is not allowed")
+        end 
+      }
+
+      check_gender = ->(gender) {
+        gender == :male || gender == :female ? Success(gender) : Failure("Invalid gender #{gender}")
+      }
+        
+      Validation() do
+        check { check_age.(person.age);          }
+        check { check_sobriety.(person.sobriety) }
+        check { check_gender.(person.gender)     }
+      end
+    end
+
+    failure = validate(Person.new(age = 's', gender = :male, sobriety = :drunk, name = 'test'))
+    failure.should be_a Failure
+    failure.success?.should be_false
+    failure.failure?.should be_true
+    failure.should == Failure(["Age must be > 0", "No drunks allowed"])
+
+    success = validate(Person.new(age = 30, gender = :male, sobriety = :sober, name = 'test'))
+    success.should be_a Success
+    success.should == Success([])
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-01 00:00:00.000000000 Z
+date: 2012-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -126,11 +126,13 @@ files:
 - lib/monadic/either.rb
 - lib/monadic/errors.rb
 - lib/monadic/option.rb
+- lib/monadic/validation.rb
 - lib/monadic/version.rb
 - monadic.gemspec
 - spec/either_spec.rb
 - spec/option_spec.rb
 - spec/spec_helper.rb
+- spec/validation_spec.rb
 homepage: http://github.com/pzol/monadic
 licenses: []
 post_install_message: 
@@ -159,3 +161,4 @@ test_files:
 - spec/either_spec.rb
 - spec/option_spec.rb
 - spec/spec_helper.rb
+- spec/validation_spec.rb