normatron 0.0.4 → 0.0.5

data/README.rdoc

@@ -1,31 +1,231 @@
 = Normatron
 
 Normatron is a attribute normalizer for ActiveRecord.
+With it you can convert attributes to the desired format before saving them in the database.
+This gem inhibits the work of having to override attributes or create a specific method to perform the normalization.
 
 = Installation
 
-Add the following into your gemfile:
+Let the bundler install the gem by adding the following into your application gemfile:
 
   gem 'normatron'
 
-Bundle it up:
+And then bundle it up:
   
   $ bundle install
 
+Or install it by yourself:
+
+  $ gem install normatron
+
+= The problem
+
+I have a product model as the following:
+
+  # ./db/migrate/20120101010000_create_products.rb
+
+  class CreateProducts < ActiveRecord::Migration
+    def change
+      create_table :products do |t|
+        t.string  :name
+        t.decimal :price, :precision => 10, :scale => 2
+      end
+    end
+  end
+
+  # ./app/models/products.rb
+
+  class Product < ActiveRecord::Base
+    attr_accessible :name, :price
+  end
+
+And I want the product name to be uppercased before save.
+I can do it basically by two ways:
+
+== a. Overriding the 'name' method
+
+  # ./app/models/products.rb
+
+  class Product < ActiveRecord::Base
+    attr_accessible :name, :price
+
+    def name=(value)
+      super value.mb_chars.upcase
+    end
+  end
+
+== b. Using the before_validation callback
+
+  # ./app/models/products.rb
+
+  class Product < ActiveRecord::Base
+    attr_accessible :name, :price
+
+    before_validation :do_upcase
+
+    def do_upcase
+      write_attribute :name, name.mb_chars.upcase
+    end
+  end
+
+Both ways are ilenegant, boring, error prone and expensive.
+Which led me to use a third method:
+
 = Usage
 
-Let's take an example model:
+  # ./app/models/products.rb
+
+  class Product < ActiveRecord::Base
+    attr_accessible :name, :price
+
+    normalize :name, :with => :upcase
+  end
+
+  $ rails console
+  > p = Product.create :name => "  memory   card    "
+  > p.name
+  => "  MEMORY   CARD    "
+
+You can assign multiple attributes to the same filter:
+
+  # ./app/models/products.rb
+
+  class Product < ActiveRecord::Base
+    attr_accessible :name, :description, :brand, :price
+
+    normalize :name, :brand, :with => :capitalize
+  end
+
+  $ rails console
+  > p = Product.create :name => "memory   card    4  GB    ", :brand => "OEM"
+  > p.name
+  => "Memory   card    4  GB    "
+  > p.brand
+  => "Oem"
+
+And/or assign multiple filters to multiple attributes:
+
+  # ./app/models/products.rb
 
-app/models/product.rb
   class Product < ActiveRecord::Base
+    attr_accessible :name, :description, :brand, :price
+
+    normalize :name, :description, :brand, :with => [:upcase, :squish, :nillify]
+  end
+
+  $ rails console
+  > p = Product.create :name => "   memory   card    4  GB    ", :description => "         ", :brand => "oem   "
+  > p.name
+  => "MEMORY CARD 4 GB"
+  > p.brand
+  => "OEM"
+  > p.description
+  => nil
+
+= Filters
+== :upcase and :downcase
+Change all character to upcase and downcase, respectively.
+Accented characters are affected too.
+
+  class User < ActiveRecord::Base
     attr_accessible :name
 
     normalize :name, :with => :upcase
   end
 
   $ rails console
