normatron 0.2.1 → 0.3.0

data/lib/normatron/filters/blank_filter.rb

@@ -0,0 +1,29 @@
+require 'normatron/filters/helpers'
+
+module Normatron
+  module Filters
+    module BlankFilter
+
+      ##
+      # Returns nil for a blank string or the string itself otherwise.
+      # 
+      # @example
+      #   BlankFilter.evaluate("")            #=> nil
+      #   BlankFilter.evaluate("     ")       #=> nil
+      #   BlankFilter.evaluate("  \n ")       #=> nil
+      #   BlankFilter.evaluate("1")           #=> "1"
+      #   BlankFilter.evaluate("It's blank?") #=> "It's blank?"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :blank
+      #   normalize :attribute_b, :with => [:custom_filter, :blank]
+      #
+      # @param input [String] A character sequence
+      # @return [String, nil] The object itself or nil
+      # @see http://api.rubyonrails.org/classes/String.html#method-i-blank-3F String#blank?
+      def self.evaluate(input)
+        input.kind_of?(String) && input.blank? ? nil : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/camelize_filter.rb

@@ -0,0 +1,50 @@
+require 'normatron/filters/helpers'
+
+module Normatron
+  module Filters
+    module CamelizeFilter
+      extend Helpers
+
+      ##
+      # Converts strings to UpperCamelCase by default and to lowerCamelCase if the <tt>:lower</tt> argument is given.
+      # <tt>camelize</tt> will also convert '/' to '::' which is useful for converting paths to namespaces.
+      # As a rule of thumb you can think of camelize as the inverse of underscore, though there are cases where that does not hold:
+      #   "SSLError".underscore.camelize # => "SslError"
+      # This filter has a similar behavior to
+      # ActiveSupport::Inflector#camelize[http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize], but with following differences:
+      # * Uses UTF-8 charset
+      # * Affects accented characters
+      # 
+      # @example
+      #   CamelizeFilter.evaluate("active_record/errors")         #=> "ActiveRecord::Errors"
+      #   CamelizeFilter.evaluate("active_record/errors", :upper) #=> "ActiveRecord::Errors"
+      #   CamelizeFilter.evaluate("active_record/errors", :lower) #=> "activeRecord::Errors"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :camelize
+      #   normalize :attribute_b, :with => [:custom_filter, :camelize]
+      #   normalize :attribute_c, :with => [[:camelize, :lower]]
+      #   normalize :attribute_d, :with => [{:camelize => :lower}]
+      #   normalize :attribute_e, :with => [:custom_filter, [:camelize, :lower]]
+      #   normalize :attribute_f, :with => [:custom_filter, {:camelize => :lower}]
+      #
+      # @param [String] input A character sequence
+      # @param [Symbol] first_letter_case <tt>:lower</tt> for lowerCamelCase or <tt>:upper</tt> for UpperCamelCase
+      # @return [String] The camelized character sequence or the object itself
+      # @see http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize ActiveSupport::Inflector#camelize
+      # @see UnderscoreFilter Normatron::Filters::UnderscoreFilter
+      # @todo Performance tests
+      # @todo Exception class
+      def self.evaluate(input, first_letter_case = :upper)
+        return input unless input.kind_of?(String)
+
+        if first_letter_case == :upper
+          string = input.sub(/^[\p{L}\d]*/u) { acronyms[$&] || mb_send(:capitalize, $&) }
+        else first_letter_case == :lower
+          string = input.sub(/^(?:#{acronym_regex}(?=\b|[\p{L}_])|\p{Word}*_)/u) { mb_send(:downcase, $&) }
+        end
+        string.gsub!(/(?:_|(\/))([\p{L}\d]*)/iu) { "#{$1}#{acronyms[$2] || mb_send(:capitalize, $2)}" }.gsub!('/', '::')
+      end
+    end
+  end
+end

data/lib/normatron/filters/capitalize_filter.rb

@@ -0,0 +1,29 @@
+require 'normatron/filters/helpers'
+
+module Normatron
+  module Filters
+    module CapitalizeFilter
+      extend Helpers
+
+      ##
+      # Makes the first character uppercase after lowercase all other characters.
+      # 
+      # @example
+      #   CapitalizeFilter.evaluate("KEEP IT SIMPLE")  #=> "Keep it simple"
+      #   CapitalizeFilter.evaluate("keep it simple")  #=> "Keep it simple"
+      #   CapitalizeFilter.evaluate(" KEEP IT SIMPLE") #=> " keep it simple"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :capitalize
+      #   normalize :attribute_b, :with => [:custom_filter, :capitalize]
+      #
+      # @param [String] input A character sequence
+      # @return [String] The capitalized character sequence or the object itself
+      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-capitalize String#capitalize
+      # @see TitleizeFilter Normatron::Filters::TitleizeFilter
+      def self.evaluate(input)
+        input.kind_of?(String) ? mb_send(:capitalize, input) : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/chomp_filter.rb

@@ -0,0 +1,34 @@
+module Normatron
+  module Filters
+    module ChompFilter
+
+      ##
+      # Remove the given record separator from the end of the string (If present).
+      # If <tt>$/</tt> has not been changed from the default Ruby record separator,
+      # then chomp also removes carriage return characters (that is it will remove <tt>\n</tt>, <tt>\r</tt>, and <tt>\r\n</tt>).
+      # 
+      # @example
+      #   ChompFilter.evaluate("Bon Scott\n")            #=> "Bon Scott"
+      #   ChompFilter.evaluate("Bon Scott\r")            #=> "Bon Scott"
+      #   ChompFilter.evaluate("Bon Scott\r\n")          #=> "Bon Scott"
+      #   ChompFilter.evaluate("Bon Scott\n\r")          #=> "Bon Scott\n"
+      #   ChompFilter.evaluate("Bon Scott", " Scott")    #=> "Bon"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :chomp
+      #   normalize :attribute_b, :with => [:custom_filter, :chomp]
+      #   normalize :attribute_c, :with => [[:chomp, "x"]]
+      #   normalize :attribute_d, :with => [{:chomp => "y"}]
+      #   normalize :attribute_e, :with => [:custom_filter, [:chomp, "z"]]
+      #   normalize :attribute_f, :with => [:custom_filter, {:chomp => "\f"}]
+      #
+      # @param [String] input A character sequence
+      # @param [String] separator A character sequence
+      # @return [String] The chopped character sequence or the object itself
+      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-chomp String#chomp
+      def self.evaluate(input, separator=$/)
+        input.kind_of?(String) ? input.chomp(separator) : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/dasherize_filter.rb

@@ -0,0 +1,25 @@
+require 'normatron/filters/helpers'
+
+module Normatron
+  module Filters
+    module DasherizeFilter
+
+      ##
+      # Replaces all underscores with dashes.
+      # 
+      # @example
+      #   DasherizeFilter.evaluate("monty_python") #=> "monty-python"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :dasherize
+      #   normalize :attribute_b, :with => [:custom_filter, :dasherize]
+      #
+      # @param [String] input A character sequence
+      # @return [String] The dasherized character sequence or the object itself
+      # @see http://api.rubyonrails.org/classes/String.html#method-i-dasherize String#dasherize
+      def self.evaluate(input)
+        input.kind_of?(String) ? input.dasherize : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/downcase_filter.rb

@@ -0,0 +1,29 @@
+require 'normatron/filters/helpers'
+
+module Normatron
+  module Filters
+    module DowncaseFilter
+      extend Helpers
+
+      ##
+      # Lowercase all characters.
+      # 
+      # @example
+      #   DowncaseFilter.evaluate("NOTHING ELSE MATTERS") #=> "nothing else matters"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :downcase
+      #   normalize :attribute_b, :with => [:custom_filter, :downcase]
+      #
+      # @param [String] input A character sequence
+      # @return [String] The lowercased character sequence or the object itself
+      # @see http://api.rubyonrails.org/classes/ActiveSupport/Multibyte/Chars.html#method-i-downcase ActiveSupport::Multibyte::Chars#downcase
+      # @see SwapcaseFilter Normatron::Filters::SwapcaseFilter
+      # @see TitleizeFilter Normatron::Filters::TitleizeFilter
+      # @see UpcaseFilter Normatron::Filters::UpcaseFilter
+      def self.evaluate(input)
+        input.kind_of?(String) ? mb_send(:downcase, input) : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/dump_filter.rb

@@ -0,0 +1,27 @@
+module Normatron
+  module Filters
+    module DumpFilter
+
+      ##
+      # Creates a literal string representation with all nonprinting characters
+      # replaced by <tt>\\n</tt> notation and all special characters escaped.
+      # 
+      # @example
+      #   DumpFilter.evaluate("I'm not\na \"clubber\"...") #=> "\"I'm not\\na \\\"clubber\\\"...\""
+      #   DumpFilter.evaluate("I'm not\na \"clubber\"...") #== '"I\'m not\na \"clubber\"..."'
+      #   DumpFilter.evaluate('I\'m not\na "clubber"...')  #=> "\"I'm not\\\\na \\\"clubber\\\"...\""
+      #   DumpFilter.evaluate('I\'m not\na "clubber"...')  #== '"I\'m not\\\na \"clubber\"..."'
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => :dump
+      #   normalize :attribute_b, :with => [:custom_filter, :dump]
+      #
+      # @param [String] input A character sequence
+      # @return [String] The dumpped character sequence or the object itself
+      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-dump String#dump
+      def self.evaluate(input)
+        input.kind_of?(String) ? input.dump : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/helpers.rb

@@ -0,0 +1,44 @@
+# encoding: UTF-8
+
+require 'active_support/core_ext/string'
+require 'active_support/inflector/inflections'
+require 'active_support/multibyte/chars'
+
+module Normatron
+  module Filters
+    module Helpers
+      def evaluate_regexp(value, action, *properties)
+        options = properties.flatten.compact.uniq
+        constructs = options.map{ |s| "\\p{#{s.to_s}}" } * ""
+        regex = /[#{'^' if action == :keep}#{constructs}]/u
+        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
+
+      def acronym_regex
+        inflections.acronym_regex
+      end
+
+      def inflections
+        ActiveSupport::Inflector::Inflections.instance
+      end
+
+      def mb_send(method, value)
+        value.mb_chars.send(method).to_s
+      end
+    end
+  end
+end

data/lib/normatron/filters/keep_filter.rb

@@ -0,0 +1,100 @@
+require 'normatron/filters/helpers'
+
+module Normatron
+  module Filters
+    module KeepFilter
+      extend Helpers
+
+      ##
+      # Remove the characters that doesn't match the given properties.
+      # The character properties follow the rule of \\p{} construct described in Regexp class.
+      # The \\p{} construct matches characters with the named property, much like POSIX bracket classes.
+      #
+      # To pass named properties to this filter, use them as Symbols:
+      # * <tt>:Alnum</tt> - Alphabetic and numeric character
+      # * <tt>:Alpha</tt> - Alphabetic character
+      # * <tt>:Blank</tt> - Space or tab
+      # * <tt>:Cntrl</tt> - Control character
+      # * <tt>:Digit</tt> - Digit
+      # * <tt>:Graph</tt> - Non-blank character (excludes spaces, control characters, and similar)
+      # * <tt>:Lower</tt> - Lowercase alphabetical character
+      # * <tt>:Print</tt> - Like :Graph, but includes the space character
+      # * <tt>:Punct</tt> - Punctuation character
+      # * <tt>:Space</tt> - Whitespace character ([:blank:], newline, carriage return, etc.)
+      # * <tt>:Upper</tt> - Uppercase alphabetical
+      # * <tt>:XDigit</tt> - Digit allowed in a hexadecimal number (i.e., 0-9a-fA-F)
+      # * <tt>:Word</tt> - A member of one of the following Unicode general category Letter, Mark, Number, Connector_Punctuation
+      # * <tt>:ASCII</tt> - A character in the ASCII character set
+      # * <tt>:Any</tt> - Any Unicode character (including unassigned characters)
+      # * <tt>:Assigned</tt> - An assigned character
+      # 
+      # A Unicode character's General Category value can also be matched with :Ab where Ab is the category’s abbreviation as described below:
+      # * <tt>:L</tt> - 'Letter'
+      # * <tt>:Ll</tt> - 'Letter: Lowercase'
+      # * <tt>:Lm</tt> - 'Letter: Mark'
+      # * <tt>:Lo</tt> - 'Letter: Other'
+      # * <tt>:Lt</tt> - 'Letter: Titlecase'
+      # * <tt>:Lu</tt> - 'Letter: Uppercase
+      # * <tt>:Lo</tt> - 'Letter: Other'
+      # * <tt>:M</tt> - 'Mark'
+      # * <tt>:Mn</tt> - 'Mark: Nonspacing'
+      # * <tt>:Mc</tt> - 'Mark: Spacing Combining'
+      # * <tt>:Me</tt> - 'Mark: Enclosing'
+      # * <tt>:N</tt> - 'Number'
+      # * <tt>:Nd</tt> - 'Number: Decimal Digit'
+      # * <tt>:Nl</tt> - 'Number: Letter'
+      # * <tt>:No</tt> - 'Number: Other'
+      # * <tt>:P</tt> - 'Punctuation'
+      # * <tt>:Pc</tt> - 'Punctuation: Connector'
+      # * <tt>:Pd</tt> - 'Punctuation: Dash'
+      # * <tt>:Ps</tt> - 'Punctuation: Open'
+      # * <tt>:Pe</tt> - 'Punctuation: Close'
+      # * <tt>:Pi</tt> - 'Punctuation: Initial Quote'
+      # * <tt>:Pf</tt> - 'Punctuation: Final Quote'
+      # * <tt>:Po</tt> - 'Punctuation: Other'
+      # * <tt>:S</tt> - 'Symbol'
+      # * <tt>:Sm</tt> - 'Symbol: Math'
+      # * <tt>:Sc</tt> - 'Symbol: Currency'
+      # * <tt>:Sc</tt> - 'Symbol: Currency'
+      # * <tt>:Sk</tt> - 'Symbol: Modifier'
+      # * <tt>:So</tt> - 'Symbol: Other'
+      # * <tt>:Z</tt> - 'Separator'
+      # * <tt>:Zs</tt> - 'Separator: Space'
+      # * <tt>:Zl</tt> - 'Separator: Line'
+      # * <tt>:Zp</tt> - 'Separator: Paragraph'
+      # * <tt>:C</tt> - 'Other'
+      # * <tt>:Cc</tt> - 'Other: Control'
+      # * <tt>:Cf</tt> - 'Other: Format'
+      # * <tt>:Cn</tt> - 'Other: Not Assigned'
+      # * <tt>:Co</tt> - 'Other: Private Use'
+      # * <tt>:Cs</tt> - 'Other: Surrogate'
+      #
+      # Lastly, this method matches a character's Unicode script. The following scripts are supported:
+      #
+      # Arabic, Armenian, Balinese, Bengali, Bopomofo, Braille, Buginese, Buhid, Canadian_Aboriginal, Carian, Cham, Cherokee, Common, Coptic, Cuneiform, Cypriot, Cyrillic, Deseret, Devanagari, Ethiopic, Georgian, Glagolitic, Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew, Hiragana, Inherited, Kannada, Katakana, Kayah_Li, Kharoshthi, Khmer, Lao, Latin, Lepcha, Limbu, Linear_B, Lycian, Lydian, Malayalam, Mongolian, Myanmar, New_Tai_Lue, Nko, Ogham, Ol_Chiki, Old_Italic, Old_Persian, Oriya, Osmanya, Phags_Pa, Phoenician, Rejang, Runic, Saurashtra, Shavian, Sinhala, Sundanese, Syloti_Nagri, Syriac, Tagalog, Tagbanwa, Tai_Le, Tamil, Telugu, Thaana, Thai, Tibetan, Tifinagh, Ugaritic, Vai, and Yi.
+      # 
+      # @example
+      #   KeepFilter.evaluate("Doom 3", :L)      #=> "Doom"    keep only letters
+      #   KeepFilter.evaluate("Doom 3", :N)      #=> "3"       keep only numbers
+      #   KeepFilter.evaluate("Doom 3", :L, :N)  #=> "Doom3"   keep only letters and numbers
+      #   KeepFilter.evaluate("Doom 3", :Lu, :N) #=> "D3"      keep only uppercased letters or numbers
+      #   KeepFilter.evaluate("Doom ˩", :Latin)  #=> "Doom"    keep only latin characters
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => [[:keep, :Lu]]
+      #   normalize :attribute_b, :with => [{:keep =>[:Lu]}]
+      #   normalize :attribute_c, :with => [:custom_filter, [:keep, :Ll, :Space]]
+      #   normalize :attribute_d, :with => [:custom_filter, {:keep => [:Ll, :Space]}]
+      #
+      # @param [String] input A character sequence
+      # @param [[Symbol]*] properties Array of Symbols equivalent to Regexp property for \\p{} construct.
+      # @return [String] The clean character sequence or the object itself
+      # @see http://www.ruby-doc.org/core-1.9.3/Regexp.html Regexp
+      # @see RemoveFilter Normatron::Filters::RemoveFilter
+      # @todo Raise exception for empty properties
+      def self.evaluate(input, *properties)
+        input.kind_of?(String) ? evaluate_regexp(input, :keep, properties) : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/remove_filter.rb

@@ -0,0 +1,37 @@
+require 'normatron/filters/helpers'
+
+module Normatron
+  module Filters
+    module RemoveFilter
+      extend Helpers
+
+      ##
+      # Remove the characters that match the given properties.
+      #
+      # For additional informations see Normatron::Filter::ClassMethods#keep documentation.
+      # 
+      # @example
+      #   RemoveFilter.evaluate("Quake 3", :L)      #=> " 3"        remove only letters
+      #   RemoveFilter.evaluate("Quake 3", :N)      #=> "Quake "    remove only numbers
+      #   RemoveFilter.evaluate("Quake 3", :L, :N)  #=> " "         remove only letters or numbers
+      #   RemoveFilter.evaluate("Quake 3", :Lu, :N) #=> "uake "     remove only uppercased letters or numbers
+      #   RemoveFilter.evaluate("Quake ˩", :Latin)  #=> " ˩"        remove only latin characters
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => [[:remove, :Lu]]
+      #   normalize :attribute_b, :with => [{:remove =>[:Lu]}]
+      #   normalize :attribute_c, :with => [:custom_filter, [:remove, :Ll, :Space]]
+      #   normalize :attribute_d, :with => [:custom_filter, {:remove => [:Ll, :Space]}]
+      #
+      # @param [String] input A character sequence
+      # @param [[Symbol]*] properties Array of Symbols equivalent to Regexp property for \\p{} construct.
+      # @return [String] The clean character sequence or the object itself
+      # @see http://www.ruby-doc.org/core-1.9.3/Regexp.html Regexp
+      # @see KeepFilter Normatron::Filters::KeepFilter
+      # @todo Raise exception for empty properties
+      def self.evaluate(input, *properties)
+        input.kind_of?(String) ? evaluate_regexp(input, :remove, properties) : input
+      end
+    end
+  end
+end

data/lib/normatron/filters/squeeze_filter.rb

@@ -0,0 +1,30 @@
+module Normatron
+  module Filters
+    module SqueezeFilter
+
+      ##
+      # Remove multiple occurences of the same character.
+      # If no option are given, all runs of identical characters are replaced by a single character.
+      # 
+      # @example
+      #   SqueezeFilter.evaluate("yellow    moon")               #=> "yelow mon"
+      #   SqueezeFilter.evaluate("  now   is  the", " ")         #=> " now is the"
+      #   SqueezeFilter.evaluate("putters shoot balls", "m-z")   #=> "puters shot balls"
+      #
+      # @example Using as ActiveRecord::Base normalizer
+      #   normalize :attribute_a, :with => [:custom_filter, :squeeze]
+      #   normalize :attribute_b, :with => [:custom_filter, [:squeeze, "a-f"]]
+      #   normalize :attribute_c, :with => [:custom_filter, {:squeeze => ["a-f"]}]
+      #
+      # @param [String] input A character sequence
+      # @param [[String]*] targets Characters to be affected
+      # @return [String] The clean character sequence or the object itself
+      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-squeeze String#squeeze
+      # @see SquishFilter Normatron::Filters::SquishFilter
+      def self.evaluate(input, *targets)
+        return input unless input.kind_of?(String)
+        targets.any? ? input.squeeze(targets.last) : input.squeeze
+      end
+    end
+  end
+end