wrapped 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*swp

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c)2011, Mike Burns
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * Neither the name of Mike Burns nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,169 @@
+Wrapped
+-------
+
+This gem is a tool you can use while developing your API to help consumers of
+your code to find bugs earlier and faster. It works like this: any time you
+write a method that could produce nil, you instead write a method that produces
+a wrapped value.
+
+Example
+-------
+
+Here's an example along with how it can help with errors:
+
+Say you have a collection of users along with a method for accessing the first
+user:
+
+    class UserCollection
+      def initialize(users)
+        @users = users
+      end
+  
+      def first_user
+        @users.first
+      end
+    end
+
+Now your friend uses your awesome UserCollection code:
+
+    class FriendGroups
+      def initialize(user_collections)
+        @user_collections = user_collections
+      end
+
+      def first_names
+        @user_collections.map do |user_collection|
+          user_collection.first_user.first_name
+        end
+      end
+    end
+
+And then she tries it:
+
+    FriendGroups.new([UserCollection.new([])]).first_names
+
+... and it promptly blows up:
+
+    NoMethodError: undefined method `first_name' for nil:NilClass
+            from (irb):52:in `first_names'
+            from (irb):51:in `map'
+            from (irb):51:in `first_names'
+            from (irb):57
+
+But that's odd; UserCollection definitely has a `#first_names` method, and we
+definitely passed a UserCollection, and ... oooh, we passed no users, and so we
+got `nil`.
+
+Right.
+
+Instead what you want to do is wrap it. Wrap that nil. Make the user know that
+they have to consider the result.
+
+    class UserCollection
+      def initialize(users)
+        @users = users
+      end
+  
+      def first_user
+        @users.first.wrapped
+      end
+    end
+
+Now in your documentation you explain that it produces a wrapped value. And
+people who skip documentation and instead read source code will see that it is
+wrapped.
+
+So they unwrap it, because they must. They can't even get a happy path without
+unwrapping it.
+
+    class FriendGroups
+      def initialize(user_collections)
+        @user_collections = user_collections
+      end
+
+      def first_names
+        @user_collections.map do |user_collection|
+          user_collection.first_user.unwrap_or('') {|user| user.first_name }
+        end
+      end
+    end
+
+Cool Stuff
+----------
+
+A wrapped value mixes in Enumerable. The functional world would say "that's a
+functor!". They're close enough.
+
+This means that you can `map`, `inject`, `to_a`, `any?`, and so on over your
+wrapped value. By wrapping it you've just made it more powerful!
+
+For example:
+
+    irb(main):054:0> 1.wrapped.inject(0) {|_, n| n+1}
+    => 2
+    irb(main):055:0> nil.wrapped.inject(0) {|_, n| n+1}
+    => 0
+
+And then we have `try`, which you can use to produce another wrapped object:
+
+    irb> 1.wrapped.try {|n| (n + 1).wrapped}.try {|n| (n*2).wrapped}.unwrap
+    => 4
+
+Those same people who will exclaim things about functors will, at this point,
+get giddy about monads. I mean, they're right, but they can relax. It's just a
+monad.
+
+Those people ("what do you mean, 'those people'?!") may prefer the `fmap`
+method:
+
+    irb> 1.wrapped.fmap {|n| n+1}.unwrap_or(0) {|n| n+4}
+    => 6
+
+Other Methods
+-------------
+
+Then we added some convenience methods to all of this. Here's a tour:
+
+    irb> require 'wrapped'
+    => true
+    irb> 1.wrapped.unwrap_or(-1)
+    => 1
+    irb> nil.wrapped.unwrap_or(-1)
+    => -1
+    irb> 1.wrapped.present {|n| p n }.blank { puts "nothing!" }
+    1
+    => #<Present:0x7fc570aed0e8 @value=1>
+    irb> nil.wrapped.present {|n| p n }.blank { puts "nothing!" }
+    nothing!
+    => #<Blank:0x7fc570ae21c0>
+    irb> 1.wrapped.unwrap
+    => 1
+    irb> nil.wrapped.unwrap
+    IndexError: Blank has no value
+    	from /home/mike/wrapped/lib/wrapped/types.rb:43:in `unwrap'
+    	from (irb):7
+    irb> 1.wrapped.present?
+    => true
+    irb> nil.wrapped.present?
+    => false
+    irb> nil.wrapped.blank?
+    => true
+    irb> 1.wrapped.blank?
+    => false
+    irb> 1.wrapped.unwrap_or(0) {|n| n * 100}
+    => 100
+    irb> nil.wrapped.unwrap_or(0) {|n| n * 100}
+    => 0
+
+Inspiration
+-----------
+
+Inspired by a conversation about a post on the thoughtbot blog titled [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).
+
+Most ideas are from Haskell and Scala. This is not new: look into the maybe
+functor or the option class for more.
+
+Copyright
+---------
+Copyright 2011 Mike Burns

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/wrapped.rb

@@ -0,0 +1,2 @@
+require 'wrapped/version'
+require 'wrapped/injection'

data/lib/wrapped/blank.rb

@@ -0,0 +1,66 @@
+# The class represents a lack of something.
+class Blank
+  include Enumerable
+
+  # It is an error (specifically, an IndexError) to use this method.
+  def unwrap
+    raise IndexError.new("Blank has no value")
+  end
+
+  # Produce the value that is passed in.
+  #
+  # > w.unwrap_or(0)
+  def unwrap_or(default)
+    default
+  end
+
+  # Does nothing, returning itself. This is chainable. See blank for its
+  # companion.
+  #
+  # w.present.blank { puts "Missing" }
+  def present
+    self
+  end
+
+  # Call the block then return itself. This is chainable. See present for its
+  # companion.
+  #
+  # w.blank { puts "I got nothing" }.present {|n| puts "got #{n}" }
+  def blank(&block)
+    block.call
+    self
+  end
+
+  # Produce the empty list.
+  #
+  # This class mixes in the Enumerable module, which relies on this.
+  #
+  # > w.each {|n| puts n }
+  def each
+    []
+  end
+
+  # False; this is not an instance of a wrapped value.
+  def present?
+    false
+  end
+
+  # True; this is an instance of nothing.
+  def blank?
+    true
+  end
+
+  # Do nothing, returning itself.
+  #
+  # > w.try {|n| n+1 }
+  def try
+    self
+  end
+
+  # Do nothing, returning itself.
+  #
+  # > w.fmap {|n| n+1 }
+  def fmap
+    self
+  end
+end

data/lib/wrapped/injection.rb

@@ -0,0 +1,22 @@
+require 'wrapped/present'
+require 'wrapped/blank'
+
+class Object
+  # Wrap the object, forcing the user to be aware of the potential for a nil
+  # value by unwrapping it.
+  #
+  # See the Present class for details on how to unwrap it.
+  def wrapped
+    Present.new(self)
+  end
+end
+
+class NilClass
+  # Wrap the nil, which is exactly the whole point. At this point the user must
+  # explictly deal with the nil, aware that it exists.
+  #
+  # See the Blank class and the README for details on how to work with this.
+  def wrapped
+    Blank.new
+  end
+end

data/lib/wrapped/present.rb

@@ -0,0 +1,89 @@
+# A class that represents a wrapped value. This class holds something that is
+# not nil.
+class Present
+  include Enumerable
+
+  # Use Object#wrapped and NilClass#wrapped instead.
+  def initialize(value) # :nodoc:
+    @value = value
+  end
+
+  # Produce the value, unwrapped.
+  #
+  # If a block is given apply the block to the value and produce that.
+  #
+  # > w.unwrap_or(0)
+  # > w.unwrap_or("hello") {|s| "Hi, #{s}" }
+  def unwrap_or(_)
+    if block_given?
+      yield unwrap
+    else
+      unwrap
+    end
+  end
+
+  # Invoke the block on the value, unwrapped. This method produces the wrapped
+  # value again, making it chainable. See `blank' for its companion.
+  #
+  # > w.present {|s| puts "Hello, #{s}" }.blank { puts "Do I know you?" }
+  def present(&block)
+    block.call(unwrap)
+    self
+  end
+
+  # Do nothing then produce the wrapped value, making it chainable. See
+  # `present' for its companion.
+  #
+  # > w.blank { puts "Symbol not found" }.present {|s| puts users[s]}
+  def blank(&ignored)
+    self
+  end
+
+  # Produce the singleton list with the unwrapped value as its only member.
+  #
+  # If a block is passed, it is run against the unwrapped value.
+  #
+  # This class mixes in Enumerable, which is controlled by this method.
+  #
+  # > w.each {|n| puts "Found #{n}" }
+  def each
+    yield unwrap if block_given?
+    [unwrap]
+  end
+
+  # The raw value. I doubt you need this method.
+  def unwrap
+    @value
+  end
+
+  # True; this is an instance of a wrapped value.
+  def present?
+    true
+  end
+
+  # False; this does not wrap a nil.
+  def blank?
+    false
+  end
+
+  # Run a block against the unwrapped value, producing the result of the block.
+  #
+  # > w.try {|n| n+1 }
+  #
+  # Also, you can use this like you would use >>= in Haskell. This and wrapped
+  # make it a monad.
+  #
+  # > w.try {|n| (n+1).wrapped }
+  def try
+    yield unwrap
+  end
+
+  # Run a block within the wrapper. This produces a wrapped value.
+  #
+  # > w.try {|n| n+1 }
+  #
+  # This makes it a functor.
+  def fmap
+    (yield unwrap).wrapped
+  end
+end

