scrubby 0.2.0 → 0.2.1

data/README.rdoc

@@ -1,6 +1,6 @@
 = scrubby
 
-It's so simple! <tt>scrubby</tt> makes sure that all your attributes are cleaned up before they make their way into your models.
+It's so simple! +scrubby+ makes sure that all your attributes are cleaned up before they make their way into your models.
 
 == Installation
 
@@ -18,25 +18,27 @@ At your application root, run:
 
 == Example
 
-By default, <tt>scrubby</tt> will strip extra whitespace from strings, and turn blank strings into nil values:
+By default, +scrubby+ will strip extra whitespace from strings, and turn blank strings into nil values:
 
   class User < ActiveRecord::Base
     scrub :first_name, :middle_name, :last_name
   end
 
+
   >> u = User.new(:first_name => " Steve", :middle_name => "  ", :last_name => "Richert ")
   => #<User first_name: "Steve", middle_name: nil, last_name: "Richert">
 
-Or you can override the default behavior, just by defining a <tt>scrub</tt> instance method:
+Or you can override the default behavior, just by defining a +scrub+ instance method:
 
   class User < ActiveRecord::Base
     scrub :first_name, :middle_name, :last_name
-  
+    
     def scrub(value)
       value.to_s.upcase
     end
   end
 
+
   >> u = User.new(:first_name => "Steve", :last_name => "Richert")
   => #<User first_name: "STEVE", middle_name: "", last_name: "RICHERT">
 
@@ -44,17 +46,19 @@ And defining your own scrubbers inline is super easy:
 
   class User < ActiveRecord::Base
     scrub(:first_name, :last_name){|v| v.blank? ? nil : v.titleize }
-  
-    scrub(:middle_name) do |value|
-      initials = value.split(" ").map{|n| n.first + "." }
+    
+    scrub :middle_name do |value|
+      initials = value.split(" ").map{|n| n.first.upcase + "." }
       initials.empty? ? nil : initials.join(" ")
-    end      
+    end
   end
 
+
   class Admin < User
     scrub(:middle_name){ nil }
   end
 
+
   >> u = User.new(:first_name => "stephen", :middle_name => "joel michael", :last_name => "richert")
   => #<User first_name: "Stephen", middle_name: "J. M.", last_name: "Richert">
   >> a = Admin.new(:first_name => "stephen", :middle_name => "joel michael", :last_name => "richert")
@@ -66,21 +70,21 @@ It's pretty straightforward, and there's nothing all that fancy happening behind
 
 Scrubbing happens only when attributes are set. That way, no time is wasted scrubbing every time an attribute is retrieved.
 
-For column attributes, the scrubbing is done at the <tt>write_attribute</tt> level, without stepping on ActiveRecord's toes by creating a bunch of unnecessary setter methods.
+For column attributes, the scrubbing is done at the +write_attribute+ level, without stepping on ActiveRecord's toes by creating a bunch of unnecessary setter methods.
 
-<tt>scrubby</tt> also works with virtual attributes, simply by adding an <tt>alias_method_chain</tt> to the corresponding setter method, so the original can still be accessed via <tt>attribute_without_scrub=</tt>.
++scrubby+ also works with virtual attributes, simply by adding an +alias_method_chain+ to the corresponding setter method, so the original can still be accessed via <tt>attribute_without_scrub=</tt>.
 
 Inheritance is respected, just as you'd expect, down through model subclasses. Scrubbers are overridden in subclasses with no problem.
 
 == Inspiration
 
