normatron 0.3.0 → 0.3.1

data/README.md

@@ -0,0 +1,345 @@
+# Normatron
+
+Normatron is a Ruby On Rails plugin that perform attribute normalizations for ActiveRecord objects.<br />
+With it you can normalize attributes to the desired format before saving them in the database.<br />
+This gem inhibits the work of having to override attributes or create a specific method to perform most of the normalizations.
+
+## Installation
+
+Let the bundler install the gem by adding the following into your application gemfile:
+
+```ruby
+gem 'normatron'
+```
+
+And then bundle it up:
+
+```bash
+$ bundle install
+```
+
+Or install it by yourself:
+
+```bash
+$ gem install normatron
+```
+
+Then run the generator:
+
+```bash
+$ rails generator normatron:install
+```
+
+## The problem
+
+Suppose you have a product model as the following:
+
+```ruby
+# ./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
+```
+```ruby
+# ./app/models/products.rb
+class Product < ActiveRecord::Base
+  attr_accessible :name, :price
+end
+```
+
+If you want the *name* attribute be uppercased before saving it into the database, the most usual approaches includes:
+
+* Override the *name* setter and convert the value to an uppercased string.
+* Write a method or block and bind it to an [ActiveRecord callback](http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html) (like *before_validation* or *before_save*).
+
+Both ways are ilenegant, boring to implement, error prone and very expensive.<br />
+What led me to make this gem and offer a third way to handle this.
+
+## Usage
+
+Call the [normalize](http://www.rubydoc.info/github/fernandors87/normatron/Normatron/Extensions/ActiveRecord/ClassMethods:normalize) class method inside your model to set the normalization rules:
+
+```ruby
+# ./app/models/products.rb
+class Product < ActiveRecord::Base
+  attr_accessible :name, :price
+  normalize :name
+end
+```
+
+And it will behave like this:
+
+```bash
+ $ rails console
+ > memory = Product.create name: "  memory   card    "
+=> #<Product id: nil, name: "memory card", price: nil>
+ > unknown = Product.create name: "    "
+=> #<Product id: nil, name: nil, price: nil>
+```
+
+In this case the `:with` option was ommited, then the [:blank](http://rubydoc.info/gems/normatron/Normatron/Filters/BlankFilter) and [:squish](http://rubydoc.info/gems/normatron/Normatron/Filters/SquishFilter) filters was called to the *name* attribute.<br />
+These are the default filters and can be easily changed in the initializer file.
+
+To specify which kind of filters will be binded to each attribute, pass the filter name to the `:with` option:
+
+```ruby
+class MyModel < ActiveRecord::Base
+  # Single filter to a single attribute
+  normalize :attr_a, :with => :upcase
+
+  # Multiple filters to multiple attributes
+  normalize :attr_b, :attr_c, :attr_d, :with => [:upcase, :squish]
+
+  # The :keep filter is an example of filter that uses arguments.
+  # In this case, the filter is passed as a Hash, where the key is the filter name,
+  # and the value is an Array of arguments.
+  normalize :attr_e, :with => {:keep => [:Latin, :Z]}
+
+  # The same as above can be obtained using an Array instead of a Hash.
+  # But when filter uses arguments, set him inside another Array is mandatory.
+  normalize :attr_f, :with => [[:keep, :Latin, :Z]]
+
+  # Mix simple filters with filters carrying arguments this way:
+  normalize :attr_g, :with => [:blank, {:keep => [:Latin, :Z]}, :squish]
+
+  # Or this way:
+  normalize :attr_h, :with => [:blank, [:keep, :Latin, :Z], :squish]
+end
+```
+
+### Filter Stackings
+
+The normalize method stack the filters when called multiple times to the same attribute.
+
+```ruby
+# 1st Way: Without stacking filters
+class MyModel < ActiveRecord::Base
+  normalize :attr_a, :with => :blank
+  normalize :attr_b, :with => [:blank, :squish]
+  normalize :attr_c, :with => [:blank, :squish, :upcase]
+end
+
+# 2nd Way: Stacking filters
+# This piece of code produces the exactly the same results as 1st way.
+class MyModel < ActiveRecord::Base
+  normalize :attr_a, :attr_b, :attr_c, :with => :blank
+  normalize :attr_b, :attr_c, :with => :squish
+  normalize :attr_c, :with => :upcase
+end
+```
+
+### Typing Less
+
+In some cases is possible to write much less by passing multiple attributes to normalize method:
+
+```ruby
+# 1st Way: Setting rules to single attributes
+class MyModel < ActiveRecord::Base
+  normalize :attr_a, :with => :blank
+  normalize :attr_b, :with => :squish
+  normalize :attr_c, :with => :upcase
+  normalize :attr_d, :with => [:blank, :squish]
+  normalize :attr_e, :with => [:blank, :upcase]
+  normalize :attr_f, :with => [:squish, :upcase]
+  normalize :attr_g, :with => [:blank, :squish, :upcase]
+end
+
+# 2nd Way: Setting rules to multiple attributes
+class MyModel < ActiveRecord::Base
+  normalize :attr_a, :attr_d, :attr_e, :attr_g, :with => :blank
+  normalize :attr_b, :attr_d, :attr_f, :attr_g, :with => :squish
+  normalize :attr_c, :attr_e, :attr_f, :attr_g, :with => :upcase
+end
+```
+
+### Filters
+
+Normatron have a bunch of built-in filters.<br />
+The list of all filters and instructions of how to use them can be found in the [Normatron::Filters](http://rubydoc.info/gems/normatron/Normatron/Filters) documentation.
+
+### Getting Normalization Rules
+
+You can know what kind of rules was set to a model as following:
+
+```
+ $ rails console
+ > User.normalize_rules
+=> {:login => {:blank => nil, :remove => [:Zs]},
+    :email => {:blank => nil, :squish => nil, :downcase => nil},
+    :name  => {:blank => nil, :squish => nil, :upcase => nil}}
+```
+
+### Applying Normalizations
+
+All attributes are automatically normalized by [before_validation](http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html) callback, what means any method that evoke the *before_validation* callback will perform the normalizations.<br />
+Some of these methods includes:
+
+* [ActiveRecord::Validations#valid?](http://api.rubyonrails.org/classes/ActiveRecord/Validations.html#method-i-valid-3F)
+* [ActiveRecord::Persistence#save](http://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save)
+* [ActiveRecord::Persistence::ClassMethods#create](http://api.rubyonrails.org/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-create)
+
+To apply the normalizations without doing validations or persistence, just call the [apply_normalizations](http://rubydoc.info/gems/normatron/Normatron/Extensions/ActiveRecord/InstanceMethods#apply_normalizations-instance_method) method as following:
+
+```
+ $ rails console
+ > user = User.new
+ > user.name = "   anon   "
+ > user.email = "ANON@GMAIL.COM"
+ > user.login = "my name \n is anon"
+ > user.attributes
+=> {:id    => nil,
+    :name  => "   anon   ",
+    :email => "ANON@GMAIL.COM",
+    :login => "my name \n is anon"}
+ > user.apply_normalizations
+ > user.attributes
+=> {:id    => nil,
+    :name  => "ANON",
+    :email => "anon@gmail.com",
+    :login => "mynameisanon"}
+```
+
+### Building Your Own Filters
+
+#### 1st way: Defining a filter as a module
+
+Create a new module with the following characteristics:
+
+* Having a module method called evaluate
+* The evaluate method must receive at least one argument
+* The first argument must be the value to be filtered
+
+Here is an example:
+
+```ruby
+# ./lib/my_filters/emoticon_filter.rb
+module MyFilters
+  module EmoticonFilter
+    def self.evaluate(value, type)
+      emot = (type == :sad) ? ":(" : ":D"
+      value + emot
+    end
+  end
+end
+```
+
+Then add him to your Normatron initializer file:
+
+```ruby
+require 'lib/my_filters/emoticon_filter'
+Normatron.setup do |config|
+  #...
+  config.filters[:emoticon] = MyFilter::EmoticonFilter
+  #...
+end
+```
+
+Usage:
+
+```ruby
+class Message < ActiveRecord::Base
+  belongs_to :person
+  normalize :content, :with => {:emoticon => :happy} # Always happy
+end
+```
+
+1. Pros
+  * Allow create specific documentation for your filter
+  * More easy to make them portable for multiple applications and purposes
+2. Cons
+  * Verbose
+
+#### 2nd way: Defining a filter as a lambda
+
+Create a new lambda object with the following characteristics:
+
+* Must receive at least one argument
+* The first argument must be the value to be filtered
+
+The lambda will be defined inside Normatron initializer:
+
+```ruby
+Normatron.setup do |config|
+  #...
+
+  config.filters[:emoticon] = lambda do |value, type|
+    emot = (type == :sad) ? ":(" : ":D"
+    value + emot
+  end
+
+  #...
+end
+```
+
+Usage:
+
+```ruby
+class Message < ActiveRecord::Base
+  belongs_to :person
+  normalize :content, :with => {:emoticon => :sad} # Always sad
+end
+```
+
+1. Pros
+  * Less verbose than 1st method
+2. Cons
+  * Hard to share filter functionalities between other applications
+  * Hard to use filter functionalities for other purposes
+
+#### 3th way: Defining a filter as model instance method
+
+Create a new instance method within your model with the following characteristics:
+
+* Must receive at least one argument
+* The first argument must be the value to be filtered
+
+The method will be defined inside your model class:
+
+```ruby
+class Message < ActiveRecord::Base
+  belongs_to :person
+  normalize :content, :with => :emoticon # Happy or sad according person's mood
+
+  def emoticon(value)
+    emot = (person.mood == :happy) ? ":D" : ":("
+    value + emot
+  end
+end
+```
+
+1. Pros
+  * Can use instance variables
+2. Cons
+  * Cannot be shared between objects
+
+# Contributing
+
+There are several ways to make this gem even better:
+
+* Forking this project
+* Adding new features or bug fixes
+* Making tests
+* Commiting your changes
+* Reporting any bug or unexpected behavior
+* Suggesting any improvement
+* Sharing with your friends, forums, communities, job, etc...
+* Helping users with difficulty using this gem
+* Paying me a beer =]
+
+# Credits
+
+This gem was initially inspired on:
+
+* [normalize_attributes](https://github.com/fnando/normalize_attributes) - I liked the cleaner code and simplicity of this gem.
+* [attribute_normalizer](https://github.com/mdeering/attribute_normalizer) - Very powerful.
+
+The idea is to mix the good things of both gems, adding some features and changing something to fit my taste.
+
+# License
+
+See file attached to source code or [click here](https://github.com/fernandors87/normatron/blob/master/MIT-LICENSE).

data/lib/generators/normatron/install_generator.rb

@@ -2,19 +2,25 @@ module Normatron
   ##
   # Creates all necessary files to run Normatron in your Ruby On Rails project.
   #
-  # These files are:
+  # Even when required, Normatron doesn't include his functionalities into your ORM automatically.
+  # It behaves this way to avoid some potential issues.
+  #
+  # Using this generator, you can get fully control of Normatron behavior through initialization file.
+  #
+  # These files includes:
   # * config/initializers/normatron.rb
   #
-  # *Usage:*
-  #   $ rails generator normatron:install
+  # h2. Usage
+  #   
+  # pre. $ rails generator normatron:install
   class InstallGenerator < Rails::Generators::Base
     source_root File.expand_path('../templates', __FILE__)
     desc "Create all necessary files to run Normatron in your Ruby On Rails project."
 
     ##
-    # Copy files from templates to their respective destination
+    # Copy files from templates to their respective destination.
     #
-    # These files are:
+    # These files includes:
     # * config/initializers/normatron.rb
     def copy_files
       copy_file "normatron.rb", "config/initializers/normatron.rb"

data/lib/generators/normatron/templates/normatron.rb

@@ -1,4 +1,21 @@
 Normatron.setup do |config|
-  config.default_filters = :blank, :squish
+  # Comment the line below to disable Normatron
   config.add_orm Normatron::Extensions::ActiveRecord
+
+  # Create your own filters using a Proc/lambda as following: 
+  # 
+  # config.filters[:smile] = lambda do |value|
+  #   value.kind_of?(String) : value + " =]" : value
+  # end
+
+  # Include your own filter module as following:
+  #
+  # config.filters[:laugh] = YourNamespace::YourFilterSet::YourFilter
+
+  # Set the default filters.
+  #
+  # Examples:
+  #   config.default_filters = :upcase, {:keep => [:L, :N]}
+  #   config.default_filters = :ascii,  [:keep, :L, :N]
+  config.default_filters = :blank, :squish
 end

data/lib/normatron/configuration.rb

@@ -9,6 +9,7 @@ module Normatron
       @default_filters = { blank: nil, squish: nil }
 
       @filters = {}
+      @filters[:ascii]      = Normatron::Filters::AsciiFilter
       @filters[:blank]      = Normatron::Filters::BlankFilter
       @filters[:camelize]   = Normatron::Filters::CamelizeFilter
       @filters[:capitalize] = Normatron::Filters::CapitalizeFilter

data/lib/normatron/extensions/active_record.rb

@@ -13,30 +13,32 @@ module Normatron
           before_validation :apply_normalizations
 
           class << self
-            attr_accessor :normalize_filters
+            attr_accessor :normalize_rules
+            alias :normalize_filters :normalize_rules
+            alias :normalize_filters= :normalize_rules=
           end
         end
       end
 
       module ClassMethods
         def normalize(*args)
-          # Check existence of all attributes
+          # Check the existence of all attributes
           options = args.extract_options!
           filters, columns = args.map(&:to_s), column_names
           raise UnknownAttributeError if (columns & filters).size != filters.size
 
-          # Specify the use of default filters or not
+          # Need to use default filters?
           if options[:with].nil? || options[:with].blank?
             new_filters = Normatron.config.default_filters
           else
             new_filters = Normatron.build_hash(options[:with])
           end
 
-          # Append to older filters hash
-          @normalize_filters ||= {}
-          @normalize_filters =
-          args.reduce(@normalize_filters) do |hash, att|
-            filters = (@normalize_filters[att] || {}).merge(new_filters)
+          # Append new filters to rules
+          @normalize_rules ||= {}
+          @normalize_rules =
+          args.reduce(@normalize_rules) do |hash, att|
+            filters = (@normalize_rules[att] || {}).merge(new_filters)
             hash.merge({att => filters})
           end
         end
@@ -44,7 +46,7 @@ module Normatron
 
       module InstanceMethods
         def apply_normalizations
-          named_filters = Normatron.configuration.filters
+          listed_filters = Normatron.configuration.filters
 
           self.class.normalize_filters.each do |attribute, filters|
             value = send("#{attribute}_before_type_cast") || send(attribute)
@@ -52,8 +54,10 @@ module Normatron
             filters.each do |filter, args|
               if self.respond_to? filter
                 value = send(filter, value, *args)
-              elsif !named_filters[filter].nil?
-                value = named_filters[filter].evaluate(value, *args)
+              elsif listed_filters[filter].kind_of? Module
+                value = listed_filters[filter].evaluate(value, *args)
+              elsif listed_filters[filter].kind_of? Proc
+                value = listed_filters[filter].call(value, *args)
               else
                 raise UnknownFilterError
               end

data/lib/normatron/filters.rb

@@ -1,31 +1,37 @@
-require 'normatron/filters/blank_filter'
-require 'normatron/filters/camelize_filter'
-require 'normatron/filters/capitalize_filter'
-require 'normatron/filters/chomp_filter'
-require 'normatron/filters/dasherize_filter'
-require 'normatron/filters/downcase_filter'
-require 'normatron/filters/dump_filter'
-require 'normatron/filters/keep_filter'
-require 'normatron/filters/remove_filter'
-require 'normatron/filters/squeeze_filter'
-require 'normatron/filters/squish_filter'
-require 'normatron/filters/strip_filter'
-require 'normatron/filters/swapcase_filter'
-require 'normatron/filters/titleize_filter'
-require 'normatron/filters/underscore_filter'
-require 'normatron/filters/upcase_filter'
+Dir[File.dirname(__FILE__) + "/filters/*_filter.rb"].each do |file|
+  require file
+end
 
 module Normatron
-  # Top-Level namespace of all native Normatron filters.
-  #
+
+  # Top-Level namespace of all built-in Normatron filters.
+  # 
   # All filters share some characteristics:
   # * They have the <code>Filter</code> suffix in the name.
   # * Has a class method called <code>evaluate</code>, which runs what the filter claims to do.
   # * The first argument of the method <code>evaluate</code> always will be the variable to be filtered.
-  # * They returns a different object from the input variable, ie, even if the value remains unchanged, the <code>object_id</code> of both variables will be different.
-  # * They treat accented characters and not just <code>/[a-zA-Z]/</code> interval.
+  # * They returns a different object from the input variable, i.e., even if object value remains unchanged, the <code>object_id</code> will be different.
+  # * They treat unicode characters(<code>/\p{Ll}\p{Lu}/u</code>) instead of only ASCII characters(<code>/[a-zA-Z]/</code>).
+  # 
+  # table{font-family: monospace; font-size: 90%}.
+  # |_. CLASS                                     |_. SYMBOL  |_. SHORT DESCRIPTION                                                                  |
+  # |"AsciiFilter":./Filters/AsciiFilter          |:ascii     |Converts Unicode(and accented ASCII) characters to their plain-text ASCII equivalents.|
+  # |"BlankFilter":./Filters/BlankFilter          |:blank     |Returns nil for a blank string or the string itself otherwise.                        |
+  # |"CamelizeFilter":./Filters/CamelizeFilter    |:camelize  |Convert string to UpperCamelCase or lowerCamelCase.                                   |
+  # |"CapitalizeFilter":./Filters/CapitalizeFilter|:capitalize|Makes only the first character as capital letter.                                     |
+  # |"ChompFilter":./Filters/ChompFilter          |:chomp     |Remove the given record separator from the end of the string.                         |
+  # |"DasherizeFilter":./Filters/DasherizeFilter  |:dasherize |Replaces all underscores with dashes.                                                 |
+  # |"DowncaseFilter":./Filters/DowncaseFilter    |:downcase  |Lowercase all characters.                                                             |
+  # |"DumpFilter":./Filters/DumpFilter            |:dump      |Creates a literal string representation.                                              |
+  # |"KeepFilter":./Filters/KeepFilter            |:keep      |Remove the characters that doesn't match the given properties.                        |
+  # |"RemoveFilter":./Filters/RemoveFilter        |:remove    |Remove the characters that match the given properties.                                |
+  # |"SqueezeFilter":./Filters/SqueezeFilter      |:squeeze   |Remove multiple occurences of the same character.                                     |
+  # |"SquishFilter":./Filters/SquishFilter        |:squish    |Strips the input, remove line-breaks and multiple spaces.                             |
+  # |"SwapcaseFilter":./Filters/SwapcaseFilter    |:swapcase  |Replaces uppercased characters by lowercased and vice versa.                          |
+  # |"TitleizeFilter":./Filters/TitleizeFilter    |:titleize  |Capitalizes the first character of each word.                                         |
+  # |"UnderscoreFilter":./Filters/UnderscoreFilter|:underscore|Makes an underscored lowercase form from the expression in the string.                |
+  # |"UpcaseFilter":./Filters/UpcaseFilter        |:upcase    |Uppercase all characters.                                                             |
   module Filters
   end
 end
 
-

data/lib/normatron/filters/ascii_filter.rb

@@ -0,0 +1,26 @@
+require 'stringex/unidecoder'
+
+module Normatron
+  module Filters
+    module AsciiFilter
+
+      ##
+      # Converts Unicode(and accented ASCII) characters to their plain-text ASCII equivalents.
+      # 
+      # @example
+      #   AsciiFilter.evaluate("EVOLUÇÃO")       #=> "EVOLUCAO"
+      #   AsciiFilter.evaluate("⠋⠗⠁⠝⠉⠑")      #=> "france"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :ascii
+      #   normalize :attribute_b, :with => [:custom_filter, :ascii]
+      #
+      # @param [String] input A character sequence
+      # @return [String] The transliterated character sequence or the object itself
+      # @see http://rubydoc.info/gems/stringex/Stringex/Unidecoder Stringex::Unidecoder
+      def self.evaluate(input, *args)
+        input.kind_of?(String) ? Stringex::Unidecoder.decode(input) : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/helpers.rb

@@ -14,16 +14,6 @@ module Normatron
         value.gsub(regex, "")
       end
 
-      def evaluate_strip(value, edges)
-        constructs = []
-        constructs << '\A\s*' if edges == :L || edges == :LR
-        constructs << '\s*\z' if edges == :R || edges == :LR
-        regex_string = constructs.join '|'
-        regex = Regexp.new(/#{regex_string}/)
-
-        value.gsub(regex, '')
-      end
-
       def acronyms
         inflections.acronyms
       end

data/lib/normatron/filters/strip_filter.rb

@@ -22,11 +22,23 @@ module Normatron
       #   normalize :attribute_e, :with => [:custom_filter, {:strip => :R}]
       #
       # @param [String] input A character sequence
-      # @param [Symbol] option :L to strip trailing spaces, :R for leading spaces and :LR for both
+      # @param [Symbol] edges :L to strip trailing spaces, :R for leading spaces and :LR for both
       # @return [String] The character sequence without trailing and leading spaces or the object itself
       # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-strip String#strip
-      def self.evaluate(input, option=:LR)
-        input.kind_of?(String) ? evaluate_strip(input, option) : input
+      def self.evaluate(input, edges=:LR)
+        return input unless input.kind_of?(String)
+        
+        regex_string = 
+          case edges
+            when :L
+              '\A\s*'
+            when :R
+              '\s*\z'
+            when :LR
+              '\A\s*|\s*\z'
+          end
+        regex = Regexp.new(/#{regex_string}/)
+        input.gsub(regex, '')
       end
     end
   end

data/lib/normatron/filters/upcase_filter.rb

@@ -9,14 +9,14 @@ module Normatron
       # Uppercase all characters.
       # 
       # @example
-      #   upcase("borderlands") #=> "BORDERLANDS"
+      #   UpcaseFilter.evaluate("borderlands") #=> "BORDERLANDS"
       #
       # @example Using as ActiveRecord::Base normalizer
       #   normalize :attribute_a, :with => :upcase
       #   normalize :attribute_b, :with => [:custom_filter, :upcase]
       #
-      # @return [String, Chars] The uppercased character sequence or the object itself
-      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-upcase String#upcase
+      # @param [String] input A character sequence
+      # @return [String] The uppercased character sequence or the object itself
       # @see http://api.rubyonrails.org/classes/ActiveSupport/Multibyte/Chars.html#method-i-upcase ActiveSupport::Multibyte::Chars#upcase
       # @see DownFilter Normatron::Filters::DownFilter
       # @see TitleizeFilter Normatron::Filters::TitleizeFilter

data/lib/normatron/version.rb

@@ -1,3 +1,3 @@
 module Normatron
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/spec/normatron/configuration_spec.rb

@@ -21,28 +21,37 @@ describe Normatron::Configuration do
   end
 
   describe :filters do
-    it "should be initialized" do
-      subject.filters[:blank]     .should eq Normatron::Filters::BlankFilter
-      subject.filters[:camelize]  .should eq Normatron::Filters::CamelizeFilter
-      subject.filters[:capitalize].should eq Normatron::Filters::CapitalizeFilter
-      subject.filters[:chomp]     .should eq Normatron::Filters::ChompFilter
-      subject.filters[:dasherize] .should eq Normatron::Filters::DasherizeFilter
-      subject.filters[:downcase]  .should eq Normatron::Filters::DowncaseFilter
-      subject.filters[:dump]      .should eq Normatron::Filters::DumpFilter
-      subject.filters[:keep]      .should eq Normatron::Filters::KeepFilter
-      subject.filters[:remove]    .should eq Normatron::Filters::RemoveFilter
-      subject.filters[:squeeze]   .should eq Normatron::Filters::SqueezeFilter
-      subject.filters[:squish]    .should eq Normatron::Filters::SquishFilter
-      subject.filters[:strip]     .should eq Normatron::Filters::StripFilter
-      subject.filters[:swapcase]  .should eq Normatron::Filters::SwapcaseFilter
-      subject.filters[:titleize]  .should eq Normatron::Filters::TitleizeFilter
-      subject.filters[:underscore].should eq Normatron::Filters::UnderscoreFilter
-      subject.filters[:upcase]    .should eq Normatron::Filters::UpcaseFilter
+    context "when initialized" do
+      it { subject.filters[:ascii]     .should eq Normatron::Filters::AsciiFilter }
+      it { subject.filters[:blank]     .should eq Normatron::Filters::BlankFilter }
+      it { subject.filters[:camelize]  .should eq Normatron::Filters::CamelizeFilter }
+      it { subject.filters[:capitalize].should eq Normatron::Filters::CapitalizeFilter }
+      it { subject.filters[:chomp]     .should eq Normatron::Filters::ChompFilter }
+      it { subject.filters[:dasherize] .should eq Normatron::Filters::DasherizeFilter }
+      it { subject.filters[:downcase]  .should eq Normatron::Filters::DowncaseFilter }
+      it { subject.filters[:dump]      .should eq Normatron::Filters::DumpFilter }
+      it { subject.filters[:keep]      .should eq Normatron::Filters::KeepFilter }
+      it { subject.filters[:remove]    .should eq Normatron::Filters::RemoveFilter }
+      it { subject.filters[:squeeze]   .should eq Normatron::Filters::SqueezeFilter }
+      it { subject.filters[:squish]    .should eq Normatron::Filters::SquishFilter }
+      it { subject.filters[:strip]     .should eq Normatron::Filters::StripFilter }
+      it { subject.filters[:swapcase]  .should eq Normatron::Filters::SwapcaseFilter }
+      it { subject.filters[:titleize]  .should eq Normatron::Filters::TitleizeFilter }
+      it { subject.filters[:underscore].should eq Normatron::Filters::UnderscoreFilter }
+      it { subject.filters[:upcase]    .should eq Normatron::Filters::UpcaseFilter }
     end
 
-    it "should allow add new filters" do
-      subject.filters[:smile] = MyFilters::SmileFilter
-      subject.filters[:smile].should eq MyFilters::SmileFilter
+    context "when new filter is added" do
+      it "module filter should be set" do
+        subject.filters[:smile] = MyFilters::SmileFilter
+        subject.filters[:smile].should eq MyFilters::SmileFilter
+      end
+
+      it "lambda filter should be set" do
+        lambda_filter = lambda { |input, value| input << value }
+        subject.filters[:append] = lambda_filter
+        subject.filters[:append].should eq lambda_filter
+      end
     end
 
     it "should allow remove filters" do

data/spec/normatron/extensions/active_record_spec.rb

@@ -10,13 +10,12 @@ describe Normatron::Extensions::ActiveRecord do
   let(:model) { User }
 
   before(:all) { ActiveRecord::Base.send(:include, Normatron::Extensions::ActiveRecord) }
-  before(:each) { model.normalize_filters = nil }
+  before(:each) { model.normalize_rules = nil }
   after(:all) do
     ActiveRecord.send(:remove_const, :Base)
     load 'active_record/base.rb'
   end
 
-
   describe :normalize do
     subject { model }
 
@@ -28,31 +27,31 @@ describe Normatron::Extensions::ActiveRecord do
 
     it "should append default filters" do
       subject.normalize :login, :email
-      subject.normalize_filters.should == { :login => configuration.default_filters,
+      subject.normalize_rules.should == { :login => configuration.default_filters,
                                             :email => configuration.default_filters }
     end
 
     it "should stack filters for multiple calls" do
       subject.normalize :login
       subject.normalize :login, :with => :upcase
-      subject.normalize_filters.should == { :login => configuration.default_filters.merge({ :upcase => nil }) }
+      subject.normalize_rules.should == { :login => configuration.default_filters.merge({ :upcase => nil }) }
     end
 
     it "should append multiple attributes" do
       subject.normalize :login, :email, :phone
-      subject.normalize_filters.should == { login: { squish: nil, blank: nil },
+      subject.normalize_rules.should == { login: { squish: nil, blank: nil },
                                             email: { squish: nil, blank: nil },
                                             phone: { squish: nil, blank: nil } }
     end
 
     it "should allow multiple filters" do
       subject.normalize :login, :with => [:upcase, :blank]
-      subject.normalize_filters.should == { login: { upcase: nil, blank: nil } }
+      subject.normalize_rules.should == { login: { upcase: nil, blank: nil } }
     end
 
     it "should allow multiple filters" do
       subject.normalize :login, :with => [[:keep, :L], { :remove => [:N] }]
-      subject.normalize_filters.should == { login: { keep: [:L], remove: [:N] } }
+      subject.normalize_rules.should == { login: { keep: [:L], remove: [:N] } }
     end
   end
 
@@ -73,6 +72,22 @@ describe Normatron::Extensions::ActiveRecord do
       subject.login.should eq "... =("
     end
 
+    it "should run module filter" do
+      Normatron.configuration.filters[:smile] = MyFilters::SmileFilter
+      model.normalize :login, :with => :smile
+      subject.login = "hello!"
+      subject.apply_normalizations
+      subject.login.should eq "hello! =]"
+    end
+
+    it "should run lambda filter" do
+      Normatron.configuration.filters[:dots] = lambda { |value| value + "..."}
+      model.normalize :login, :with => :dots
+      subject.login = "word"
+      subject.apply_normalizations
+      subject.login.should eq "word..."
+    end
+
     it "should run native filter" do
       model.normalize :login, :with => :squish
       subject.login = "  word  "

data/spec/normatron/filters/ascii_filter_spec.rb

@@ -0,0 +1,14 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+require 'normatron/filters/ascii_filter'
+
+describe Normatron::Filters::AsciiFilter do
+  it_should_behave_like "string processor"
+  it_should_behave_like "evaluable filter", ["ÉBRIO"              ], "EBRIO"
+  it_should_behave_like "evaluable filter", ["até"                ], "ate"
+  it_should_behave_like "evaluable filter", ["cirurgião"          ], "cirurgiao"
+  it_should_behave_like "evaluable filter", ["email@domain.com"   ], "email@domain.com"
+  it_should_behave_like "evaluable filter", ["éçü&! *¬¬"          ], "ecu&! *!!"
+  it_should_behave_like "evaluable filter", ["⠋⠗⠁⠝⠉⠑"          ], "france"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: normatron
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-10 00:00:00.000000000 Z
+date: 2012-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -43,6 +43,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: stringex
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.0
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -106,13 +122,14 @@ files:
 - lib/normatron/filters/helpers.rb
 - lib/normatron/filters/downcase_filter.rb
 - lib/normatron/filters/chomp_filter.rb
+- lib/normatron/filters/ascii_filter.rb
 - lib/normatron/extensions.rb
 - lib/normatron/version.rb
 - lib/normatron/extensions/active_record.rb
 - lib/normatron.rb
 - MIT-LICENSE
 - Rakefile
-- README.textile
+- README.md
 - spec/spec_helper.rb
 - spec/support/user_model.rb
 - spec/support/my_filters.rb
@@ -123,6 +140,7 @@ files:
 - spec/normatron/filters/chomp_filter_spec.rb
 - spec/normatron/filters/capitalize_filter_spec.rb
 - spec/normatron/filters/upcase_filter_spec.rb
+- spec/normatron/filters/ascii_filter_spec.rb
 - spec/normatron/filters/strip_filter_spec.rb
 - spec/normatron/filters/underscore_filter_spec.rb
 - spec/normatron/filters/keep_filter_spec.rb
@@ -170,6 +188,7 @@ test_files:
 - spec/normatron/filters/chomp_filter_spec.rb
 - spec/normatron/filters/capitalize_filter_spec.rb
 - spec/normatron/filters/upcase_filter_spec.rb
+- spec/normatron/filters/ascii_filter_spec.rb
 - spec/normatron/filters/strip_filter_spec.rb
 - spec/normatron/filters/underscore_filter_spec.rb
 - spec/normatron/filters/keep_filter_spec.rb

data/README.textile

@@ -1,200 +0,0 @@
-h1. Normatron
-
-Normatron is a Ruby On Rails plugin that perform attribute normalizations for ActiveRecord objects.
-With it you can normalize 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 most of the normalizations.
-
-h2. Installation
-
-Let the bundler install the gem by adding the following into your application gemfile:
-
-pre. gem 'normatron'
-
-And then bundle it up:
-
-pre. $ bundle install
-
-Or install it by yourself:
-
-pre. $ gem install normatron
-
-Then run the generator:
-
-pre. $ rails generator normatron:install
-
-h2. The problem
-
-Suppose you have a product model as the following:
-
-pre. # ./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
-
-pre. # ./app/models/products.rb
-class Product < ActiveRecord::Base
-  attr_accessible :name, :price
-end
-
-And we want the _name_ attribute be uppercased before saving it into the database.
-The most usual approach to do this includes:
-
-* Override the _name_ setter and convert the value to an uppercased string.
-* Write a method or block and bind it to the "before_validation":http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html callback.
-
-Both ways are ilenegant, boring, error prone and very expensive.
-What led me to make this gem and offer a third way to solve this issue:
-
-h2. Usage
-
-Normatron uses ":squish":http://rubydoc.info/gems/normatron/Normatron/Filters/SquishFilter and ":blank":http://rubydoc.info/gems/normatron/Normatron/Filters/BlankFilter as default filters.
-These filters are applied to all attributes through "normalize":http://rubydoc.info/gems/normatron/Normatron/Extensions/ActiveRecord/ClassMethods#normalize-instance_method function, since no options is given.
-
-pre. # ./app/models/products.rb
-class Product < ActiveRecord::Base
-  attr_accessible :name, :price
-  normalize :name
-end
-
-pre.  $ rails console
- > memory = Product.create name: "  memory   card    "
-=> #<Product id: nil, name: "memory card", price: nil>
- > null = Product.create name: "    "
-=> #<Product id: nil, name: nil, price: nil>
-
-h3. Configurations
-
-"normatron:install":http://rubydoc.info/gems/normatron/Normatron/InstallGenerator generator creates a configuration file located at @./config/initializers/normatron.rb@.
-
-For now, you can set the default normalization filters or disable normatron by commenting the @add_orm@ line.
-
-h3. Applying normalizations
-
-Methods like "create":http://api.rubyonrails.org/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-create, "valid?":http://api.rubyonrails.org/classes/ActiveRecord/Validations.html#method-i-valid-3F or "save":http://api.rubyonrails.org/classes/ActiveRecord/Validations.html#method-i-valid-3F always call the "apply_normalizations":http://rubydoc.info/gems/normatron/Normatron/Extensions/ActiveRecord/InstanceMethods#apply_normalizations-instance_method method, thought "before_validation":http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html callback.
-This is the method that invokes all filters to their attributes. So you can perform the normalizations without necessarily having to perform the model validations.
-
-pre.  $ rails console
- > product = Product.new name: "  hard    drive"
-=> #<Product id: nil, name: "  hard    drive", price: nil>
- > product.apply_normalizations
- > product
-=> #<Product id: nil, name: "hard drive", price: nil>
-
-h3. Setting normalization rules
-
-The @:with@ option allows to bind filters to one or more attribute.
-
-pre. class Product < ActiveRecord::Base
-  normalize :name, :with => :upcase
-end
-
-pre.  $ rails console
- > Product.normalize_filters
-=> { :name => { :upcase => [] } }
-
-The filters passed throught @:with@ option will not stack with default filters.
-When "normalize":http://rubydoc.info/gems/normatron/Normatron/Extensions/ActiveRecord/ClassMethods#normalize-instance_method method is used multiple times for the same attribute, it will stack the filter bindings.
-
-pre. class Product < ActiveRecord::Base
-  normalize :name
-  normalize :name, :with => :upcase
-end
-
-pre.  $ rails console
- > Product.normalize_filters
-=> { :name => { :squish => [],
-                :blank  => [],
-                :upcase => [] } }
-
-The same result can be obtained using:
-
-pre. normalize :name, :with => [:squish, :blank, :upcase]
-
-Some filters may use arguments to perferm normalizations.
-There are two approaches to deal with filter arguments in Normatron:
-
-a) Using a Hash where the key is the filter name and the value is an arguments Array.
-
-pre. class Product < ActiveRecord::Base
-  normalize :name,        :with => [ { :keep => [:Latin], :remove => [:Nd, :Zs] } ]
-  normalize :description, :with => :squeeze
-  normalize :brand,       :with => { :squeeze => ["a-z"] }
-end
-
-b) Using an Array where the first element if the attribute name and rest is the filter arguments.
-
-pre. class Product < ActiveRecord::Base
-  normalize :name,        :with => [ [:keep, :Latin], [:remove, :Nd, :Zs] ]
-  normalize :description, :with => :squeeze
-  normalize :brand,       :with => [ [:squeeze, "a-z"] ]
-end
-
-Both ways will produce the same result:
-
-pre.  $ rails console
- > Product.normalize_filters
-=> { :name        => { :keep    => [:Latin],
-                       :remove  => [:Nd, :Zs] },
-     :description => { :squeeze => [] },
-     :brand       => { :squeeze => ["a-z"] } }
-
-h3. Using instance method as filter
-
-Create an instance method returning the value as you want.
-The first argument is mandatory, and will receive the original value of the attribute.
-If you need to use aditional arguments or varargs, just add them after the first argument.
-
-<pre>
-# ./app/models/client.rb
-class Client < ActiveRecord::Base
-  normalize :phone,  :with => [:custom_a, [:custom_b, :a, :b], {:custom_c => [:a, :b, :c]}]
-  normalize :mobile, :with => [:custom_a, {:custom_b => [:a, :b]}, [:custom_c, :a, :b, :c]]
-
-  def custom_a(value)
-    # ...
-  end
-
-  def custom_b(value, *args)
-    # ...
-  end
-
-  def custom_c(value, arg_a, arg_b, arg_c)
-    # ...
-  end
-end
-</pre>
-
-h2. Filters
-
-Information about native filters and how to use them can be found in "Normatron::Filters(Normatron::Filters Rubydoc)":http://rubydoc.info/gems/normatron/Normatron/Filters.
-
-h1. Contributing
-
-There are several ways to make this gem even better:
-
-* Forking this project
-* Adding new features or bug fixes
-* Making tests
-* Commiting your changes
-* Reporting any bug or unexpected behavior
-* Suggesting any improvement
-* Sharing with your friends, forums, communities, job, etc...
-* Helping users with difficulty using this gem
-* Paying me a beer =]
-
-h1. Credits
-
-This gem was initially inspired on:
-* "normalize_attributes (normalize_attributes Gem)":https://github.com/fnando/normalize_attributes - I liked the cleaner code and simplicity of this gem.
-* "attribute_normalizer (attribute_normalizer Gem)":https://github.com/mdeering/attribute_normalizer - Very powerful.
-
-The idea is to mix the good things of both gems, adding some features and changing something to fit my taste.
-
-h1. License
-
-See file attached to source code or click "here":https://github.com/fernandors87/normatron/blob/master/MIT-LICENSE.