data/lib/wrapped/version.rb

@@ -0,0 +1,3 @@
+module Wrapped
+  VERSION = "0.0.1"
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'wrapped'

data/spec/wrapped_spec.rb

@@ -0,0 +1,175 @@
+require 'spec_helper'
+
+describe Wrapped, 'conversion' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it "converts the value to a Present" do
+    just.should be_instance_of(Present)
+  end
+
+  it "converts the nil to a Blank" do
+    nothing.should be_instance_of(Blank)
+  end
+end
+
+describe Wrapped, 'accessing' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it 'produces the value of the wrapped object' do
+    just.unwrap.should == value
+  end
+
+  it 'raises an exception when called on the wrapped nil' do
+    expect { nothing.unwrap }.to raise_error(IndexError)
+  end
+end
+
+describe Wrapped, 'callbacks' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it 'calls the proper callback for a wrapped value' do
+    result = false
+    just.present {|v| result = v}
+    result.should be_true
+  end
+
+  it 'calls the proper callback for a wrapped nil' do
+    result = false
+    nothing.blank {result = true}
+    result.should be_true
+  end
+
+  it 'ignores the other callback for a wrapped value' do
+    result = true
+    just.blank { result = false }
+    result.should be_true
+  end
+
+
+  it 'ignores the other callback for a wrapped nil' do
+    result = true
+    nothing.present { result = false }
+    result.should be_true
+  end
+
+  it 'chains for wrapped values' do
+    result = false
+    just.present { result = true }.blank { result = false }
+    result.should be_true
+  end
+
+  it 'chains for wrapped nils' do
+    result = false
+    nothing.present { result = false }.blank { result = true }
+    result.should be_true
+  end
+end
+
+# This behavior is different from Haskell and Scala.
+# It is done this way for consistency with Ruby.
+# See the functor description later for `fmap'.
+describe Wrapped, 'enumerable' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it 'acts over the value for #each on a wrapped value' do
+    result = -1
+    just.each {|v| result = v }
+    result.should == value
+  end
+
+  it 'produces a singleton array of the value for a wrapped value on #each' do
+    just.each.should == [value]
+  end
+
+  it 'skips the block for #each on a wrapped nil' do
+    result = -1
+    nothing.each {|v| result = v }
+    result.should == -1
+  end
+
+  it 'produces the empty array for a wrapped nil on #each' do
+    nothing.each.should be_empty
+  end
+
+  it 'maps over the value for a wrapped value' do
+    just.map {|n| n + 1}.should == [value+1]
+  end
+
+  it 'map produces the empty list for a wrapped nil' do
+    nothing.map {|n| n + 1}.should == []
+  end
+end
+
+describe Wrapped, 'queries' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it 'knows whether it is present' do
+    just.should be_present
+    nothing.should_not be_present
+  end
+
+  it 'knows whether it is blank' do
+    just.should_not be_blank
+    nothing.should be_blank
+  end
+end
+
+describe Wrapped, 'unwrap_or' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it 'produces the value for a wrapped value' do
+    just.unwrap_or(-1).should == value
+  end
+
+  it 'produces the default for a wrapped nil' do
+    nothing.unwrap_or(-1).should == -1
+  end
+
+  it 'produces the value of the block for a wrapped object' do
+    just.unwrap_or(-1) {|n| n+1}.should == value + 1
+  end
+
+  it 'produces the default for a wrapped nil even with a block' do
+    nothing.unwrap_or(-1) {2}.should == -1
+  end
+end
+
+describe Wrapped, 'monadic' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it 'produces the value from #try for a wrapped value' do
+    just.try {|n| (n+1).wrapped }.unwrap.should == value+1
+  end
+
+  it 'produces blank from #try for a wrapped nil' do
+    nothing.try {|n| (n+1).wrapped}.should be_blank
+  end
+end
+
+describe Wrapped, 'functor' do
+  let(:value)   { 1 }
+  let(:just)    { 1.wrapped }
+  let(:nothing) { nil.wrapped }
+
+  it 'unwraps, applies the block, then re-wraps for a wrapped value' do
+    just.fmap {|n| n+1}.unwrap.should == value+1
+  end
+
+  it 'produces the blank for a wrapped nil' do
+    nothing.fmap {|n| n+1}.should be_blank
+  end
+end