-Those of you who are familiar with <tt>attribute_normalizer</tt>[http://github.com/mdeering/attribute_normalizer] will recognize the how <tt>scrubby</tt> looks and feels, and that's no accident! <tt>attribute_normalizer</tt> has a simple, clean and effective interface.
+Those of you who are familiar with +attribute_normalizer+[http://github.com/mdeering/attribute_normalizer] will recognize the how +scrubby+ looks and feels, and that's no accident! +attribute_normalizer+ has a simple, clean and effective interface.
 
-But <tt>scrubby</tt> was written to be an improvement on what's happening behind the scenes, particularly with regards to inheritance and avoiding unnecessary method definitions. Basically, the idea was to really clean up and simplify the back-end of an already awesome interface.
+But +scrubby+ was written to be an improvement on what's happening behind the scenes, particularly with regards to inheritance and avoiding unnecessary method definitions. Basically, the idea was to really clean up and simplify the back-end of an already awesome interface.
 
 == Contributing
 
-* Fork[http://github.com/laserlemon/scrubby/fork] the project
+* Fork the project
 * Make your feature addition or bug fix
 * Add, change or remove corresponding tests
 * Commit (please don't change Rakefile or VERSION)

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/scrubby.rb

@@ -1,5 +1,25 @@
+# +scrubby+ cleans up incoming ActiveRecord model attributes by hijacking attribute setters and
+# reformatting the attribute value before passing it along to be set as usual.
+#
+# Author:: Steve Richert
+# Copyright:: Copyright (c) 2010 Steve Richert
+# License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
+#
+# To enable scrubbing on a model, simply use the +scrub+ method:
+#
+#   class User < ActiveRecord::Base
+#     scrub :name
+#   end
+#
+#
+#   user = User.new(:name => " Steve Richert ")
+#   user.name # => "Steve Richert"
+#   noname = User.new(:name => " ")
+#   noname.name # => nil
+#
+# See the +scrub+ class method documentation for more details.
 module Scrubby
-  def self.included(base)
+  def self.included(base) #:nodoc:
     base.class_eval do
       class_inheritable_hash :scrubbers
       self.scrubbers = {}
@@ -12,6 +32,34 @@ module Scrubby
   end
 
   module ClassMethods
+    # +scrub+ accepts multiple symbol or string arguments, representing model attributes that are
+    # to be scrubbed before being set. The +scrub+ method accepts no options, but an optional block
+    # can be included which will be used for scrubbing. Otherwise, the +scrub+ instance method is
+    # used.
+    #
+    # The +scrub+ instance method and the optional block both expect one argument: the incoming
+    # attribute value, and should return one value: the new, all-cleaned-up attribute value.
+    # However, when a custom block is given, the single argument can be left out if for some
+    # reason it's not needed.
+    #
+    # == Examples
+    #
+    #   class User < ActiveRecord::Base
+    #     scrub :first_name, :last_name
+    #   end
+    #
+    #
+    #   class User < ActiveRecord::Base
+    #     scrub :first_name, :last_name do |value|
+    #       value.blank? ? nil : value.titleize
+    #     end
+    #   end
+    #
+    #
+    #   class User < ActiveRecord::Base
+    #     scrub(:first_name){|v| v.to_s.upcase }
+    #     scrub(:last_name){ nil }
+    #   end
     def scrub(*attributes, &block)
       scrubber = block_given? ? block : instance_method(:scrub)
       self.scrubbers = attributes.inject({}){|s,a| s.merge!(a.to_s => scrubber) }
@@ -31,6 +79,12 @@ module Scrubby
   end
 
   module InstanceMethods
+    # An alias of the +write_attribute+ method, +write_attribute_with_scrub+ will check whether a
+    # scrubber exists for the given attribute and if so, scrub the given value before passing it
+    # on to the original +write_attribute+ method.
+    #
+    # This is used for column-based attributes, while virtual attributes are handled by aliasing
+    # the corresponding setter methods and scrubbing there.
     def write_attribute_with_scrub(attribute, value)
       if scrubber = scrubbers[attribute.to_s]
         value = scrubber.bind(self).call(value)
@@ -39,6 +93,11 @@ module Scrubby
       write_attribute_without_scrub(attribute, value)
     end
 
+    # The +scrub+ instance method is the default way in which incoming values are cleaned. By
+    # default, the behavior is to strip string values and to return nil for blank strings.
+    #
+    # If a different behavoir is required, this method can be overridden at the ActiveRecord::Base
+    # level and/or at the level of any of ActiveRecord's inherited models.
     def scrub(value)
       value = value.dup if value.duplicable?
 

data/scrubby.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{scrubby}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Steve Richert"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: scrubby
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Steve Richert