monadic 0.0.1 → 0.0.2

data/README.md

@@ -7,7 +7,7 @@ See also http://en.wikipedia.org/wiki/Monad
 Planned are the following monadics:
 
 - Option (Maybe in Haskell)
-- Either
+- Either *planned
 
 ## Installation
 
@@ -25,7 +25,88 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Option
+Is an optional type, which helps to handle error conditions gracefully. The one thing to remember about option is: 'What goes into the Option, stays in the Option'.
+
+Basic usage examples:
+
+    # handling nil (None serves as NullObject)
+    obj = nil
+    Option(obj).a.b.c            == None
+
+    # None stays None
+    Option(nil)._                == "None"
+    "#{Option(nil)}"             == "None"
+    Option(nil)._("unknown")     == "unknown"
+    Option(nil).none?            == true
+    Option(nil).empty?           == true
+    Option(nil).truly?           == false
+
+    # Some stays Some, unless you unbox it
+    Option('FOO').downcase       == Some('foo') 
+    Option('FOO').downcase.value == "foo"
+    Option('FOO').downcase._     == "foo"
+    Option('foo').none?          == false
+    Option('foo').empty?         == false
+    Option('foo').truly?         == true
+
+Map, select:
+    
+    Option(123).map   { |value| User.find(value) } == Option(someUser)    # if user found
+    Option(0).map     { |value| User.find(value) } == None                # if user not found
+    Option([1,2]).map { |value| value.to_s }       == Option(["1", "2"])  # for all Enumerables
+
+    Option('foo').select { |value| value.start_with?('f') } == Some('foo')
+    Option('bar').select { |value| value.start_with?('f') } == None
+
+Treat it like an array:
+
+    Option(123).to_a         == [123]
+    Option([123, 456]).to_a  == [123, 456]
+    Option(nil)              == []
+
+Falsey values (kind-of) examples:
+
+    user = Option(User.find(123))
+    user.value('You are not logged in') { |user| "You are logged in as #{user.name}" }.should == 'You are logged in as foo'
+
+    if user != nil
+      "You are logged in as foo"
+    else
+      "You are not logged in"
+
+    user.subscribed?              # always true
+    user.subscribed?.truly?       # true if subscribed is true
+    user.subscribed?.value(false) # same as above
+    user.subscribed?.or(false)    # same as above
+
+Remember! an Option is never false, if you want to know if it is false, call `#none?` of `#truly?`
+
+`#truly?` will return true or false, always.
+
+Slug example
+
+    # instead of 
+    def slug(title)
+      if title
+        title.strip.downcase.tr_s('^[a-z0-9]', '-')
+      end
+    end
+
+    # or 
+
+    def slug(title)
+      title && title.strip.downcase.tr_s('^[a-z0-9]', '-')
+    end
+
+    # do it with a default
+    def slug(title)
+      Option(title).strip.downcase.tr_s('^[a-z0-9]', '-')._('unknown-title')
+    end
+
+
+see also [Option Type ](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/) and 
+[NullObject and Falsiness by @avdi](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/)
 
 ## Contributing
 

data/lib/monadic/option.rb

@@ -0,0 +1,89 @@
+require 'singleton'
+
+def Option(value)
+  return None if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+  return Some.new(value)
+end
+alias :Some :Option
+
+class Some 
+  def initialize(value)
+    @value = value
+  end
+
+  def none?
+    false
+  end
+  alias :empty? :none?
+
+  def truly?
+    @value == true
+  end
+
+  def else(default)
+    return default if none?
+    return self
+  end  
+
+  def to_ary
+    return [@value].flatten if @value.respond_to? :flatten
+    return [@value]
+  end
+  alias :to_a :to_ary
+
+  def map(&block)
+    return Option(@value.map(&block)) if @value.is_a?(Enumerable)
+    return Option(block.call)
+  end
+
+  def select(&block)
+    return Option(@value.select(&block)) if @value.is_a?(Enumerable)
+    return None unless block.call(@value)
+    return self
+  end
+
+  def value(default=None, &block)
+    return default if none?
+    return block.call(@value)  if block_given?
+    return @value
+  end  
+  alias :or :value
+  alias :_  :value
+
+  def method_missing(m, *args)
+    Option(@value.__send__(m, *args))
+  end  
+
+  def ==(other)
+    return false unless other.is_a? Some
+    @value == other.instance_variable_get(:@value)
+  end  
+end
+
+class None
+  class << self
+    def method_missing(m, *args)
+      self
+    end
+
+    def value(default=self)
+      default
+    end
+    alias :or :value
+    alias :_  :value
+
+    def to_ary
+      []
+    end
+    alias :to_a :to_ary
+
+    def none?
+      true
+    end
+    alias :empty? :none?
+
+    def truly?
+      false
+    end
+  end
+end

