vacuum_cleaner 0.5.0 → 1.0.0

data/Rakefile

@@ -3,22 +3,13 @@ require 'rake/testtask'
 
 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'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-end
-
 begin
   require 'yard'
   desc 'Generate documentation for vacuum_cleaner. (requires yard)'
   YARD::Rake::YardocTask.new(:doc) do |t|
     t.files = ['lib/**/*.rb']
     t.options = [
+        "--no-private",
         "--readme", "README.md",
         "--title", "vacuum_cleaner (v#{VacuumCleaner::VERSION}) API Documentation"
     ]
@@ -42,7 +33,6 @@ begin
     gemspec.extra_rdoc_files = %w{README.md}
     
     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.files.reject! { |file| file =~ /\.gemspec$/ } # kinda redundant
@@ -59,6 +49,24 @@ task :clean do |t|
   FileUtils.rm_rf ".yardoc"
 end
 
+namespace :test do
+  desc 'Test the vacuum_cleaner plugin.'
+  Rake::TestTask.new(:unit) do |t|
+    t.libs << 'test'
+    t.pattern = 'test/unit/**/*_test.rb'
+    t.verbose = true
+  end
+
+  desc 'Run integration tests for the vacuum_cleaner plugin.'
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << 'test'
+    t.pattern = 'test/integration/**/*_test.rb'
+    t.verbose = true
+  end
+  
+  task :all => [:'test:unit', :'test:integration']
+end  
+
 namespace :metrics do
   desc 'Report all metrics, i.e. stats and code coverage.'
   task :all => [:stats, :coverage]

data/init.rb

@@ -1 +1 @@
-require File.dirname(__FILE__) + "rails/init"
+require File.join(File.dirname(__FILE__), 'rails', 'init')

data/lib/vacuum_cleaner.rb

@@ -1,7 +1,11 @@
-# Fancy value normalization utility for ruby (and rails).
+# Fancy value normalization utility for ruby (and rails),
+# see {VacuumCleaner::Normalizations} for more information about usage.
+#
+# @see VacuumCleaner::Normalizations
+# @see VacuumCleaner::Normalizer
 module VacuumCleaner
-  # +VacuumCleaner+ version string, current version is 0.1.0.
-  VERSION = "0.5.0".freeze
+  # +VacuumCleaner+ version
+  VERSION = "1.0.0".freeze
   
   autoload :Normalizer, 'vacuum_cleaner/normalizer'
   autoload :Normalizations, 'vacuum_cleaner/normalizations'

data/lib/vacuum_cleaner/normalizations.rb

@@ -1,7 +1,11 @@
 module VacuumCleaner
+
+  # @private
   # Suffix added to existing setter methods
   WITHOUT_NORMALIZATION_SUFFIX = "_without_normalization"
   
+  # Base module required to be included in 
+  #
   module Normalizations
     
     def self.included(base)
@@ -9,6 +13,27 @@ module VacuumCleaner
     end
         
     module ClassMethods
+      
+      # Enables normalization chain for supplied attributes.
+      #
+      # @example Basic usage for plain old ruby objects.
+      #   class Doctor
+      #     include VacuumCleaner::Normalizations
+      #     attr_accessor :name      
+      #     normalizes :name
+      #   end
+      #
+      # 
+      # @param [Strings, Symbols] attributes list of attribute names to normalize, at least one attribute is required
+      # @param [Hash] options optional list of normalizers to use, like +:downcase => true+. To not run the default
+      #        normalizer ({VacuumCleaner::Normalizer#normalize_value}) set +:default => false+
+      #
+      # @yield [value] optional block to define some one-time custom normalization logic
+      # @yieldparam value can be +nil+, otherwise value as passed through the default normalizer
+      # @yieldreturn should return value as normalized by the block
+      #
+      # @yield [instance, attribute, value] optional (extended) block with all arguments, like the +object+ and
+      #        current +attribute+ name. Everything else behaves the same es the single-value +yield+
       def normalizes(*attributes, &block)
         metaklass = class << self; self; end
         
