rumonade 0.1.0

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.idea
+html
+rdoc
+

data/CHANGELOG.rdoc

@@ -0,0 +1,7 @@
+=== 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/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in rumonade.gemspec
+gemspec

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Marc Siegel
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,15 @@
+= Rumonade
+=== A Ruby Monad Library, Inspired by Scala
+
+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.
+
+The goal of this library is to make the most common scala monad idioms available in ruby:
+* Option
+* Arrays of Options / Options of Arrays
+* Either
+* for comprehensions
+
+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/Rakefile

@@ -0,0 +1,25 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+end
+
+#require "rdoc/task"
+#RDoc::Task.new do |rdoc|
+#  rdoc.main = "README.rdoc"
+#  rdoc.rdoc_files.include("README.rdoc", "CHANGELOG.rdoc", "lib/**/*.rb")
+#end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  require File.expand_path("../lib/rumonade/version", __FILE__)
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.title = "Rumonade #{Rumonade::VERSION}"
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('CHANGELOG.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/rumonade.rb

@@ -0,0 +1,41 @@
+#--
+# Copyright (c) 2011 Marc Siegel
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+require "rumonade/version"
+require "rumonade/monad"
+require "rumonade/lazy_identity"
+require "rumonade/option"
+require "rumonade/array"
+
+# = Rumonade
+#
+# Rumonade is a ruby module providing a scala-like system of monads, including:
+# * Option
+# * Array
+#
+# See the examples in link:files/README_rdoc.html for more insight.
+#
+module Rumonade
+end
+
+# bring into global namespace Monad, Option, etc
+include Rumonade

data/lib/rumonade/array.rb

@@ -0,0 +1,26 @@
+require 'rumonade/monad'
+
+module Rumonade
+  module ArrayExtensions
+    module ClassMethods
+      def unit(value)
+        [value]
+      end
+
+      def empty
+        []
+      end
+    end
+
+    module InstanceMethods
+      def bind(lam = nil, &blk)
+        f = lam || blk
+        inject([]) { |arr, elt| arr + f.call(elt).to_a }
+      end
+    end
+  end
+end
+
+Array.send(:extend, Rumonade::ArrayExtensions::ClassMethods)
+Array.send(:include, Rumonade::ArrayExtensions::InstanceMethods)
+Array.send(:include, Rumonade::Monad)

data/lib/rumonade/lazy_identity.rb

@@ -0,0 +1,27 @@
+# Adapted from http://stackoverflow.com/questions/2709361/monad-equivalent-in-ruby
+class LazyIdentity
+  def initialize(lam = nil, &blk)
+    @lazy = lam || blk
+    @lazy.is_a?(Proc) || raise(ArgumentError, "not a Proc")
+    @lazy.arity.zero? || raise(ArgumentError, "arity must be 0, was #{@lazy.arity}")
+  end
+
+  attr_reader :lazy
+
+  def force
+    @lazy[]
+  end
+
+  def self.unit(lam = nil, &blk)
+    LazyIdentity.new(lam || blk)
+  end
+
+  def bind(lam = nil, &blk)
+    f = lam || blk
+    f[@lazy]
+  end
+
+  def ==(other)
+    other.is_a?(LazyIdentity) && other.force == force
+  end
+end

data/lib/rumonade/monad.rb

@@ -0,0 +1,36 @@
+module Rumonade
+  # TODO: Document this
+  module Monad
+    METHODS_TO_REPLACE = [:flat_map, :flatten]
+
+    def self.included(base)
+      base.class_eval do
+        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|
+          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
+      end
+    end
+
+    include Enumerable
+
+    def map(lam = nil, &blk)
+      bind { |v| (lam || blk).call(v) }
+    end
+
+    def each(lam = nil, &blk)
+      map(lam || blk); nil
+    end
+
+    def shallow_flatten
+      bind { |x| x.is_a?(Monad) ? x : self.class.unit(x) }
+    end
+
+    def flatten_with_monad
+      bind { |x| x.is_a?(Monad) ? x.flatten_with_monad : self.class.unit(x) }
+    end
+  end
+end

data/lib/rumonade/option.rb

@@ -0,0 +1,102 @@
+require 'singleton'
+require 'rumonade/monad'
+
+module Rumonade # :nodoc:
+  # TODO: Document this
+  class Option
+    class << self
+      def unit(value)
+        Rumonade.Option(value)
+      end
+
+      def empty
+        None
+      end
+    end
+
+    def initialize
+      raise(TypeError, "class Option is abstract; cannot be instantiated") if self.class == Option
+    end
+
+    def bind(lam = nil, &blk)
+      f = lam || blk
+      empty? ? self : f.call(value)
+    end
+
+    include Monad
+
+    def empty?
+      raise(NotImplementedError)
+    end
+
+    def get
+      if !empty? then value else raise NoSuchElementError end
+    end
+
+    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
+
+    def or_nil
+      get_or_else(nil)
+    end
+  end
+
+  # TODO: Document this
+  class Some < Option
+    def initialize(value)
+      @value = value
+    end
+
+    attr_reader :value
+
+    def empty?
+      false
+    end
+
+    def ==(other)
+      other.is_a?(Some) && other.value == value
+    end
+
+    def to_s
+      "Some(#{value.to_s})"
+    end
+  end
+
+  # TODO: Document this
+  class NoneClass < Option
+    include Singleton
+
+    def empty?
+      true
+    end
+
+    def ==(other)
+      other.equal?(self.class.instance)
+    end
+
+    def to_s
+      "None"
+    end
+  end
+
+  # TODO: Document this
+  class NoSuchElementError < RuntimeError; end
+
+  # TODO: Document this
+  def Option(value)
+    value.nil? ? None : Some(value)
+  end
+
+  # TODO: Document this
+  def Some(value)
+    Some.new(value)
+  end
+
+  # TODO: Document this
+  None = NoneClass.instance
+
+  module_function :Option, :Some
+  public :Option, :Some
+end

data/lib/rumonade/version.rb

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

data/rumonade.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "rumonade/version"
+
+Gem::Specification.new do |s|
+  s.name        = "rumonade"
+  s.version     = Rumonade::VERSION
+  s.authors     = ["Marc Siegel"]
+  s.email       = ["marc@usainnov.com"]
+  s.homepage    = "http://github.com/ms-ati/rumonade"
+  s.summary     = "A Scala-inspired Monad library for Ruby"
+  s.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."
+
+  s.rubyforge_project = "rumonade"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  #s.add_development_dependency "rdoc"
+  #s.add_development_dependency "test-unit"
+  #s.add_development_dependency "rr"
+end

data/test/array_test.rb

@@ -0,0 +1,45 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class ArrayTest < Test::Unit::TestCase
+  include Rumonade
+  include MonadAxiomTestHelpers
+
+  def test_when_unit_returns_1_elt_array
+    assert_equal [1], Array.unit(1)
+  end
+
+  def test_when_empty_returns_empty_array
+    assert_equal [], Array.empty
+  end
+
+  def test_monad_axioms
+    f = lambda { |x| Array.unit(x && x * 2) }
+    g = lambda { |x| Array.unit(x && x * 5) }
+    [1, 42].each do |value|
+      assert_monad_axiom_1(Array, value, f)
+      assert_monad_axiom_2(Array.unit(value))
+      assert_monad_axiom_3(Array.unit(value), f, g)
+    end
+  end
+
+  def test_flat_map_behaves_correctly
+    assert_equal ["FOO", "BAR"], ["foo", "bar"].flat_map { |s| [s.upcase] }
+  end
+
+  def test_map_behaves_correctly
+    assert_equal ["FOO", "BAR"], ["foo", "bar"].map { |s| s.upcase }
+  end
+
+  def test_shallow_flatten_behaves_correctly
+    assert_equal [0, 1, [2], [[3]], [[[4]]]], [0, [1], [[2]], [[[3]]], [[[[4]]]]].shallow_flatten
+    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
+  end
+
+  def test_flatten_behaves_correctly
+    assert_equal [0, 1, 2, 3, 4], [0, [1], [[2]], [[[3]]], [[[[4]]]]].flatten
+    assert_equal [1, 2], [None, Some(1), Some(Some(2))].flatten
+    assert_equal [], [Some(Some(Some(None)))].flatten
+  end
+end

data/test/lazy_identity_test.rb

@@ -0,0 +1,16 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'test_helper'))
+
+class LazyIdentityTest < Test::Unit::TestCase
+  include Rumonade
+  include MonadAxiomTestHelpers
+
+  def test_monad_axioms
+    f = lambda { |lazy| v = lazy.call * 2; LazyIdentity.new { v } }
+    g = lambda { |lazy| v = lazy.call + 5; LazyIdentity.new { v } }
+    lazy_value = lambda { 42 } # returns 42 when called
+    assert_monad_axiom_1(LazyIdentity, lazy_value, f)
+    assert_monad_axiom_2(LazyIdentity.new(lazy_value))
+    assert_monad_axiom_3(LazyIdentity.new(lazy_value), f, g)
+  end
+
+end