-  > p = Product.new
-  > p.name = "  memory   card    "
-  > p.valid?
+  > d = User.create :name => "Darth Vader"
+  > d.name
+  => "DARTH VADER"
+  > j = User.create :name => " José    Negrão  "
+  > j.name
+  => " JOSÉ    NEGRÃO  "
+
+== :capitalize
+Capitalize the first character of the sequence.
+Accented characters are affected too.
+
+  class Player < ActiveRecord::Base
+    attr_accessible :name, :race
+
+    normalize :name, :race, :with => :capitalize
+  end
+
+  $ rails console
+  > a = Player.create :name => "ÉBANO PEREIRA", :race => " protoss"
+  > a.name
+  => "Ébano pereira"
+  > a.race
+  => " protoss"
+
+== :titlecase or :titleize
+Capitalize the first character of each word.
+Accented characters are affected too.
+
+  class Player < ActiveRecord::Base
+    attr_accessible :name, :race
+
+    normalize :name, :race, :with => :titleize
+  end
+
+  $ rails console
+  > a = Player.create :name => "fernando rodrigues", :race => " zerg"
+  > a.name
+  => "Fernando Rodrigues"
+  > a.race
+  => " Zerg"
+
+== :strip, :lstrip and :rstrip
+Remove trailing and/or leading spaces.
+
+  class Address < ActiveRecord::Base
+    attr_accessible :city, :district, :street
+
+    normalize :city, :with => :strip
+    normalize :district, :with => :lstrip
+    normalize :street, :with => :rstrip
+  end
+
+  $ rails console
+  > a = Address.create :city => " gotham ", :district => " red light ", :street => " no name "
+  > a.city
+  => "gotham"
+  > a.district
+  => "red light "
+  > a.street
+  => " no name"
+
+== :squish
+Remove trailing and leading spaces and then changing remaining consecutive whitespace groups into one space each.
+
+  class Product < ActiveRecord::Base
+    attr_accessible :description
+
+    normalize :description, :with => :squish
+  end
+
+  $ rails console
+  > p = Product.create :description => "   \t My   product is \n cheap!  !    !     "
+  > p.description
+  => "My product is cheap!!!"
+
+== :nillify, :nullify or :nil
+Convert a blank attribute into nil.
+
+  class Person < ActiveRecord::Base
+    attr_accessible :gender, :name
+
+    normalize :gender, :with => :nil
+  end
+
+  $ rails console
+  > p = Person.create :gender => "     ", :name => "  "
+  > p.gender
+  => nil
   > p.name
