just_maybe 0.2.2 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d2d252ffb42e2b682f5a18422cabec3209753c1a
+  data.tar.gz: ab0e342a64665b8964da74aa3dd8fec43dd2507e
+SHA512:
+  metadata.gz: 715a90005076e8bfb1d5f886041bb67763da284ea2a882f6d26bceee852ce9d7cbe9e9ddbd65452cc9b9f9b4ced31627e20d036be0cb41ba9f2c1b92aaeb54cf
+  data.tar.gz: a024ad10967d3734eb8029e68d0d216b0c18c2606d7b48b3b6f6d0b5f0c1e50282b53168ecba1f101dd0f91ea1b92723deb8288622db9dae76d79c509fe223c3

data/README.md

@@ -1,88 +1,74 @@
 # JustMaybe
 
-A simple implementation of the "Maybe" - "Special Case" pattern.  
+An implementation of the "Maybe" pattern.
 
-Maybe provides a generic null object that allows you to defer
-the interpretation of what it means to be null until you need
-to use the object.
+The philosophy of this particular implementation of the Maybe pattern is that you should use the `Maybe` function to wrap values before returning them from any method that could potentially return nil.  This forces the consumer of the returned object to pro-actively acknowledge that it could be nil by forcing them to use the `try` method to access it.
+
+This implementation also does no monkey patching and does not rely on method missing or any other Ruby magic for it's implementation.
+
+It also has a tiny API.  Maybe objects respond to `nothing?`, `something?`, and `try`.
 
-Specifically they allow you to safely chain any number of method
-calls on an object before returning it or a default value.
 
-```ruby
-Maybe(nil).foo.bar.or_else { 'default' }
-```
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your applications Gemfile:
 
-    gem "just_maybe", "~> 0.2.1"
+```ruby
+gem 'just_maybe'
+```
 
 And then execute:
 
-    $ bundle
+```console
+bundle
+```
 
-## Background
+Or install it locally with:
 
-I created JustMaybe because I wanted a really simple solution that didn't
-introduce any changes on Object and I found this paticular syntax very 
-readable.
+```console
+gem install just_maybe
+```
 
-My paticular use case was for presenter objects that needed to aggregate
-lots of information by walking method chains of a supplied objects.  In 
-this sitation the Presenter is aware of the appropriate default value to
-use if the reference fails.  
+Then load it using:
+
+```ruby
+require 'just_maybe'
+```
 
-Using Maybe allows me to get the benefit of null objects without having 
-to modify the underlying code.
 
 ## Examples
 
 ```ruby
 require 'just_maybe'
-# => true 
-
-# Calling Maybe(object) returns that object wrapped in a instance of Maybe
-Maybe(42)
-# => #<Maybe:0x000000010e7c88 @value=42>
-
-# An instance of maybe will pass all valid messages to the underlying value
-# and wrap the result in a new instance Maybe
-Maybe(42).next
-# => <Maybe:0x0000000110b0e8 @value=43> 
-
-# If the Maybe's underlying value doesn't respond to the message it returns
-# nil wrapped in a new instance of Maybe
-Maybe(42).foo
-# => #<Maybe:0x00000001113540 @value=nil>
-
-# This allows you to make arbitrarily long method chains with no risk of raising
-# NoMethodError on a nil object
-Maybe(nil).foo.bar.baz
-# => #<Maybe:0x00000001120830 @value=nil>
-
-# Finally Maybe responds to #or_else { ... }.  This causes the Maybe to return the 
-# underlying value if it exists or the result of the block if it does not.
-Maybe('FOO').downcase.or_else { 'unknown' }
-# => "foo"
-Maybe(nil).downcase.or_else { 'unknown' }
-# => "unknown"
-   
-# There are a number of convenience methods that operate like or_else for common null values
-Maybe(nil).foo.bar.or_a   # => []
-Maybe(nil).foo.bar.or_f   # => 0.0
-Maybe(nil).foo.bar.or_h   # => {}
-Maybe(nil).foo.bar.or_nil # => nil 
-Maybe(nil).foo.bar.or_s   # => ''
-
-# Remember if you don't call or_else or one of it's alternatives you will get back 
-# an instance of Maybe.  It is possible to get the underlying value back by calling
-# __object__ but I'd generally consider using this a code smell.
-Maybe(42).__object__              
-# => 42
-Maybe(42).foo.bar.baz.__object__  
-# => nil
+# => true
+
+# Calling Maybe(object) returns that object wrapped in an instance of Just
+Maybe('anything')
+# => <Just:0x000000020e04f0 @object="anything">
+
+# Calling Maybe(nil) returns an instance of Nothing
+Maybe(nothing)
+# => <Nothing:0x000000020b1718>
+
+# Instances of Just and Nothing respond to the replicate methods nothing? and something?
+Maybe(42).nothing?                   # => false
+Maybe(42).something?                 # => true
+Maybe(nil).nothing?                  # => true
+Maybe(nil).something?                # => false
+
+# When try is called on instances of Just it passes the underlying object to the block
+# and returns the result of the block.
+Maybe(40).try{|m| m.succ.succ }      # => 42
+
+# When try is called on instances of Nothing it returns nil
+Maybe(nil).try{|m| m.succ.succ }     # => nil
 ```
