monadic 0.0.3 → 0.0.4

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.0.4
+
+To be more idiomatic rubyuesque, rename `#value` to `#fetch`, which throws now an `NoValueError`.  
+Thanks to [@pithyless](https://twitter.com/#!/pithyless) for the suggestion.
+
+It now supports the Either monad, e.g.
+
+    either = Success(0).
+      bind { Success(1) }.
+      bind { Failure(2) }.
+      bind { Success(3) }
+
+    either == Failure(2)      # the third bind is NOT executed  
+
 ## v0.0.3
 
 `Some#map` and `Some#select` accept proc and block, you can now use:
@@ -9,3 +23,5 @@
     Option("FOO").downcase                  # old
 
 Removed `#none?`, please use `#empty?` instead.
+
+`Some` and `None` are now in the `Monadic` namespace, however they are aliased when requiring `monadic`

data/README.md

@@ -2,12 +2,12 @@
 
 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).
 
-See also http://en.wikipedia.org/wiki/Monad
+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:
 
-- Option (Maybe in Haskell)
-- Either *planned
+- Option (Maybe in Haskell) - Scala like with a rubyesque flavour
+- Either - more Haskell like
 
 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.
@@ -17,15 +17,14 @@ Thus you contain the erroneous behaviour within a monad - an indivisible, impene
 ### Option
 Is an optional type, which helps to handle error conditions gracefully. The one thing to remember about option is: 'What goes into the Option, stays in the Option'. 
 
-
-    Option(User.find(123)).name._         # ._ is a shortcut for .value 
+    Option(User.find(123)).name._         # ._ is a shortcut for .fetch 
 
     # if you prefer the alias Maybe instead of option
     Maybe(User.find(123)).name._
 
     # confidently diving into nested hashes
     Maybe({})[:a][:b][:c]                   == None
-    Maybe({})[:a][:b][:c].value('unknown')  == None
+    Maybe({})[:a][:b][:c].fetch('unknown')  == None
     Maybe(a: 1)[:a]._                       == 1
 
 Basic usage examples:
@@ -43,7 +42,7 @@ Basic usage examples:
 
     # Some stays Some, unless you unbox it
     Option('FOO').downcase       == Some('foo') 
-    Option('FOO').downcase.value == "foo"
+    Option('FOO').downcase.fetch == "foo"
     Option('FOO').downcase._     == "foo"
     Option('foo').empty?         == false
     Option('foo').truly?         == true
@@ -68,7 +67,7 @@ Falsey values (kind-of) examples:
     user = Option(User.find(123))
     user.name._
 
-    user.value('You are not logged in') { |user| "You are logged in as #{user.name}" }.should == 'You are logged in as foo'
+    user.fetch('You are not logged in') { |user| "You are logged in as #{user.name}" }.should == 'You are logged in as foo'
 
     if user != nil
       "You are logged in as foo"
@@ -77,7 +76,7 @@ Falsey values (kind-of) examples:
 
     user.subscribed?              # always true
     user.subscribed?.truly?       # true if subscribed is true
-    user.subscribed?.value(false) # same as above
+    user.subscribed?.fetch(false) # same as above
     user.subscribed?.or(false)    # same as above
 
 Remember! an Option is never false (in Ruby terms), if you want to know if it is false, call `#empty?` of `#truly?`
@@ -104,9 +103,65 @@ Slug example
       Option(title).strip.downcase.tr_s('^[a-z0-9]', '-')._('unknown-title')
     end
 