data/wrapped.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "wrapped/version"
+
+Gem::Specification.new do |s|
+  s.name        = "wrapped"
+  s.version     = Wrapped::VERSION
+  s.authors     = ["Mike Burns"]
+  s.email       = ["mike@mike-burns.com"]
+  s.homepage    = ""
+  s.summary     = %q{The maybe functor for Ruby}
+  s.description = %q{The unchecked nil is a dangerous concept leading to NoMethodErrors at runtime. It would be better if you were forced to explictly unwrap potentially nil values. This library provides mechanisms and convenience methods for making this more possible.}
+
+  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"]
+
+  s.add_development_dependency('rspec')
+  s.add_development_dependency('rake')
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification 
+name: wrapped
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Mike Burns
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-29 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: The unchecked nil is a dangerous concept leading to NoMethodErrors at runtime. It would be better if you were forced to explictly unwrap potentially nil values. This library provides mechanisms and convenience methods for making this more possible.
+email: 
+- mike@mike-burns.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/wrapped.rb
+- lib/wrapped/blank.rb
+- lib/wrapped/injection.rb
+- lib/wrapped/present.rb
+- lib/wrapped/version.rb
+- spec/spec_helper.rb
+- spec/wrapped_spec.rb
+- wrapped.gemspec
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: The maybe functor for Ruby
+test_files: []
+