+
+
+## Notice
+
+The public interace of this gem was radically changed with the jump to version 1.0.  If you were using version `0.2` or earlier you should pin the version in your Gemfile at "~> 0.2"
+
 ## Related
    * [Null Objects and Falsiness](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/)
    * [If you gaze into nil, nil gazes also into you](http://robots.thoughtbot.com/post/8181879506/if-you-gaze-into-nil-nil-gazes-also-into-you)

data/just_maybe.gemspec

@@ -4,8 +4,8 @@ require File.expand_path('../lib/just_maybe/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Michael Greenly"]
   gem.email         = ["mgreenly@gmail.com"]
-  gem.description   = %q{A simple implmenetation of the Maybe special case pattern}
-  gem.summary       = %q{A simple implmenetation of the Maybe special case pattern}
+  gem.description   = %q{A simple implmenetation of the Maybe pattern}
+  gem.summary       = %q{A simple implmenetation of the Maybe  pattern}
   gem.homepage      = "https://github.com/mgreenly/just_maybe"
 
   gem.files         = `git ls-files`.split($\)

data/lib/just_maybe/just.rb

@@ -0,0 +1,25 @@
+class Just
+  def initialize(object)
+    @object = object
+  end
+
+  def nothing?
+    false
+  end
+
+  def something?
+    true
+  end
+
+  def try
+    yield @object if block_given?
+  end
+
+  def to_s
+    "Just: #{@object}"
+  end
+end
+
+def Just(object)
+  Just.new(object)
+end

data/lib/just_maybe/nothing.rb

@@ -0,0 +1,27 @@
+require 'singleton'
+
+class Nothing
+  include Singleton
+
+  def initialize
+  end
+
+  def nothing?
+    true
+  end
+
+  def something?
+    false
+  end
+
+  def try
+  end
+
+  def to_s
+    "Nothing"
+  end
+end
+
+#def Nothing
+#  NothingSingleton.instance
+#end

data/lib/just_maybe/version.rb

@@ -1,3 +1,3 @@
 module JustMaybe
-  VERSION = "0.2.2"
+  VERSION = "1.0.0"
 end

data/lib/just_maybe.rb

@@ -1 +1,11 @@
-require 'just_maybe/maybe'
+require 'just_maybe/just'
+require 'just_maybe/nothing'
+
+
+def Maybe(object)
+  if object.nil?
+    Nothing.instance
+  else
+    Just(object)
+  end
+end

data/spec/just_spec.rb

@@ -0,0 +1,22 @@
+require 'just_maybe/just'
+
+describe Just do
+
+  it "just 'anything' is something" do
+    expect(Just('anything')).to be_something
+  end
+
+  it "just 'anything' is not nothing" do
+    expect(Just('anything')).not_to be_nothing
+    expect(Just(nil)).not_to be_nothing
+  end
+
+  it "just nil is something and not nothing" do
+    expect(Just(nil)).to be_something
+    expect(Just(nil)).not_to be_nothing
+  end
+
+  it "just 'anything' yields once with 'anything' to try" do
+    expect(Just('anything').try{|o| o.reverse }).to eq('gnihtyna')
+  end
+end

data/spec/nothing_spec.rb

@@ -0,0 +1,17 @@
+require 'just_maybe/nothing'
+
+describe Nothing.instance do
+  let(:nothing) { Nothing.instance }
+
+  it "Nothing is not something" do
+    expect(nothing).not_to be_something
+  end
+
+  it "Nothing is nothing" do
+    expect(nothing).to be_nothing
+  end
+
+  it "Nothing never yeilds to try" do
+    expect{ nothing.try{|n| raise "an error" } }.not_to raise_error
+  end
+end

metadata

@@ -1,56 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: just_maybe
 version: !ruby/object:Gem::Version
-  version: 0.2.2
-  prerelease: 
+  version: 1.0.0
 platform: ruby
 authors:
 - Michael Greenly
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-17 00:00:00.000000000 Z
+date: 2014-08-03 00:00:00.000000000 Z
 dependencies: []
-description: A simple implmenetation of the Maybe special case pattern
+description: A simple implmenetation of the Maybe pattern
 email:
 - mgreenly@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - just_maybe.gemspec
 - lib/just_maybe.rb
-- lib/just_maybe/maybe.rb
+- lib/just_maybe/just.rb
+- lib/just_maybe/nothing.rb
 - lib/just_maybe/version.rb
-- spec/maybe_spec.rb
+- spec/just_spec.rb
+- spec/nothing_spec.rb
 homepage: https://github.com/mgreenly/just_maybe
 licenses: []
+metadata: {}
 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: 
-rubygems_version: 1.8.19
+rubygems_version: 2.2.2
 signing_key: 
-specification_version: 3
-summary: A simple implmenetation of the Maybe special case pattern
+specification_version: 4
+summary: A simple implmenetation of the Maybe  pattern
 test_files:
-- spec/maybe_spec.rb
+- spec/just_spec.rb
+- spec/nothing_spec.rb

data/lib/just_maybe/maybe.rb

@@ -1,61 +0,0 @@
-class Maybe < BasicObject
-  def initialize(object)
-    begin
-      @object = object.__object__
-    rescue
-      @object = object
-    end 
-  end
-
-  def __object__
-    @object
-  end
-
-  def inspect
-    ::Kernel.sprintf('#<Maybe:0x%0.14x @object=%s>', __id__ * 2, @object.inspect)
-  end
-
-  def method_missing(method, *args, &block)
-    begin
-      ::Maybe.new(@object.__send__(method, *args, &block))
-    rescue ::NoMethodError
-      ::Maybe.new(nil)
-    end
-  end
-
-  def or_else(&block)
-    @object ? @object : yield
-  end
-
-  def or_a
-    or_else { [] }
-  end
-
-  def or_f
-    or_else { 0.0 }
-  end
-
-  def or_false
-    or_else { false }
-  end
-
-  def or_h
-    or_else { {} }
-  end
-
-  def or_i
-    or_else { 0 }
-  end
-
-  def or_nil
-    or_else { nil }
-  end
-
-  def or_s
-    or_else { '' }
-  end
-end
-
-def Maybe(object)
-  Maybe.new(object)
-end

data/spec/maybe_spec.rb

@@ -1,90 +0,0 @@
-require 'just_maybe/maybe'
-
-describe Maybe do
-  let(:object) { double }
-
-  before do
-    object.stub(:__object__).and_raise(NoMethodError)
-  end
-
-  it "delegates messages to wrapped object" do
-    object.should_receive(:foo).with('bar')
-    Maybe(object).foo('bar')
-  end
-
-  it "calling methods that don't exist return Maybe(nil)" do
-    Maybe(nil).foo.__object__.should be_nil 
-  end
-
-  it "it doesn't nest" do
-    Maybe(Maybe(nil)).__object__.should_not be_instance_of(Maybe)
-  end
-
-  it "__object__ unwraps the underlying object" do
-    Maybe(object).__object__.should be(object)
-  end
-
-  it "#or_else returns the underlying object when it's not nil" do
-    Maybe(object).or_else{'unexpected result'}.should == object
-  end
-
-  it "#or_else yields to supplied block when the underlying object is nil" do
-    Maybe(nil).or_else{'expected result'}.should == 'expected result'
-  end
-
-  it "#or_a returns the underlying object when it's not nil" do
-    Maybe(object).or_a.should be(object)
-  end
-
-  it "#or_a defaults to []" do
-    Maybe(nil).or_a.should == []
-  end
-
-  it "#or_f returns the underlying object when it's not nil" do
-    Maybe(object).or_f.should be(object)
-  end
-
-  it "#or_f defaults to 0.0" do
-    Maybe(nil).or_f.should == 0.0
-  end
-
-  it "#or_false returns the underlying object when it's not nil" do
-    Maybe(object).or_false.should be(object)
-  end
-
-  it "#or_false defaults to false" do
-    Maybe(nil).or_false.should be(false)
-  end
-
-  it "#or_h returns the underlying object when it's not nil" do
-    Maybe(object).or_h.should be(object)
-  end
-
-  it "#or_h defaults to {}" do
-    Maybe(nil).or_h.should == {} 
-  end
-
-  it "#or_i returns the underlying object when it's not nil" do
-    Maybe(object).or_i.should be(object)
-  end
-
-  it "#or_i defaults to 0" do
-    Maybe(nil).or_i.should == 0 
-  end
-
-  it "#or_nil returns the underlying object when it's not nil" do
-    Maybe(object).or_nil.should be(object)
-  end
-
-  it "#or_nil defaults to nil" do
-    Maybe(nil).or_nil.should == nil 
-  end
-
-  it "#or_s returns the underlying object when it's not nil" do
-    Maybe(object).or_s.should be(object)
-  end
-
-  it "#or_s defaults to ''" do
-    Maybe(nil).or_s.should == '' 
-  end
-end