rumonade 0.3.0 → 0.4.0

data/.travis.yml

@@ -1,3 +1,6 @@
 language: ruby
 rvm:
-  - 1.9.2
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode
+  - rbx-19mode

data/HISTORY.md

@@ -1,5 +1,10 @@
 # HISTORY
 
+## v0.4.0 (Nov 11, 2012)
+
+  - added scala-like extensions to Hash
+  - See full list @ https://github.com/ms-ati/rumonade/compare/v0.3.0...v0.4.0
+
 ## v0.3.0 (Apr 29, 2012)
 
   - added Either#lift_to_a (and #lift)

data/MIT-LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Marc Siegel
+Copyright (c) 2012 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.rdoc

@@ -2,9 +2,9 @@
 
 = Rumonade[https://rubygems.org/gems/rumonade]
 
-Project: github[http://github.com/ms-ati/rumonade]
+*_Project_*: github[http://github.com/ms-ati/rumonade]
 
-Documentation: rubydoc.info[http://rubydoc.info/gems/rumonade/frames]
+*_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]
 
@@ -17,20 +17,20 @@ The goal of this library is to make the most common and useful Scala monadic idi
 * {Rumonade::Option Option}
 * {Rumonade::ArrayExtensions Array}
 * {Rumonade::Either Either}
-* Hash -- _coming_ _soon!_
+* {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, modelling Scala's
+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
+== Usage Examples
 
-==== {Rumonade::Option Option}: handle _possibly_ _nil_ values in a _functional_ fashion:
+=== {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)
@@ -49,7 +49,8 @@ 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:
+---
+=== {Rumonade::Either Either}: handle failures ({Rumonade::Left Left}) and successes ({Rumonade::Right Right}) in a _functional_ fashion:
 
   def find_person(name)
     case name
@@ -68,16 +69,39 @@ Note:
   find_person("Jill")
   # => Left("No such person: Jill")
 
-  # on the 'happy path', we can functionally combine and transform successes:
-  (find_person("Jack").lift_to_a + find_person("John").lift_to_a).right.map { |*names| names.join(" and ") }
+  # 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")
 
-  # while the failure cases are easily handled as well:
+  # 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")
+  # => 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_...)
 
@@ -96,11 +120,14 @@ The priorities for Rumonade are:
    * <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
+   * 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, and Array are complete.
-Please try it out, and let me know what you think!
+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.rb

@@ -26,6 +26,7 @@ require "rumonade/monad"
 require "rumonade/lazy_identity"
 require "rumonade/option"
 require "rumonade/array"
+require "rumonade/hash"
 require "rumonade/either"
 require "rumonade/error_handling"
 

data/lib/rumonade/array.rb

@@ -14,6 +14,9 @@ module Rumonade
     end
 
     module InstanceMethods
+      # Preserve native +map+ method for performance
+      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 }
       end

data/lib/rumonade/either.rb

@@ -5,6 +5,10 @@ module Rumonade
   # The data constructors {Rumonade::Left} and {Rumonade::Right} represent the two possible values.
   # The +Either+ type is often used as an alternative to {Rumonade::Option} where {Rumonade::Left} represents
   # failure (by convention) and {Rumonade::Right} is akin to {Rumonade::Some}.
+  #
+  # This implementation of +Either+ also contains ideas from the +Validation+ class in the
+  # +scalaz+ library.
+  #
   # @abstract
   class Either
     def initialize

data/lib/rumonade/hash.rb

@@ -0,0 +1,35 @@
+require 'rumonade/monad'
+
+module Rumonade
+  # TODO: Document use of Hash as a Monad
+  module HashExtensions
+    module ClassMethods
+      def unit(value)
+        raise ArgumentError, "argument not a 2-element Array for Hash.unit" unless (value.is_a?(Array) && value.size == 2)
+        Hash[*value]
+      end
+
+      def empty
+        {}
+      end
+    end
+
+    module InstanceMethods
+      # Preserve native +map+ and +flatten+ methods for compatibility
+      METHODS_TO_REPLACE_WITH_MONAD = Monad::DEFAULT_METHODS_TO_REPLACE_WITH_MONAD - [:map, :flatten]
+
+      def bind(lam = nil, &blk)
+        inject(self.class.empty) { |hsh, elt| hsh.merge((lam || blk).call(elt)) }
+      end
+
+      # @return [Option] a Some containing the value associated with +key+, or None if not present
+      def get(key)
+        Option(self[key])
+      end
+    end
+  end
+end
+
+Hash.send(:extend, Rumonade::HashExtensions::ClassMethods)
+Hash.send(:include, Rumonade::HashExtensions::InstanceMethods)
+Hash.send(:include, Rumonade::Monad)

data/lib/rumonade/monad.rb

@@ -1,19 +1,25 @@
 module Rumonade
-  # Mix-in for common monad functionality dependent on implementation of monadic methods unit and bind
+  # 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
+  # * Classes should include this module AFTER defining the monadic methods +unit+ and +bind+
+  # * When +Monad+ is mixed into a class, if the class already contains methods in
+  #   {METHODS_TO_REPLACE}, they will be renamed to add the suffix +_without_monad+,
+  #   and replaced with the method defined here which has the suffix +_with_monad+
   #
   module Monad
-    METHODS_TO_REPLACE = [:flat_map, :flatten] # :nodoc:
+    # Methods to replace when mixed in -- unless class defines +METHODS_TO_REPLACE_WITH_MONAD+
+    DEFAULT_METHODS_TO_REPLACE_WITH_MONAD = [:map, :flat_map, :flatten]
+
+    # When mixed into a class, this callback is executed
+    def self.included(base)
+      methods_to_replace = base::METHODS_TO_REPLACE_WITH_MONAD rescue DEFAULT_METHODS_TO_REPLACE_WITH_MONAD
 
-    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
-        METHODS_TO_REPLACE.each do |method_name|
+        methods_to_replace.each do |method_name|
           alias_method "#{method_name}_without_monad".to_sym, method_name if public_instance_methods.include? method_name
           alias_method method_name, "#{method_name}_with_monad".to_sym
         end
@@ -28,19 +34,26 @@ module Rumonade
     end
 
     # Returns a monad whose elements are the results of applying the given function to each element in this monad
-    def map(lam = nil, &blk)
+    #
+    # NOTE: normally aliased as +map+ when +Monad+ is mixed into a class
+    def map_with_monad(lam = nil, &blk)
       bind { |v| self.class.unit((lam || blk).call(v)) }
     end
 
     # Returns the results of applying the given function to each element in this monad
+    #
+    # NOTE: normally aliased as +flat_map+ when +Monad+ is mixed into a class
     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
+    # NOTE: normally aliased as +flatten+ when +Monad+ is mixed into a class
+    #
+    # @example
+    #   [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) }
@@ -57,6 +70,16 @@ module Rumonade
     # 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).
     #
+    # @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
+    #   #=> [1, None]
+    #   [1, None].shallow_flatten
+    #   #=> [1]
+    #
     def shallow_flatten
       bind { |x| x.is_a?(Monad) ? x : self.class.unit(x) }
     end

data/lib/rumonade/version.rb

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

data/test/hash_test.rb

@@ -0,0 +1,61 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class HashTest < Test::Unit::TestCase
+  include Rumonade
+  include MonadAxiomTestHelpers
+
+  def test_when_unit_with_2_elt_array_returns_hash
+    assert_equal({ :k => :v }, Hash.unit([:k, :v]))
+  end
+
+  def test_when_unit_with_non_2_elt_array_raises
+    assert_raise(ArgumentError) { Hash.unit([1]) }
+    assert_raise(ArgumentError) { Hash.unit([1, 2, 3]) }
+    assert_raise(ArgumentError) { Hash.unit([1, 2, 3, 4]) }
+    assert_raise(ArgumentError) { Hash.unit("not an array at all") }
+  end
+
+  def test_when_empty_returns_empty_array
+    assert_equal({}, Hash.empty)
+  end
+
+  def test_monad_axioms
+    f = lambda { |p| Hash.unit([p[0].downcase, p[1] * 2]) }
+    g = lambda { |p| Hash.unit([p[0].upcase, p[1] * 5]) }
+    [["Foo", 1], ["Bar", 2]].each do |value|
+      assert_monad_axiom_1(Hash, value, f)
+      assert_monad_axiom_2(Hash.unit(value))
+      assert_monad_axiom_3(Hash.unit(value), f, g)
+    end
+  end
+
+  def test_flat_map_behaves_correctly
+    assert_equal({ "FOO" => 2, "BAR" => 4 }, { "Foo" => 1, "Bar" => 2 }.flat_map { |p| { p[0].upcase => p[1] * 2 } })
+  end
+
+  # Special case: because Hash#map is built into Ruby, must preserve existing behavior
+  def test_map_still_behaves_normally_returning_array_of_arrays
+   assert_equal([["FOO", 2], ["BAR", 4]], { "Foo" => 1, "Bar" => 2 }.map { |p| [p[0].upcase, p[1] * 2] })
+  end
+
+  # We add Hash#map_with_monad to return a Hash, as one might expect Hash#map to do
+  def test_map_with_monad_behaves_correctly_returning_hash
+    assert_equal({ "FOO" => 2, "BAR" => 4 }, { "Foo" => 1, "Bar" => 2 }.map_with_monad { |p| [p[0].upcase, p[1] * 2] })
+  end
+
+  # Special case: because Hash#flatten is built into Ruby, must preserve existing behavior
+  unless (RUBY_ENGINE.to_s rescue nil) == 'rbx' # Except on Rubinius, where it's broken, apparently
+    def test_flatten_still_behaves_normaly_returning_array_of_alternating_keys_and_values    
+      assert_equal ["Foo", 1, "Bar", 2], { "Foo" => 1, "Bar" => 2 }.flatten
+    end
+  end
+
+  def test_shallow_flatten_raises_type_error
+    assert_raise(TypeError) { { "Foo" => "Bar" }.shallow_flatten }
+  end
+
+  def test_get_returns_option_of_value
+    assert_equal None, { "Foo" => 1, "Bar" => 2 }.get("Baz")
+    assert_equal Some(1), { "Foo" => 1, "Bar" => 2 }.get("Foo")
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rumonade
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   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-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-unit
@@ -63,6 +63,7 @@ files:
 - lib/rumonade/either.rb
 - lib/rumonade/error_handling.rb
 - lib/rumonade/errors.rb
+- lib/rumonade/hash.rb
 - lib/rumonade/lazy_identity.rb
 - lib/rumonade/monad.rb
 - lib/rumonade/option.rb
@@ -71,6 +72,7 @@ files:
 - test/array_test.rb
 - test/either_test.rb
 - test/error_handling_test.rb
+- test/hash_test.rb
 - test/lazy_identity_test.rb
 - test/option_test.rb
 - test/test_helper.rb
@@ -94,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: rumonade
-rubygems_version: 1.8.21
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A Scala-inspired Monad library for Ruby
@@ -102,7 +104,7 @@ test_files:
 - test/array_test.rb
 - test/either_test.rb
 - test/error_handling_test.rb
+- test/hash_test.rb
 - test/lazy_identity_test.rb
 - test/option_test.rb
 - test/test_helper.rb
-has_rdoc: