normatron 0.3.1 → 0.3.2

data/lib/normatron/filters/keep_filter.rb

@@ -2,96 +2,113 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # 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:
+    #
+    # |_<.Property  |_<.Description                                                                                         |
+    # | @:Alnum@    | Alphabetic and numeric character                                                                      |
+    # | @:Alpha@    | Alphabetic character                                                                                  |
+    # | @:Blank@    | Space or tab                                                                                          |
+    # | @:Cntrl@    | Control character                                                                                     |
+    # | @:Digit@    | Digit                                                                                                 |
+    # | @:Graph@    | Non-blank character (excludes spaces, control characters, and similar)                                |
+    # | @:Lower@    | Lowercase alphabetical character                                                                      |
+    # | @:Print@    | Like :Graph, but includes the space character                                                         |
+    # | @:Punct@    | Punctuation character                                                                                 |
+    # | @:Space@    | Whitespace character (@[:blank:]@, newline, carriage return, etc.)                                    |
+    # | @:Upper@    | Uppercase alphabetical                                                                                |
+    # | @:XDigit@   | Digit allowed in a hexadecimal number (i.e., 0-9a-fA-F)                                               |
+    # | @:Word@     | A member of one of the following Unicode general category Letter, Mark, Number, Connector_Punctuation |
+    # | @:ASCII@    | A character in the ASCII character set                                                                |
+    # | @:Any@      | Any Unicode character (including unassigned characters)                                               |
+    # | @:Assigned@ | 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:
+    #
+    # |_<.Property |_<.Description              |
+    # | @:L@       | Letter                     |
+    # | @:Ll@      | Letter: Lowercase          |
+    # | @:Lm@      | Letter: Mark               |
+    # | @:Lo@      | Letter: Other              |
+    # | @:Lt@      | Letter: Titlecase          |
+    # | @:Lu@      | Letter: Uppercas           |
+    # | @:Lo@      | Letter: Other              |
+    # | @:M@       | Mark                       |
+    # | @:Mn@      | Mark: Nonspacing           |
+    # | @:Mc@      | Mark: Spacing Combining    |
+    # | @:Me@      | Mark: Enclosing            |
+    # | @:N@       | Number                     |
+    # | @:Nd@      | Number: Decimal Digit      |
+    # | @:Nl@      | Number: Letter             |
+    # | @:No@      | Number: Other              |
+    # | @:P@       | Punctuation                |
+    # | @:Pc@      | Punctuation: Connector     |
+    # | @:Pd@      | Punctuation: Dash          |
+    # | @:Ps@      | Punctuation: Open          |
+    # | @:Pe@      | Punctuation: Close         |
+    # | @:Pi@      | Punctuation: Initial Quote |
+    # | @:Pf@      | Punctuation: Final Quote   |
+    # | @:Po@      | Punctuation: Other         |
+    # | @:S@       | Symbol                     |
+    # | @:Sm@      | Symbol: Math               |
+    # | @:Sc@      | Symbol: Currency           |
+    # | @:Sc@      | Symbol: Currency           |
+    # | @:Sk@      | Symbol: Modifier           |
+    # | @:So@      | Symbol: Other              |
+    # | @:Z@       | Separator                  |
+    # | @:Zs@      | Separator: Space           |
+    # | @:Zl@      | Separator: Line            |
+    # | @:Zp@      | Separator: Paragraph       |
+    # | @:C@       | Other                      |
+    # | @:Cc@      | Other: Control             |
+    # | @:Cf@      | Other: Format              |
+    # | @:Cn@      | Other: Not Assigned        |
+    # | @:Co@      | Other: Private Use         |
+    # | @:Cs@      | 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 Out of box
+    #   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]}]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/Regexp.html Regexp
+    # @see RemoveFilter Normatron::Filters::RemoveFilter
     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.
+      # Performs input conversion according to filter requirements.
       #
-      # 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'
+      # This method returns the object itself when the first argument is not a String.
       #
