rumonade 0.4.0 → 0.4.1

data/.rvmrc

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
+# Only full ruby name is supported here, for short names use:
+#     echo "rvm use 1.9.3" > .rvmrc
+environment_id="ruby-1.9.3-p385@rumonade"
+
+# Uncomment the following lines if you want to verify rvm version per project
+# rvmrc_rvm_version="1.18.8 (stable)" # 1.10.1 seams as a safe start
+# eval "$(echo ${rvm_version}.${rvmrc_rvm_version} | awk -F. '{print "[[ "$1*65536+$2*256+$3" -ge "$4*65536+$5*256+$6" ]]"}' )" || {
+#   echo "This .rvmrc file requires at least RVM ${rvmrc_rvm_version}, aborting loading."
+#   return 1
+# }
+
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments"
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+  [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]] &&
+    \. "${rvm_path:-$HOME/.rvm}/hooks/after_use" || true
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create  "$environment_id" || {
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  }
+fi
+
+# If you use bundler, this might be useful to you:
+# if [[ -s Gemfile ]] && {
+#   ! builtin command -v bundle >/dev/null ||
+#   builtin command -v bundle | GREP_OPTIONS= \grep $rvm_path/bin/bundle >/dev/null
+# }
+# then
+#   printf "%b" "The rubygem 'bundler' is not installed. Installing it now.\n"
+#   gem install bundler
+# fi
+# if [[ -s Gemfile ]] && builtin command -v bundle >/dev/null
+# then
+#   bundle install | GREP_OPTIONS= \grep -vE '^Using|Your bundle is complete'
+# fi

data/HISTORY.md

@@ -1,5 +1,11 @@
 # HISTORY
 
+## v0.4.1 (May 9, 2013)
+
+  - fixed behavior of #flatten called with optional depth parameter
+      - thanks Martin Mauch (@nightscape)!
+  - See full list @ https://github.com/ms-ati/rumonade/compare/v0.4.0...v0.4.1
+
 ## v0.4.0 (Nov 11, 2012)
 
   - added scala-like extensions to Hash

