rumonade 0.1.0 → 0.1.1

data/CHANGELOG.rdoc

@@ -1,7 +1,13 @@
+=== 0.1.1 / 2011-09-19
+
+* Maintenance
+  * added a first stab at documentation for Option
+  * fixed certain errors with #map
+  * added #select
+
 === 0.1.0 / 2011-09-17
 
 * Initial Feature Set
-
   * general implementation and testing of monadic laws based on `unit` and `bind`
   * scala-like Option class w/ Some & None
   * scala-like extensions to Array

data/README.rdoc

@@ -1,15 +1,67 @@
-= Rumonade
-=== A Ruby Monad Library, Inspired by Scala
+= Rumonade[https://rubygems.org/gems/rumonade]
 
-Are you working in both the Scala and Ruby worlds, and finding that you miss some of the practical benefits
-of Scala's monads in Ruby? Then Rumonade is for you.
+== A Ruby[http://www.ruby-lang.org] Monad[http://en.wikipedia.org/wiki/Monad_(functional_programming)] Library, Inspired by Scala[http://www.scala-lang.org]
 
-The goal of this library is to make the most common scala monad idioms available in ruby:
-* Option
-* Arrays of Options / Options of Arrays
+Are you working in both the Scala[http://www.scala-lang.org] and Ruby[http://www.ruby-lang.org] worlds,
+and finding that you miss some of the practical benefits of Scala's
+monads[http://james-iry.blogspot.com/2007/09/monads-are-elephants-part-1.html] in Ruby?
+Then Rumonade is for you.
+
+The goal of this library is to make the most common and useful Scala monadic idioms available in Ruby via the following classes:
+* Rumonade::Option
+* Array
 * Either
-* for comprehensions
+* Hash
+* (more TBD)
 
-This code is in a very early state, but the Option monad is already present.
-Please try it out and let me know what you think.
+Syntactic support for scala-like for-comprehensions[http://www.scala-lang.org/node/111] will be implemented
+as a sequence of calls to #flat_map, #select, etc, modelling Scala's
+approach[http://stackoverflow.com/questions/3754089/scala-for-comprehension/3754568#3754568].
+
+Support for an all_catch[http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/scala/util/control/Exception$.html]
+idiom will be implemented to turn blocks which might throw exceptions into Option or Either
+results. If this proves useful (and a good fit for Ruby), then more narrow functional catchers can be implemented as well.
+
+== Usage
+
+You can transform possibly nil values in a functional fashion, which many find more clear and elegant:
+
+  require 'date'
+  require 'time'
+  require 'rumonade'
+
+  def format_date_in_march(time_or_date_or_nil)
+    Option(time_or_date_or_nil).
+        map(&:to_date).select {|d| d.month == 3}.
+        map(&:to_s).map {|s| s.gsub('-', '')}.get_or_else("not in march!")
+  end
+
+  format_date_in_march(nil)                            # => "not in march!"
+  format_date_in_march(Time.parse('2011-01-01 12:34')) # => "not in march!"
+  format_date_in_march(Time.parse('2011-03-21 12:34')) # => "20110321"
 
+(more examples coming soon...)
+
+== Approach
+
+There have been many[http://moonbase.rydia.net/mental/writings/programming/monads-in-ruby/00introduction.html]
+posts[http://pretheory.wordpress.com/2008/02/14/the-maybe-monad-in-ruby/]
+and[http://www.valuedlessons.com/2008/01/monads-in-ruby-with-nice-syntax.html]
+discussions[http://stackoverflow.com/questions/2709361/monad-equivalent-in-ruby]
+about monads in Ruby, which have sparked a number of approaches.
+
+Rumonade wants to be a practical drop-in Monad solution that will fit well into the Ruby world.
+
+The priorities for Rumonade are:
+1. Practical usability in day-to-day Ruby
+   * <b>don't</b> mess up normal idioms of the language (e.g., Array#map)
+   * <b>don't</b> slow down normal idioms of the language (e.g., Array#map)
+2. Rubyish-ness of usage
+   * Monad is a mix-in, requiring methods self.unit and #bind be implemented by target classes
+   * Prefer blocks to lambda/Procs where possible
+3. Equivalent idioms to Scala where possible
+
+== Status
+
+This code is in a very early state, but the Option monad is already present.
+Please try it out, and let me know what you think!

data/lib/rumonade/lazy_identity.rb

@@ -1,5 +1,5 @@
 # Adapted from http://stackoverflow.com/questions/2709361/monad-equivalent-in-ruby
-class LazyIdentity
+class LazyIdentity # :nodoc:
   def initialize(lam = nil, &blk)
     @lazy = lam || blk
     @lazy.is_a?(Proc) || raise(ArgumentError, "not a Proc")

data/lib/rumonade/monad.rb

@@ -1,10 +1,15 @@
 module Rumonade
-  # TODO: Document this
+  # Mix-in for common monad functionality dependent on implementation of monadic methods unit and bind
+  #
+  # Notes:
+  # * classes should include this module AFTER defining the monadic methods unit and bind
+  #
   module Monad
-    METHODS_TO_REPLACE = [:flat_map, :flatten]
+    METHODS_TO_REPLACE = [:flat_map, :flatten] # :nodoc:
 
-    def self.included(base)
+    def self.included(base) # :nodoc:
       base.class_eval do
+        # optimization: replace flat_map with an alias for bind, as they are identical
         alias_method :flat_map_with_monad, :bind
 
         # force only a few methods to be aliased to monad versions; others can stay with native or Enumerable versions
@@ -17,20 +22,43 @@ module Rumonade
 
     include Enumerable
 
-    def map(lam = nil, &blk)
-      bind { |v| (lam || blk).call(v) }
+    # Applies the given procedure to each element in this monad
+    def each(lam = nil, &blk)
+      bind { |v| (lam || blk).call(v) }; nil
     end
 
-    def each(lam = nil, &blk)
-      map(lam || blk); nil
+    # Returns a monad whose elements are the results of applying the given function to each element in this monad
+    def map(lam = nil, &blk)
+      bind { |v| self.class.unit((lam || blk).call(v)) }
     end
 
-    def shallow_flatten
-      bind { |x| x.is_a?(Monad) ? x : self.class.unit(x) }
+    # Returns the results of applying the given function to each element in this monad
+    def flat_map_with_monad(lam = nil, &blk)
+      bind(lam || blk)
     end
 
+    # Returns a monad whose elements are the ultimate (non-monadic) values contained in all nested monads
+    #
+    #    [1] == [[Some(Some(1)), Some(Some(None))], [None]].flatten
+    #    => true
+    #
     def flatten_with_monad
       bind { |x| x.is_a?(Monad) ? x.flatten_with_monad : self.class.unit(x) }
     end
+
+    # Returns a monad whose elements are all those elements of this monad for which the given predicate returned true
+    def select(lam = nil, &blk)
+      bind { |x| (lam || blk).call(x) ? self.class.unit(x) : self.class.empty }
+    end
+    alias_method :find_all, :select
+
+    # Returns a monad whose elements are the values contained in the first level of nested monads
+    #
+    # This method is equivalent to the Scala flatten call (single-level flattening), whereas #flatten is in keeping
+    # with the native Ruby flatten calls (multiple-level flattening).
+    #
+    def shallow_flatten
+      bind { |x| x.is_a?(Monad) ? x : self.class.unit(x) }
+    end
   end
 end

data/lib/rumonade/option.rb

@@ -2,54 +2,92 @@ require 'singleton'
 require 'rumonade/monad'
 
 module Rumonade # :nodoc:
-  # TODO: Document this
+  # Represents optional values. Instances of Option are either an instance of Some or the object None.
+  #
+  # The most idiomatic way to use an Option instance is to treat it as a collection or monad
+  # and use map, flat_map, select, or each:
+  #
+  #   name = Option(params[:name])
+  #   upper = name.map(&:strip).select { |s| s.length != 0 }.map(&:upcase)
+  #   puts upper.get_or_else("")
+  #
+  # Note that this is equivalent to
+  #
+  #   # TODO: IMPLEMENT FOR COMPREHENSIONS
+  #   # see http://stackoverflow.com/questions/1052476/can-someone-explain-scalas-yield
+  #   val upper = for {
+  #     name    <- Option(params[:name])
+  #     trimmed <- Some(name.strip)
+  #     upper   <- Some(trimmed.upcase) if trimmed.length != 0
+  #   } yield upper
+  #   puts upper.get_or_else("")
+  #
+  # Because of how for comprehension works, if None is returned from params#[], the entire expression results in None
+  # This allows for sophisticated chaining of Option values without having to check for the existence of a value.
+  #
+  # A less-idiomatic way to use Option values is via direct comparison:
+  #
+  #   name_opt = params[:name]
+  #   case name_opt
+  #     when Some
+  #       puts name_opt.get.strip.upcase
+  #     when None
+  #       puts "No name value"
+  #   end
+  #
   class Option
     class << self
+      # Returns a new Option containing the given value
       def unit(value)
         Rumonade.Option(value)
       end
 
+      # Returns the empty Option (None)
       def empty
         None
       end
     end
 
-    def initialize
+    def initialize # :nodoc:
       raise(TypeError, "class Option is abstract; cannot be instantiated") if self.class == Option
     end
 
+    # Returns None if None, or the result of executing the given block or lambda on the contents if Some
     def bind(lam = nil, &blk)
-      f = lam || blk
-      empty? ? self : f.call(value)
+      empty? ? self : (lam || blk).call(value)
     end
 
     include Monad
 
+    # Returns +true+ if None, +false+ if Some
     def empty?
       raise(NotImplementedError)
     end
 
+    # Returns contents if Some, or raises NoSuchElementError if None
     def get
       if !empty? then value else raise NoSuchElementError end
     end
 
+    # Returns contents if Some, or given value or result of given block or lambda if None
     def get_or_else(val_or_lam = nil, &blk)
       v_or_f = val_or_lam || blk
       if !empty? then value else (v_or_f.respond_to?(:call) ? v_or_f.call : v_or_f) end
     end
 
+    # Returns contents if Some, or +nil+ if None
     def or_nil
       get_or_else(nil)
     end
   end
 
-  # TODO: Document this
+  # Represents an Option containing a value
   class Some < Option
     def initialize(value)
       @value = value
     end
 
-    attr_reader :value
+    attr_reader :value # :nodoc:
 
     def empty?
       false
@@ -64,7 +102,7 @@ module Rumonade # :nodoc:
     end
   end
 
-  # TODO: Document this
+  # Represents an Option which is empty, accessed via the constant None
   class NoneClass < Option
     include Singleton
 
@@ -81,21 +119,21 @@ module Rumonade # :nodoc:
     end
   end
 
-  # TODO: Document this
+  # Exception raised on attempts to access the value of None
   class NoSuchElementError < RuntimeError; end
 
-  # TODO: Document this
+  # Returns an Option wrapping the given value: Some if non-nil, None if nil
   def Option(value)
     value.nil? ? None : Some(value)
   end
 
-  # TODO: Document this
+  # Returns a Some wrapping the given value, for convenience
   def Some(value)
     Some.new(value)
   end
 
-  # TODO: Document this
-  None = NoneClass.instance
+  # The single global instance of NoneClass, representing the empty Option
+  None = NoneClass.instance # :doc:
 
   module_function :Option, :Some
   public :Option, :Some

data/lib/rumonade/version.rb

@@ -1,3 +1,3 @@
 module Rumonade
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/test/option_test.rb

@@ -63,7 +63,7 @@ class OptionTest < Test::Unit::TestCase
   end
 
   def test_map_behaves_correctly
-    assert_equal "FOO", Some("foo").map { |s| s.upcase }
+    assert_equal Some("FOO"), Some("foo").map { |s| s.upcase }
     assert_equal None, None.map { |s| s.upcase }
   end
 
@@ -102,4 +102,10 @@ class OptionTest < Test::Unit::TestCase
     assert_equal [1], Some(1).to_a
     assert_equal [], None.to_a
   end
-end
+
+  def test_select_behaves_correctly
+    assert_equal Some(1), Some(1).select { |n| n > 0 }
+    assert_equal None, Some(1).select { |n| n < 0 }
+    assert_equal None, None.select { |n| n < 0 }
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: rumonade
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Marc Siegel
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-17 00:00:00 Z
+date: 2011-09-20 00:00:00 Z
 dependencies: []
 
 description: A Scala-inspired Monad library for Ruby, aiming to share the most common idioms for folks working in both languages. Includes Option, Array, etc.