matilda-maybe 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dfedc2eb085cf84abaaf05050cee7cfc895ceaa0
+  data.tar.gz: 9ed28c975b9844f0075515bdb07f95fdbdea8bb5
+SHA512:
+  metadata.gz: d2e91c2a516f70cd7ab6b056aa8e32a69b75dd503f0bbefd8326b6d49a66e3453b006f6beba49a8e783978e3ff9007e1942d524ae5369b5e93d4217c717b8d10
+  data.tar.gz: 0a147b5b11ad2d7d7d7d15b7892418f9ea90c48c4e6b68947f72f5b043a3289f6448addece82cdfcb859c6d29a1573d8f9ad3e5d140fe400be08f6c81ea74f67

data/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+coverage

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+    - 1.9.3
+    - 2.0.0
+    - jruby-19mode

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'coveralls', require: false
+
+group :test do
+  gem 'rake'
+end

data/Gemfile.lock

@@ -0,0 +1,27 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    colorize (0.5.8)
+    coveralls (0.6.7)
+      colorize
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      thor
+    mime-types (1.23)
+    multi_json (1.7.3)
+    rake (10.0.3)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    thor (0.18.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coveralls
+  rake

data/LICENSE.md

@@ -0,0 +1,7 @@
+The MIT License (MIT) Copyright (c) Callum Stott, http://www.seadowg.com
+
+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.md

@@ -0,0 +1,95 @@
+# ruby-maybe
+
+[![Build Status](https://travis-ci.org/seadowg/ruby-maybe.png?branch=master)](https://travis-ci.org/seadowg/ruby-maybe)
+
+![](http://f.cl.ly/items/2o2A3k1N2d3a1b0V3V0T/maybe.png)
+
+## Installation
+
+Either include in your Gemfile:
+
+    gem 'ruby-maybe'
+
+Or, install for your system:
+
+    > gem install ruby-maybe
+
+## Usage
+
+### The Basics
+
+'Maybe' not 'Maeby'. This is an implementation of the 'Maybe' or 'Option' monad similar to that used
+[Haskell](http://www.haskell.org/haskellwiki/Maybe). Monads provide a
+safe way to create non deterministic programs (for example, when not all
+values are known at compile time). The Maybe monad allows programmers to
+deal with values that may or may not be undefined.
+
+Imagine we are access accessing an array via a method:
+
+    array = [1,2,3]
+
+    def access(n)
+      array[n]
+    end
+
+    access(1) # => 2
+    access(5) # => nil
+
+Now what if we want to take some index and add `5` to the array value
+stored there?
+
+    access(5) + 5 # => NoMethodError: undefined method `+' for nil:NilClass
+
+Hmmm, that fails pretty miserably. We can solve this with `Maybe`. Lets
+rewrite `access`:
+
+    def access(n)
+      if array[n]
+        Just.new(array[n])
+      else
+        Nothing
+      end
+    end
+
+`Nothing` and `Just` used here are both instances of `Maybe`. This means
+that they will both respond to the `bind` method:
+
+    access(1).bind { |val| Just.new(val + 5) } # => Just.new(7)
+    access(5).bind { |val| Just.new(val + 5) } # => Nothing.new
+
+For instances of `Just`, `bind` will execute the passed block with
+respect to its contained value and for `Nothing` it will skip the block
+and simply return another instance of `Nothing`. This allows a neat
+mechanism for dealing with non determinitic methods such as `access`
+without having them throw exceptions or simply return `nil`.
+
+`Maybe` is a very basic monad and at first might not seem that powerful
+but after using it instead of the more verbose control flow it replaces
+you might just learn to love it.
+
+### Method Lifting
+
+Ok so using `bind` to operate on Maybe is all well and good, but what if
+you want to add three Maybe's together:
+
+    x.bind { |x_val|
+      y.bind { |y_val|
+        z.bind { |z_val|
+          Just.new(x + y + z)
+        }
+      }
+    }
+
+Yeah... I don't think so. In languages like Haskell we can use [Applicative Functors](http://learnyouahaskell.com/functors-applicative-functors-and-monoids)
+to deal with making expressions like the above less verbose. You can go read about them but that's not really important.
+With ruby-maybe methods on the contained object in a Maybe can be lifted to operate on the Maybe:
+
+    Just.new(5) + Just.new(6) # => Just.new(11)
+    Just.new("OMG").downcase # => Just.new("omg")
+    Just.new([1,2]).inject(Just.new(0), :+) # => Just.new(3)
+
+All operations can be lifted like this and you can mix and match actual values and Maybes in the arguments. This also
+works for Nothing:
+
+    Nothing.new + Just.new(5) # => Nothing.new
+    Just.new(0) * Nothing.new / Just.new(1) # => Nothing.new

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "spec"
+  t.test_files = FileList['spec/*_spec.rb']
+  t.verbose = true
+end

data/lib/matilda-maybe.rb

@@ -0,0 +1,3 @@
+require 'matilda-maybe/maybe'
+require 'matilda-maybe/just'
+require 'matilda-maybe/nothing'

data/lib/matilda-maybe/just.rb

@@ -0,0 +1,46 @@
+class Just < Maybe
+  def method_missing(method_name, *args, &block)
+    values = args.map { |arg|
+      return Nothing.new if arg == Nothing.new
+      arg.kind_of?(Just) ? arg.value : arg
+    }
+
+    Just.new(@value.public_send(method_name, *values, &block))
+  end
+
+  def initialize(value)
+    @value = value
+  end
+
+  def bind(&block)
+    computed = block.call(@value)
+    warn("Not returning a Maybe from #bind is really bad form...") unless computed.kind_of?(Maybe)
+    computed
+  end
+
+  def map(&block)
+    Just.new(block.call(@value))
+  end
+
+  def or(*args, &block)
+    self
+  end
+
+  def get(*args, &block)
+    @value
+  end
+
+  def ==(object)
+    if object.class == Just
+      object.value == self.value
+    else
+      false
+    end
+  end
+
+  protected
+
+  def value
+    @value
+  end
+end

data/lib/matilda-maybe/maybe.rb

@@ -0,0 +1,9 @@
+class Maybe
+  def self.from(value)
+    if !value.nil?
+      Just.new(value)
+    else
+      Nothing.new
+    end
+  end
+end

data/lib/matilda-maybe/nothing.rb

@@ -0,0 +1,37 @@
+class Nothing < Maybe
+  def method_missing(method_name, *args, &block)
+    Nothing.new
+  end
+
+  def bind
+    Nothing.new
+  end
+
+  def map
+    Nothing.new
+  end
+
+  def or(*args, &block)
+    if args.empty?
+      block.call
+    else
+      args.first
+    end
+  end
+
+  def get(*args, &block)
+    if args.empty?
+      block.call
+    else
+      args.first
+    end
+  end
+
+  def ==(object)
+    if object.class == Nothing
+      true
+    else
+      false
+    end
+  end
+end

data/matilda-maybe.gemspec

@@ -0,0 +1,15 @@
+lib = File.expand_path('../lib/', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+Gem::Specification.new do |s|
+  s.name = "matilda-maybe"
+  s.version = "0.3.0"
+  s.platform = Gem::Platform::RUBY
+  s.authors = ["Callum Stott"]
+  s.email = ["callum@seadowg"]
+  s.summary = "Maybe monad implementation for Ruby"
+  s.license = 'MIT'
+
+  s.require_paths = ['lib']
+  s.files = `git ls-files`.split("\n")
+end

data/spec/integration_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+require 'matilda-maybe'
+
+describe "Integration Specs" do
+  it "works as expected" do
+    Just.new(5).bind { |val|
+      Just.new(val).map { |val|
+        val * 3
+      }
+    }.bind { |val|
+      if (val > 10)
+        Nothing.new
+      else
+        Just.new(val) + 1
+      end
+    }.must_equal(Nothing.new)
+  end
+
+  it "has the correct interface" do
+    has_method(:bind)
+    has_method(:map)
+    has_method(:or)
+    has_method(:get)
+    has_method(:==)
+  end
+end
+
+def has_method(name)
+  assert(Just.method_defined?(name), "Just does not respond to #{name}")
+  assert(Nothing.method_defined?(name), "Nothing does not respond to #{name}")
+end

data/spec/just_spec.rb

@@ -0,0 +1,57 @@
+require 'spec_helper'
+require 'matilda-maybe'
+
+describe "Just" do
+  describe "#bind" do
+    it "applys the passed block to its boxed value" do
+      Just.new(5).bind { |val| Just.new(val * 2) }.must_equal Just.new(10)
+    end
+  end
+
+  describe "#or" do
+    it "ignores arg and returns self" do
+      (Just.new(5).or { 0 }).must_equal Just.new(5)
+    end
+  end
+
+  describe "#get" do
+    it "ignores the arguments and returns the value" do
+      (Just.new(5).get { 0 }).must_equal 5
+      Just.new(5).get(0).must_equal 5
+    end
+  end
+
+  describe "#==" do
+    it "returns false if the passed object is not a Just" do
+      (Just.new(5) == 5).must_equal false
+    end
+
+    it "returns true if the passed object is a Just with the same value" do
+      (Just.new(5) == Just.new(5)).must_equal true
+    end
+  end
+
+  describe "method lifting" do
+    it "allows using a method for the contained type" do
+      just = Just.new(5)
+      just.+(5).must_equal(Just.new(10))
+    end
+
+    it "allows passed arguments to be Maybe instances" do
+      just = Just.new(5)
+      just.+(Just.new(5)).must_equal(Just.new(10))
+    end
+
+    it "returns Nothing if any argument is Nothing" do
+      just = Just.new("Hello")
+      just.slice(Just.new(0), Nothing.new).must_equal(Nothing.new)
+    end
+
+    it "passes blocks correctly" do
+      count = 0
+      just = Just.new(5)
+      just.times { |i| count += i }
+      count.must_equal(10)
+    end
+  end
+end

data/spec/maybe_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+require 'matilda-maybe'
+
+describe "Maybe" do
+  describe "#from" do
+    it "returns Nothing if passed nil" do
+      Maybe.from(nil).must_equal Nothing.new
+    end
+
+    it "returns Just if passed non-nil value" do
+      Maybe.from(false).must_equal Just.new(false)
+      Maybe.from(11).must_equal Just.new(11)
+    end
+  end
+end

data/spec/nothing_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+require 'matilda-maybe'
+
+describe "Nothing" do
+  describe "#bind" do
+    it "does not execute the passed block" do
+      executed = false
+      Nothing.new.bind { |val| executed = true }
+      executed.must_equal false
+    end
+
+    it "returns a Nothing" do
+      Nothing.new.bind { |val| val }.kind_of?(Nothing).must_equal true
+    end
+  end
+
+  describe "#map" do
+    it "returns Nothing" do
+      Nothing.new.map { |val| val }.must_equal Nothing.new
+    end
+  end
+
+  describe "#or" do
+    it "evaluates arg, returning result" do
+      (Nothing.new.or { Just.new(5) }).must_equal Just.new(5)
+      Nothing.new.or(Just.new(5)).must_equal Just.new(5)
+    end
+
+    it "chain or calls, returning last value" do
+      (Nothing.new.or { Nothing.new.or { Just.new(10) } }).must_equal Just.new(10)
+    end
+  end
+
+  describe "#get" do
+    it "evaluates arg, returning result" do
+      (Nothing.new.get { 5 }).must_equal 5
+      Nothing.new.get(5).must_equal 5
+    end
+  end
+
+  describe "#==" do
+    it "returns false if the passed object is not a Nothing" do
+      (Nothing.new == 5).must_equal false
+    end
+
+    it "returns true if the passed object is a Nothing" do
+      (Nothing.new == Nothing.new).must_equal true
+    end
+  end
+
+  describe "method lifting" do
+    it "returns Nothing for any method call" do
+      Nothing.new.missing.must_equal(Nothing.new)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'coveralls'
+Coveralls.wear!
+
+require 'minitest/autorun'

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: matilda-maybe
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Callum Stott
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-07 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- callum@seadowg
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/matilda-maybe.rb
+- lib/matilda-maybe/just.rb
+- lib/matilda-maybe/maybe.rb
+- lib/matilda-maybe/nothing.rb
+- matilda-maybe.gemspec
+- spec/integration_spec.rb
+- spec/just_spec.rb
+- spec/maybe_spec.rb
+- spec/nothing_spec.rb
+- spec/spec_helper.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0
+signing_key: 
+specification_version: 4
+summary: Maybe monad implementation for Ruby
+test_files: []