+### 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.
+
+`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`.
+
+    result = parse_and_validate_params(params).
+                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) }
+
+    if result.success?
+      @user = result.fetch                                      # result.fetch or result._ contains the 
+      render 'page'
+    else
+      @error = result.fetch
+      render 'error_page'
+    end
+
+You can use alternate syntaxes to achieve the same goal:
+
+    # block and Haskell like >= operator
+    Either(operation).
+      >= { successful_method }.
+      >= { failful_operation }
+
+    # start with a Success, for instance a parameter
+    Success('pzol').
+      bind ->(previous) { good }.
+      bind ->           { bad  }
+
+    Either.chain do
+      bind ->                   { good   }                     # >= is not supported for Either.chain, only bind
+      bind ->                   { better }                     # better returns Success(some_int)
+      bind ->(previous_result)  { previous_result + 1 }
+    end
+
+    either = Either(something)
+    either += truth? Success('truth, only the truth') : Failure('lies, damn lies')
+
+Exceptions are wrapped into a Failure:
+
+    Either(true).
+      bind -> { fail 'get me out of here' }                    # return a Failure(RuntimeError)
+
+Another example:
+
+    Success(params).
+      bind ->(params)   { Either(params.fetch(:path)) }
+      bind ->(path)     { load_stuff(params) }
+
 
-see also
+## 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)
  * [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/)

data/lib/monadic/either.rb

@@ -0,0 +1,97 @@
+# Chain various method calls 
+module Either
+  class NoEitherError < StandardError; end
+
+  def self.chain(initial=nil, &block)
+    Either::Chain.new(&block).call(initial)
+  end
+
+  def success?
+    is_a? Success
+  end
+
+  def failure?
+    is_a? Failure
+  end
+
+  def fetch(default=@value)
+    return default if failure?
+    return @value
+  end
+  alias :_     :fetch
+
+  def bind(proc=nil, &block)
+    return self if failure?
+
+    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
+  end
+  alias :>=     :bind
+  alias :+      :bind
+  alias :chain  :bind
+
+  def to_s
+    "#{self.class.name}(#{@value.nil? ? 'nil' : @value.to_s})"
+  end
+
+  def ==(other)
+    return false unless self.class === other
+    return other.fetch == @value
+  end
+
+end
+
+class Either::Chain
+  def initialize(&block)
+    @chain = []
+    instance_eval(&block)
+  end
+
+  def call(initial)
+    @chain.inject(Success(initial)) do |result, current|
+      result.bind(current)
+    end
+  end
+
+  def bind(proc=nil, &block)
+    @chain << (proc || block)
+  end
+  alias :chain :bind
+
+end
+
+class Success 
+  include Either
+  def initialize(value)
+    @value = value
+  end
+end
+
+class Failure 
+  include Either
+  def initialize(value)
+    @value = value
+  end
+end
+
+def Success(value)
+  Success.new(value)
+end
+
+def Failure(value)
+  Failure.new(value)
+end
+
+def Either(value)
+  return Failure(value) if value.nil? || (value.respond_to?(:empty?) && value.empty?) || !value
+  return Success(value)
+end

data/lib/monadic/errors.rb

@@ -0,0 +1,4 @@
+module Monadic
+  # thrown by Option#fetch if it has no value and no default was provided
+  class NoValueError < StandardError; end
+end

data/lib/monadic/option.rb

@@ -5,89 +5,97 @@ require 'singleton'
 # Helper function which returns Some or None respectively, depending on their value
 # I find this moar simplistic in ruby than the traditional #bind and #unit
 def Option(value)
-  return None if value.nil? || (value.respond_to?(:empty?) && value.empty?)
-  return Some.new(value)
+  return Monadic::None if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+  return Monadic::Some.new(value)
 end
 alias :Some  :Option
 alias :Maybe :Option
 
-# Represents the Option if there is some value available
-class Some
-  def initialize(value)
-    @value = value
-  end
-
-  def to_ary
-    return [@value].flatten if @value.respond_to? :flatten
-    return [@value]
-  end
-  alias :to_a :to_ary
-
-  def empty?
-    false
-  end
-
-  def truly?
-    @value == true
-  end
-
-  def value(default=None, &block)
-    return default if empty?
-    return block.call(@value)  if block_given?
-    return @value
-  end
-  alias :or :value
-  alias :_  :value
 