-      # 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
+      # @param input      [String]    The String to be filtered
+      # @param properties [[Symbol]*] Symbols equivalent to Regexp property for @\\p{}@ construct
+      # @return [String] A new clean String
       def self.evaluate(input, *properties)
         input.kind_of?(String) ? evaluate_regexp(input, :keep, properties) : input
       end

data/lib/normatron/filters/remove_filter.rb

@@ -2,33 +2,38 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Remove the characters that match the given properties.
+    #
+    # For additional informations see Normatron::Filter::ClassMethods#keep documentation.
+    # 
+    # @example Out of box
+    #   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]}]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/Regexp.html Regexp
+    # @see KeepFilter Normatron::Filters::KeepFilter
     module RemoveFilter
       extend Helpers
 
       ##
-      # Remove the characters that match the given properties.
+      # Performs input conversion according to filter requirements.
       #
-      # 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
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @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
+      # @param input      [String]    The String to be filtered
+      # @param properties [[Symbol]*] Symbols equivalent to Regexp property for @\\p{}@ construct
+      # @return [String] A new clean String
       def self.evaluate(input, *properties)
         input.kind_of?(String) ? evaluate_regexp(input, :remove, properties) : input
       end

data/lib/normatron/filters/squeeze_filter.rb

@@ -1,26 +1,34 @@
 module Normatron
   module Filters
+    
+    ##
+    # Remove multiple occurences of the same character.
+    #
+    # If no option are given, all runs of identical characters are replaced by a single character.
+    # 
+    # @example Out of box
+    #   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"]}]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-squeeze String#squeeze
+    # @see SquishFilter Normatron::Filters::SquishFilter
+    # @see StripFilter  Normatron::Filters::StripFilter
     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"
+      # Performs input conversion according to filter requirements.
       #
-      # @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"]}]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @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
+      # @param input   [String]    The String to be filtered
+      # @param targets [[String]*] Characters to be affected
+      # @return [String] A new squeezed String
       def self.evaluate(input, *targets)
         return input unless input.kind_of?(String)
         targets.any? ? input.squeeze(targets.last) : input.squeeze

data/lib/normatron/filters/squish_filter.rb

@@ -2,24 +2,31 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Strip input, remove line-breaks and multiple spaces.
+    # 
+    # @example Out of box
+    #   SquishFilter.evaluate("   the simpsons   ") #=> "the simpsons"
+    #   SquishFilter.evaluate("family      guy")    #=> "family guy"
+    #   SquishFilter.evaluate("the \n simpsons")    #=> "the simpsons"
+    #   SquishFilter.evaluate("the\nsimpsons")      #=> "the simpsons"
+    #
+    # @example Using as ActiveRecord::Base normalizer
+    #   normalize :attribute, :with => [:custom_filter, :squish]
+    #
+    # @see http://api.rubyonrails.org/classes/String.html#method-i-squish String#squish
+    # @see SqueezeFilter Normatron::Filters::SqueezeFilter
+    # @see StripFilter  Normatron::Filters::StripFilter
     module SquishFilter
 
       ##
-      # Strip input, remove line-breaks and multiple spaces.
-      # 
-      # @example
-      #   SquishFilter.evaluate("   the simpsons   ") #=> "the simpsons"
-      #   SquishFilter.evaluate("family      guy")    #=> "family guy"
-      #   SquishFilter.evaluate("the \n simpsons")    #=> "the simpsons"
-      #   SquishFilter.evaluate("the\nsimpsons")      #=> "the simpsons"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute, :with => [:custom_filter, :squish]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @return [String] The clean character sequence or the object itself
-      # @see http://api.rubyonrails.org/classes/String.html#method-i-squish String#squish
-      # @see SqueezeFilter Normatron::Filters::SqueezeFilter
+      # @param input [String] The String to be filtered
+      # @return [String] A new squished String
       def self.evaluate(input)
         input.kind_of?(String) ? input.squish : input
       end

data/lib/normatron/filters/strip_filter.rb