data/lib/monadic/version.rb

@@ -1,3 +1,3 @@
 module Monadic
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/monadic.rb

@@ -1,5 +1,5 @@
-require "monadic/version"
+require 'monadic/version'
 
-module Monadic
-  # Your code goes here...
-end
+$LOAD_PATH << File.expand_path('..', __FILE__)
+
+require 'monadic/option'

data/spec/option_spec.rb

@@ -1,7 +1,108 @@
 require 'spec_helper'
 
-class Option
-end
+describe 'Option' do 
+  it 'nil as value always returns None()' do
+     Option(nil).a.b.c.should == None
+  end
+
+  it 'None stays None' do
+    Option(nil)._.should == None
+    Option(nil).none?.should be_true
+    Option(nil).empty?.should be_true
+  end
+
+  it 'Some stays Some' do
+    Option('foo').should be_kind_of(Some) 
+    Option('foo').none?.should be_false
+    Option('foo').empty?.should be_false
+  end
+
+  it 'None to_s is "None"' do
+    option = Option(nil)
+    "#{option}".should   == "None"
+    "#{option._}".should == "None"
+  end
+
+  it '[] as value always returns None()' do
+    Option([]).a.should == None
+  end
+
+  it 'calling methods on Option always returns an Option with the transformed value' do
+    Option('FOO').downcase.should == Some('foo')
+  end
+
+  it 'returns the value of an option' do 
+    Option('foo').value.should == 'foo'
+    Option('foo')._.should == 'foo'
+  end
+
+  it 'returns the value of an option with a default, in case value is None' do
+    Option(nil).value('bar').should == 'bar'
+    Option(nil)._('bar').should == 'bar'
+  end
+
+  it 'returns the value and not the default if it is Some' do
+    Option('FOO').downcase.value('bar').should == 'foo'
+    Option('FOO').downcase._('bar').should == 'foo'
+  end
+
+  it 'returns the value applied to a block if it is Some' do
+    Option('foo').value('bar') { |val| "You are logged in as #{val}" }.should == 'You are logged in as foo'
+    Option(nil).value('You are not logged in') { |val| "You are logged in as #{val}" }.should == 'You are not logged in'
+  end
+
+  it 'is never falsey' do
+    Option('foo').should_not be_false
+    Option(nil).should_not be_false
+  end
+
+  it 'tells you if it is none when calling #none?' do
+    Option('foo').none?.should be_false
+    Option(nil).none?.should be_true
+  end
+
+  class User 
+    attr_reader :name
+    def initialize(name)
+      @name = name
+    end
+    def subscribed?
+      true
+    end
+  end
+
+  it 'allows to use a block with value and _' do
+    user = Option(User.new('foo'))
+    user.value('You are not logged in') { |user| "You are logged in as #{user.name}" }.should == 'You are logged in as foo'
+  end
+
+  it 'handles (kind-of) falsey values' do
+    user = Option(User.new('foo'))
+    user.subscribed?.or(false).should be_true
+    user.subscribed?.truly?.should be_true
+
+    user = Option(nil)
+    user.subscribed?.or(false).should be_false
+    user.subscribed?.truly?.should be_false
+  end
+
+  it 'allows to use map' do
+    Option(nil).map { |e| Hash.new(:key => e) }.should == None
+    Option('foo').map { |e| Hash.new(:key => e) }.should == Some(Hash.new(:key => 'foo'))
+    Option([1,2]).map { |e| e.to_s }.should == Some(["1", "2"])
+  end
+
+  it 'allows to use select' do
+    Option('foo').select  { |e| e.start_with?('f') }.should == Some('foo')
+    Option('bar').select  { |e| e.start_with?('f') }.should == None
+    Option(nil).select    { |e| e.never_called     }.should == None
+    Option([1, 2]).select { |e| e == 1             }.should == Some([1])
+  end
+
+  it 'acts as an array' do
+    Option('foo').to_a.should == ['foo']
+    Option(['foo', 'bar']).to_a.should == ['foo', 'bar']
+    Option(nil).to_a.should == []
+  end
 
-describe Option do 
 end

data/spec/spec_helper.rb

@@ -1,2 +1,4 @@
 require 'bundler/setup'
 Bundler.require(:default, :test)
+
+require File.expand_path('../../lib/monadic', __FILE__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -106,6 +106,7 @@ files:
 - README.md
 - Rakefile
 - lib/monadic.rb
+- lib/monadic/option.rb
 - lib/monadic/version.rb
 - monadic.gemspec
 - spec/option_spec.rb