monadic 0.0.2 → 0.0.3

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## v0.0.3
+
+`Some#map` and `Some#select` accept proc and block, you can now use:
+
+    Option("FOO").map(&:downcase)           # NEW
+    Option("FOO").map { |e| e.downcase }    # old
+    Option("FOO").downcase                  # old
+
+Removed `#none?`, please use `#empty?` instead.

data/README.md

@@ -1,32 +1,32 @@
 # Monadic
 
-is a gem to help 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 to my ruby projects (hence I will be using more Scala like constructs than Haskell).
 
 See also http://en.wikipedia.org/wiki/Monad
 
-Planned are the following monadics:
+We have the following monadics:
 
 - Option (Maybe in Haskell)
 - Either *planned
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'monadic'
+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.
 
-And then execute:
+## Usage
 
-    $ bundle
+### 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'. 
 
-Or install it yourself as:
 
-    $ gem install monadic
+    Option(User.find(123)).name._         # ._ is a shortcut for .value 
 
-## Usage
+    # if you prefer the alias Maybe instead of option
+    Maybe(User.find(123)).name._
 
-### 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'.
+    # confidently diving into nested hashes
+    Maybe({})[:a][:b][:c]                   == None
+    Maybe({})[:a][:b][:c].value('unknown')  == None
+    Maybe(a: 1)[:a]._                       == 1
 
 Basic usage examples:
 
@@ -38,7 +38,6 @@ Basic usage examples:
     Option(nil)._                == "None"
     "#{Option(nil)}"             == "None"
     Option(nil)._("unknown")     == "unknown"
-    Option(nil).none?            == true
     Option(nil).empty?           == true
     Option(nil).truly?           == false
 
@@ -46,7 +45,6 @@ Basic usage examples:
     Option('FOO').downcase       == Some('foo') 
     Option('FOO').downcase.value == "foo"
     Option('FOO').downcase._     == "foo"
-    Option('foo').none?          == false
     Option('foo').empty?         == false
     Option('foo').truly?         == true
 
@@ -68,6 +66,8 @@ Treat it like an array:
 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'
 
     if user != nil
@@ -80,7 +80,7 @@ Falsey values (kind-of) examples:
     user.subscribed?.value(false) # same as above
     user.subscribed?.or(false)    # same as above
 
-Remember! an Option is never false, if you want to know if it is false, call `#none?` of `#truly?`
+Remember! an Option 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.
 
@@ -105,8 +105,34 @@ Slug example
     end
 
 
-see also [Option Type ](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/) and 
-[NullObject and Falsiness by @avdi](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/)
+see also
+
+ * [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/)
+ * [andand](https://github.com/raganwald/andand/blob/master/README.textile)
+ * [ick](http://ick.rubyforge.org/)
+ * [Monads in Ruby](http://moonbase.rydia.net/mental/writings/programming/monads-in-ruby/00introduction.html)
+ * [The Maybe Monad in Ruby](http://pretheory.wordpress.com/2008/02/14/the-maybe-monad-in-ruby/)
+ * [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)
+ * [Monads for functional programming](http://homepages.inf.ed.ac.uk/wadler/papers/marktoberdorf/baastad.pdf)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'monadic'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install monadic
 
 ## Contributing
 

data/lib/monadic/option.rb

@@ -1,89 +1,93 @@
 require 'singleton'
+# Represents optional values. Instances of Option are either an instance of Some or the object None.
+#
 
+# 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)
 end
-alias :Some :Option
+alias :Some  :Option
+alias :Maybe :Option
 
-class Some 
+# Represents the Option if there is some value available
+class Some
   def initialize(value)
     @value = value
   end
 
-  def none?
-    false
-  end
-  alias :empty? :none?
-
-  def truly?
-    @value == true
-  end
-
-  def else(default)
-    return default if none?
-    return self
-  end  
-
   def to_ary
     return [@value].flatten if @value.respond_to? :flatten
     return [@value]
   end
   alias :to_a :to_ary
 
-  def map(&block)
-    return Option(@value.map(&block)) if @value.is_a?(Enumerable)
-    return Option(block.call)
+  def empty?
+    false
   end
 
-  def select(&block)
-    return Option(@value.select(&block)) if @value.is_a?(Enumerable)
-    return None unless block.call(@value)
-    return self
+  def truly?
+    @value == true
   end
 
   def value(default=None, &block)
-    return default if none?
+    return default if empty?
     return block.call(@value)  if block_given?
     return @value
-  end  
+  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  
+  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  
+  end
+
+  def to_s
+    "Some(#{@value.to_s})"
+  end
 end
 
+# Represents the Option if there is no value available
 class None
   class << self
-    def method_missing(m, *args)
-      self
-    end
-
-    def value(default=self)
-      default
-    end
-    alias :or :value
-    alias :_  :value
-
     def to_ary
       []
     end
     alias :to_a :to_ary
 
-    def none?
+    def empty?
       true
     end
-    alias :empty? :none?
+
+    def method_missing(m, *args)
+      self
+    end
 
     def truly?
       false
     end
+
+    def value(default=self)
+      default
+    end
+    alias :or :value
+    alias :_  :value
   end
 end

data/lib/monadic/version.rb

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

data/monadic.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'guard-rspec'
   gem.add_development_dependency 'guard-bundler'
   gem.add_development_dependency 'growl'
+  gem.add_development_dependency 'activesupport'
 end

data/spec/option_spec.rb

@@ -7,22 +7,29 @@ describe 'Option' do
 
   it 'None stays None' do
     Option(nil)._.should == None
-    Option(nil).none?.should be_true
     Option(nil).empty?.should be_true
   end
 
   it 'Some stays Some' do
     Option('foo').should be_kind_of(Some) 
-    Option('foo').none?.should be_false
     Option('foo').empty?.should be_false
   end
 
-  it 'None to_s is "None"' do
+  it 'Some#to_s is "Some(value)"' do
+    Some(123).to_s.should == "Some(123)"
+  end
+
+  it 'None#to_s is "None"' do
     option = Option(nil)
     "#{option}".should   == "None"
     "#{option._}".should == "None"
   end
 
+  it 'None is always empty' do
+    None.empty?.should be_true
+    Maybe(nil).empty?.should be_true
+  end
+
   it '[] as value always returns None()' do
     Option([]).a.should == None
   end
@@ -56,11 +63,6 @@ describe 'Option' do
     Option(nil).should_not be_false
   end
 
-  it 'tells you if it is none when calling #none?' do
-    Option('foo').none?.should be_false
-    Option(nil).none?.should be_true
-  end
-
   class User 
     attr_reader :name
     def initialize(name)
@@ -105,4 +107,25 @@ describe 'Option' do
     Option(nil).to_a.should == []
   end
 
+  it 'diving into hashes' do
+    Maybe({})['a']['b']['c'].should == None
+    Maybe({a: 1})[:a]._.should == 1
+  end
+
+  it 'should support Rumonades example' do
+    require 'active_support/time'
+    def format_date_in_march(time_or_date_or_nil)
+    Option(time_or_date_or_nil).    # wraps possibly-nil value in an Option monad (Some or None)
+      map(&:to_date).               # transforms a contained Time value into a Date value
+      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
+    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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-29 00:00:00.000000000 Z
+date: 2012-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -91,6 +91,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: brings some functional goodness to ruby
 email:
 - pz@anixe.pl
@@ -100,6 +116,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- CHANGELOG.md
 - Gemfile
 - Guardfile
 - LICENSE