naught 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+/naught.org
+/naught.html

data/.rspec

@@ -0,0 +1 @@
+-fs --color --order rand

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in naught.gemspec
+gemspec
+
+group :test do
+  gem "libnotify"
+end

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec, cli: '-fs --color --order rand' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Avdi Grimm
+
+MIT License
+
+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.org

@@ -0,0 +1,340 @@
+#+TITLE: Naught: A Ruby Null Object Library
+
+* A quick intro to Naught
+
+*What's all this now then?*
+
+Naught is a toolkit for building  [[http://en.wikipedia.org/wiki/Null_Object_pattern][Null Objects]] in Ruby.
+
+*What's that supposed to mean?*
+
+Null Objects can make your code more [[http://confidentruby.com][confident]].
+
+Here's a method that's not very sure of itself.
+
+#+BEGIN_SRC ruby
+  class Geordi
+    def make_it_so(logger=nil)
+      logger && logger.info "Reversing the flux phase capacitance!"
+      logger && logger.info "Bounding a tachyon particle beam off of Data's cat!"
+      logger && logger.warn "Warning, bogon levels are rising!"
+    end
+  end
+#+END_SRC
+
+Now, observe as we give it a dash of confidence with the Null Object
+pattern!
+
+#+BEGIN_SRC ruby
+  class NullLogger
+    def debug(*); end
+    def info(*); end
+    def warn(*); end
+    def error(*); end
+    def fatal(*); end
+  end
+  
+  class Geordi
+    def make_it_so(logger=NullLogger.new)
+      logger.info "Reversing the flux phase capacitance!"
+      logger.info "Bounding a tachyon particle beam off of Data's cat!"
+      logger.warn "Warning, bogon levels are rising!"
+    end
+  end
+#+END_SRC
+
+By providing a =NullLogger= which implements [some of] the =Logger=
+interface as no-op methods, we've gotten rid of those unsightly =&&=
+operators.
+
+*That was simple enough. Why do I need a library for it?*
+
+You don't! The Null Object pattern is a very simple one at its core.
+
+*And yet here we are...*
+
+Yes. While you don't /need/ a Null Object library, this one offers
+some conveniences you probably won't find elsewhere.
+
+But there's an even more important reason I wrote this library. In
+the immortal last words of James T. Kirk: "It was... /fun!/"
+
+*OK, so how do I use this thing?*
+
+Well, what would you like to do?
+
+*I dunno, gimme an object that responds to any message with =nil=*
+
+Sure thing!
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build
+  
+  null = NullObject.new
+  null.foo                        # => nil
+  null.bar                        # => nil
+#+END_SRC
+
+*That was... weird. What's with this "build" business?*
+
+Naught is a /toolkit/ for building null object classes. It is not a
+one-size-fits-all solution.
+
+What else can I make for you?
+
+*How about a "black hole" null object that supports infinite chaining
+of methods?*
+
+OK.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  BlackHole = Naught.build do |b|
+    b.black_hole
+  end
+  
+  null = BlackHole.new
+  null.foo                           # => <null>
+  null.foo.bar.baz                   # => <null>
+  null << "hello" << "world"         # => <null>
+#+END_SRC
+
+*What's that "b" thing?*
+
+That stands for "builder". Naught uses the [[http://en.wikipedia.org/wiki/Builder_pattern][Builder Pattern]] for
+rolling custom null object classes.
+
+*Whatever. What if I want a null object that has conversions to =Integer=, =String=, etc. using sensible conversions to "zero values"?*
+
+We can do that.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build do |b|
+    b.define_explicit_conversions
+  end
+  
+  null = NullObject.new
+  
+  null.to_s                          # => ""
+  null.to_i                          # => 0
+  null.to_f                          # => 0.0
+  null.to_a                          # => []
+  null.to_h                          # => {}
+  null.to_c                          # => (0+0i)
+  null.to_r                          # => (0/1)
+#+END_SRC
+
+*Ah, but what about /implicit/ conversions such as #to_str? Like what if I want a null object that implicitly splats the same way as an
+empty array?*
+
+Gotcha covered.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build do |b|
+    b.define_implicit_conversions
+  end
+  
+  null = NullObject.new
+  
+  null.to_str                     # => ""
+  null.to_ary                     # => []
+  
+  a, b, c = []
+  a                               # => nil
+  b                               # => nil
+  c                               # => nil
+  x, y, z = null
+  x                               # => nil
+  y                               # => nil
+  z                               # => nil
+#+END_SRC
+
+*How about a null object that only stubs out the methods from a specific class*
+
+That's what =mimic= is for.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullIO = Naught.build do |b|
+    b.mimic IO
+  end
+  
+  null_io = NullIO.new
+  
+  null_io << "foo"                # => nil
+  null_io.readline                # => nil
+  null_io.foobar                  # => 
+  # ~> -:11:in `<main>': undefined method `foobar' for 
+  #  <null:IO>:NullIO (NoMethodError)
+#+END_SRC
+
+There is also =impersonate= which takes =mimic= one step further. The
+generated null class will be derived from the impersonated class.
+This is handy when refitting legacy code that contains type checks.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullIO = Naught.build do |b|
+    b.impersonate IO
+  end
+  
+  null_io = NullIO.new
+  IO === null_io                  # => true
+  
+  case null_io
+  when IO
+    puts "Yep, checks out!"
+    null_io << "some output"
+  else
+    raise "Hey, I expected an IO!"
+  end
+  # >> Yep, checks out!
+#+END_SRC
+
+*Alright smartypants. What if I want to add my own methods?*
+
+Not a problem, just define them in the =.build= block.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build do |b|
+    b.define_explicit_conversions
+    def to_s
+      "NOTHING TO SEE HERE MOVE ALONG"
+    end
+  
+    def to_path
+      "/dev/null"
+    end
+  end
+  
+  null = NullObject.new
+  null.to_s                       # => "NOTHING TO SEE HERE MOVE ALONG"
+  null.to_path                    # => "/dev/null"
+#+END_SRC
+
+*Got anything else up your sleeve?*
+
+Well, we can make the null class a singleton, since null objects
+generally have no state.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build do |b|
+    b.singleton
+  end
+  
+  null = NullObject.instance
+  
+  null.__id__                     # => 17844080
+  NullObject.instance.__id__      # => 17844080
+  NullObject.new                  # => 
+  # ~> -:11:in `<main>': private method `new' called for 
+  #  NullObject:Class (NoMethodError)
+#+END_SRC
+
+Speaking of null objects with state, we can also enable tracing. This
+is handy for playing "where'd that null come from?!" Try doing /that/
+with =nil=!
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build do |b|
+    b.traceable
+  end
+  
+  null = NullObject.new           # line 7
+  
+  null.__file__                   # => "example.rb"
+  null.__line__                   # => 7
+#+END_SRC
+
+We can even conditionally enable either singleton mode (for
+production) or tracing (for development). Here's an example of using
+the =$DEBUG= global variable (set with the =-d= option to ruby) to
+choose which one.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build do |b|
+    if $DEBUG
+      b.traceable
+    else
+      b.singleton
+    end
+  end  
+#+END_SRC
+
+The only caveat is that when swapping between singleton and
+non-singleton implementations, you should be careful to always
+instantiate your null objects with =NullObject.get=, not =.new= or
+=.instance=. =.get= will work whether the class is implemented as a
+singleton or not.
+
+#+BEGIN_SRC ruby
+  NullObject.get                  # => <null>
+#+END_SRC
+
+*Are you done yet?*
+
+Just one more thing. For maximum convenience, Naught-generated null
+classes also come with a full suite of conversion functions which can
+be included into your classes.
+
+#+BEGIN_SRC ruby
+  require 'naught'
+  
+  NullObject = Naught.build
+  
+  include NullObject::Conversions
+  
+  # Convert nil to null objects. Everything else passes through.
+  Maybe(42)                       # => 42
+  Maybe(nil)                      # => <null>
+  Maybe(NullObject.get)           # => <null>
+  Maybe{ 42 }                     # => 42
+  
+  # Insist on a non-null (or nil) value
+  Just(42)                        # => 42
+  Just(nil) rescue $!             # => #<ArgumentError: Null value: nil>
+  Just(NullObject.get) rescue $!  # => #<ArgumentError: Null value: <null>>
+  
+  # nils and nulls become nulls. Everything else is rejected.
+  Null()                          # => <null>
+  Null(42) rescue $!              # => #<ArgumentError: 42 is not null!>
+  Null(nil)                       # => <null>
+  Null(NullObject.get)            # => <null>
+  
+  # Convert nulls back to nils. Everything else passes throuhgh. Useful
+  # for preventing null objects from "leaking" into public API return
+  # values.
+  Actual(42)                      # => 42
+  Actual(nil)                     # => nil
+  Actual(NullObject.get)          # => nil
+  Actual { 42 }                   # => 42
+#+END_SRC
+
+* Requirements
+
+  - Ruby 1.9
+
+* Contributing
+  
+  - Fork, branch, submit PR, blah blah blah. Don't forget tests.
+
+* Who's responsible
+
+  Naught is by [[http://devblog.avdi.org][Avdi Grimm]].

data/Rakefile

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

data/bin/autospec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'autospec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'autospec')

data/bin/coderay

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'coderay' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('coderay', 'coderay')

data/bin/guard

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', 'guard')