-  def map(func = nil, &block)
-    return Option(@value.map(&block)) if @value.is_a?(Enumerable)
-    return Option((func || block).call(@value))
-  end
-
-  def method_missing(m, *args)
-    Option(@value.__send__(m, *args))
-  end
-
-  def select(func = nil, &block)
-    return Option(@value.select(&block)) if @value.is_a?(Enumerable)
-    return None unless (func || block).call(@value)
-    return self
-  end
-
-  def ==(other)
-    return false unless other.is_a? Some
-    @value == other.instance_variable_get(:@value)
-  end
-
-  def to_s
-    "Some(#{@value.to_s})"
-  end
-end
+# Represents the Option if there is some value available
+module Monadic
+  class Some
+    def initialize(value)
+      @value = value
+    end
 
-# Represents the Option if there is no value available
-class None
-  class << self
     def to_ary
-      []
+      return [@value].flatten if @value.respond_to? :flatten
+      return [@value]
     end
     alias :to_a :to_ary
 
     def empty?
-      true
+      false
+    end
+
+    def truly?
+      @value == true
+    end
+
+    def fetch(default=None, &block)
+      return block.call(@value)  if block_given?
+      return @value
+    end
+    alias :or :fetch
+    alias :_  :fetch
+
+    def map(func = nil, &block)
+      return Option(@value.map(&block)) if @value.is_a?(Enumerable)
+      return Option((func || block).call(@value))
     end
 
     def method_missing(m, *args)
-      self
+      Option(@value.__send__(m, *args))
     end
 
-    def truly?
-      false
+    def select(func = nil, &block)
+      return Option(@value.select(&block)) if @value.is_a?(Enumerable)
+      return None unless (func || block).call(@value)
+      return self
     end
 
-    def value(default=self)
-      default
+    def to_s
+      "Some(#{@value.to_s})"
+    end
+
+    def ==(other)
+      return false unless other.is_a? Some
+      @value == other.instance_variable_get(:@value)
+    end    
+  end
+
+  # Represents the Option if there is no value available
+  class None
+    class << self
+      def to_ary
+        []
+      end
+      alias :to_a :to_ary
+
+      def empty?
+        true
+      end
+
+      def fetch(default=nil)
+        raise NoValueError if default.nil?
+        default
+      end
+      alias :or :fetch
+      alias :_  :fetch
+
+      def method_missing(m, *args)
+        self
+      end
+
+      def to_s
+        'None'
+      end
+
+      def truly?
+        false
+      end
+
     end
-    alias :or :value
-    alias :_  :value
   end
 end

data/lib/monadic/version.rb

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

data/lib/monadic.rb

@@ -1,5 +1,12 @@
 require 'monadic/version'
 
-$LOAD_PATH << File.expand_path('..', __FILE__)
-
+require 'monadic/errors'
 require 'monadic/option'
+require 'monadic/either'
+
+module Monadic
+end
+
+include Monadic
+None = Monadic::None
+Some = Monadic::Some

data/spec/either_spec.rb

