null_and_void 1.0.0

data/README.md

@@ -0,0 +1,240 @@
+Null And Void
+================================
+
+**Create Null Objects with Ease**
+
+<img src="http://cdn.memegenerator.net/instances/300x/34275719.jpg" align="right" />
+
+Using the Null Object pattern in Ruby is rather easy so why create a gem?
+
+I found myself using the same implementation around the [Null Object
+pattern](https://en.wikipedia.org/wiki/Null_object_pattern#Ruby) over and over.
+Rather than duplicating the logic in every one of my projects, I decided to
+package it up as a gem.
+
+In the process of doing research to make sure I was implementing this gem the
+best way possible, I came across [an article by Avdi
+Grimm](http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness). In the
+article Avdi brings up a lot of the same ideas I was implementing in my gem.
+Additionally, he had come up with some [other](#helper-methods)
+[nicities](#maybies) that I hadn't thought of.
+
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+
+Installation
+--------------------------------
+
+    gem install null_and_void
+
+Usage
+--------------------------------
+
+Whenever you want to return a Null Object you can do something like:
+
+```ruby
+def first_tps_line_item
+  TpsReport.line_items.first || NullAndVoid::NullObject.instance
+end
+```
+
+Alternatively, you can [define your own Null Objects](#defineyourownnullobjects)
+such as:
+
+```ruby
+def first_tps_line_item
+  TpsReport.line_items.first || NullTpsLineItem.instance
+end
+```
+
+If you decide to [use the mixin](#includeintoyourobjectsoptional) you can call
+the `as_null_object` method on the class and use convention to figure out which
+Null Object you want:
+
+```ruby
+def first_tps_line_item
+  TpsReport.line_items.first || TpsLineItem.as_null_object
+end
+```
+
+In this case it will return a `NullTpsLineItem` if it's defined and otherwise
+will return a `NullAndVoid::NullObject`.
+
+Implementation
+--------------------------------
+
+### Method Implementation #####################################################
+
+With the exception of those defined below, any calls to any methods on a Null
+Object that inherits from `NullAndVoid::NullObject` will result in itself.
+
+**Example:**
+
+```ruby
+null_object = NullAndVoid::NullObject.instance
+
+null_object == null_object.foobar # => true
+```
+
+### Helper Methods ############################################################
+
+Many common Ruby methods are implemented as 'noops' such as:
+
+```ruby
+null_object = NullUser.instance
+
+null_object.to_i      # => 0
+null_object.to_int    # => 0
+null_object.to_f      # => 0.0
+null_object.to_r      # => (0/1)
+null_object.to_a      # => []
+null_object.to_ary    # => []
+null_object.to_hash   # => {}
+null_object.to_html   # => ''
+null_object.to_json   # => ''
+null_object.to_xml    # => ''
+null_object.to_model  # => User.new
+null_object.to_s      # => ''
+```
+
+### Falsity ###################################################################
+
+`NullAndVoid::NullObject` attempts to be falsey whenever possible however it's
+my opinion that this is an anti-pattern and only the basic attempts are made to
+make this work.  For example:
+
+```ruby
+null_object = NullAndVoid::NullObject.instance
+
+!null_object          # => true
+null_object.nil?      # => true
+null_object.blank?    # => true
+null_object.present?  # => false
+```
+
+### Singleton Implementation ##################################################
+
+`NullAndVoid::NullObject` is a singleton.  All calls to an implementation of it
+will result in the same object.  Therefore:
+
+```ruby
+NullUser.instance == User.new.as_null_object == User.as_null_object # => true
+```
+
+### Define Your Own Null Objects ##############################################
+
+When implementing a Null Object for a specific class that you own, simply
+include `NullAndVoid::Nullified` like so:
+
+```ruby
+require 'null_and_void/nullified'
+
+class NullUser
+  include NullAndVoid::Nullified
+
+  def admin?
+    false
+  end
+end
+```
+
+### Maybies ###################################################################
+
+Unfortunately when you're programming in the 'Real World &copy;" you don't
+always have control over the API you're using.  And sometimes, those APIs,
+rather than doing the sane thing and always returning the same type no matter
+what, instead return nils.
+
+In these situations, you could do this:
+
+```ruby
+class Foo
+  def bar
+    call_some_method_that_could_return_nils || NullAndVoid::NullObject.instance
+  end
+end
+```
+
+Or instead, you can simply mixin `NullAndVoid::Mayby` and it will handle that
+for you. For example:
+
+```ruby
+class Foo
+  include NullAndVoid::Maybe
+
+  def bar
+    maybe(call_some_method_that_could_return_nils)
+  end
+end
+```
+
+If you'd rather not mix it into your class, you can also just call it directly:
+
+```ruby
+class Foo
+  def bar
+    NullAndVoid.maybe(call_some_method_that_could_return_nils)
+  end
+end
+```
+
+### Include Into Your Objects (Optional) ######################################
+
+You can add Null Object creation to your class by including
+`NullAndVoid::ModelSupport`.
+
+```ruby
+class User
+  include NullAndVoid::ModelSupport
+
+  def admin?
+    type == 'admin'
+  end
+end
+```
+
+This will endow your class with two methods `.as_null_object` and
+`#as_null_object`. Both of which return either the Null Object for that class
+(eg `NullUser`) or the generic `NullAndVoid::NullObject`.
+
+Now, when calling:
+
+```ruby
+User.as_null_object
+```
+
+or:
+
+```ruby
+User.new.as_null_object
+```
+
+Will return:
+
+```ruby
+NullUser.instance
+```
+
+Issues
+------
+
+If you have problems, please create a [Github issue](issues).
+
+Credits
+-------
+
+![thekompanee](http://www.thekompanee.com/public_files/kompanee-github-readme-logo.png)
+
+null_and_void is maintained by [The Kompanee, Ltd.](http://www.thekompanee.com)
+
+The names and logos for The Kompanee are trademarks of The Kompanee, Ltd.
+
+License
+-------
+
+null_and_void is Copyright &copy; 2013 The Kompanee. It is free software, and may be redistributed under the terms specified in the LICENSE file.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/null_and_void.rb

@@ -0,0 +1,7 @@
+require 'null_and_void/version'
+require 'null_and_void/null_object'
+require 'null_and_void/maybe'
+
+module NullAndVoid
+  extend NullAndVoid::Maybe
+end

data/lib/null_and_void/convertible.rb

@@ -0,0 +1,54 @@
+require 'active_support/inflector/methods'
+
+module NullAndVoid
+  module Convertible
+    def to_i
+      0
+    end
+
+    alias :to_int :to_i
+
+    def to_f
+      0.0
+    end
+
+    def to_r
+      Rational(0)
+    end
+
+    def to_a
+      Array.new
+    end
+
+    alias :to_ary :to_a
+
+    def to_hash
+      Hash.new
+    end
+
+    def to_html
+      ''
+    end
+
+    def to_json
+      ''
+    end
+
+    def to_xml
+      ''
+    end
+
+    def to_s
+      ''
+    end
+
+    def to_model
+      base_path         = ActiveSupport::Inflector.demodulize(self.class.name)
+      module_path       = ActiveSupport::Inflector.deconstantize(self.class.name)
+      source_model      = base_path.gsub(/^Null/, '')
+      source_model_path = "#{module_path}::#{source_model}"
+
+      ActiveSupport::Inflector.constantize(source_model_path).new
+    end
+  end
+end

data/lib/null_and_void/falsifiable.rb

@@ -0,0 +1,19 @@
+module NullAndVoid
+  module Falsifiable
+    def !
+      true
+    end
+
+    def blank?
+      true
+    end
+
+    def nil?
+      true
+    end
+
+    def present?
+      false
+    end
+  end
+end

data/lib/null_and_void/maybe.rb

@@ -0,0 +1,9 @@
+require 'null_and_void/null_object'
+
+module NullAndVoid
+  module Maybe
+    def maybe(parameter)
+      parameter.nil? ? NullAndVoid::NullObject.instance : parameter
+    end
+  end
+end

data/lib/null_and_void/model_support.rb

@@ -0,0 +1,27 @@
+require 'active_support/inflector/methods'
+require 'null_and_void/null_object'
+
+module NullAndVoid
+  module ModelSupport
+    module ClassMethods
+      def as_null_object
+        base_path         = ActiveSupport::Inflector.demodulize(self.name)
+        module_path       = ActiveSupport::Inflector.deconstantize(self.name)
+        null_object_base  = "Null#{base_path}"
+        source_model_path = "#{module_path}::#{null_object_base}"
+
+        ActiveSupport::Inflector.constantize(source_model_path).new
+      rescue NameError
+        NullAndVoid::NullObject.instance
+      end
+    end
+
+    def as_null_object
+      self.class.as_null_object
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+  end
+end

data/lib/null_and_void/null_object.rb

@@ -0,0 +1,7 @@
+require 'null_and_void/nullified'
+
+module NullAndVoid
+  class NullObject
+    include ::NullAndVoid::Nullified
+  end
+end

data/lib/null_and_void/nullified.rb

@@ -0,0 +1,15 @@
+require 'singleton'
+require 'null_and_void/stubbable'
+require 'null_and_void/convertible'
+require 'null_and_void/falsifiable'
+
+module NullAndVoid
+  module Nullified
+    def self.included(base)
+      base.send(:include, Singleton)
+      base.send(:include, Stubbable)
+      base.send(:include, Convertible)
+      base.send(:include, Falsifiable)
+    end
+  end
+end

data/lib/null_and_void/stubbable.rb

@@ -0,0 +1,7 @@
+module NullAndVoid
+  module Stubbable
+    def method_missing(*args, &block)
+      self
+    end
+  end
+end

data/lib/null_and_void/version.rb

@@ -0,0 +1,3 @@
+module NullAndVoid
+  VERSION = '1.0.0'
+end

data/spec/convertible_spec.rb

@@ -0,0 +1,70 @@
+require 'rspectacular'
+require 'null_and_void/convertible'
+
+module FooBar
+  class NullObject
+    include NullAndVoid::Convertible
+  end
+
+  class NullBaz
+    include NullAndVoid::Convertible
+  end
+
+  class Object
+  end
+end
+
+describe NullAndVoid::Convertible do
+  let(:null_object) { FooBar::NullObject.new }
+
+  it 'is zero when the attempt is made to convert it to an Integer' do
+    null_object.to_i.should be_an Integer
+    null_object.to_i.should be_zero
+
+    null_object.to_int.should be_an Integer
+    null_object.to_int.should be_zero
+  end
+
+  it 'is zero when the attempt is made to convert it to a Float' do
+    null_object.to_f.should be_a Float
+    null_object.to_f.should be_zero
+  end
+
+  it 'is zero when the attempt is made to convert it to a Rational' do
+    null_object.to_r.should be_a Rational
+    null_object.to_r.should be_zero
+  end
+
+  it 'is an empty Array when the attempt is made to convert it to an Array' do
+    null_object.to_a.should   eql []
+    null_object.to_ary.should eql []
+  end
+
+  it 'is an empty Hash when the attempt is made to convert it to an Hash' do
+    null_object.to_hash.should eql Hash.new
+  end
+
+  it 'is an empty String when the attempt is made to convert it to HTML' do
+    null_object.to_html.should eql ''
+  end
+
+  it 'is an empty String when the attempt is made to convert it to JSON' do
+    null_object.to_json.should eql ''
+  end
+
+  it 'is an empty String when the attempt is made to convert it to XML' do
+    null_object.to_xml.should eql ''
+  end
+
+  it 'is an empty String when the attempt is made to convert it to a String' do
+    null_object.to_s.should eql ''
+  end
+
+  it 'is the class the Null Object is based on when the attempt is made to convert it to a value object' do
+    null_object.to_model.should be_a FooBar::Object
+  end
+
+  it 'raises an error if the model the Null Object is based on does not exist' do
+    expect { FooBar::NullBaz.new.to_model }.to raise_error NameError
+  end
+end

data/spec/falsifiable_spec.rb

@@ -0,0 +1,26 @@
+require 'rspectacular'
+require 'null_and_void/falsifiable'
+
+class NullObject
+  include NullAndVoid::Falsifiable
+end
+
+describe NullAndVoid::Falsifiable do
+  let(:null_object) { NullObject.new }
+
+  it 'can be double inverted to be false' do
+    (!!null_object).should be_false
+  end
+
+  it 'is blank' do
+    null_object.should be_blank
+  end
+
+  it 'is nil' do
+    null_object.should be_nil
+  end
+
+  it 'is not present' do
+    null_object.should_not be_present
+  end
+end

data/spec/maybe_spec.rb

@@ -0,0 +1,20 @@
+require 'rspectacular'
+require 'null_and_void/maybe'
+
+class MyObject
+  include NullAndVoid::Maybe
+end
+
+describe NullAndVoid::Maybe do
+  context 'when it is passed a nil' do
+    it 'is a null object' do
+      MyObject.new.maybe(nil).should be_a NullAndVoid::NullObject
+    end
+  end
+
+  context 'when it is passed something other than nil' do
+    it 'is the non-nil object' do
+      MyObject.new.maybe(1).should eql 1
+    end
+  end
+end

data/spec/model_support_spec.rb

@@ -0,0 +1,31 @@
+require 'rspectacular'
+require 'null_and_void/model_support'
+
+module FooBar
+  class MyNullableModel
+    include NullAndVoid::ModelSupport
+  end
+
+  class NullMyNullableModel
+  end
+end
+
+class NonNullableModel
+  include NullAndVoid::ModelSupport
+end
+
+describe NullAndVoid::ModelSupport do
+  let(:model) { FooBar::MyNullableModel.new }
+
+  it 'can convert a model into its Null Object if it exists' do
+    model.as_null_object.should be_a FooBar::NullMyNullableModel
+  end
+
+  it "can convert the model's class into its Null Object if it exists" do
+    model.class.as_null_object.should be_a FooBar::NullMyNullableModel
+  end
+
+  it 'can convert a model into a generic Null Object a model-specific Null Object does not exist' do
+    NonNullableModel.as_null_object.should be_a NullAndVoid::NullObject
+  end
+end

data/spec/null_and_void_spec.rb

@@ -0,0 +1,8 @@
+require 'rspectacular'
+require 'null_and_void'
+
+describe NullAndVoid do
+  it 'can perform "maybies"' do
+    NullAndVoid.maybe(nil).should be_a NullAndVoid::NullObject
+  end
+end

data/spec/null_object_spec.rb

@@ -0,0 +1,22 @@
+require 'rspectacular'
+require 'null_and_void/null_object'
+
+describe NullAndVoid::NullObject do
+  let(:null_object) { NullAndVoid::NullObject.instance }
+
+  it 'is a singleton' do
+    null_object == NullAndVoid::NullObject.instance
+  end
+
+  it 'is stubbable' do
+    null_object.should be_a NullAndVoid::Stubbable
+  end
+
+  it 'is convertible' do
+    null_object.should be_a NullAndVoid::Convertible
+  end
+
+  it 'is falsifiable' do
+    null_object.should be_a NullAndVoid::Falsifiable
+  end
+end

data/spec/nullified_spec.rb

@@ -0,0 +1,39 @@
+require 'rspectacular'
+require 'null_and_void/null_object'
+require 'null_and_void/nullified'
+
+class NullWidget
+  include NullAndVoid::Nullified
+
+  def my_null_object_method
+    'i am null'
+  end
+end
+
+describe NullAndVoid::Nullified do
+  let(:null_object) { NullWidget.instance }
+
+  it 'is a singleton' do
+    null_object == NullWidget.instance
+  end
+
+  it 'is not a NullAndVoid::NullObject singleton' do
+    null_object != NullAndVoid::NullObject.instance
+  end
+
+  it 'handles undefined methods' do
+    null_object.foobar.should eql NullWidget.instance
+  end
+
+  it 'handles conversions' do
+    null_object.to_a.should eql []
+  end
+
+  it 'is falsifiable' do
+    (!!null_object).should be_false
+  end
+
+  it 'can implement its own methods' do
+    null_object.my_null_object_method.should eql 'i am null'
+  end
+end

data/spec/stubbable_spec.rb

@@ -0,0 +1,14 @@
+require 'rspectacular'
+require 'null_and_void/stubbable'
+
+class NullObject
+  include NullAndVoid::Stubbable
+end
+
+describe NullAndVoid::Stubbable do
+  let(:null_object) { NullObject.new }
+
+  it 'returns itself for all unknown method calls' do
+    null_object.foobar.should eql null_object
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: null_and_void
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- jfelchner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    none: false
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    none: false
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.12'
+    none: false
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.12'
+    none: false
+- !ruby/object:Gem::Dependency
+  name: rspectacular
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    none: false
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    none: false
+description: Makes generating Null Objects easy.
+email: accounts+git@thekompanee.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- lib/null_and_void/convertible.rb
+- lib/null_and_void/falsifiable.rb
+- lib/null_and_void/maybe.rb
+- lib/null_and_void/model_support.rb
+- lib/null_and_void/null_object.rb
+- lib/null_and_void/nullified.rb
+- lib/null_and_void/stubbable.rb
+- lib/null_and_void/version.rb
+- lib/null_and_void.rb
+- Rakefile
+- README.md
+- spec/convertible_spec.rb
+- spec/falsifiable_spec.rb
+- spec/maybe_spec.rb
+- spec/model_support_spec.rb
+- spec/null_and_void_spec.rb
+- spec/null_object_spec.rb
+- spec/nullified_spec.rb
+- spec/stubbable_spec.rb
+homepage: https://github.com/jfelchner/null_and_void
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset = UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project: null_and_void
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Easy Null Objects
+test_files:
+- spec/convertible_spec.rb
+- spec/falsifiable_spec.rb
+- spec/maybe_spec.rb
+- spec/model_support_spec.rb
+- spec/null_and_void_spec.rb
+- spec/null_object_spec.rb
+- spec/nullified_spec.rb
+- spec/stubbable_spec.rb
+has_rdoc: