plow 0.1.0 → 1.0.0

data/.gitignore

@@ -4,6 +4,6 @@ coverage
 rdoc
 pkg
 .yardoc
-doc
 plow.gemspec
-plow.tmproj
+plow.tmproj
+yardoc

data/.yardopts

@@ -1,6 +1,8 @@
+--output-dir ./yardoc
 --markup markdown
 --private
 -
 LICENSE
-HISTORY
-SECURITY
+doc/HISTORY.markdown
+doc/SECURITY.markdown
+doc/ROAD-MAP.markdown

data/README.markdown

@@ -2,26 +2,24 @@
 
 Image courtesy of [Mother Earth News](http://www.motherearthnews.com/Modern-Homesteading/1974-05-01/Walking-Plow.aspx)
 
-PLOW Release 0.1.0 (October 13th 2009)
+Plow release 1.0.0 (November 21, 2009)
 ======================================
 
-Copyright © 2009 Ryan Sobol. Licensed under the MIT license.  Please see the {file:LICENSE} for more information.
+Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license.  Please see the {file:LICENSE} for more information.
 
-**Homepage**:       [http://github.com/ryansobol/plow](http://github.com/ryansobol/plow)  
-
-**Documentation**:  [http://rdoc.info/projects/ryansobol/plow](http://rdoc.info/projects/ryansobol/plow)  
+**Homepage**: [http://gemcutter.org/gems/plow](http://gemcutter.org/gems/plow)  
+**Source Code**: [http://github.com/ryansobol/plow](http://github.com/ryansobol/plow)  
+**Documentation**: [http://yardoc.org/docs/ryansobol-plow](http://yardoc.org/docs/ryansobol-plow)  
 **Code Metrics**: [http://devver.net/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fryansobol%2Fplow.git](http://devver.net/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fryansobol%2Fplow.git)  
+**Bug Tracker**: [http://github.com/ryansobol/plow/issues](http://github.com/ryansobol/plow/issues)  
+**Wiki**: [http://wiki.github.com/ryansobol/plow](http://wiki.github.com/ryansobol/plow)  
 
 WHAT'S NEW?
 -----------
 
-**v0.1.0**
-
-* Canonical 'plow' namespace reserved on [Gemcutter](http://gemcutter.org/gems/plow) and [Rubyforge](http://rubyforge.org/projects/plow/)
-
-I'm currently working at towards assembling a "complete software" package for you.  Please stay tuned for the official launch of version 1.0.0.  :D
+The first official public release of Plow!
 
-Please see {file:HISTORY} for the historical overview of the project.
+Please see {file:doc/HISTORY.markdown} for the historical overview of the project.
 
 SYNOPSIS
 --------
@@ -47,13 +45,12 @@ REQUIREMENTS
 
 * Ruby 1.9.1
 
-**Optional automated specification dependencies**
+**Optional development dependencies**
 
-* RSpec 1.2.8
-
-**Optional generated API documentation dependencies**
-
-* YARD 0.2.3.5
+* Rake 0.8.7 (bundled with Ruby 1.9.1)
+* Jeweler 1.3.0
+* RSpec 1.2.9
+* YARD 0.4.0
 * BlueCloth 2.0.5
 
 INSTALLING
@@ -63,7 +60,9 @@ Plow is distributed though the RubyGems ecosystem.  Assuming you've already inst
 
     sudo gem install plow
 
-LET ME BE CRYSTAL CLEAR.  DO NOT INSTALL THIS PACKAGE TO ANY NON-ROOT USER'S GEM REPOSITORY.  YOU'VE BEEN WARNED.  Please see {file:SECURITY} for a detailed explanation of this advisory.
+**LET ME BE CRYSTAL CLEAR.  DO NOT INSTALL THIS PACKAGE TO ANY NON-ROOT USER'S GEM REPOSITORY.  YOU'VE BEEN WARNED.**
+
+Please see {file:doc/SECURITY.markdown} for a detailed explanation of this advisory.
 
 Note that Plow is RubyGems **compatible** while also simultaneously **decoupled** from it.  Feel free to install Plow manually or use any Ruby package management system of your choice.
 
@@ -89,13 +88,38 @@ Plow is bundled with two executables named `plow` and `plow1.9`.  They are nearl
 EXAMPLE
 -------
 
-    $ plow steve www.apple.com apple.com
+    $ sudo plow steve www.apple.com apple.com
+    Plow 1.0.0. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license.
+    ==> creating steve user
+    Adding user `steve' ...
+    Adding new group `steve' (1001) ...
+    Adding new user `steve' (1001) with group `steve' ...
+    Creating home directory `/home/steve' ...
+    Copying files from `/etc/skel' ...
+    Enter new UNIX password: 
+    Retype new UNIX password: 
+    passwd: password updated successfully
+    Changing the user information for steve
+    Enter the new value, or press ENTER for the default
+    	Full Name []: 
+    	Room Number []: 
+    	Work Phone []: 
+    	Home Phone []: 
+    	Other []: 
+    Is the information correct? [y/N] y
+    ==> existing /home/steve
+    ==> creating /home/steve/sites
+    ==> creating /home/steve/sites/www.apple.com
+    ==> creating /home/steve/sites/www.apple.com/public
+    ==> creating /home/steve/sites/www.apple.com/log
+    ==> creating /etc/apache2/sites-available/www.apple.com.conf
+    ==> installing /etc/apache2/sites-available/www.apple.com.conf
     
-    ... plow interation ...
+    $ su - steve
+    Password: 
     
     $ tree /home/steve/sites/
     /home/steve/sites/
-    |-- README
     `-- www.apple.com
         |-- log
         |   `-- apache2
@@ -103,50 +127,71 @@ EXAMPLE
         |       `-- error.log
         `-- public
             `-- index.html
-    
-    4 directories, 4 files
+            
+    4 directories, 3 files
     
     $ ls -hal /home/steve/sites/www.apple.com/log/apache2/
-    total 196K
-    drwxr-x--- 2 root  steve 4.0K Sep  5 03:11 .
-    drwxr-xr-x 3 steve steve 4.0K Sep  5 03:09 ..
-    -rw-r----- 1 root  steve 136K Sep  9 11:10 access.log
-    -rw-r----- 1 root  steve  48K Sep  9 09:06 error.log
+    total 8.0K
+    drwxr-x--- 2 root  steve 4.0K 2009-11-21 16:33 .
+    drwxr-xr-x 3 steve steve 4.0K 2009-11-21 16:33 ..
+    -rw-r----- 1 root  steve    0 2009-11-21 16:33 access.log
+    -rw-r----- 1 root  steve    0 2009-11-21 16:33 error.log
+    
+    $ cat /etc/apache2/sites-available/www.apple.com.conf
+    
+    <VirtualHost *:80>
+      ServerAdmin webmaster
+      ServerName www.apple.com
+      
+      ServerAlias apple.com
+      
+      DirectoryIndex index.html
+      DocumentRoot /home/steve/sites/www.apple.com/public
+      
+      LogLevel warn
+      ErrorLog  /home/steve/sites/www.apple.com/log/apache2/error.log
+      CustomLog /home/steve/sites/www.apple.com/log/apache2/access.log combined
+    </VirtualHost>
+    
 
 MOTIVATION
 ----------
 
-There exists numerous software products for controlling and/or managing a unix-based operating systems and web servers.  So, why did I decide to write yet another?  With Plow, I needed to prove to myself that I have the necessary proficiency **to contribute free, open-source, and complete software for the benefit human-kind**.
+As of the time of writing, there exists countless software products for managing unix-based operating systems and web servers.  So then, why did I decide to write yet another?  For me, Plow was a self-issued challenge **to contribute free, open-source, and complete software for the benefit human-kind**.
 
-The terms "free" and "open-source" are common enough to be implicitly understood, or at least, [easily googled](http://www.google.com/searchq=free+open-source).  But what of the term "complete software"?  For me, complete software means four exclusive characteristics:
+The terms "free" and "open-source" software are common enough to be implicitly understood, or at least, [easily googled](http://www.google.com/searchq=free+open-source).  But what of the term "complete software"?  For me, complete software has four exclusive characteristics:
 
-* Usability enhanced through elegant user-interface combined with straight-forward documentation
+* Usability enhanced through elegant user-interface and straight-forward documentation
 * Stability verified through automated test specifications
 * Performance demonstrated through benchmarks
 * Sustainability preserved through both human and computer readable code
 
-I have tirelessly worked to achieve a high standard in all four characteristics.  As my peer, I am grateful of your input on improving this project in any of these areas.  Please see the sections on REPORTING ISSUES and CONTRIBUTING for further information.
+Though never finished, I have worked tirelessly to set a the bar high within each of these characteristics.  As my peer, I am grateful of your input on improving this project.  If you are interested in generously donating your time to Plow, please read the below sections on REPORTING ISSUES and CONTRIBUTING to learn how to best direct your energy.
 
 REPORTING ISSUES
 ----------------
 
-Is Plow not behaving like you expect it should?  Please forgive me!  Would you take a moment to shed light on my negligence over at the [Issue Tracker](http://github.com/ryansobol/plow/issues)?  
+Is Plow not behaving like you expect it should?  Please forgive me!  Would you take a moment to shed light on my negligence over at the [Issue Tracker](http://github.com/ryansobol/plow/issues)?  Here's a **Pro Tip** -- you can read through existing issues and vote for which issues you'd like to see resolved first!
 
-Thank you, in advance, for taking the time to help improve Plow.
+Thank you for taking the time to help improve Plow.
 
 CONTRIBUTING
 ------------
 
-Is Plow not behaving like you need?  Open-source to the rescue!  There is a plethora of documentation to bring you up to speed.  The API documentation is generated, once the dependencies are met (please see the REQUIREMENTS section), by running the follow:
+Is Plow not behaving like you need?  Open-source to the rescue!  There is a plethora of documentation to bring a Rubyist of any level up to speed.  The API documentation is generated, once the dependencies are met (please see the REQUIREMENTS section), by issuing the follow command:
 
-    $ rake yardoc
+    $ rake yard
 
-Patches are always welcome and appreciated!  To contribute your work back to the source, the process is straight-forward:
+Patches are always welcome and appreciated!  The process is straight-forward for contributing your work back to the source:
 
 * Fork the project -- may I suggest [Github](http://www.github.com)?
-* Make your feature addition or bug fix with specifications -- it's important that I don't break your hard work in a future version unintentionally.
-* Please do not casually alter files in the project root. (e.g. HISTORY, LICENSE, Rakefile, README.markdown, ROAD-MAP, SECURITY, VERSION, etc.)
+* Make your feature addition or bug fix **with specifications**.  It's important that I don't break your hard work in a future version unintentionally.
+* Please do not casually alter files in the project root. (e.g. LICENSE, Rakefile, README.markdown, VERSION, etc.)
 * Commit your changes and publish the change-set.
-* Send me a pull request.  All specs must pass!
+* Send me a pull request.  Remember, all specs must pass!
+
+Before making your change, take a moment to get a feel for the style of coding, specifications, and in-line documentation.
+
+Please see {file:doc/ROAD-MAP.markdown} to learn how to flow with the project.  In the near future, I plan on pushing this content directly into the [Issue Tracker](http://github.com/ryansobol/plow/issues).
 
-Take a moment to get a feel for the style of coding, specifications, and in-line documentation.  I apologize in advance for setting the standards so high.  Please see {file:ROAD-MAP} to learn how to flow with the project.
+Again, thank you for taking the time to help improve Plow.

data/Rakefile

@@ -1,52 +1,58 @@
-require 'rubygems'
-require 'rake'
+# encoding: UTF-8
+require 'lib/plow'
+Plow::Dependencies.warn_at_exit
+
+###################################################################################################
 
 begin
+  # TODO experiment with how rubygems activates gems by version requirement in ruby 1.9.1.
+  # gem 'jeweler', '1.3.0'
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
+    # The gem object is a kind of Gem::Specification 
+    # For additional settings, see http://www.rubygems.org/read/chapter/20
     gem.name              = "plow"
-    gem.rubyforge_project = "plow"
+    gem.rubyforge_project = "plow" # rubyforge's days are numbered...
     gem.summary           = "Plows the fertile soil of your filesystem into neatly organized plots of web-site templates"
     gem.description       = "Plows the fertile soil of your filesystem into neatly organized plots of web-site templates"
     gem.email             = "code@ryansobol.com"
     gem.homepage          = "http://github.com/ryansobol/plow"
-    gem.authors           = ["Ryan Sobol"]    
-    gem.add_development_dependency "rspec", "= 1.2.8"
-    gem.add_development_dependency "yard", "= 0.2.3.5"
-    gem.add_development_dependency "bluecloth", "= 2.0.5"  # hidden yard dependency for markdown support
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.authors           = ["Ryan Sobol"]
+    
+    gem.required_ruby_version = "~> #{Plow::Dependencies::REQUIRED_RUBY_VERSION}"
+    
+    Plow::Dependencies::DEVELOPMENT_GEMS.each_pair do |name, version|
+      gem.add_development_dependency(name.to_s, version)
+    end
   end
+  
   Jeweler::GemcutterTasks.new
   
   Jeweler::RubyforgeTasks.new do |task|
-    task.doc_task = "yardoc"
+    task.doc_task = false # rubyforge's days are numbered...
   end
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+rescue LoadError => e
+  Plow::Dependencies.create_warning_for(e)
 end
 
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |task|
-  task.libs << 'lib' << 'spec'
-  task.spec_files = FileList['spec/**/*_spec.rb']
-  task.spec_opts  = %w{ -O spec/spec.opts }
-end
+###################################################################################################
 
-Spec::Rake::SpecTask.new(:rcov) do |task|
-  task.libs << 'lib' << 'spec'
-  task.pattern = 'spec/**/*_spec.rb'
-  task.rcov    = true
+begin
+  require 'spec/rake/spectask'
+  Spec::Rake::SpecTask.new(:spec)  
+  task :default => :spec
+rescue LoadError => e
+  Plow::Dependencies.create_warning_for(e)
 end
 
-task :spec => :check_dependencies
-
-task :default => :spec
+###################################################################################################
 
 begin
   require 'yard'
-  YARD::Rake::YardocTask.new
-rescue LoadError => e
-  task :yardoc do
-    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  require 'bluecloth' # hidden yard dependency for markdown support
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.options += ['--title', "Plow #{Plow::VERSION} Documentation"]
   end
+rescue LoadError => e
+  Plow::Dependencies.create_warning_for(e)
 end

data/VERSION

@@ -1 +1 @@
-0.1.0
+1.0.0

data/bin/plow

@@ -1,10 +1,4 @@
 #!/usr/bin/env ruby
 # encoding: UTF-8
-
-unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__) + '/../lib'))
-  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/../lib'))
-end
-
-require 'plow'
-
+require File.expand_path(File.dirname(__FILE__) + '/../lib/plow')
 Plow::Application.launch(*ARGV)

data/bin/plow1.9

@@ -1,10 +1,4 @@
 #!/usr/bin/env ruby1.9
 # encoding: UTF-8
-
-unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__) + '/../lib'))
-  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/../lib'))
-end
-
-require 'plow'
-
+require File.expand_path(File.dirname(__FILE__) + '/../lib/plow')
 Plow::Application.launch(*ARGV)

data/doc/HISTORY.markdown

@@ -0,0 +1,41 @@
+Plow release 1.0.0 (November 21, 2009)
+========================================
+
+The first official public release of Plow!
+
+SYNOPSIS
+--------
+
+Plows the fertile soil of your filesystem into neatly organized plots of web-site templates
+
+FEATURES
+--------
+
+1. Sharpens it's blade by ensuring that both a Linux system user account and it's home path exist
+2. Penetrates the soil by forming the web-site root path within the user home
+3. Seeds the web-site with an index page and web server log files
+4. Fertilizes the web-site by installing a virtual host configuration into the web server
+
+REQUIREMENTS
+------------
+
+**Supported operating system + web server combinations**
+
+* Linux Ubuntu 8.04.3 LTS (Hardy Heron) + Apache 2.2.8
+
+**Required dependencies**
+
+* Ruby 1.9.1
+
+**Optional development dependencies**
+
+* Rake 0.8.7 (bundled with Ruby 1.9.1)
+* Jeweler 1.3.0
+* RSpec 1.2.9
+* YARD 0.4.0
+* BlueCloth 2.0.5
+
+Plow release 0.1.0 (October 13, 2009)
+=======================================
+
+  * Canonical gem namespace, 'plow', reserved on [Gemcutter](http://gemcutter.org/gems/plow) and [Rubyforge](http://plow.rubyforge.org/)

data/doc/ROAD-MAP.markdown

@@ -0,0 +1,12 @@
+Road-map of Potential Improvements
+==================================
+
+In no particular order of importance:
+
+  * Generating and installing web-site specific `logrotated` scripts
+  * Removing plowed directories and files and uninstalling service scripts
+  * Additional template generating strategies of operating systems and web-sever combinations
+  * Run-time checking and validating of operating systems and installed web-servers
+  * Generating different web-site template structures
+  * Automatic deployment of web-sites from SCM repositories
+  * Flexible argument parsing including option flags as needed

data/{SECURITY → doc/SECURITY.markdown}

@@ -1,14 +1,15 @@
-== A Brief Note About Security
+A Brief Note About Security
+===========================
 
 Any and all processes invoking this library must be owned, aka executed, by the root user.  Root ownership is required by this package to automate system administrative tasks, including but not limited to:
 
 * Creating and/or modifying operating system user accounts that are _typically controlled by the root user_
 * Generating and installing virtual host configuration files for web servers that are _typically owned by the root user_
 
-By installing this package, you are acknowledging the risks inherit of the above implications.  If this package, including the library source code and it's non-compiled executables, is owned by any non-root user, then anyone who has or gains access to that non-root account could modify the code in this package, without your knowledge.  The next time you execute the program, as the root user, you could now be unwittingly comprising your own system by running malicious code injected into this package.
+By installing this package, you are acknowledging the risks inherit of the aforementioned tasks.  If this package, including the library source code and it's non-compiled executables, is owned by any non-root user, then anyone who has or gains access to that non-root account could modify the code in this package, without your knowledge.  The next time you execute the program, as the root user, you could now be unwittingly comprising your own system by running malicious code injected into this package.
 
 If you wish to install this package as a RubyGem with a user account granted root privileges via sudo, then please install this package by running the following command:
 
     sudo gem install plow
 
-LET ME BE CRYSTAL CLEAR.  DO NOT INSTALL THIS PACKAGE TO ANY NON-ROOT USER'S GEM REPOSITORY.  YOU'VE BEEN WARNED.
+**LET ME BE CRYSTAL CLEAR.  DO NOT INSTALL THIS PACKAGE TO ANY NON-ROOT USER'S GEM REPOSITORY.  YOU'VE BEEN WARNED.**

data/lib/plow/application.rb

@@ -2,8 +2,34 @@
 require 'plow/generator'
 
 class Plow
+  # It's probably no surprise that `Plow::Application` is an **application** class.
+  #
+  # With a single public method, `.launch`, it has the distinct honor of being the point of
+  # execution for the library.  As described further in the documentation, it designed to
+  # accept and parse raw command-line arguments (i.e. the `ARGV` constant).
+  #
+  # @see Plow::Application.launch
   class Application
     class << self
+      # The starting point of executation for the Plow library.  The procedure for launching the 
+      # `Plow::Application` is as follows:
+      #
+      # 1. Output a version stamp.
+      # 2. Ensure at least 2 arguments are provided or aborting execution with a usage message.
+      # 3. Parse the user-supplied arguments.
+      # 4. Start a new `Plow::Generator` while handling any library specific exceptions raised.
+      #
+      # @example A simple executable file (assume a working Ruby $LOAD_PATH)
+      #   #!/usr/bin/env ruby1.9
+      #   require 'plow'
+      #   Plow::Application.launch(*ARGV)
+      #
+      # @param [Array] *arguments A splatted `Array` of user-specified, command-line arguments.
+      #   At least 2 arguments must be provided.
+      # @return [Number] Success returns 0, while failure results in any raised `Exception`. :(
+      # @raise [SystemExit] Raised when a critical, library-specific exception is rescued and
+      #   executation must be terminiated.
+      # @see http://www.ruby-doc.org/ruby-1.9/classes/SystemExit.html
       def launch(*arguments)
         puts version_stamp
         
@@ -58,8 +84,14 @@ MESSAGE
       
       private
       
+      # Similar to a time stamp, this will return a version stamp of the Plow library containing
+      # the version number along with the copyright and license details.
+      #
+      # @return [String] Version stamp
+      # @example Sample version stamp
+      #   Plow 1.0.0. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license.
       def version_stamp
-        "Plow v#{Plow::VERSION}. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license."
+        "Plow #{Plow::VERSION}. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license."
       end
     end
   end

data/lib/plow/binding_struct.rb

@@ -1,13 +1,49 @@
 # encoding: UTF-8
 
 class Plow
+  # `BindingStruct` is an **adapter** between the friendly declarative-style of `Hash` key/value
+  # pairs and the built-in, `ERB` (i.e. embedded ruby) class, which takes an optional `Binding`
+  # object for the scope of template evaluation.  
+  #
+  # This class is very similar to Ruby's built-in `OpenStruct` class.  It differs internally as
+  # `BindingStruct` converts each element of the `Hash` object into an instance variable during
+  # initialization.  Once initialized, an instance of `BindingStruct` is able to return a
+  # reference to it's internal `Binding` object.  This object can be further passed along to an
+  # `ERB` object for evaluation within a template.
+  #
+  # @example Sample template file at /path/to/a/template/file.txt'
+  #   <%= @first_name %> <%= @last_name %> invented the Universe.
+  #
+  # @example Evaluating an `ERB` template file with a `BindingStruct` context
+  #   template = ERB.new(File.read('/path/to/a/template/file.txt'))
+  #   context  = Plow::BindingStruct.new({ first_name: 'Carl', last_name: 'Sagan' })
+  #   result   = template.result(context.get_binding)  #=> Carl Sagan invented the Universe.
+  #
+  # @see http://www.ruby-doc.org/ruby-1.9/classes/Binding.html
+  # @see http://www.ruby-doc.org/ruby-1.9/classes/ERB.html
+  # @see http://www.ruby-doc.org/ruby-1.9/classes/OpenStruct.html
   class BindingStruct
-    def initialize(hash)
-      hash.each_pair do |name, val|
+    
+    # Creates a new `BindingStruct` from a `Hash` where each key/value pair is converted to an
+    # instance variable.
+    #
+    # @param [Hash] source A source of data
+    # @example A peek into the internals of an instance post initialization
+    #   bstruct = Plow::BindingStruct.new({first_name: 'Carl', last_name: 'Sagan'})
+    #   bstruct.instance_variables.sort              #=> [:@first_name, :@last_name]
+    #   bstruct.instance_variable_get(:@first_name)  #=> 'Carl'
+    #   bstruct.instance_variable_get(:@last_name)   #=> 'Sagan'
+    def initialize(source)
+      source.each_pair do |name, val|
         instance_variable_set("@#{name}".to_sym, val)
       end
     end
     
+    # Returns a reference to its internal `Binding` which can be used in conjunction with `ERB`
+    # template evaluation.
+    #
+    # @return [Binding] An reference to its internal `Binding`
+    # @see http://www.ruby-doc.org/ruby-1.9/classes/Binding.html
     def get_binding
       binding
     end

data/lib/plow/core_ext/object.rb

@@ -1,7 +1,15 @@
 # encoding: UTF-8
 
+# Mindfully expanding the base `Object` class with sensible methods.
 class Object
-  # See http://api.rubyonrails.org/classes/Object.html#M000279
+  # An object is blank if it‘s false, empty, or a whitespace string. 
+  # For example, "", " ", nil, [], and {} are blank.
+  # 
+  # @example This simplifies
+  #   if !address.nil? && !address.empty?
+  # @example to
+  #   if !address.blank?
+  # @see http://api.rubyonrails.org/classes/Object.html#M000279
   def blank?
     respond_to?(:empty?) ? empty? : !self
   end