monadic 0.0.6 → 0.0.7

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.0.7 
+
+Implements the #map method for all Monads. It works on value types and on Enumerable collections.  
+Provide a proc or a block and it will return a transformed value or collection boxed back in the monad.
+
+    Monad.unit('FOO').map(&:capitalize).map {|v| "Hello #{v}"}    == Monad(Hello Foo)
+
+Add the Elvis operator _? - ruby does not allow ?: as operator and use it like the excellent [andand](https://github.com/raganwald/andand)
+
+    nil._?           == Nothing
+    "foo"._?         == 'foo'
+    {}._?.a.b        == Nothing
+    {}._?[:foo]      == Nothing
+
 ## v0.0.6
 **Contains Breaking Changes**
 

data/README.md

@@ -1,4 +1,5 @@
 # Monadic
+[![Build Status](https://secure.travis-ci.org/pzol/monadic.png?branch=master)](http://travis-ci.org/pzol/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](http://www.scala-lang.org/) and [Haskell](http://www.haskell.org/) to my ruby projects.
 
@@ -18,9 +19,11 @@ A monad is most effectively described as a computation that eventually returns a
 ## Usage
 
 ### Maybe
-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'. 
+Most people probably will be interested in the Maybe monad, as it solves the problem with nil invocations, similar to [andand](https://github.com/raganwald/andand) and others.
 
-    Option(User.find(123)).name._         # ._ is a shortcut for .fetch 
+Maybe is an optional type, which helps to handle error conditions gracefully. The one thing to remember about option is: 'What goes into the Maybe, stays in the Maybe'. 
+
+    Maybe(User.find(123)).name._         # ._ is a shortcut for .fetch 
 
     # if you prefer the alias Maybe instead of option
     Maybe(User.find(123)).name._
@@ -76,7 +79,7 @@ Falsey values (kind-of) examples:
     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?`
+Remember! a Maybe is never false (in Ruby terms), if you want to know if it is false, call `#empty?` of `#truly?`
 
 `#truly?` will return true or false, always.
 
@@ -100,6 +103,17 @@ Slug example
       Maybe(title).strip.downcase.tr_s('^[a-z0-9]', '-')._('unknown-title')
     end
 
+### Object#_?
+Works similar to the Elvis operator _? - ruby does not allow ?: as operator and use it like the excellent [andand](https://github.com/raganwald/andand)
+
+    require 'monadic/core_ext/object'   # this will import _? into the global Object
+    nil._?           == Nothing
+    "foo"._?         == 'foo'
+    {}._?.a.b        == Nothing
+    {}._?[:foo]      == Nothing
+
+In fact this is a shortcut notation for `Maybe(obj)`
+
 ### 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.  
@@ -202,6 +216,29 @@ 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.
+
+### 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.
+
+__#map__ is used to map the inner value
+
+    Monad.unit('FOO').map(&:capitalize).map {|v| "Hello #{v}"}    == Monad(Hello Foo)
+    Monad.unit([1,2]).map {|v| v + 1}                             == Monad([2, 3])
+
+__#bind__ allows (priviledged) access to the boxed value. This is the traditional _no-magic_ `#bind` as found in Haskell, 
+You are responsible for re-wrapping the value into a Monad again.
+  
+    # due to the way it works, it will simply return the value, don't rely on this though, different Monads may
+    # implement bind differently (e.g. Maybe involves some _magic_)
+    Monad.unit('foo').bind(&:capitalize)                          == Foo
+
+    # proper use
+    Monad.unit('foo').bind {|v| Monad.unit(v.capitalize) }        == Monad(Foo)
+
+__#fetch__ extracts the inner value of the Monad, some Monads will override this standard behaviour, e.g. the Maybe Monad
+
+    Monad.unit('foo').fetch                                       == "foo"
 
 ## References
 
@@ -239,7 +276,6 @@ Or install it yourself as:
 ## Compatibility
 Monadic is tested under ruby MRI 1.9.2, 1.9.3, jruby 1.9 mode, rbx 1.9 mode.
 
-See the build status [![Build Status](https://secure.travis-ci.org/pzol/monadic.png?branch=master)](http://travis-ci.org/pzol/monadic) 
 
 ## Contributing
 

data/lib/monadic/core_ext/object.rb

@@ -0,0 +1,5 @@
+class Object
+  def _?
+    Maybe(self).fetch(nil)
+  end
+end

data/lib/monadic/either.rb

@@ -12,9 +12,7 @@ module Monadic
 
     # Initialize is private, because it always would return an instance of Either, but Success or Failure 
     # are required (Either is abstract).
-    def initialize(value)
-      raise NoMethodError, "private method `new' called for #{self.class.name}, use `unit' instead"
-    end
+    private_class_method :new
 
     def success?
       is_a? Success
@@ -68,6 +66,13 @@ module Monadic
 
   # @private instance and class methods for Success and Failure
   module SuccessFailure
+    def self.included(base)
+      base.class_eval do
+        public_class_method :new
+        extend  ClassMethods
+        include InstanceMethods
+      end
+    end
     module ClassMethods
       def unit(value)
         new(value)
@@ -81,13 +86,11 @@ module Monadic
   end
 
   class Success < Either
-    extend  SuccessFailure::ClassMethods
-    include SuccessFailure::InstanceMethods
+    include SuccessFailure
   end
 
   class Failure < Either
-    extend  SuccessFailure::ClassMethods
-    include SuccessFailure::InstanceMethods
+    include SuccessFailure
   end
 
   def Failure(value)

data/lib/monadic/maybe.rb

@@ -1,21 +1,5 @@
 module Monadic
-  # @api private helps treating `Maybe` like Either in Scala
-  module ScalaStuff
-    def map(proc = nil, &block)
-      return Maybe(@value.map(&block)) if @value.is_a?(Enumerable)
-      return Maybe((proc || block).call(@value))
-    end
-
-    def select(proc = nil, &block)
-      return Maybe(@value.select(&block)) if @value.is_a?(Enumerable)
-      return Nothing unless (proc || block).call(@value)
-      return self
-    end
-  end
-
   class Maybe < Monad
-    include ScalaStuff
-
     def self.unit(value)
       return Nothing if value.nil? || (value.respond_to?(:empty?) && value.empty?)
       return Just.new(value)
@@ -23,9 +7,7 @@ module Monadic
 
     # Initialize is private, because it always would return an instance of Maybe, but Just or Nothing 
     # are required (Maybe is abstract).
-    def initialize(*args)
-      raise NoMethodError, "private method `new' called for #{self.class.name}, use `unit' instead"
-    end
+    private_class_method :new
 
     def empty?
       @value.respond_to?(:empty?) && @value.empty?
@@ -37,15 +19,19 @@ module Monadic
     end
     alias :to_a :to_ary
 
+    def select(proc = nil, &block)
+      return Maybe(@value.select(&block)) if @value.is_a?(::Enumerable)
+      return Nothing unless (proc || block).call(@value)
+      return self
+    end
+
     def truly?
       @value == true
     end
   end
 
   class Just < Maybe
-    def initialize(value)
-      @value = join(value)
-    end
+    public_class_method :new
 
     def fetch(default=nil)
       @value

data/lib/monadic/monad.rb

@@ -20,11 +20,22 @@ module Monadic
     end
 
     # Unwraps the the Monad
+    # @return the value contained in the monad
     def fetch
       @value
     end
     alias :_ :fetch
 
+    # A functor applying the proc or block on the boxed `value` and returning the Monad with the transformed values.
+    # If the underlying `value` is an `Enumerable`, the map is applied on each element of the collection.
+    # (A -> B) -> M[A] -> M[B]
+    def map(proc = nil, &block)
+      func = (proc || block)
+      return self.class.unit(@value.map {|v| func.call(v) }) if @value.is_a?(::Enumerable)
+      return self.class.unit(func.call(@value))
+    end
+
+    # 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})"

data/lib/monadic/version.rb

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

data/lib/monadic.rb

@@ -6,7 +6,4 @@ require 'monadic/maybe'
 require 'monadic/either'
 require 'monadic/validation'
 
-module Monadic
-end
-
 include Monadic

data/spec/core_ext/object_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+require 'monadic/core_ext/object'
+
+describe 'pseudo Elvis operator _?' do
+  it 'works' do
+    nil._?.should    == Nothing
+    "foo"._?.should  == 'foo'
+    {}._?.a.b.should == Nothing
+    {}._?[:foo]      == Nothing
+  end
+end

data/spec/monad_axioms.rb

@@ -32,6 +32,26 @@ shared_examples 'a Monad' do
       end
 
       id1.should == id2
-    end    
+    end
+  end
+
+  describe '#map functor' do
+    add100 = ->(value) { value + 100 }
+    it 'on value types, returns the transformed value, wrapped in the Monad' do
+      res = monad.unit(1).map {|v| add100.(v) }
+      res.should == monad.unit(101)
+
+      res = monad.unit(1).map {|v| monad.unit(v + 100) }
+      res.should == monad.unit(101)
+    end
+
+    it 'on enumerables, returns the transformed collection, wrapped in the Monad' do
+      res = monad.unit([1,2,3]).map {|v| add100.(v) }
+      res.should == monad.unit([101,102,103])
+
+      # The following does not work... not sure whether it should
+      # res = monad.unit([1,2,3]).map {|v| monad.unit(v + 100) }
+      # res.should == monad.unit([101,102,103])
+    end
   end
 end

data/spec/monad_spec.rb

@@ -9,4 +9,16 @@ describe Monadic::Monad do
     Monad.unit(1).to_s.should == 'Monad(1)'
     Monad.unit(nil).to_s.should == 'Monad(nil)'
   end
+
+  describe '#map' do
+    it 'applies the function to the underlying value directly' do
+      Monad.unit(1).map {|v| v + 2}.should == Monad.unit(3)
+      Monad.unit('foo').map(&:upcase).should == Monad.unit('FOO')
+    end
+
+    it 'delegates #map to an underlying collection and wraps the resulting collection' do
+      Monad.unit([1,2]).map {|v| v + 1}.should == Monad.unit([2, 3])
+      Monad.unit(['foo', 'bar']).map(&:upcase).should == Monad.unit(['FOO', 'BAR'])
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-03 00:00:00.000000000 Z
+date: 2012-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -140,6 +140,7 @@ files:
 - README.md
 - Rakefile
 - lib/monadic.rb
+- lib/monadic/core_ext/object.rb
 - lib/monadic/either.rb
 - lib/monadic/errors.rb
 - lib/monadic/maybe.rb
@@ -147,6 +148,7 @@ files:
 - lib/monadic/validation.rb
 - lib/monadic/version.rb
 - monadic.gemspec
+- spec/core_ext/object_spec.rb
 - spec/either_spec.rb
 - spec/jruby_fixes.rb
 - spec/maybe_spec.rb
@@ -179,6 +181,7 @@ signing_key:
 specification_version: 3
 summary: see README
 test_files:
+- spec/core_ext/object_spec.rb
 - spec/either_spec.rb
 - spec/jruby_fixes.rb
 - spec/maybe_spec.rb