@@ -0,0 +1,194 @@
+require 'spec_helper'
+
+describe 'Either' do
+  it 'Success and Failure should be kind of Either' do
+    Success.new(0).should be_kind_of(Either)
+    Failure.new(0).should be_kind_of(Either)
+  end
+
+  it '#to_s works' do
+    Success.new("it worked!").to_s.should == "Success(it worked!)"
+    Failure.new(nil).to_s.should == "Failure(nil)"
+  end
+
+  it 'allows to verify equality' do
+    Success(1).should == Success(1)
+    Success(2).should_not == Success(1)
+    Success(1).should_not == Failure(1)
+    Failure(1).should == Failure(1)
+    Failure(1).should_not == Failure(2)
+  end
+
+  it 'wraps a nil result to Failure' do
+    Success(nil).bind { nil }.should == Failure(nil)
+  end
+
+  it 'catches exceptions and returns them as Failure' do
+    either = Success(nil).
+      bind { raise 'error' }
+
+    either.should be_kind_of Failure
+    error = either.fetch
+    error.should be_kind_of RuntimeError
+    error.message.should == 'error'
+  end
+
+  class User
+    def self.find(id)
+      case id 
+      when -1; raise 'invalid user id'
+      when  0; nil
+      else User.new(id)
+      end
+    end
+
+    attr_reader :name
+    def initialize(id)
+      @name = "User #{id}"
+    end
+  end
+
+  it 'Either(nil || false) returns a Failure' do
+    Either(nil).should == Failure(nil)
+    Either(false).should == Failure(false)
+    Failure.should === Either(nil)
+  end
+
+  it 'Either with a non-falsey value returns success' do
+    Success.should === Either(1)
+    Success.should === Either(true)
+    Success.should === Either("string")
+  end
+
+  it 'works' do
+    either = Either(true).
+              chain -> { User.find(-1) }
+    either.failure?.should be_true
+    RuntimeError.should === either.fetch
+  end
+
+  it 'does NOT call subsequent binds on Failure and returns the first Failure in the end' do
+    either = Success(0).
+      bind { Failure(1) }.
+      bind { Failure(2) }.
+      bind { Success(3) }
+
+    either.should == Failure(1)
+  end
+
+  it 'returns the last Success' do
+    either = Success(nil).
+      bind { Success(1) }.
+      bind { Success(2) }
+
+    either.should == Success(2)
+  end
+
+  it 'allows to #fetch the value of the Success or Failure' do
+    Failure(1).fetch.should == 1
+    Success(2).fetch.should == 2
+  end
+
+  it 'allows to #fetch the value with a default if it failed' do
+    Failure(1).fetch(2).should == 2
+    Success(1).fetch(2).should == 1
+  end
+
+  it 'works with pattern matching (kind of)' do
+    either = Success('ok')
+
+    matched = case either
+    when Success; "yeah: #{either.fetch}"
+    when Failure; "oh no: #{either.fetch}"
+    end
+
+    matched.should == "yeah: ok"
+  end
+
+  it 'allows Haskell like syntax' do
+    either = Success(1).
+      >= { Success(2) }
+
+    either.should == Success(2)
+  end
+
+  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 + 100) }  # lambda/proc
+
+    either.should == Success(102)
+  end
+
+  it 'returns the boxed value with the #_ alias for #fetch' do
+    Failure(99)._.should == 99
+  end
+
+  it 'allows you to use parameterless lambdas (#arity == 0)' do
+    (Success(0) >= 
+      -> { Success(1) }
+    ).should == Success(1)
+  end
+
+  it 'allows you to use lambdas with the + operator' do
+    either = Success(0) +
+      -> { Success(1) } +
+      -> { Success(2) }
+
+    either.should == Success(2)
+  end
+
+  it 'allows you to use +=' do
+    either = Success(0)
+    either += -> { Success(1) }
+
+    either.should == Success(1)
+  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
+
+    Failure(2).success?.should be_false
+    Failure(3).failure?.should be_true
+  end
+
+  it 'supprts Either.chain' do
+    Either.chain do 
+      bind -> { Success(1) }
+      bind -> { Success(2) }
+    end.should == Success(2)
+
+    Either.chain do 
+      bind ->    { Success(1)     }
+      bind ->(p) { Success(p + 1) }
+    end.should == Success(2)
+
+    Either.chain do
+      bind { Success(1) }
+    end.should == Success(1)
+  end
+
+  it 'README example' do
+    params = { :path => 'foo' }
+    def load_file(path); 
+      fail "invalid path" unless path
+      Success("bar"); 
+    end
+    def process_content(content); content.start_with?('b') ? Success(content.upcase) : Failure('invalid content'); end
+
+    either = Either(true).
+              bind {          params.fetch(:path)      }.
+              bind {|path|    load_file(path)          }.
+              bind {|content| process_content(content) }
+    either.should be_a_success
+    either.fetch.should == 'BAR'
+
+    either = Either(true).
+              bind {          {}.fetch(:path)          }.
+              bind {|path|    load_file(path)          }.
+              bind {|content| process_content(content) }
+    either.should be_a_failure
+    KeyError.should === either.fetch
+  end
+end

data/spec/option_spec.rb

@@ -6,7 +6,7 @@ describe 'Option' do
   end
 
   it 'None stays None' do