data/test/option_test.rb

@@ -0,0 +1,105 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class OptionTest < Test::Unit::TestCase
+  include Rumonade
+  include MonadAxiomTestHelpers
+
+  def test_when_option_with_nil_returns_none_singleton
+    assert_same None, Option.unit(nil)
+    assert_same None, Option(nil)
+    assert_same NoneClass.instance, None
+  end
+
+  def test_when_option_with_value_returns_some
+    assert_equal Some(42), Option.unit(42)
+    assert_equal Some(42), Option(42)
+    assert_equal Some(42), Some.new(42)
+    assert_not_equal None, Some(nil)
+  end
+
+  def test_when_option_constructor_raises
+    assert_raise(TypeError) { Option.new }
+  end
+
+  def test_monad_axioms
+    f = lambda { |x| Option(x && x * 2) }
+    g = lambda { |x| Option(x && x * 5) }
+    [nil, 42].each do |value|
+      assert_monad_axiom_1(Option, value, f)
+      assert_monad_axiom_2(Option(value))
+      assert_monad_axiom_3(Option(value), f, g)
+    end
+  end
+
+  def test_when_empty_returns_none
+    assert_equal None, Option.empty
+  end
+
+  def test_when_value_on_some_returns_value_but_on_none_raises
+    assert_equal "foo", Some("foo").value
+    assert_raise(NoMethodError) { None.value }
+  end
+
+  def test_when_get_on_some_returns_value_but_on_none_raises
+    assert_equal "foo", Some("foo").get
+    assert_raise(NoSuchElementError) { None.get }
+  end
+
+  def test_when_get_or_else_on_some_returns_value_but_on_none_returns_value_or_executes_block_or_lambda
+    assert_equal "foo", Some("foo").get_or_else("bar")
+    assert_equal "bar", None.get_or_else("bar")
+    assert_equal "blk", None.get_or_else { "blk" }
+    assert_equal "lam", None.get_or_else(lambda { "lam"} )
+  end
+
+  def test_when_or_nil_on_some_returns_value_but_on_none_returns_nil
+    assert_equal 123, Some(123).or_nil
+    assert_nil None.or_nil
+  end
+
+  def test_flat_map_behaves_correctly
+    assert_equal Some("FOO"), Some("foo").flat_map { |s| Some(s.upcase) }
+    assert_equal None, None.flat_map { |s| Some(s.upcase) }
+  end
+
+  def test_map_behaves_correctly
+    assert_equal "FOO", Some("foo").map { |s| s.upcase }
+    assert_equal None, None.map { |s| s.upcase }
+  end
+
+  def test_shallow_flatten_behaves_correctly
+    assert_equal Some(Some(1)), Some(Some(Some(1))).shallow_flatten
+    assert_equal None, Some(None).shallow_flatten
+    assert_equal Some(1), Some(1).shallow_flatten
+    assert_equal [None, Some(1)], Some([None, Some(1)]).shallow_flatten
+  end
+
+  def test_flatten_behaves_correctly
+    assert_equal Some(1), Some(Some(Some(1))).flatten
+    assert_equal None, Some(None).flatten
+    assert_equal Some(1), Some(1).flatten
+    assert_equal [1], Some([None, Some(1)]).flatten
+  end
+
+  def test_to_s_behaves_correctly
+    assert_equal "Some(1)", Some(1).to_s
+    assert_equal "None", None.to_s
+    assert_equal "Some(Some(None))", Some(Some(None)).to_s
+  end
+
+  def test_each_behaves_correctly
+    vals = [None, Some(42)].inject([]) { |arr, opt| assert_nil(opt.each { |val| arr << val }); arr }
+    assert_equal [42], vals
+  end
+
+  def test_enumerable_methods_are_available
+    assert Some(1).all? { |v| v < 10 }
+    assert !Some(1).all? { |v| v > 10 }
+    assert None.all? { |v| v > 10 }
+  end
+
+  def test_to_a_behaves_correctly
+    assert_equal [1], Some(1).to_a
+    assert_equal [], None.to_a
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,20 @@
+$:.unshift(File.dirname(File.dirname(File.expand_path(__FILE__))) + '/lib')
+require "rubygems"
+require "test/unit"
+require "rr"
+require "rumonade"
+
+# see http://stackoverflow.com/questions/2709361/monad-equivalent-in-ruby
+module MonadAxiomTestHelpers
+  def assert_monad_axiom_1(monad_class, value, f)
+    assert_equal f[value], monad_class.unit(value).bind(f)
+  end
+
+  def assert_monad_axiom_2(monad)
+    assert_equal monad, monad.bind(lambda { |v| monad.class.unit(v) })
+  end
+
+  def assert_monad_axiom_3(monad, f, g)
+    assert_equal monad.bind(f).bind(g), monad.bind { |x| f[x].bind(g) }
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: rumonade
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Marc Siegel
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-17 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.
+email: 
+- marc@usainnov.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- CHANGELOG.rdoc
+- Gemfile
+- MIT-LICENSE.txt
+- README.rdoc
+- Rakefile
+- lib/rumonade.rb
+- lib/rumonade/array.rb
+- lib/rumonade/lazy_identity.rb
+- lib/rumonade/monad.rb
+- lib/rumonade/option.rb
+- lib/rumonade/version.rb
+- rumonade.gemspec
+- test/array_test.rb
+- test/lazy_identity_test.rb
+- test/option_test.rb
+- test/test_helper.rb
+homepage: http://github.com/ms-ati/rumonade
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: rumonade
+rubygems_version: 1.8.8
+signing_key: 
+specification_version: 3
+summary: A Scala-inspired Monad library for Ruby
+test_files: 
+- test/array_test.rb
+- test/lazy_identity_test.rb
+- test/option_test.rb
+- test/test_helper.rb