-  => "  MEMORY   CARD    "
+  => "  "
+
+= Special Thanks
+This gem was inspired on work of {fnando}[https://github.com/fnando] called {normalize_attributes}[https://github.com/fnando/normalize_attributes].
+I just forked his gem and added some functionalities.
+He has a lot of interesting gems on his repo, please take a look.

data/lib/normatron.rb

@@ -1,4 +1,4 @@
-require "normatron/conversors"
+require "normatron/filters"
 require "normatron/active_record"
 
 ActiveRecord::Base.send :include, Normatron::ActiveRecord

data/lib/normatron/active_record.rb

@@ -16,53 +16,45 @@ module Normatron
     end
 
     module ClassMethods
-      # Set an attribute normalization before model validation.
-      # Args uses the attribute names following by a hash with conversion options.
-      #
-      # Example 1:
-      # normalize :attribute_name
-      # 
-      # Example 2:
-      # normalize :attribute_name, :with => :upcase
-      #
-      # Example 3:
-      # normalize :attribute_name, :with => [:squish, :downcase]
+
       def normalize(*args)
         # Extract options
         @normalization_options ||= {}
         options = args.extract_options!
 
-        # Set conversors
-        conversors = []
+        # Set callbacks
+        filters = []
         if options.empty? # Default standardization
-          conversors << [:squish, :strip, :nillify]
+          filters << [:squish, :nillify]
         elsif options.has_key? :with
-          conversors << options[:with]
+          filters << options[:with]
         else
           raise "Wrong normalization key in #{self.name}, use :with instead of #{options.keys.first}"
         end
 
         # Make a prettier array
-        conversors = conversors.flatten.compact
-        conversors.map! { |v| v = v.to_sym }
+        filters = filters.flatten.compact
+        filters.map! { |v| v = v.to_sym }
 
-        # Check conversors
-        conversors.each do |c|
-          unless Conversors::CALLBACKS.include? c
-            raise "Normalization callback '#{c}' doesn't exist"
+        # Check filters
+        filters.each do |f|
+          unless Filters::NAMES.include? f
+            raise "Normalization filter '#{f}' doesn't exist"
           end
         end
 
-        # Add normalization conversors
+        # Add normalization callbacks
         args.each do |attribute|
           # Check attributes
           unless self.column_names.include? attribute.to_s
             raise "Attribute '#{attribute}' doesn't exist in #{self.name}"
           end
 
-          @normalization_options[attribute] = conversors
+          @normalization_options[attribute] ||= []
+          @normalization_options[attribute] += filters
         end
       end
+      alias :normatron :normalize
     end
 
     def normalize_attributes
@@ -73,8 +65,7 @@ module Normatron
         value = send("#{attribute}_before_type_cast")  || send(attribute)
 
         methods.each do |method|
-          # Skip if value is nil originally or the method 'nullify' was called before
-          value = Conversors.convert(method, value) unless value.nil?
+          value = Filters.do_filter(method, value) unless value.nil?
 
           if value == :no_method
             raise ArgumentError, "Method :#{method} cannot be resolved.

data/lib/normatron/{conversors.rb → filters.rb}

@@ -2,49 +2,54 @@ require "i18n"
 require "active_support/all"
 
 module Normatron
-  module Conversors
+  module Filters
+
+    private
 
     MB_CHARS_METHODS = [:upcase, :downcase, :capitalize, :lstrip, :rstrip, :strip, :titlecase, :titleize]
-    SELF_METHODS = [:nillify, :nullify, :nil, :squish, :currency, :integer, :float, :postal_code, :phone, :digits, :phrase]
-    CALLBACKS = MB_CHARS_METHODS + SELF_METHODS
+    SELF_METHODS = [:nillify, :nullify, :nil, :squish, :currency, :integer, :float]
+
+    public
+
+    NAMES = MB_CHARS_METHODS + SELF_METHODS
 
-    def self.convert(method, value)
+    def self.do_filter(method, value)
       if MB_CHARS_METHODS.include? method
         value.mb_chars.send(method).to_s
       elsif SELF_METHODS.include? method
-        send("convert_#{method}", value)
+        send("filter_#{method}", value)
       else
         :no_method
       end
     end
 
     # Return nil if value is blank or else value itself.
-    def self.convert_nillify(value)
+    def self.filter_nillify(value)
       value.blank? ? nil : value
     end
     class << self
-      alias :convert_nil      :convert_nillify
-      alias :convert_nullify  :convert_nillify
+      alias :filter_nil      :filter_nillify
+      alias :filter_nullify  :filter_nillify
     end
 
     # Remove repeated spaces from the string.
-    def self.convert_squish(value)
-      value.mb_chars.to_s.gsub(/\p{Zs}+/u, ' ')
+    def self.filter_squish(value)
+      value.squish
     end
 
-    def self.convert_currency(value)
-      convert_number value, :currency
+    def self.filter_currency(value)
+      filter_number value, :currency
     end
 
-    def self.convert_float(value)
-      convert_number value, :float
+    def self.filter_float(value)
+      filter_number value, :float
     end
 
-    def self.convert_integer(value)
-      convert_number value
+    def self.filter_integer(value)
+      filter_number value
     end
 
-    def self.convert_number(value, type = :integer)
+    def self.filter_number(value, type = :integer)
       return value unless value.is_a?(String) && value.present?
 
       # Find the first number in the sequence
@@ -63,30 +68,12 @@ module Normatron
       decimal_places = value.size - chars_until_separator
 
       # Build number
-      res = convert_digits(value).to_f
+      res = filter_digits(value).to_f
       res *= -1 if negative
       res /= 10 ** decimal_places
       res = res.to_i if type == :integer
 
       res
     end
-
-    def self.convert_postal_code(value)
-      res = convert_digits value
-      res.size == 8 ? "%s-%s" % [res[0..4], res[5..7]] : value
-    end
-
-    def self.convert_phone(value)
-      res = convert_digits value
-      res.size == 10 ? "(%s) %s-%s" % [res[0..1], res[2..5], res[6..9]] : value
-    end
-
-    def self.convert_digits(value)
-      value.to_s.gsub(/[^\d]/, '')
-    end
-
-    def self.convert_phrase(value)
-      convert(:squish, convert(:strip, value))
-    end
   end
 end

data/lib/normatron/version.rb

@@ -1,3 +1,3 @@
 module Normatron
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/spec/filters_spec.rb

@@ -0,0 +1,77 @@
+# encoding: utf-8
+
+require "spec_helper"
+
+describe Normatron::Filters do
+
+  before :each do
+    TestModel.normalization_options = nil
+  end
+
+  it :capitalize do
+    TestModel.normalize :string_column, :with => :capitalize
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "   abc   \f   def   \n   123   áèç   \t !*&   \r   4gü   "
+
+    m.string_column = "abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü"
+    m.valid?
+    m.string_column.should == "Abc   \f   def   \n   123   áèç   \t !*&   \r   4gü"
+  end
+
+  it :downcase do
+    TestModel.normalize :string_column, :with => :downcase
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "   abc   \f   def   \n   123   áèç   \t !*&   \r   4gü   "
+  end
+
+  it :squish do
+    TestModel.normalize :string_column, :with => :squish
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "abc DEF 123 áÈç !*& 4gü"
+  end
+
+  it :strip do
+    TestModel.normalize :string_column, :with => :strip
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü"
+  end
+
+  it :titlecase do
+    TestModel.normalize :string_column, :with => :titlecase
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "   Abc   \f   Def   \n   123   Áèç   \t !*&   \r   4gü   "
+  end
+
+  it :upcase do
+    TestModel.normalize :string_column, :with => :upcase
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "   ABC   \f   DEF   \n   123   ÁÈÇ   \t !*&   \r   4GÜ   "
+  end
+
+  it :nillify do
+    TestModel.normalize :string_column, :with => :nillify
+
+    m = TestModel.create :string_column => "               "
+    m.string_column.should == nil
+  end
+
+  it :lstrip do
+    TestModel.normalize :string_column, :with => :lstrip
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+  end
+
+  it :rstrip do
+    TestModel.normalize :string_column, :with => :rstrip
+
+    m = TestModel.create :string_column => "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü   "
+    m.string_column.should == "   abc   \f   DEF   \n   123   áÈç   \t !*&   \r   4gü"
+  end
+end

data/spec/normatron_spec.rb

@@ -5,35 +5,21 @@ require "spec_helper"
 describe Normatron do
   before :each do
     TestModel.normalization_options = nil
-    @instance = TestModel.new
   end
 
-  it "should allow save without any normalize option" do
-    lambda do
-      @instance.string_column = "Any string"
-      @instance.save!
-    end.should_not raise_error
-  end
-
-  it "should raise an error if attribute doesn't exist" do
-    lambda do
-      TestModel.normalize :ghost_attribute
-    end.should raise_error "Attribute 'ghost_attribute' doesn't exist in TestModel"
+  it "should respond to aliases" do
+    TestModel.should respond_to :normatron
   end
 
-  it "should raise an error if a wrong option is set" do
+  it "should save without normalization option" do
     lambda do
-      TestModel.normalize :string_column, :wrong_option => :upcase
-    end.should raise_error "Wrong normalization key in TestModel, use :with instead of wrong_option"
-  end
-
-  it "should raise an error if wrong conversor is called" do
-    lambda do
-      TestModel.normalize :string_column, :with => :wrong_conversor
-    end.should raise_error "Normalization callback 'wrong_conversor' doesn't exist"
+      instance = TestModel.new
+      instance.string_column = "Any string"
+      instance.save!
+    end.should_not raise_error
   end
 
-  it "options should be accessible" do
+  it "filters should be accessible" do
     TestModel.normalize :string_column, :with => [:capitalize, :upcase]
     TestModel.normalize :integer_column, :with => :integer
     TestModel.normalization_options.should == { :string_column => [:capitalize, :upcase], :integer_column => [:integer] }
@@ -41,108 +27,60 @@ describe Normatron do
     TestModel.normalization_options.should == { :integer_column => [:integer] }
   end
 
-  describe "Conversors" do
-    it :capitalize do
-      TestModel.normalize :string_column, :with => :capitalize
-
-      m = TestModel.create :string_column => "áb c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == "Áb c, 1 2 3 def ghi i oz "
-    end
-
-    it :digits do
-      TestModel.normalize :string_column, :with => :digits
-
-      m = TestModel.create :string_column => " 1a 2b 3c 4d 5e 6f "
-      m.string_column.should == "123456"
-    end
-
-    it :downcase do
-      TestModel.normalize :string_column, :with => :downcase
-
-      m = TestModel.create :string_column => " a b c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == " a b c, 1 2 3 def ghi i oz "
-    end
-
-    it :phone do
-      TestModel.normalize :string_column, :with => :phone
-
-      m = TestModel.create :string_column => "(99) 9999-9999"
-      m.string_column.should == "(99) 9999-9999"
-
-      m = TestModel.create :string_column => "9999999999"
-      m.string_column.should == "(99) 9999-9999"
-
-      m = TestModel.create :string_column => "999999999"
-      m.string_column.should == "999999999"
-    end
-
-    it :phrase do
-      TestModel.normalize :string_column, :with => :phrase
+  it "should apply single filter" do
+    TestModel.normalize :string_column, :with => :upcase
 
-      m = TestModel.create :string_column => " a b c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == "a b c, 1 2 3 DEF GHI i oz"
-    end
-
-    it :postal_code do
-      TestModel.normalize :string_column, :with => :postal_code
-
-      m = TestModel.create :string_column => "88888-888"
-      m.string_column.should == "88888-888"
-
-      m = TestModel.create :string_column => "88888888"
-      m.string_column.should == "88888-888"
-
-      m = TestModel.create :string_column => "8888888"
-      m.string_column.should == "8888888"
-    end
-
-    it :squish do
-      TestModel.normalize :string_column, :with => :squish
-
-      m = TestModel.create :string_column => " a b c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == " a b c, 1 2 3 DEF GHI i oz "
-    end
-
-    it :strip do
-      TestModel.normalize :string_column, :with => :strip
+    m = TestModel.create :string_column => "master of puppets"
+    m.string_column.should == "MASTER OF PUPPETS"
+  end
 
-      m = TestModel.create :string_column => " a b c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == "a b c, 1 2 3 DEF GHI i oz"
-    end
+  it "should apply multiple filters" do
+    TestModel.normalize :string_column, :with => [:downcase, :squish, :nil]
 
-    it :titlecase do
-      TestModel.normalize :string_column, :with => :titlecase
+    m = TestModel.create :string_column => "     YOU   SHALL    NOT   PASS    "
+    m.string_column.should == "you shall not pass"
 
-      m = TestModel.create :string_column => " aé áb c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == " Aé Áb C, 1 2 3 Def Ghi I Oz "
-    end
+    m = TestModel.create :string_column => "     "
+    m.string_column.should == nil
+  end
 
-    it :upcase do
-      TestModel.normalize :string_column, :with => :upcase
+  it "should stack filters for the same attribute" do
+    TestModel.normalize :string_column, :with => [:upcase, :squish]
+    TestModel.normalize :string_column, :with => :nil
+    TestModel.normalization_options.should == { :string_column => [:upcase, :squish, :nil] }
+  end
 
-      m = TestModel.create :string_column => " a b c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == " A B C, 1 2 3 DEF GHI I OZ "
-    end
+  it "default filters should be :squish and :nillify" do
+    TestModel.normalize :string_column
+    TestModel.normalization_options.should == { :string_column => [:squish, :nillify] }
+  end
 
-    it :nillify do
-      TestModel.normalize :string_column, :with => :nillify
+   it "default filters should be :squish and :nillify" do
+    TestModel.normalize :string_column
+    TestModel.normalization_options.should == { :string_column => [:squish, :nillify] }
+  end
 
-      m = TestModel.create :string_column => " "
-      m.string_column.should == nil
-    end
+  it "should filter multiple attributes" do
+    TestModel.normalize :string_column, :integer_column, :with => :nil
 
-    it :lstrip do
-      TestModel.normalize :string_column, :with => :lstrip
+    m = TestModel.create :string_column => "      ", :integer_column => "      "
+    m.string_column.should == nil
+    m.integer_column.should == nil
+  end
 
-      m = TestModel.create :string_column => " a b c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == "a b c, 1 2 3 DEF GHI i oz "
-    end
+  it "should raise error if a wrong option is set and the right isn't" do
+    lambda do
+      TestModel.normalize :string_column, :wrong_option => :upcase
+    end.should raise_error "Wrong normalization key in TestModel, use :with instead of wrong_option"
 
-    it :rstrip do
-      TestModel.normalize :string_column, :with => :rstrip
+    lambda do
+      TestModel.normalize :string_column, :wrong_option => :upcase, :with => :downcase
+    end.should_not raise_error
+  end
 
-      m = TestModel.create :string_column => " a b c, 1 2 3 DEF GHI i oz "
-      m.string_column.should == " a b c, 1 2 3 DEF GHI i oz"
-    end
+  it "should raise error if wrong filter is called" do
+    lambda do
+      TestModel.normalize :string_column, :with => :wrong_filter
+    end.should raise_error "Normalization filter 'wrong_filter' doesn't exist"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: normatron
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-28 00:00:00.000000000 Z
+date: 2012-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -68,8 +68,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/normatron/filters.rb
 - lib/normatron/active_record.rb
-- lib/normatron/conversors.rb
 - lib/normatron/version.rb
 - lib/normatron.rb
 - MIT-LICENSE
@@ -78,6 +78,7 @@ files:
 - spec/support/test_model.rb
 - spec/normatron_spec.rb
 - spec/schema.rb
+- spec/filters_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/fernandors87/normatron
 licenses: []
@@ -107,4 +108,5 @@ test_files:
 - spec/support/test_model.rb
 - spec/normatron_spec.rb
 - spec/schema.rb
+- spec/filters_spec.rb
 - spec/spec_helper.rb