-    Option(nil)._.should == None
+    expect { Option(nil)._ }.to raise_error Monadic::NoValueError
     Option(nil).empty?.should be_true
   end
 
@@ -22,7 +22,6 @@ describe 'Option' do
   it 'None#to_s is "None"' do
     option = Option(nil)
     "#{option}".should   == "None"
-    "#{option._}".should == "None"
   end
 
   it 'None is always empty' do
@@ -38,24 +37,24 @@ describe 'Option' do
     Option('FOO').downcase.should == Some('foo')
   end
 
-  it 'returns the value of an option' do 
-    Option('foo').value.should == 'foo'
+  it '#fetch returns the value of an option' do 
+    Option('foo').fetch.should == 'foo'
     Option('foo')._.should == 'foo'
   end
 
   it 'returns the value of an option with a default, in case value is None' do
-    Option(nil).value('bar').should == 'bar'
+    Option(nil).fetch('bar').should == 'bar'
     Option(nil)._('bar').should == 'bar'
   end
 
   it 'returns the value and not the default if it is Some' do
-    Option('FOO').downcase.value('bar').should == 'foo'
+    Option('FOO').downcase.fetch('bar').should == 'foo'
     Option('FOO').downcase._('bar').should == 'foo'
   end
 
   it 'returns the value applied to a block if it is Some' do
-    Option('foo').value('bar') { |val| "You are logged in as #{val}" }.should == 'You are logged in as foo'
-    Option(nil).value('You are not logged in') { |val| "You are logged in as #{val}" }.should == 'You are not logged in'
+    Option('foo').fetch('bar') { |val| "You are logged in as #{val}" }.should == 'You are logged in as foo'
+    Option(nil).fetch('You are not logged in') { |val| "You are logged in as #{val}" }.should == 'You are not logged in'
   end
 
   it 'is never falsey' do
@@ -73,9 +72,9 @@ describe 'Option' do
     end
   end
 
-  it 'allows to use a block with value and _' do
+  it 'allows to use a block with fetch and _' do
     user = Option(User.new('foo'))
-    user.value('You are not logged in') { |user| "You are logged in as #{user.name}" }.should == 'You are logged in as foo'
+    user.fetch('You are not logged in') { |user| "You are logged in as #{user.name}" }.should == 'You are logged in as foo'
   end
 
   it 'handles (kind-of) falsey values' do
@@ -120,12 +119,11 @@ describe 'Option' do
       select {|d| d.month == 3}.    # filters out non-matching Date values (Some becomes None)
       map(&:to_s).                  # transforms a contained Date value into a String value
       map {|s| s.gsub('-', '')}.    # transforms a contained String value by removing '-'
-      value("not in march!")        # returns the contained value, or the alternative if None
+      fetch("not in march!")        # returns the contained value, or the alternative if None
     end
 
     format_date_in_march(nil).should == "not in march!"
     format_date_in_march(Time.parse('2009-01-01 01:02')).should == "not in march!"
     format_date_in_march(Time.parse('2011-03-21 12:34')).should == "20110321"    
-end
-
+  end
 end

data/spec/spec_helper.rb

@@ -1,4 +1,5 @@
 require 'bundler/setup'
 Bundler.require(:default, :test)
 
+$LOAD_PATH << File.expand_path('../../lib', __FILE__)
 require File.expand_path('../../lib/monadic', __FILE__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-30 00:00:00.000000000 Z
+date: 2012-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -123,9 +123,12 @@ files:
 - README.md
 - Rakefile
 - lib/monadic.rb
+- lib/monadic/either.rb
+- lib/monadic/errors.rb
 - lib/monadic/option.rb
 - lib/monadic/version.rb
 - monadic.gemspec
+- spec/either_spec.rb
 - spec/option_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/pzol/monadic
@@ -153,5 +156,6 @@ signing_key:
 specification_version: 3
 summary: see README
 test_files:
+- spec/either_spec.rb
 - spec/option_spec.rb
 - spec/spec_helper.rb