vacuum_cleaner 0.1.0 → 0.5.0

data/README.md

@@ -1,6 +1,76 @@
 Vacuum Cleaner
 ==============
 
-A Ruby (and Rails) attribute normalization gem.
+A Ruby (and Rails) attribute normalization gem, which is supposedly [semver](http://semver.org/)-compliant.
 
-** TODO **
+Installation
+------------
+
+1. Install as gem from [rubygems](http://rubygems.org/gems/vacuum_cleaner): `sudo gem install vacuum_cleaner`.
+   Then load it in your app: `require 'rubygems'; require 'vacuum_cleaner'`      
+2. Install as gem using [bundler](http://github.com/carlhuda/bundler), add `gem "vacuum_cleaner"` to your
+   `Gemfile` and run `bundle install`
+3. Or as a Rails plugin, for Rails 2.x run `./script/plugin install git://github.com/lwe/vacuum_cleaner.git`, when using Rails 3.x
+   goodeness run `rails plugin install git://github.com/lwe/vacuum_cleaner.git`
+
+Usage
+-----
+
+It creates a new setter method for an attribute and thus allows the gem to reprozess the input value.
+
+    class Doctor
+      include VacuumCleaner::Normalizations  # enables #normalizes, NOTE: not required for ActiveRecord models                                             
+      attr_accessor :name                    # create some reader/writter
+      
+      normalizes :name                       # enables strip/clean-up magic on attribute :name
+    end
+    
+    @doc = Doctor.new
+    
+    # set name with leading/trailing spaces
+    @doc.name = "  Elliot Reid\n\t"
+    @doc.name   # => "Elliot Reid"
+    
+    # empty strings => nil
+    @doc.name = "\t\n"
+    @doc.name   # => nil
+
+Okay, this is it. Now, let the fun part begin...
+
+    # can be used with multiple attributes (if they all share the same normalizer)
+    normalizes :name, :company
+    
+    # provides a fancy :downcase and :upcase normalizer (guess what they do)
+    normalizes :email, :downcase => true
+    # "JD@EXAMPLE.COM \n" => "jd@example.com"
+    
+    # provides a :method normalizer which takes a string/symbol as argument which is
+    # then called upon the resulting value (if it respond_to)
+    normalizes :name, :method => :titleize
+    # "carla ESPINOSA" => "Carla Espinosa" PS: only works if ActiveSupport is available :)
+    
+    # or a simple URL normalizer, which prefixes http:// if not starting with
+    # http or https
+    normalizes :homepage, :url => true
+    # "google.com" => "http://google.com"
+    # "http://example.com" => "http://example.com" PS: left as is
+    
+Assuming this already allows to fix 99.9% of all attribute normalization cases, if there's
+that special need, then `normalizes` accepts a block:
+
+    # strips all whitespace within a string
+    normalizes(:phone) { |value| value.to_s.gsub(/\s+/, '') unless value.nil? }    
+    # "\t+45 123 123  " => "+45123123" PS: yes, the standard strip etc. magic is still run
+    
+    # no need for the default normalizer and feeling really custom?
+    normalizes(:phone, :default => false, :upcase => true) { |value| value.to_s.strip.gsub(/\s+/, '') }
+    # "\t0800 sacred heart" => "0800SACREDHEART"
+    # "\t\n" => ""
+    # nil => ""
+    
+Need access to the object within the block? As easy as:
+
+    # naming J.D. after some girly girl?
+    normalizes(:first_name) do |obj, attribute, value|
+      obj.name == "Dorian" ? %w{Agnes Shirley Denise}[rand(3)] : value
+    end

data/Rakefile

@@ -1,8 +1,10 @@
 require 'rake'
 require 'rake/testtask'
-require 'yard'
+
 require File.join(File.dirname(__FILE__), 'lib', 'vacuum_cleaner')
 
+task :default => :test
+
 desc 'Test the vacuum_cleaner plugin.'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
@@ -11,13 +13,18 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
-desc 'Generate documentation for vacuum_cleaner. (requires yard)'
-YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = ['lib/**/*.rb']
-  t.options = [
-      "--readme", "README.md",
-      "--title", "vacuum_cleaner (v#{VacuumCleaner::VERSION}) API Documentation"
-  ]
+begin
+  require 'yard'
+  desc 'Generate documentation for vacuum_cleaner. (requires yard)'
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files = ['lib/**/*.rb']
+    t.options = [
+        "--readme", "README.md",
+        "--title", "vacuum_cleaner (v#{VacuumCleaner::VERSION}) API Documentation"
+    ]
+  end
+rescue LoadError
+  puts "yard is not available (required for doc task). Install it with: sudo gem install yard (or use rdoc manually)"
 end
 
 begin
@@ -26,11 +33,7 @@ begin
     gemspec.name = "vacuum_cleaner"
     gemspec.version = VacuumCleaner::VERSION
     gemspec.summary = "Ruby (and Rails) attribute cleaning support, provides some nice default normalization strategies."
-    description = <<-DESC
-      ** Swoooosh ** - and all those leading and trailing whitespaces are gone, or ** Frooom ** - and the value
-      is normalized to always be prefixed by 'http://' and much more. Works with both plain old Ruby, and Rails (ActiveModel
-      and ActiveSupport).
-    DESC
+    description = "Ruby (and Rails) attribute cleaning support, provides some nice and easy to enhance default normalization strategies."
     gemspec.description = description.strip
     gemspec.email = "lukas.westermann@gmail.com"
     gemspec.homepage = "http://github.com/lwe/vacuum_cleaner"
@@ -40,7 +43,9 @@ begin
     
     gemspec.add_development_dependency('shoulda', '>= 2.10.2')
     gemspec.add_development_dependency('rr', '>= 0.10.5')
-    # gemspec.add_development_dependency('activesupport', '>= 2.3.5')
+    gemspec.add_development_dependency('activesupport', '>= 2.3.5')
+    
+    gemspec.files.reject! { |file| file =~ /\.gemspec$/ } # kinda redundant
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/init.rb

@@ -1,4 +1 @@
-require 'vacuum_cleaner'
-
-ActiveRecord::Base.class_eval { include VacuumCleaner::Normalizations } # all versions of rails
-ActiveModel::Base.class_eval { include VacuumCleaner::Normalizations } if defined?(ActiveModel::Base) # Rails 3+
+require File.dirname(__FILE__) + "rails/init"

data/lib/vacuum_cleaner/normalizations/url.rb

@@ -1,5 +1,9 @@
 module VacuumCleaner
   module Normalizations
+    
+    # 
+    #
+    #
     class UrlNormalizer < Normalizer
       def initialize(options = {})
         options = { :scheme => "http://", :unless => %r{\Ahttps?://}i } if options.nil? || options.empty?

data/lib/vacuum_cleaner/normalizations.rb

@@ -33,7 +33,7 @@ module VacuumCleaner
             block_given? ? (block.arity == 1 ? yield(value) : yield(self, attribute, value)) : value
           end
           original_setter = "#{attribute}#{VacuumCleaner::WITHOUT_NORMALIZATION_SUFFIX}=".to_sym
-          send(:alias_method, original_setter, "#{attribute}=") if instance_methods.include?("#{attribute}=")
+          send(:alias_method, original_setter, "#{attribute}=") if instance_methods.include?(RUBY_VERSION =~ /^1.9/ ? :"#{attribute}=" : "#{attribute}=")
                     
           rb_src = <<-RUBY
             def #{attribute}=(value)                                                                          #  1.  def name=(value)
@@ -52,9 +52,9 @@ module VacuumCleaner
   
   # Okay, because this library currently does not depend on
   # <tt>ActiveSupport</tt> or anything similar an "independent" camelizing process is
-  # required. So it works pretty easy.
+  # required.
   #
-  # If <tt>value.to_s</tt> responds to <tt>:camelize</tt>, then call it else use implementation
+  # <b>How it works:</b> If <tt>value.to_s</tt> responds to <tt>:camelize</tt>, then call it else, use implementation
   # taken from http://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb#L25
   def camelize_value(value)
     value = value.to_s

data/lib/vacuum_cleaner/normalizer.rb

@@ -2,31 +2,32 @@ module VacuumCleaner #:nodoc:
   
   # A small base class for implementing custom value normalizers.
   # Might seem like a slight overkill, yet makes the library pretty
-  # reusable and all. Based on Rails 3 validator stuff.
-  #
-  #
-  #   class Person
-  #     include VacuumCleaner::Normalizations
-  #     normalizes :name, :titleize => true
-  #   end
+  # reusable and all. Works like ActiveModel validators.
   #
   #   class TitleizeNormalizer < VacuumCleaner::Normalizer
   #     def normalize_value(value)
   #       value.titelize unless value.blank?
   #     end
   #   end
+  #  
+  #   class Person
+  #     include VacuumCleaner::Normalizations
+  #     normalizes :name, :titleize => true
+  #   end
   #
   # Any class that inherits from +VacuumCleaner::Normalizer+ must implement
-  # a method called <tt>normalize_value</tt> which accepts the <tt>value</tt> to normalize. Furthermore
-  # the value returned by <tt>normalize</tt> is used as the new value for
+  # a method called <tt>normalize_value</tt> which accepts the <tt>value</tt> to normalize.
+  # Furthermore the value returned by <tt>normalize_value</tt> is used as the new value for
   # the attribute.
   #
   # To reuse the behaviour as defined by the default normalizer (strip & empty),
   # just use <tt>super</tt>.
   #
-  #   class TitleizeNormalizer < VacuumCleaner::Normalizer
+  #   class MoreNilNormalizer < VacuumCleaner::Normalizer
   #     def normalize_value(value)
-  #       super(value).try(:titelize)
+  #       value = super
+  #       value = value.downcase if value.respond_to(:downcase)
+  #       %w{0 nil null nul zero nix}.include?(value) ? nil : value
   #     end
   #   end
   #
@@ -39,9 +40,15 @@ module VacuumCleaner #:nodoc:
   #      end
   #    end
   #
+  # When the normalization process is started for an attribute, the method
+  # +normalize+ is called with the object, attribute and the value. The default
+  # implementation of +normalize+ (as provided by this class) just calls
+  # +normalize_value+.
+  #
   # This can be used together with the +normalizes+ method (see
-  # VacuumCleaner::Normalizers.normalizes for more on this).
+  # {{VacuumCleaner::Normalizers.normalizes}} for more on this).
   class Normalizer
+    # Options as supplied to the normalizer.
     attr_reader :options
         
     # Accepts an array of options, which will be made available through the +options+ reader.

data/lib/vacuum_cleaner.rb

@@ -1,5 +1,7 @@
+# Fancy value normalization utility for ruby (and rails).
 module VacuumCleaner
-  VERSION = "0.1.0".freeze
+  # +VacuumCleaner+ version string, current version is 0.1.0.
+  VERSION = "0.5.0".freeze
   
   autoload :Normalizer, 'vacuum_cleaner/normalizer'
   autoload :Normalizations, 'vacuum_cleaner/normalizations'

data/rails/init.rb

@@ -1,4 +1,4 @@
 require 'vacuum_cleaner'
 
 ActiveRecord::Base.class_eval { include VacuumCleaner::Normalizations } # all versions of rails
-ActiveModel::Base.class_eval { include VacuumCleaner::Normalizations } if defined?(ActiveModel::Base) # Rails 3+
+# ActiveModel::Base.class_eval { include VacuumCleaner::Normalizations } if defined?(ActiveModel::Base) # Rails 3+

data/test/unit/vacuum_cleaner/normalizations_test.rb

@@ -50,32 +50,32 @@ class VacuumCleaner::NormalizationsTest < Test::Unit::TestCase
       should "take multiple symbols as argument" do
         klass = Class.new { include VacuumCleaner::Normalizations; normalizes(:name, :first_name) }
         assert_respond_to klass, :normalizes
-        #assert_respond_to klass, :normalize_name
-        #assert_respond_to klass, :normalize_first_name
       end
 
       should "create a setter for supplied attribute" do
         obj = Class.new { include VacuumCleaner::Normalizations; normalizes(:name) }.new
         assert_respond_to obj, :name=
+        assert_respond_to obj, :normalize_name
       end
 
       should "set the instance variable using the setter" do
-        obj = Class.new { include VacuumCleaner::Normalizations; normalizes(:name) }.new
+        obj = Class.new { include VacuumCleaner::Normalizations; attr_reader :name; normalizes(:name) }.new
         obj.name = "J.D."
-        assert_equal "J.D.", obj.instance_variable_get(:@name)
+        assert_equal "J.D.", obj.name
       end
       
       should "alias method to <attr>_without_normalization= if <attr>= already defined" do
         klass = Class.new do
           include VacuumCleaner::Normalizations
+          attr_reader :name, :foo
           def name=(name); @foo = name end
           normalizes :name
         end
         obj = klass.new
         obj.name = "Elliot Reid"
         assert_respond_to obj, :name_without_normalization=
-        assert_equal "Elliot Reid", obj.instance_variable_get(:@foo)
-        assert_nil obj.instance_variable_get(:@name)
+        assert_equal "Elliot Reid", obj.foo
+        assert_nil obj.name
       end
 
       should "convert any blank input, like empty string, nil etc. to => <nil>" do

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 5
   - 0
-  version: 0.1.0
+  version: 0.5.0
 platform: ruby
 authors: 
 - Lukas Westermann
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-24 00:00:00 +01:00
+date: 2010-03-09 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -45,10 +45,21 @@ dependencies:
         version: 0.10.5
   type: :development
   version_requirements: *id002
-description: |-
-  ** Swoooosh ** - and all those leading and trailing whitespaces are gone, or ** Frooom ** - and the value
-        is normalized to always be prefixed by 'http://' and much more. Works with both plain old Ruby, and Rails (ActiveModel
-        and ActiveSupport).
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 5
+        version: 2.3.5
+  type: :development
+  version_requirements: *id003
+description: Ruby (and Rails) attribute cleaning support, provides some nice and easy to enhance default normalization strategies.
 email: lukas.westermann@gmail.com
 executables: []
 
@@ -73,7 +84,6 @@ files:
 - test/unit/vacuum_cleaner/normalizations/url_test.rb
 - test/unit/vacuum_cleaner/normalizations_test.rb
 - test/unit/vacuum_cleaner/normalizer_test.rb
-- vacuum_cleaner.gemspec
 has_rdoc: true
 homepage: http://github.com/lwe/vacuum_cleaner
 licenses: 

data/vacuum_cleaner.gemspec

@@ -1,69 +0,0 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
-# -*- encoding: utf-8 -*-
-
-Gem::Specification.new do |s|
-  s.name = %q{vacuum_cleaner}
-  s.version = "0.1.0"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Lukas Westermann"]
-  s.date = %q{2010-02-24}
-  s.description = %q{** Swoooosh ** - and all those leading and trailing whitespaces are gone, or ** Frooom ** - and the value
-      is normalized to always be prefixed by 'http://' and much more. Works with both plain old Ruby, and Rails (ActiveModel
-      and ActiveSupport).}
-  s.email = %q{lukas.westermann@gmail.com}
-  s.extra_rdoc_files = [
-    "README.md"
-  ]
-  s.files = [
-    ".gitignore",
-     "LICENSE",
-     "README.md",
-     "Rakefile",
-     "init.rb",
-     "lib/vacuum_cleaner.rb",
-     "lib/vacuum_cleaner/normalizations.rb",
-     "lib/vacuum_cleaner/normalizations/method.rb",
-     "lib/vacuum_cleaner/normalizations/url.rb",
-     "lib/vacuum_cleaner/normalizer.rb",
-     "rails/init.rb",
-     "test/test_helper.rb",
-     "test/unit/vacuum_cleaner/normalizations/method_test.rb",
-     "test/unit/vacuum_cleaner/normalizations/url_test.rb",
-     "test/unit/vacuum_cleaner/normalizations_test.rb",
-     "test/unit/vacuum_cleaner/normalizer_test.rb",
-     "vacuum_cleaner.gemspec"
-  ]
-  s.homepage = %q{http://github.com/lwe/vacuum_cleaner}
-  s.licenses = ["LICENSE"]
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
-  s.summary = %q{Ruby (and Rails) attribute cleaning support, provides some nice default normalization strategies.}
-  s.test_files = [
-    "test/test_helper.rb",
-     "test/unit/vacuum_cleaner/normalizations/method_test.rb",
-     "test/unit/vacuum_cleaner/normalizations/url_test.rb",
-     "test/unit/vacuum_cleaner/normalizations_test.rb",
-     "test/unit/vacuum_cleaner/normalizer_test.rb"
-  ]
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<shoulda>, [">= 2.10.2"])
-      s.add_development_dependency(%q<rr>, [">= 0.10.5"])
-    else
-      s.add_dependency(%q<shoulda>, [">= 2.10.2"])
-      s.add_dependency(%q<rr>, [">= 0.10.5"])
-    end
-  else
-    s.add_dependency(%q<shoulda>, [">= 2.10.2"])
-    s.add_dependency(%q<rr>, [">= 0.10.5"])
-  end
-end
-