@@ -2,29 +2,37 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Removes traling and leading spaces.
+    # 
+    # @example Out of box
+    #   StripFilter.evaluate("   copy   ")      #=> "copy"
+    #   StripFilter.evaluate("   copy   ", :L)  #=> "copy   "
+    #   StripFilter.evaluate("   copy   ", :R)  #=> "   copy"
+    #   StripFilter.evaluate("   copy   ", :LR) #=> "copy"
+    #
+    # @example Using as ActiveRecord::Base normalizer
+    #   normalize :attribute_a, :with => :strip
+    #   normalize :attribute_b, :with => { :strip => :L }
+    #   normalize :attribute_c, :with => [:custom_filter, :strip]
+    #   normalize :attribute_d, :with => [:custom_filter, [:strip, :L]]
+    #   normalize :attribute_e, :with => [:custom_filter, {:strip => :R}]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-strip String#strip
+    # @see SqueezeFilter Normatron::Filters::SqueezeFilter
+    # @see SquishFilter Normatron::Filters::SquishFilter
     module StripFilter
       extend Helpers
 
       ##
-      # Remove traling and/or leading spaces from the string.
-      # 
-      # @example
-      #   StripFilter.evaluate("   copy   ")      #=> "copy"
-      #   StripFilter.evaluate("   copy   ", :L)  #=> "copy   "
-      #   StripFilter.evaluate("   copy   ", :R)  #=> "   copy"
-      #   StripFilter.evaluate("   copy   ", :LR) #=> "copy"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :strip
-      #   normalize :attribute_b, :with => { :strip => :L }
-      #   normalize :attribute_c, :with => [:custom_filter, :strip]
-      #   normalize :attribute_d, :with => [:custom_filter, [:strip, :L]]
-      #   normalize :attribute_e, :with => [:custom_filter, {:strip => :R}]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @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
+      # @param input [String] The String to be filtered
+      # @param edges [Symbol] @:L@ to strip trailing spaces, @:R@ for leading spaces or @:LR@ for both
+      # @return [String] A new stripped String
       def self.evaluate(input, edges=:LR)
         return input unless input.kind_of?(String)
         

data/lib/normatron/filters/swapcase_filter.rb

@@ -2,25 +2,31 @@ require 'normatron/filters/helpers'
 
 module Normatron
   module Filters
+    
+    ##
+    # Replaces uppercased characters by lowercased and vice versa.
+    # 
+    # @example Out of box
+    #   SwapcaseFilter.evaluate("As you Wish!") #=> "aS YOU wISH!"
+    #
+    # @example Using as ActiveRecord::Base normalizer
+    #   normalize :attribute_a, :with => :swapcase
+    #   normalize :attribute_b, :with => [:custom_filter, :swapcase]
+    #
+    # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-swapcase String#swapcase
+    # @see DownFilter     Normatron::Filters::DownFilter
+    # @see TitleizeFilter Normatron::Filters::TitleizeFilter
+    # @see UpcaseFilter   Normatron::Filters::UpcaseFilter
     module SwapcaseFilter
       extend Helpers
 
       ##
-      # Replaces uppercased characters by lowercased and vice versa.
-      # 
-      # @example
-      #   SwapcaseFilter.evaluate("As you Wish!") #=> "aS YOU wISH!"
+      # Performs input conversion according to filter requirements.
       #
-      # @example Using as ActiveRecord::Base normalizer
-      #   normalize :attribute_a, :with => :swapcase
-      #   normalize :attribute_b, :with => [:custom_filter, :swapcase]
+      # This method returns the object itself when the first argument is not a String.
       #
-      # @param [String] input A character sequence
-      # @return [String] The swapped case character sequence or the object itself
-      # @see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-swapcase String#swapcase
-      # @see DownFilter Normatron::Filters::DownFilter
-      # @see TitleizeFilter Normatron::Filters::TitleizeFilter
-      # @see UpcaseFilter Normatron::Filters::UpcaseFilter
+      # @param input [String] The String to be filtered
+      # @return [String] A new swapcased String
       def self.evaluate(input)
         return input unless input.kind_of?(String)
         input.gsub(/([\p{Ll}])|(\p{Lu})|([^\p{Ll}\p{Lu}])/u) { $3 || ($2 ? mb_send(:downcase, $2) : mb_send(:upcase, $1)) }