data/MIT-LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Marc Siegel
+Copyright (c) 2011-2013 Marc Siegel
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,148 @@
+# [Rumonade](https://rubygems.org/gems/rumonade)
+
+[![Build Status](https://travis-ci.org/ms-ati/rumonade.png)](https://travis-ci.org/ms-ati/rumonade)
+[![Dependency Status](https://gemnasium.com/ms-ati/rumonade.png)](https://gemnasium.com/ms-ati/rumonade)
+
+*_Project_*: [github](http://github.com/ms-ati/rumonade)
+
+*_Documentation_*: [rubydoc.info](http://rubydoc.info/gems/rumonade/frames)
+
+## 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)
+
+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?
+If so, 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:
+* [Option](http://rubydoc.info/gems/rumonade/Rumonade/Option)
+* [Array](http://rubydoc.info/gems/rumonade/Rumonade/ArrayExtensions)
+* [Either](http://rubydoc.info/gems/rumonade/Rumonade/Either)
+* [Hash](http://rubydoc.info/gems/rumonade/Rumonade/Hash)
+* _more coming soon_
+
+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, modeling [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 Examples
+
+### Option: handle _possibly_ _nil_ values in a _functional_ fashion:
+
+```ruby
+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 '-'
+    get_or_else("not in march!")  # returns the contained value, or the alternative if None
+end
+
+format_date_in_march(nil)                            # => "not in march!"
+format_date_in_march(Time.parse('2009-01-01 01:02')) # => "not in march!"
+format_date_in_march(Time.parse('2011-03-21 12:34')) # => "20110321"
+```
+
+Note:
+* each step of the chained computations above are functionally isolated
+* the value can notionally _start_ as nil, or _become_ nil during a computation, without effecting any other chained computations
+
+---
+### Either: handle failures (Left) and successes (Right) in a _functional_ fashion:
+
+```ruby
+def find_person(name)
+  case name
+    when /Jack/i, /John/i
+      Right(name.capitalize)
+    else
+      Left("No such person: #{name.capitalize}")
+  end
+end
+
+# success looks like this:
+find_person("Jack")
+# => Right("Jack")
+
+# failure looks like this:
+find_person("Jill")
+# => Left("No such person: Jill")
+
+# lift the contained values into Array, in order to combine them:
+find_person("Joan").lift_to_a
+# => Left(["No such person: Joan"])
+
+# on the 'happy path', combine and transform successes into a single success result:
+(find_person("Jack").lift_to_a + 
+ find_person("John").lift_to_a).right.map { |*names| names.join(" and ") }
+# => Right("Jack and John")
+
+# but if there were errors, we still have a Left with all the errors inside:
+(find_person("Jack").lift_to_a +
+ find_person("John").lift_to_a +
+ find_person("Jill").lift_to_a +
+ find_person("Joan").lift_to_a).right.map { |*names| names.join(" and ") }
+# => Left(["No such person: Jill", "No such person: Joan"])
+
+# equivalent to the previous example, but shorter:
+%w(Jack John Jill Joan).
+  map { |nm| find_person(nm).lift_to_a }.inject(:+).
+  right.map { |*names| names.join(" and ") }
+# => Left(["No such person: Jill", "No such person: Joan"])
+```
+
+Also, see the `Either` class in action in the [Ruby version](https://gist.github.com/2553490) 
+of [A Tale of Three Nightclubs](http://bugsquash.blogspot.com/2012/03/example-of-applicative-validation-in.html)
+validation example in F#, and compare it to the [Scala version using scalaz](https://gist.github.com/970717).
+
+---
+### Hash: `flat_map` returns a Hash for each key/value pair; `get` returns an Option
+
+```ruby
+h = { "Foo" => 1, "Bar" => 2, "Baz" => 3 }
+
+h = h.flat_map { |k, v| { k => v, k.upcase => v * 10 } }
+# => {"Foo"=>1, "FOO"=>10, "Bar"=>2, "BAR"=>20, "Baz"=>3, "BAZ"=>30}
+
+h = h.select { |k, v| k =~ /^b/i }
+# => {"Bar"=>2, "BAR"=>20, "Baz"=>3, "BAZ"=>30}
+
+h.get("Bar")
+# => Some(2)
+
+h.get("Foo")
+# => None
+```
+
+## 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., `Hash#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 class
+    *  Prefer blocks to lambda/Procs where possible, but allow both
+3.  Equivalent idioms to Scala where possible
+
+## Status
+
+Option, Either, Array, and Hash are already usable.
+
+<b><em>Supported Ruby versions</em></b>: MRI 1.9.2, MRI 1.9.3, JRuby in 1.9 mode, and Rubinius in 1.9 mode.
+
+Please try it out, and let me know what you think! Suggestions are always welcome.

data/lib/rumonade/array.rb

@@ -18,7 +18,10 @@ module Rumonade
       METHODS_TO_REPLACE_WITH_MONAD = Monad::DEFAULT_METHODS_TO_REPLACE_WITH_MONAD - [:map]
 
       def bind(lam = nil, &blk)
-        inject(self.class.empty) { |arr, elt| arr + (lam || blk).call(elt).to_a }
+        inject(self.class.empty) do |arr, elt|
+          res = (lam || blk).call(elt)
+          arr + (res.respond_to?(:to_a) ? res.to_a : [res])
+        end
       end
     end
   end

data/lib/rumonade/either.rb

@@ -319,4 +319,7 @@ module Rumonade
       end
     end
   end
+
+  module_function :Left, :Right
+  public :Left, :Right
 end

data/lib/rumonade/monad.rb

@@ -55,8 +55,12 @@ module Rumonade
     #   [Some(Some(1)), Some(Some(None))], [None]].flatten
     #   #=> [1]
     #
-    def flatten_with_monad
-      bind { |x| x.is_a?(Monad) ? x.flatten_with_monad : self.class.unit(x) }
+    def flatten_with_monad(depth=nil)
+      if depth.is_a? Integer
+        depth.times.inject(self) {|e, _| e.shallow_flatten }
+      else
+        bind { |x| x.is_a?(Monad) ? x.flatten_with_monad : self.class.unit(x) }
+      end
     end
 
     # Returns a monad whose elements are all those elements of this monad for which the given predicate returned true
@@ -71,11 +75,9 @@ module Rumonade
     # with the native Ruby flatten calls (multiple-level flattening).
     #
     # @example
-    #   [Some(Some(1)), Some(Some(None))], [None]].shallow_flatten
-    #   #=> [Some(Some(1)), Some(Some(None)), None]
-    #   [Some(Some(1)), Some(Some(None)), None].shallow_flatten
-    #   #=> [Some(1), Some(None)]
-    #   [Some(1), Some(None)].shallow_flatten
+    #   [Some(Some(1)), Some(Some(None)), [None]].shallow_flatten
+    #   #=> [Some(1), Some(None), None]
+    #   [Some(1), Some(None), None].shallow_flatten
     #   #=> [1, None]
     #   [1, None].shallow_flatten
     #   #=> [1]

data/lib/rumonade/version.rb

@@ -1,3 +1,3 @@
 module Rumonade
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/test/array_test.rb

@@ -24,6 +24,7 @@ class ArrayTest < Test::Unit::TestCase
 
   def test_flat_map_behaves_correctly
     assert_equal ["FOO", "BAR"], ["foo", "bar"].flat_map { |s| [s.upcase] }
+    assert_equal [2, 4, 6], [1, 2, 3].flat_map { |i| i * 2 }
   end
 
   def test_map_behaves_correctly
@@ -35,6 +36,7 @@ class ArrayTest < Test::Unit::TestCase
     assert_equal [1], [None, Some(1)].shallow_flatten
     assert_equal [1, Some(2)], [None, Some(1), Some(Some(2))].shallow_flatten
     assert_equal [Some(Some(None))], [Some(Some(Some(None)))].shallow_flatten
+    assert_equal [Some(1), Some(None), None], [Some(Some(1)), Some(Some(None)), [None]].shallow_flatten
   end
 
   def test_flatten_behaves_correctly
@@ -42,4 +44,15 @@ class ArrayTest < Test::Unit::TestCase
     assert_equal [1, 2], [None, Some(1), Some(Some(2))].flatten
     assert_equal [], [Some(Some(Some(None)))].flatten
   end
+
+  def test_flatten_with_argument_behaves_correctly
+    assert_equal [0, 1, [2], [[3]], [[[4]]]], [0, [1], [[2]], [[[3]]], [[[[4]]]]].flatten(1)
+    assert_equal [0, 1, 2, [3], [[4]]], [0, [1], [[2]], [[[3]]], [[[[4]]]]].flatten(2)
+    assert_equal [0, 1, 2, 3, [4]], [0, [1], [[2]], [[[3]]], [[[[4]]]]].flatten(3)
+    assert_equal [0, 1, 2, 3, 4], [0, [1], [[2]], [[[3]]], [[[[4]]]]].flatten(4)
+    assert_equal [Some(Some(1)), Some(Some(None)), [None]], [Some(Some(1)), Some(Some(None)), [None]].flatten(0)
+    assert_equal [Some(1), Some(None), None], [Some(Some(1)), Some(Some(None)), [None]].flatten(1)
+    assert_equal [1, None], [Some(Some(1)), Some(Some(None)), [None]].flatten(2)
+    assert_equal [1], [Some(Some(1)), Some(Some(None)), [None]].flatten(3)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rumonade
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-12 00:00:00.000000000 Z
+date: 2013-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-unit
@@ -52,11 +52,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rvmrc
 - .travis.yml
 - Gemfile
 - HISTORY.md
 - MIT-LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - lib/rumonade.rb
 - lib/rumonade/array.rb
@@ -96,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: rumonade
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: A Scala-inspired Monad library for Ruby

data/README.rdoc

@@ -1,133 +0,0 @@
-{<img src="https://secure.travis-ci.org/ms-ati/rumonade.png?branch=master" alt="Build Status" />}[http://travis-ci.org/ms-ati/rumonade]
-
-= Rumonade[https://rubygems.org/gems/rumonade]
-
-*_Project_*: github[http://github.com/ms-ati/rumonade]
-
-*_Documentation_*: rubydoc.info[http://rubydoc.info/gems/rumonade/frames]
-
-== 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]
-
-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 Option}
-* {Rumonade::ArrayExtensions Array}
-* {Rumonade::Either Either}
-* {Rumonade::Hash Hash}
-* (_more_ _TBD_)
-
-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, modeling 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 Examples
-
-=== {Rumonade::Option Option}: handle _possibly_ _nil_ values in a _functional_ fashion:
-
-  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 '-'
-        get_or_else("not in march!")  # returns the contained value, or the alternative if None
-  end
-
-  format_date_in_march(nil)                            # => "not in march!"
-  format_date_in_march(Time.parse('2009-01-01 01:02')) # => "not in march!"
-  format_date_in_march(Time.parse('2011-03-21 12:34')) # => "20110321"
-
-Note:
-* each step of the chained computations above are functionally isolated
-* the value can notionally _start_ as nil, or _become_ nil during a computation, without effecting any other chained computations
-
----
-=== {Rumonade::Either Either}: handle failures ({Rumonade::Left Left}) and successes ({Rumonade::Right Right}) in a _functional_ fashion:
-
-  def find_person(name)
-    case name
-      when /Jack/i, /John/i
-        Right(name.capitalize)
-      else
-        Left("No such person: #{name.capitalize}")
-    end
-  end
-
-  # success looks like this:
-  find_person("Jack")
-  # => Right("Jack")
-
-  # failure looks like this:
-  find_person("Jill")
-  # => Left("No such person: Jill")
-
-  # lift the contained values into Array, in order to combine them:
-  find_person("Joan").lift_to_a
-  # => Left(["No such person: Joan"])
-
-  # on the 'happy path', combine and transform successes into a single success result:
-  (find_person("Jack").lift_to_a +
-   find_person("John").lift_to_a).right.map { |*names| names.join(" and ") }
-  # => Right("Jack and John")
-
-  # but if there were errors, we still have a Left with all the errors inside:
-  (find_person("Jack").lift_to_a +
-   find_person("John").lift_to_a +
-   find_person("Jill").lift_to_a +
-   find_person("Joan").lift_to_a).right.map { |*names| names.join(" and ") }
-  # => Left(["No such person: Jill", "No such person: Joan"])
-
-  # equivalent to the previous example, but shorter:
-  %w(Jack John Jill Joan).map { |nm| find_person(nm).lift_to_a }.inject(:+).
-    right.map { |*names| names.join(" and ") }
-  # => Left(["No such person: Jill", "No such person: Joan"])
-
----
-=== {Rumonade::Hash Hash}:
-
-  h = { "Foo" => 1, "Bar" => 2, "Baz" => 3 }
-  h = h.flat_map { |k, v| { k => v, k.upcase => v * 10 } }
-  # => {"Foo"=>1, "FOO"=>10, "Bar"=>2, "BAR"=>20, "Baz"=>3, "BAZ"=>30}
-  h = h.select { |k, v| k =~ /^b/i }
-  # => {"Bar"=>2, "BAR"=>20, "Baz"=>3, "BAZ"=>30}
-  h.get("Bar")
-  # => Some(2)
-  h.get("Foo")
-  # => None
-
-(_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., Hash#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, but allow both
-3. Equivalent idioms to Scala where possible
-
-== Status
-
-Option, Either, Array, and Hash are already usable.
-
-<b><em>Supported Ruby versions</em></b>: MRI 1.9.2, MRI 1.9.3, JRuby in 1.9 mode, and Rubinius in 1.9 mode.
-
-Please try it out, and let me know what you think! Suggestions are always welcome.