@@ -38,8 +63,8 @@ module VacuumCleaner
           rb_src = <<-RUBY
             def #{attribute}=(value)                                                                          #  1.  def name=(value)
               value = send(:'normalize_#{attribute}', value)                                                  #  2.    value = send(:'normalize_name', value)
-              return send(#{original_setter.inspect}, value) if respond_to?(#{original_setter.inspect})       #  3.    return send(:'name_wo...=', value) if respond_to?(:'name_wo...=')
-              return send(:write_attribute, #{attribute.inspect}, value) if respond_to?(:write_attribute)     #  4.    return send(:write_attribute, :name, value) if respond_to?(:write_attribute)
+              return send(#{original_setter.inspect}, value) if respond_to?(#{original_setter.inspect})       #  3.    return send(:'name_wi...=', value) if respond_to?(:'name_wi...=')
+              return self[#{attribute.inspect}] = value if respond_to?(:[]=)                                  #  4.    return self[:name] = value if respond_to?(:write_attribute)
               @#{attribute} = value                                                                           #  5.   @name = value
             end                                                                                               #  6.  end
           RUBY
@@ -50,6 +75,7 @@ module VacuumCleaner
     end    
   end
   
+  # @private
   # Okay, because this library currently does not depend on
   # <tt>ActiveSupport</tt> or anything similar an "independent" camelizing process is
   # required.

data/lib/vacuum_cleaner/normalizations/method.rb

@@ -13,10 +13,7 @@ module VacuumCleaner
     # Subclasses of the +MethodNormalizer+ can take advantage of it's
     # +normalize_if_respond_to+ method, to easily create custom
     # normalizers based on methods availble on the result value.
-    class MethodNormalizer < Normalizer
-      # Ensure access to default normalization method
-      alias_method :default_normalize_value, :normalize_value
-      
+    class MethodNormalizer < Normalizer      
       # Helper method to "bake" a method normalizer from a method, enabling us to do stuff like.
       #
       #   TitelizeNormalizer = MethodNormalizer.build(:titleize)
@@ -31,11 +28,11 @@ module VacuumCleaner
         super(args)
       end
       
-      # Normalize value by calling the default normalizer (strip + nil if empty)
-      # and then if not <tt>nil</tt> call the method defined.
+      # Normalize value by trying to call the method at hand, if
+      # +value+ does not respond to the defined method, returns +nil+.
       def normalize_value(value)
         sym = options[:method]
-        value.respond_to?(sym) ? value.send(sym) : value
+        value.respond_to?(sym) ? value.send(sym) : nil
       end      
     end
     

data/lib/vacuum_cleaner/normalizations/url.rb

@@ -1,17 +1,38 @@
 module VacuumCleaner
   module Normalizations
     
-    # 
+    # Normalizer which is used to prefix strings with a scheme, if missing.
+    # This is useful to ensure, that an input field always has e.g. the
+    # "http://" scheme added. Please note, that this normalizer does not
+    # validate a URL in any way.
     #
+    #   normalizes :homepage, :url => true
     #
+    # Accepts a string as input, so to normalize for instance FTP URLs.
+    #
+    #   normalizes :download_url, :url => "ftp://"
+    #
+    # To make further customizations, the constructor accepts a hash.
+    #
+    #   normalizes, :contact_url, :url => { :scheme => "http://",
+    #                                       :unless => %r{\A(https?://|xmpp:|gtalk:|mailto:)} }
+    #
+    # The key <tt>:scheme</tt> is always used as the prefix, when the input
+    # does not a match the regex in <tt>:unless</tt>.
     class UrlNormalizer < Normalizer
+      
+      # Accepts either a hash or a string.
       def initialize(options = {})
         options = { :scheme => "http://", :unless => %r{\Ahttps?://}i } if options.nil? || options.empty?
         options = { :scheme => options, :unless => %r{\A#{options}}i } unless options.is_a?(Hash)
         super(options)
       end
       
+      # Prefixes input with <tt>options[:scheme]</tt> if it doesn't matches
+      # <tt>options[:unless]</tt>.
       def normalize_value(value)
+        value = super # just ensure that default stripping/cleaning is done already
+        return nil if value == options[:scheme]
         value =~ options[:unless] ? value : "#{options[:scheme]}#{value}" unless value.nil?
       end
     end

data/lib/vacuum_cleaner/normalizer.rb

@@ -1,4 +1,4 @@
-module VacuumCleaner #:nodoc:
+module VacuumCleaner
   
   # A small base class for implementing custom value normalizers.
   # Might seem like a slight overkill, yet makes the library pretty
@@ -46,7 +46,7 @@ module VacuumCleaner #:nodoc:
   # +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
@@ -59,7 +59,7 @@ module VacuumCleaner #:nodoc:
     # Only override this method if access to the <tt>object</tt> or <tt>attribute</tt> name
     # is required, else override +normalize_value+, makes life much simpler :)
     #
-    # Default behaviour just calls <tt>normalize_value(value)</tt>.
+    # Default behaviour just calls #normalize_value.
     def normalize(object, attribute, value); normalize_value(value) end
     
     # Override this method in subclasses to specifiy custom normalization steps and magic.

data/rails/init.rb

@@ -1,4 +1,3 @@
 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+
+ActiveRecord::Base.class_eval { include VacuumCleaner::Normalizations } if defined?(ActiveRecord::Base) # all versions of rails

data/test/integration/active_record_integration_test.rb

@@ -0,0 +1,67 @@
+require 'test_helper'
+
+# load ActiveRecord
+require 'active_record'
+
+# open connection to in-memory db
+ActiveRecord::Base.establish_connection({
+  :adapter => RUBY_PLATFORM =~ /java/ ? 'jdbcsqlite3' : 'sqlite3',
+  :database => ':memory:'})
+
+# run init.rb
+require File.join(File.dirname(__FILE__), '..', '..', 'init')
+
+puts "Running integration tests against: active_record-#{ActiveRecord::VERSION::STRING}"
+
+class ActiveRecordIntegrationTest < ::Test::Unit::TestCase
+  context "ActiveRecord::Base" do    
+    should "include VacuumCleaner::Normalizations" do
+      assert ActiveRecord::Base.included_modules.include?(VacuumCleaner::Normalizations)
+    end    
+    
+    context "with a sqlite connection" do
+      setup do
+        # build db
+        ActiveRecord::Base.connection.create_table :dummies, :force => true do |t|
+          t.column :name, :string
+        end
+      end
+      
+      should "respond to normalize and normalize :name on set" do
+        klass = Class.new(ActiveRecord::Base) do; set_table_name 'dummies'; normalizes :name end
+      
+        object = klass.new({ :name => "Elliot Reid\n" })
+        assert_equal "Elliot Reid", object.name        
+      end
+      
+      should "normalize on +object.name+ accessors as well" do
+        klass = Class.new(ActiveRecord::Base) do; set_table_name 'dummies'; normalizes :name end
+        
+        object = klass.new
+        object.name = " Dorian\t\n"
+        assert_equal "Dorian", object.name
+      end
+      
+      should "not normalize when accessing directly using []/write_attribute" do
+        klass = Class.new(ActiveRecord::Base) do; set_table_name 'dummies'; normalizes :name end
+        object = klass.new
+        object[:name] = "Elliot Reid\n\t"
+        assert_equal "Elliot Reid\n\t", object.name
+      end
+      
+      should "not normalize when reading from database" do        
+        ActiveRecord::Base.connection.execute "INSERT INTO dummies VALUES(NULL,'Elliot Reid\n\t');"
+        klass = Class.new(ActiveRecord::Base) do; set_table_name 'dummies'; normalizes :name end        
+        assert_equal "Elliot Reid\n\t", klass.last.name
+      end
+      
+      should "work with customized setter methods, masking AR-attributes" do
+        klass = Class.new(ActiveRecord::Base) do; set_table_name 'dummies'; def name=(n); self[:name] = n; end; normalizes :name end
+        object = klass.new :name => " J.D.\n"
+        assert_equal "J.D.", object.name
+        object.name = "Dorian\n\r"
+        assert_equal "Dorian", object.name
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -1,10 +1,3 @@
 require 'rubygems'
 require 'test/unit'
 require 'shoulda'
-require 'rr'
-
-# require 'normalo'
-
-Test::Unit::TestCase.send(:include, RR::Adapters::TestUnit)
-
-# Dir[File.dirname(__FILE__) + "/fixtures/*.rb"].each { |fixture| require fixture }

data/test/unit/vacuum_cleaner/normalizations/method_test.rb

@@ -17,6 +17,11 @@ class VacuumCleaner::Normalizations::MethodTest < Test::Unit::TestCase
       assert_equal "ELLIOT\n", upcaser.normalize_value("Elliot\n")
       assert_equal "  \t", upcaser.normalize_value("  \t")      
     end
+    
+    should "convert value to <nil> if object does not respond to supplied method" do
+      normalizer = MethodNormalizer.new(:this_method_does_certainly_not_exist)
+      assert_nil normalizer.normalize_value("Elliot")
+    end
   end
     
   context "DowncaseNormalizer#normalize_value" do

data/test/unit/vacuum_cleaner/normalizations/url_test.rb

@@ -35,5 +35,14 @@ class VacuumCleaner::Normalizations::UrlTest < Test::Unit::TestCase
       assert_equal "jabber:jd@sh.com", n.normalize_value("jabber:jd@sh.com")
       assert_equal "https://docs.google.com", n.normalize_value("https://docs.google.com")
     end
+    
+    should "normalize to <nil> if only scheme is given" do
+      assert_nil UrlNormalizer.new.normalize_value("http://")
+      assert_nil UrlNormalizer.new.normalize_value(" http://\n")
+    end
+    
+    should "be stupid, so if some other scheme is used, just override it, haha" do
+      assert_equal "xmpp:mailto:jd@sacred-heart.com", UrlNormalizer.new("xmpp:").normalize_value("mailto:jd@sacred-heart.com")
+    end
   end
 end

metadata

@@ -3,10 +3,10 @@ name: vacuum_cleaner
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 5
   - 0
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Lukas Westermann
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-09 00:00:00 +01:00
+date: 2010-04-21 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -31,24 +31,10 @@ dependencies:
         version: 2.10.2
   type: :development
   version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rr
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        - 10
-        - 5
-        version: 0.10.5
-  type: :development
-  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: activesupport
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -58,7 +44,7 @@ dependencies:
         - 5
         version: 2.3.5
   type: :development
-  version_requirements: *id003
+  version_requirements: *id002
 description: Ruby (and Rails) attribute cleaning support, provides some nice and easy to enhance default normalization strategies.
 email: lukas.westermann@gmail.com
 executables: []
@@ -79,6 +65,7 @@ files:
 - lib/vacuum_cleaner/normalizations/url.rb
 - lib/vacuum_cleaner/normalizer.rb
 - rails/init.rb
+- test/integration/active_record_integration_test.rb
 - test/test_helper.rb
 - test/unit/vacuum_cleaner/normalizations/method_test.rb
 - test/unit/vacuum_cleaner/normalizations/url_test.rb
@@ -115,6 +102,7 @@ signing_key:
 specification_version: 3
 summary: Ruby (and Rails) attribute cleaning support, provides some nice default normalization strategies.
 test_files: 
+- test/integration/active_record_integration_test.rb
 - test/test_helper.rb
 - test/unit/vacuum_cleaner/normalizations/method_test.rb
 - test/unit/vacuum_cleaner/normalizations/url_test.rb