monadic 0.4.0 → 0.5.0

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.5.0
+
+Add the `Try` helper which works similar to Either, but takes a block
+
+    Try { Date.parse('2012-02-30') }       == Failure
+    Try { Date.parse('2012-02-28') }       == Success
+
+`Either` else now supports also a block
+
+    Failure(1).else {|other| 1 + 2 }       == Failure(3)
+
 ## v0.4.0
 `#or` returns for Nothing an alternative
 

data/Guardfile

@@ -8,6 +8,7 @@ end
 
 guard 'rspec', :version => 2 do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch(%r{^lib/monadic/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/monadic.rb$})           { "spec" }
+  watch('spec/spec_helper.rb')          { "spec" }
 end

data/README.md

@@ -1,9 +1,9 @@
 # Monadic
-[![Build Status](https://secure.travis-ci.org/pzol/monadic.png?branch=master)](http://travis-ci.org/pzol/monadic) 
+[![Build Status](https://secure.travis-ci.org/pzol/monadic.png?branch=master)](http://travis-ci.org/pzol/monadic) [![endorse](http://api.coderwall.com/pzol/endorsecount.png)](http://coderwall.com/pzol)
 
 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/) and [Haskell](http://www.haskell.org/) to my ruby projects.
 
-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"). 
+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 (monads, functors, applicatives and variations):
 
@@ -13,7 +13,7 @@ We have the following monadics (monads, functors, applicatives and variations):
 
 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. Functional programming considers _throwing_ exceptions to be a side-effect, instead we _propagate_ exceptions, i.e. return them as a result of a function call.
- 
+
 A monad is most effectively described as a computation that eventually returns a value. -- Wolfgang De Meuter
 
 ## Usage
@@ -50,7 +50,7 @@ Maybe(nil).empty?           == true
 Maybe(nil).truly?           == false
 
 # Just stays Just, unless you unbox it
-Maybe('FOO').downcase       == Just('foo') 
+Maybe('FOO').downcase       == Just('foo')
 Maybe('FOO').downcase.fetch == "foo"          # unboxing the value
 Maybe('FOO').downcase._     == "foo"          
 Maybe('foo').empty?         == false          # always non-empty
@@ -92,6 +92,7 @@ Maybe(1).to_s             == '1'
 `#or`
 Maybe(nil).or(1)          == 1
 Maybe(1).or(2)            == 1
+Maybe(nil).or(nil)        == Just(nil)
 
 Falsey values (kind-of) examples:
 
@@ -214,6 +215,12 @@ Either(false == true).else('false was not true')          == Failure(false was n
 Success('truth needs no sugar coating').else('all lies')  == Success('truth needs no sugar coating')
 ```
 
+`Either#else` supports also a block
+
+```ruby
+Failure(1).else {|other| 1 + 2 }                          == Failure(3)
+```
+
 Storing intermediate results in instance variables is possible, although it is not very elegant:
 
 ```ruby
@@ -224,9 +231,20 @@ result = Either.chain do
 end
 
 result == Success(101)
-```    
+```  
+
+#### Try
+
+`Try` helper which works similar to Either, but takes a block
+
+```ruby
+Try { Date.parse('2012-02-30') }                                        == Failure
+Try { Date.parse('2012-02-28') }                                        == Success
+Try { Date.parse('2012-02-30') }.else {|e| "Exception: #{e.message}" }  == Failure("Exception: invalid date")
+```
+
 
-### Validation 
+### 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.
@@ -237,7 +255,7 @@ Example:
 def validate(person)
   check_age = ->(age_expr) {
     age = age_expr.to_i
-    case 
+    case
     when age <=  0; Failure('Age must be > 0')
     when age > 130; Failure('Age must be < 130')
     else Success(age)
@@ -266,16 +284,16 @@ end
 
 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 [examples/validation.rb](https://github.com/pzol/monadic/blob/master/examples/validation.rb) and [examples/validation_module](https://github.com/pzol/monadic/blob/master/examples/validation_module.rb) 
+See also [examples/validation.rb](https://github.com/pzol/monadic/blob/master/examples/validation.rb) and [examples/validation_module](https://github.com/pzol/monadic/blob/master/examples/validation_module.rb)  
 
-### Monad 
+### Monad
 All Monads include this module. Standalone it is an Identity monad. Not useful on its own. It's methods are usable on all its descendants.
 
 __#map__ is used to map the inner value
 
 ```ruby
 # minimum implementation of a monad
-class Identity 
+class Identity
   include Monadic::Monad
   def self.unit(value)
     new(value)

data/examples/validation.rb

@@ -5,7 +5,7 @@ class AgeTooHighError < ArgumentError; end
 
 valid_age = ->(age_expr) {
   age = age_expr.to_i
-  case 
+  case
   when age <=  0; Failure(AgeTooLowError.new(age_expr))
   when age > 130; Failure(AgeTooHighError.new(age_expr))
   else Success(age)
@@ -13,7 +13,7 @@ valid_age = ->(age_expr) {
 }
 
 valid_name = ->(name) {
-  case 
+  case
   when name =~ /\w{3,99}/i; Success(name)
   else Failure('Invalid name')
   end

data/lib/monadic/either.rb

@@ -1,6 +1,6 @@
 module Monadic
   # @abstract Chains function calls and stops executing if one of them fails.
-  class Either 
+  class Either
     include Monadic::Monad
     def self.chain(initial=nil, &block)
       Either::Chain.new(&block).call(initial)
@@ -12,11 +12,11 @@ module Monadic
       return Success.new(value)
     end
 
-    # Initialize is private, because it always would return an instance of Either, but Success or Failure 
+    # Initialize is private, because it always would return an instance of Either, but Success or Failure
     # are required (Either is abstract).
     private_class_method :new
 
-    # Allows privileged access to the +Either+'s inner value from within a block. 
+    # 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)
@@ -26,15 +26,16 @@ module Monadic
       begin
         Either(call(proc, block))
       rescue StandardError => error
-        Failure(error)      
+        Failure(error)
       end
     end
     alias :>=  :bind
     alias :+   :bind
 
     # If it is a Failure it will return a new Failure with the provided value
-    # @return [Success, Failure] 
-    def else(value)
+    # @return [Success, Failure]
+    def else(value=nil, &block)
+      return Failure(block.call(@value)) if failure? && block_given?
       return Failure(value) if failure?
       return self
     end
@@ -53,7 +54,7 @@ module Monadic
       is_a? Failure
     end
 
-    private 
+    private
     def call(proc=nil, block)
       func = (proc || block)
       raise "No block or lambda given" unless func.is_a? Proc
@@ -99,7 +100,7 @@ module Monadic
     module InstanceMethods
       def initialize(value)
         @value = join(value)
-      end 
+      end
     end
   end
 
@@ -115,7 +116,7 @@ module Monadic
     Failure.new(value)
   end
 
-  # Factory method 
+  # Factory method
   # @return [Success]
   def Success(value)
     Success.new(value)

data/lib/monadic/maybe.rb

@@ -24,6 +24,7 @@ module Monadic
       return self
     end
 
+    # @return [true, false] true if the underlying value is true
     def truly?
       @value == true
     end
@@ -33,6 +34,7 @@ module Monadic
   class Just < Maybe
     public_class_method :new
 
+    # @return the underlying value
     def fetch(default=nil)
       @value
     end
@@ -42,13 +44,10 @@ module Monadic
       Maybe(@value.__send__(m, *args))
     end
 
+    # @return always self for Just
     def or(other)
       self
     end
-
-    def to_s
-      @value.to_s
-    end
   end
 
   # Represents a NullObject
@@ -56,6 +55,7 @@ module Monadic
     class << self
       undef name
 
+      # @return the default value passed
       def fetch(default=nil)
         return self if default.nil?
         return default
@@ -66,10 +66,15 @@ module Monadic
         self
       end
 
+      # @return an alternative value, the passed value is NOT coerced into Maybe, thus Nothing.or(nil) will be Just(nil)
       def or(other)
-        Maybe(other)
+        Just.new(other)
       end
 
+      # def respond_to?
+
+      # end
+
       def to_ary
         []
       end

data/lib/monadic/monad.rb

@@ -45,7 +45,7 @@ module Monadic
     # Return the string representation of the Monad
     def to_s
       pretty_class_name = self.class.name.split('::')[-1]
-      "#{pretty_class_name}(#{@value.nil? ? 'nil' : @value.to_s})"
+      "#{pretty_class_name}(#{self.fetch.inspect})"
     end
 
     def ==(other)

data/lib/monadic/try.rb

@@ -0,0 +1,10 @@
+module Monadic
+  def Try(proc = nil, &block)
+    begin
+      return Either(proc) unless proc.nil? || proc.is_a?(Proc)
+      return Either((proc || block).call)
+    rescue => error
+      Failure(error)
+    end
+  end
+end

data/lib/monadic/version.rb

@@ -1,3 +1,3 @@
 module Monadic
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/monadic.rb

@@ -4,6 +4,7 @@ require 'monadic/errors'
 require 'monadic/monad'
 require 'monadic/maybe'
 require 'monadic/either'
+require 'monadic/try'
 require 'monadic/validation'
 
 include Monadic

data/spec/either_spec.rb

@@ -16,7 +16,7 @@ describe Monadic::Either do
   it 'Failure.new and Failure.unit and Failure() return the same' do
     Failure(1).should == Failure.unit(1)
     Failure.new(1).should == Failure.unit(1)
-    
+
     Failure(nil).should == Failure.unit(nil)
     Failure.new(nil).should == Failure.unit(nil)
   end
@@ -27,7 +27,7 @@ describe Monadic::Either do
   end
 
   it '#to_s works' do
-    Success.unit("it worked!").to_s.should == "Success(it worked!)"
+    Success.unit("it worked!").to_s.should == 'Success("it worked!")'
     Failure.unit(nil).to_s.should == "Failure(nil)"
   end
 
@@ -56,15 +56,20 @@ describe Monadic::Either do
   it '#else returns an alternative value considered Success if it is Nothing' do
     Failure(false).else(true).should == Failure(true)
     Either(nil).else(true).should == Failure(true)
+    Failure(1).else(nil).should == Failure(nil)
     Success(true).else(false).should == Success(true)
     Either(true).else(false).should == Success(true)
     Success(false).else(true).should == Success(false)
   end
 
+  it '#else with a block gets the original value passed' do
+    (Failure(1).else { |other| other + 1 }).should == Failure(2)
+  end
+
   class User
     attr :age, :gender, :sobriety
     def self.find(id)
-      case id 
+      case id
       when -1; raise 'invalid user id'
       when  0; nil
       else User.new(id)
@@ -149,7 +154,7 @@ describe Monadic::Either do
 
   it 'passes the result value from the previous call to the next' do
     either = Success(1).
-      >= {|prev| Success(prev + 1) }.     # a block 
+      >= {|prev| Success(prev + 1) }.     # a block
       >= -> prev { Success(prev + 100) }  # lambda/proc
 
     either.should == Success(102)
@@ -160,7 +165,7 @@ describe Monadic::Either do
   end
 
   it 'allows you to use parameterless lambdas (#arity == 0)' do
-    (Success(0) >= 
+    (Success(0) >=
       -> { Success(1) }
     ).should == Success(1)
   end
@@ -198,12 +203,12 @@ describe Monadic::Either do
   end
 
   it 'supports Either.chain' do
-    Either.chain do 
+    Either.chain do
       bind -> { Success(1) }
       bind -> { Success(2) }
     end.should == Success(2)
 
-    Either.chain do 
+    Either.chain do
       bind ->    { Success(1)     }
       bind ->(p) { Success(p + 1) }
     end.should == Success(2)
@@ -215,9 +220,9 @@ describe Monadic::Either do
 
   it 'README example' do
     params = { :path => 'foo' }
-    def load_file(path); 
+    def load_file(path);
       fail "invalid path" unless path
-      Success("bar"); 
+      Success("bar");
     end
     def process_content(content); content.start_with?('b') ? Success(content.upcase) : Failure('invalid content'); end
 

data/spec/examples/applicative_spec.rb

@@ -10,11 +10,11 @@ module Applicative
   alias :<< :apply
 end
 
-class Maybe
+class Monadic::Just
   include Applicative
 end
 
-class Either
+class Monadic::Either
   include Applicative
 end
 

data/spec/examples/hotel_booking_spec.rb

@@ -0,0 +1,133 @@
+require 'spec_helper'
+require 'active_support/time'
+
+describe 'Hotel Booking Example' do
+
+  class Request < Struct
+    def self.create(params, params_module)
+      value = self.create_value(params || {}, params_module)
+
+      if value.values.all?(&:success?)
+        Success(value)
+      else
+        Failure(value)
+      end
+    end
+
+    def to_hash
+      Hash[*members.zip(values).flatten]
+    end
+
+    def unwrap
+      Struct.new(*members).new(*values.map(&:fetch))
+      # self.class.new(*values.map(&:fetch))
+    end
+
+    private
+    def self.create_value(params, params_module)
+      properties = params_module.methods - Module.methods
+      request_klas = self.new(*properties)
+      properties.reduce(request_klas.new) do |request, property|
+        request[property] = params_module.send(property, params)
+        request
+      end
+    end
+  end
+
+  module HotelBookingRequestParams
+    extend self
+
+    def hotel_code(params)
+      value = params['hotel_code']
+      case
+      when value.nil?
+        Failure('hotel_code must not be empty')
+      when not(value =~ /^[A-Z]{3}[A-Z0-9]{4}$/)
+        Failure('hotel_code must be of pattern XXX0001')
+      else
+        Success(value)
+      end
+    end
+
+    def nights(params)
+      value = params.fetch('nights', 0).to_i
+      if value <= 0
+        Failure("nights must be a number greater than 0 (got '#{params['nights']}')")
+      else
+        Success(value)
+      end
+    end
+
+    VALID_ROOM_TYPE = %w[SR DR TR QR]
+    def room_type(params)
+      case value = params['room_type']
+      when nil
+        Failure('room_type must not be empty')
+      when is_valid_room_type
+        Success(value)
+      else
+        Failure("room_type '#{value}' must be one of #{VALID_ROOM_TYPE.join(', ')}")
+      end
+    end
+
+    def check_in(params)
+      param = params['check_in']
+      return Failure("check_in must not be empty")    if param.nil?
+      return Try { Date.parse(param) }.else {|e| "check_in #{e.message} '#{param}'" }
+    end
+
+    private
+    def is_valid_room_type
+      Object.new.tap {|matcher|
+        def matcher.===(value)
+          VALID_ROOM_TYPE.include? value
+        end
+      }
+    end
+  end
+
+  let(:params_proto) do
+    {'hotel_code'  => 'STO0001',
+     'check_in'    => '2012-06-15',
+     'nights'      => '3',
+     'room_type'   => 'DR',
+     'guest1'      => 'Max Payne',
+     'guest2'      => 'Jenny Payne'}
+  end
+
+  it 'builds a valid request' do
+    result = Request.create(params_proto, HotelBookingRequestParams)
+    result.should be_a Success
+    request = result.fetch.unwrap
+    request.hotel_code.should eq "STO0001"
+    request.nights.should eq 3
+  end
+
+  it 'reports an invalid room_type' do
+    params = params_proto.merge 'room_type' => 'XX'
+    result = Request.create(params, HotelBookingRequestParams)
+    result.should be_a Failure
+    request = result.fetch
+    request.room_type.should be_a Failure
+  end
+
+  it 'reports an invalid check_in time' do
+    params = params_proto.merge 'check_in' => '2012-11-31'
+    result = Request.create(params, HotelBookingRequestParams)
+    result.should be_a Failure
+    request = result.fetch
+    request.check_in.should be_a Failure
+    request.check_in.should == Failure("check_in invalid date '2012-11-31'")
+  end
+
+  it 'builds a failure request with no params' do
+    result = Request.create(nil, HotelBookingRequestParams)
+    result.should be_a Failure
+    request = result.fetch
+    request.hotel_code.should be_a Failure
+    request.nights.should be_a Failure
+    request.room_type.should be_a Failure
+    request.check_in.should be_a Failure
+  end
+
+end

data/spec/maybe_spec.rb

@@ -69,11 +69,21 @@ describe Monadic::Maybe do
     end
 
     it 'Just#to_s is "value"' do
-      Just.unit(123).to_s.should == "123"
+      Just.unit(123).to_s.should == "Just(123)"
     end
 
     it 'Just#or return self' do
-      Maybe(1).or(2).should == Just(1)
+      Maybe(1).or(2).should              == Just(1)
+      Maybe(nil).or(nil).should          == Just.new(nil)
+      Maybe(nil).something.or('').fetch.should == ''
+    end
+
+    it 'Just#inspect returns Just(value)' do
+      Just(1).inspect.should == 'Just(1)'
+    end
+
+    it 'works with method_missing !caution! with Monad.methods like #join' do
+      Maybe([1, 2]).join(' ').should == ' '
     end
 
   end

data/spec/try_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe 'Monadic::Try' do
+  it 'catches exceptions' do
+    Try { Date.parse('2012-02-30') }.should be_a Failure
+  end
+
+  it 'returns Failure when the value is nil or false' do
+    Try { nil }.should be_a Failure
+    Try { false }.should be_a Failure
+  end
+
+  it 'returns Failure for an empty collection' do
+    Try { [] }.should be_a Failure
+  end
+
+  it 'without a block it works like Either' do
+    Try(true).should be_a Success
+    Try(false).should be_a Failure
+    Try(nil).should be_a Failure
+  end
+
+  it 'with a proc' do
+    pending
+  end
+
+  it 'returns Success for non-nil values' do
+    Try { 1 }.should == Success(1)
+    Try { "string" }.should == Success("string")
+  end
+
+  it 'combined with else and a block' do
+    Try { Date.parse('2012-02-30') }.else {|e| "Exception: #{e.message}" }.should == Failure("Exception: invalid date")
+    Try { Date.parse('2012-02-28') }.else {|e| "Exception: #{e.message}" }.should == Success(Date.parse('2012-02-28'))
+  end
+end

data/spec/validation_spec.rb

@@ -8,7 +8,7 @@ describe Monadic::Validation do
     def validate(person)
       check_age = ->(age_expr) {
         age = age_expr.to_i
-        case 
+        case
         when age <=  0; Failure('Age must be > 0')
         when age > 130; Failure('Age must be < 130')
         else Success(age)
@@ -20,13 +20,13 @@ describe Monadic::Validation do
         when :sober, :tipsy; Success(sobriety)
         when :drunk        ; Failure('No drunks allowed')
         else Failure("Sobriety state '#{sobriety}' is not allowed")
-        end 
+        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) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-29 00:00:00.000000000 Z
+date: 2012-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -147,17 +147,20 @@ files:
 - lib/monadic/errors.rb
 - lib/monadic/maybe.rb
 - lib/monadic/monad.rb
+- lib/monadic/try.rb
 - lib/monadic/validation.rb
 - lib/monadic/version.rb
 - monadic.gemspec
 - spec/core_ext/object_spec.rb
 - spec/either_spec.rb
 - spec/examples/applicative_spec.rb
+- spec/examples/hotel_booking_spec.rb
 - spec/jruby_fixes.rb
 - spec/maybe_spec.rb
 - spec/monad_axioms.rb
 - spec/monad_spec.rb
 - spec/spec_helper.rb
+- spec/try_spec.rb
 - spec/validation_spec.rb
 homepage: http://github.com/pzol/monadic
 licenses: []
@@ -173,7 +176,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4582123822322674017
+      hash: 44748107420070269
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -182,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4582123822322674017
+      hash: 44748107420070269
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -193,9 +196,11 @@ test_files:
 - spec/core_ext/object_spec.rb
 - spec/either_spec.rb
 - spec/examples/applicative_spec.rb
+- spec/examples/hotel_booking_spec.rb
 - spec/jruby_fixes.rb
 - spec/maybe_spec.rb
 - spec/monad_axioms.rb
 - spec/monad_spec.rb
 - spec/spec_helper.rb
+- spec/try_spec.rb
 - spec/validation_spec.rb