attribute-filters 1.4.0 → 2.0.0

data/docs/HISTORY

@@ -1,3 +1,45 @@
+=== 2.0.0 / 2012-10-01
+
+* major enhancements
+
+  * Operating speed increased by 100%
+  * API change:
+    * AttributeSet is now based on a Hash
+    * Added MetaSet for keeping sets of attribute sets
+    * Added DSL keyword for registering filtering methods
+    * DSL method `filter_attributes` is using filtering methods registered before
+  * Creation of duplicates for sets moved to class-level accessors
+  * Adding elements to sets improved, `AttributeSet` initializer uses the method `add`
+  * Common Filters seriously refactored (easily expandable and parametrizable now)
+  * Added common filters: Convert, Order, Pick, Presence
+
+* minor enhancements
+
+  * DSL class methods for models have now aliases named in third person
+  * `AttributeSet#annotations` returns a hash containing annotated attributes only
+  * Documentation updated, common filters specific documentation moved to `COMMON-FILTERS`
+  * Added `AttributeSet::Enumerable#each_name_value` enumerator
+  * Added `AttributeSet::Enumerable#select_accessible` enumerator
+  * Added DSL for attribute name gethering from next method name in a chain
+  * Added `filtered_attribute_simple` DSL method
+  * Added `attribute_set_exists?` DSL class method
+  * Added `virtual?` and `semi_real?` to `AttributeSet::AttrQuery` and `AttributeSet::Query`
+  * Added `changed?` and `unchanged?` to `AttributeSet::AttrQuery` and `AttributeSet::Query`
+  * Added `AttributeSet#to_set`
+  * Improved DSL methods: `valid?`, `invalid?`, `accessible?`, `protected?`
+  * Improved `AttributeSet::Query` initializer (added error checking)
+  * Improved `attributes_to_filter` DLS method (removed redundant calls to duplicates of a set)
+  * Overriden `inspect` method in `AttributeSet`
+
+* major bugfixes
+
+  * Fixed `AttributeSet::Query` wrapper calls (passing custom calls to next method was broken)
+  * Replaced `hash.merge(hash)` expressions with more `HashWithIndifferentAccess` compliant
+
+* minor bugfixes
+
+  *  Enumerators wrapped to return `AttributeSet::Enumerator` objects
+
 === 1.4.0 / 2012-08-24
 
 * major enhancements

data/docs/TODO

@@ -1,20 +1,37 @@
-* add more rspec examples (+ nil and boolean attributes)
 
-* add parameter support to squeeze common filter
+* attr_virtual - wrap method_defined? and add some gotchas into it that will wait for accessor to be added
+  there already is a hash for attr_virtual, all we need to do is to check any added accessor against that hash
+  that will only apply when there weren't accessors while using attr_virtual
 
-* add: changed? all.changed? any.changed? one.changed? none.changed? to attrquery and query proxies
-  - they can use methods that internally are checking it
 
-* add stringify to common filters
-* add numerize to common filters
-* add booleanize to common filters
-* add nullify to common filters
-* add clear to common filters
-* add reverse to common filters
-* add sanitize to common filters (that calls needed)
-  -- sanitize_email
+* add sanitize to common filters
   -- sanitize_url
   -- sanitize_string
   -- sanitize_name
   -- sanitize_country
   -- sanitize_iban (future, in a gem attribute-filters-common-iban)
+
+  sanitize_the_attribute :name
+  sanitize_the_attribute :name => { :as => :name }
+  sanitize :name
+  the_attribute :name, :should_be_sanitized
+  the_attribute :name, :should_be_sanitized => { :as => :name }
+  
+  before_save :sanitize_attributes
+
+* one module for sanitizing - AttributeFilters::Sanitize
+* possible submodules that enable certain/additional sanitizing methods
+
+
+  class User
+    sanitize_attributes :name, :email, :home => { :as => :address }
+  end
+
+-> uses :should_be_sanitized same as filters do.
+-> sanitization often uses each_element helper
+-> sanitization methods taken from: Sanitize.instance_methods(false) [and aliases]
+-> uses one main method for sanitization called sanitize_attributes
+    - for each attribute from a set the method checks the :as annotation (sanitize_attributes should add it)
+    - if there is no annotation it tries to guess it by the name
+      (uses global dictionary against name and its parts from the last one: e.g real_name takes 'name' first)
+

data/docs/USAGE.md

@@ -4,58 +4,62 @@ Usage of Attribute Filters
 Attribute sets
 --------------
 
-Attribute set is a set of attribute names. It's like an array
-or, to be exact, like a set (a hash that can only have true values
-assigned to elements in order to just know whether the key exists or not).
+Attribute set is a set of attribute names and optional annotations.
+It's like a hash and internally it is a kind of Hash, but differs in
+many places.
 
 Attribute sets have simple function; **they group attribute names**. What can
 you do with that? For example you can use it to perform some tasks
-on all attributes that are listed in a set.
+on all attribute names that are stored in a set (or their values). You can also
+combine sets, intersect, exclusively disjuct them, merge with other data, query them,
+iterate through them, and so on.
 
 ### Data structures ###
 
 Attribute sets are instances of
 [`ActiveModel::AttributeSet`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeSet)
-class. You can create and update sets freely and store them wherever you want,
-but when it comes to models then (at the class-level) you can (and you should) rely
-on a storage that is already prepared to handle sets.
+class. You can create and update sets freely and store in them wherever you want.
 
-The attribute sets assigned to models are stored as [class instance variable](http://blog.codegram.com/2011/4/understanding-class-instance-variables-in-ruby).
-**You cannot and should not interact with that storage directly**
-but by using dedicated class methods that are available in your models.
+For your convenience Attribute Filters also provides globally created attribute sets that are bound to your models
+(at the class-level). The binding is realized simply by using the hash of all these sets. The attribute sets
+assigned to models are stored as
+[class instance variable](http://blog.codegram.com/2011/4/understanding-class-instance-variables-in-ruby).
+
+**You should interact with the global sets using dedicated DSL keywords** that are available in your models.
 These methods will allow you to read or write some data from/to global attribute sets.
 
-Attribute Filters are using `AttributeSet` instances
-not just to store internal data but also to interact
-with other parts of a program. So whenever there is
-a method that returns a set of attributes or even
-a set of set names, the returned value will probably
-be an instance of the class `AttributeSet`.
+Attribute Filters are using `AttributeSet` instances not just to store internal data
+but also to interact with other parts of a program. So whenever there is a method
+that returns a set of attributes or even a set of set names, the returned value
+will probably be an instance of the `AttributeSet` class.
 
 Note that when sets are returned the convention is that:
 
   * **attribute names are strings**
   * **set names are symbols**
+  * **annotations are hashes** attached to attribute names (strings)
+  * **annotation keys are symbols**
 
-Also note that once you create a set that is bound to your model you cannot
-remove elements from it and any query returning its contents will give you
-a copy. That's because **model-bound attribute sets should be considered
-a part of the interface**.
+Once you create some set that is bound to your model (there is a class method `attribute_set` for it)
+you cannot remove elements from it. Moreover, any query returning its contents will always
+give you the deep copy. Such a separation is a consequence of the idea that **the model-bound attribute
+sets should be a part of the interface**, which shouldn't change at runtime. This approach
+enforces the declarative design (which is very concise and clear as you read the code).
 
-### Defining the attribute sets ###
+### Defining the model-level attribute sets ###
 
 First thing that should be done when using the Attribute Filters
 is defining the sets of attributes in models.
 
 You can also create local sets (using `ActiveModel::AttributeSet.new`)
-or a local sets with extra syntactic sugar (using `ActiveModel::AttributeSet.new`)
-but in real-life scenarios you should first create some model-bound sets that
-can be later used by filters and by your own methods.
+or a local sets with extra syntactic sugar (using `ActiveModel::AttributeSet::Query.new`)
+but in real-life scenarios you will use model-bound sets that can be later used
+by common filters and by your own methods.
  
 #### `attribute_set(set_name => attr_names)` ####
 
 The [`attribute_set`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods:attribute_set)
-(a.k.a `attributes_that`) class method allows to **create or update a set** that will be
+(a.k.a `has_attributes_that`) class method allows to **create or update a set** that will be
 tied to a model.
 
 Example:
@@ -63,18 +67,18 @@ Example:
 ```ruby
 class User < ActiveRecord::Base
 
-  attributes_that should_be_stripped:     [ :username, :email, :real_name ]
-  attributes_that should_be_downcased:    [ :username, :email ]
-  attributes_that should_be_capitalized:  [ :real_name ]
+  has_attributes_that should_be_stripped:     [ :username, :email, :real_name ]
+  has_attributes_that should_be_downcased:    [ :username, :email ]
+  has_attributes_that should_be_capitalized:  [ :real_name ]
 
 end
 ```
 
 Instead of `attribute_set` you may also use one of the aliases:
 
-  * `attributes_that`, `attributes_that_are`, `are_attributes_that_are`, `from_attributes_that_are`,   
-    `within_attributes_that_are`, `attributes_that`, `attributes_are`, `attributes_for`,  
-    `are_attributes`, `are_attributes_for`, `attributes_set`, `properties_that`   
+  * `attributes_set`, `attributes_that_are`, `attributes_that`, `properties_that`,         
+    `has_attribute_set`, `has_attribute_that`, `has_attribute_that_is`, `has_attributes`,          
+    `has_attributes_set`, `has_attributes_that_are`, `has_attributes_that`, `has_properties_that`
 
 #### `filter_attribute(attr => set_names)` ####
 
@@ -90,17 +94,18 @@ Example:
 ```ruby
 class User < ActiveRecord::Base
 
-  the_attribute real_name:  [ :should_be_stripped, :should_be_capitalized ]
-  the_attribute username:   [ :should_be_stripped, :should_be_downcased   ]
-  the_attribute email:      [ :should_be_stripped, :should_be_downcased   ]
+  its_attribute real_name:  [ :should_be_stripped, :should_be_capitalized ]
+  its_attribute username:   [ :should_be_stripped, :should_be_downcased   ]
+  its_attribute email:      [ :should_be_stripped, :should_be_downcased   ]
 
 end
 ```
 
 Instead of `filter_attribute` you may also use one of the aliases:
 
-  * `filtered_attribute`, `the_attribute`, `add_attribute_to_set`,    
-    `add_attribute_to_sets`, `attribute_to_set`, `filtered_attributes`
+  * `the_attribute`, `attribute_to_set`, `filtered_attribute`, `filtered_attributes`,
+    `filters_attribute`, `filters_attributes`, `its_attribute`, `has_attribute`,
+    `has_the_attribute`, `has_filtered_attribute`, `has_filtered_attributes`
 
 #### Mixing the syntaxes ####
 
@@ -110,11 +115,11 @@ You can also use regular arguments instead of hashes to create sets:
 ```ruby
 class User < ActiveRecord::Base
 
-  attributes_that :should_be_stripped, :username, :email, :real_name
+  has_attributes_that :should_be_stripped, :username, :email, :real_name
 
-  the_attribute :real_name, :should_be_capitalized
-  the_attribute :username,  :should_be_downcased
-  the_attribute :email,     :should_be_downcased
+  its_attribute :real_name, :should_be_capitalized
+  its_attribute :username,  :should_be_downcased
+  its_attribute :email,     :should_be_downcased
 
 end
 ```
@@ -128,8 +133,12 @@ of class methods to query them.
 
 The [`attribute_set`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods:attribute_set)
 (a.k.a `attributes_that`) class method called with a single argument **returns the attribute set
-of the given name**. It will always return the instance of `AttributeSet` class, even if there
-is no set registered under the given name (in that case the resulting set will be empty).
+of the given name**.
+
+It will always return the instance of `AttributeSet` class, even if there is no set registered under
+the given name (in that case the resulting set will be empty). To know if the returned set is a stub
+(placed instead of the missing one) you can use `frozen?` on it or you can call the DSL method
+`attribute_set_exists?(set_name)` before querying the global sets for a model.
 
 Example:
 
@@ -140,16 +149,23 @@ Example:
 
 Note that the returned set will be a copy of the original set stored within your model.
 
+Alternative syntax:
+
+```ruby
+  User.attributes_that.should_be_stripped - User.attributes_that.should_be_downcased
+  # => #<ActiveModel::AttributeSet: {"real_name"}>
+```
+
 Instead of `attribute_set` you may also use one of the aliases:
 
-  * `attributes_that`, `attributes_that_are`, `are_attributes_that_are`, `from_attributes_that_are`,   
-    `within_attributes_that_are`, `attributes_that`, `attributes_are`, `attributes_for`,  
-    `are_attributes`, `are_attributes_for`, `attributes_set`, `properties_that`
+  * `attributes_set`, `attributes_that_are`, `attributes_that`, `properties_that`,         
+    `has_attribute_set`, `has_attribute_that`, `has_attribute_that_is`, `has_attributes`,          
+    `has_attributes_set`, `has_attributes_that_are`, `has_attributes_that`, `has_properties_that`
 
 #### `attribute_sets` ####
 
 The [`attribute_sets`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods:attribute_sets)
-class method returns a hash containing **all the defined attribute sets** indexed by their names.
+class method returns a MetaSet kind of value containing **all the defined attribute sets** indexed by their names.
 
 Example:
 
@@ -174,8 +190,15 @@ Note that the returned sets will be copies of the original sets stored within yo
 #### `attribute_set` ####
 
 The [`attribute_set`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods:attribute_set)
-(a.k.a `attributes_that`) class method called without any arguments is a wrapper that calls `attribute_sets` which
-returns a hash containing **all the defined attribute sets**.
+(a.k.a `attributes_that`) class method called without any arguments is a DSL wrapper that calls `attribute_set(set_name)`
+with `set_name` taken from next method call.
+
+Example:
+
+```ruby
+  User.attributes_that.should_be_downcased
+  # => #<ActiveModel::AttributeSet: {"username", "email"}>
+```
 
 #### `filter_attribute(attribute_name)` ####
 
@@ -200,9 +223,8 @@ Instead of `filter_attribute` you may also use one of the aliases:
 #### `attributes_to_sets` ####
 
 The [`attributes_to_sets`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods:attributes_to_sets)
-class method returns a hash containing **all filtered attributes and arrays of sets**
-that the attributes belong to. The hash is indexed by attribute names.
-(Filtered means that they belong to some sets.)
+class method returns a MetaSet kind of value containing **all filtered attributes and sets that the attributes
+belong to**. The meta set is indexed by attribute names.
 
 Example:
 
@@ -223,8 +245,8 @@ Instead of `attributes_to_sets` you may also use one of the aliases:
 The [`filter_attribute`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods:filter_attribute)
 (a.k.a `the_attribute`) class method called without any arguments
 is a wrapper that calls `attributes_to_sets` which returns
-a hash containing **all filtered attributes and arrays of sets**
-that the attributes belong to.
+a returns a MetaSet kind of value containing **all filtered attributes and sets that the attributes
+belong to**.
 
 ### Querying sets in model objects ###
 
@@ -234,7 +256,8 @@ To do that you may use instance methods that are designed for that purpose.
 #### `attribute_set` ####
 
 The [`attribute_set`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:attribute_set)
-instance method called withount an argument **returns the attribute set object containing all attributes known in a current object**.
+instance method called withount an argument **returns the attribute set object containing all attributes known
+in a current model**.
 
 Example:
 
@@ -280,15 +303,21 @@ There are also variants of this method that differ in a kind of taken argument:
 
 Instead of `attribute_set` you may also use one of the aliases:
 
-  * `attributes_that_are`, `from_attributes_that`, `are_attributes_that_are`, `from_attributes_that_are`,   
-    `within_attributes_that_are`, `attributes_that`, `attributes_are`,      
-    `attributes_for`, `are_attributes`, `are_attributes_for`, `attributes_set`,            
-    `properties_that`
+  * `attributes_set`, `attributes_that_are`, `attributes_that`, `properties_that`,         
+    `has_attribute_set`, `has_attribute_that`, `has_attribute_that_is`, `has_attributes`,          
+    `has_attributes_set`, `has_attributes_that_are`, `has_attributes_that`, `has_properties_that`
+    
+Instead of `attribute_set` you may also use:
+
+  * `attribute_set_simple(set_name)`
+
+It works same way as `attribute_set(set_name)` but doesn't wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
 
 #### `attribute_sets` ####
 
 The [`attribute_sets`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:attribute_sets)
-method returns a hash containing **all the defined attribute sets** indexed by their names.
+method returns a meta set containing **all the defined attribute sets** indexed by their names.
 It won't return the exact internal hash but a duplicate and every set within it will also be a duplicate
 of the original one.
 
@@ -303,7 +332,7 @@ Example:
 ```
 
 Note that the returned hash will have a default value set to instance of the `AttributeSet`.
-If you'll try to get the value of an element that doesn't exist **the empty set will be returned**.
+If you'll try to get the value of an element that doesn't exist **the empty, frozen set will be returned**.
 
 Instead of `attribute_sets` you may also use one of the aliases:
 
@@ -312,7 +341,10 @@ Instead of `attribute_sets` you may also use one of the aliases:
 #### `all_attributes` ####
 
 The [`all_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:all_attributes)
-method **returns the attribute set containing all known attributes**.
+method **returns the attribute set containing all known attributes**. It combines many other sets,
+including the sets containing attributes marked as semi-real and virtual (explained later)
+and temporary sets obtained by calling various Rails methods. It just tries to collect as many
+known attribute names as possible.
 
 Example:
 
@@ -321,14 +353,25 @@ Example:
   # =>  #<ActiveModel::AttributeSet: {"id", "username", "email", "password", "language", "created_at", "updated_at"}>
 ```
 
-Be aware that this method requires that the used ORM has `attributes` data structure available for any model object.
+Be aware that this method requires that the used ORM has `attributes` method available for a model object.
 
 Instead of `all_attributes` you may also use the alias:
 
   * `all_attributes_set`
-  
+
 or call the instance method `attribute_set` without arguments.
 
+The `all_attributes` synopsis is really:
+
+  * `all_attributes(simple = false, no_presence_check = true)`
+
+First argument (`simple`) causes the method to not wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
+
+Second argument (`no_presence_check`) causes the method to not
+check if each attribute exists by verifying presence of its accessor
+in case of semi-real attributes set that is merged into the resulting set.
+
 #### `all_accessible_attributes` ####
 
 The [`all_accessible_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:all_accessible_attributes)
@@ -340,12 +383,57 @@ Example:
   User.first.all_accessible_attributes
   # =>  #<ActiveModel::AttributeSet: {"username", "email", "language"}> 
 ```
-
-Be aware that this method requires that the used ORM has `accessible_attributes` data structure available for any model class.
+Be aware that this method requires that the used ORM has `accessible_attributes` method available for a model
+class. This method works only if your Rails application supoorts accessible attributes (versions up to 3 support it).
 
 Instead of `all_accessible_attributes` you may also use the alias:
 
   * `accessible_attributes_set`
+  
+Instead of `all_accessible_attributes` you may also use:
+
+  * `all_accessible_attributes(true)`
+
+It works the same way but doesn't wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
+
+#### `all_inaccessible_attributes` ####
+
+The [`all_inaccessible_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:all_inaccessible_attributes)
+method **returns the attribute set containing all inaccessible attributes**.
+
+Example:
+
+```ruby
+  User.first.all_inaccessible_attributes
+  # =>  #<ActiveModel::AttributeSet: {"id", "confirmation_token", "encrypted_password", "deleted_at"}> 
+```
+
+Be aware that this method requires that the used ORM has `accessible_attributes` and `protected_attributes`
+method available in a model. This method works only if your Rails application supoorts accessible
+attributes (versions up to 3 support it).
+
+Instead of `all_inaccessible_attributes` you may also use the alias:
+
+  * `inaccessible_attributes_set`
+  
+Instead of `all_inaccessible_attributes` you may also use:
+
+  * `all_inaccessible_attributes(true)`
+
+It works the same way but doesn't wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
+
+The `all_inaccessible_attributes` synopsis is really:
+
+  * `all_inaccessible_attributes(simple = false, no_presence_check = true)`
+
+First argument (`simple`) causes the method to not wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
+
+Second argument (`no_presence_check`) causes the method to not
+check if each attribute exists by verifying presence of its accessor
+in case of semi-real attributes set that is used to compute the resulting set.
 
 #### `all_protected_attributes` ####
 
@@ -356,34 +444,80 @@ Example:
 
 ```ruby
   User.first.all_protected_attributes
-  # =>  #<ActiveModel::AttributeSet: {"id"}> 
+  # =>  #<ActiveModel::AttributeSet: {"id", "type"}> 
 ```
 
-Be aware that this method requires that the used ORM has `protected_attributes` data structure available for any model class.
+Be aware that this method requires that the used ORM has `protected_attributes` method available for a model
+class. This method works only if your Rails application supoorts accessible attributes (versions up to 3 support it).
 
 Instead of `all_protected_attributes` you may also use the alias:
 
   * `protected_attributes_set`
 
-#### `all_inaccessible_attributes` ####
+Instead of `all_protected_attributes` you may also use:
 
-The [`all_inaccessible_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:all_inaccessible_attributes)
-method **returns the attribute set containing all inaccessible attributes**. Inaccessible attributes are attributes
-that aren't listed as accessible, which includes protected attributes and attributes for which the `attr_accessible` clause
-wasn't used.
+  * `all_protected_attributes(true)`
+
+It works the same way but doesn't wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
+
+#### `all_semi_real_attributes` ####
+
+The [`all_semi_real_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:all_semi_real_attributes)
+method **returns the attribute set containing all attributes marked as semi-real**. This is the concept
+of Attribute Filters used to handle attributes that aren't stored in a database (a.k.a virtual attributes, explained later).
 
 Example:
 
 ```ruby
-  User.first.all_inaccessible_attributes
-  # =>  #<ActiveModel::AttributeSet: {"id", "password", "created_at", "updated_at"}> 
+  class User
+    treats_as_real :trololo
+  end
+  User.first.all_semi_real_attributes
+  # =>  #<ActiveModel::AttributeSet: {"trololo"}> 
 ```
 
-Be aware that this method requires that the used ORM has `accessible_attributes` data structure available for any model class.
+Instead of `all_semi_real_attributes` you may also use one of the aliases:
 
-Instead of `all_inaccessible_attributes` you may also use the alias:
+  * `semi_real_attributes_set`
+  * `treat_as_real` (without arguments)
 
-  * `inaccessible_attributes_set`
+The `all_semi_real_attributes` synopsis is really:
+
+  * `all_semi_real_attributes(simple = false, no_presence_check = true)`
+
+First argument (`simple`) causes the method to not wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
+
+Second argument (`no_presence_check`) causes the method to not
+check if each attribute exists in order to include its name into set.
+
+
+#### `all_virtual_attributes` ####
+
+The [`all_virtual_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:all_virtual_attributes)
+method **returns the attribute set containing all virtual attributes**.
+
+Example:
+
+```ruby
+  class User
+    attr_virtual :lol
+  end
+  User.first.all_virtual_attributes
+  # =>  #<ActiveModel::AttributeSet: {"lol"}> 
+```
+
+Instead of `all_virtual_attributes` you may also use the alias:
+
+  * `virtual_attributes_set`
+
+Instead of `all_virtual_attributes` you may also use:
+
+  * `all_virtual_attributes(true)`
+
+It works the same way but doesn't wrap the result in a transparent proxy
+object that brings some syntactic sugar (explained later).
 
 #### `filtered_attribute(attribute_name)` ####
 
@@ -391,7 +525,10 @@ The [`filtered_attribute`](http://rubydoc.info/gems/attribute-filters/ActiveMode
 (a.k.a `the_attribute`) method called with a single argument is used for checking
 **what are the sets that the attribute belongs to**. It won't return the exact set object but a duplicate.
 It will always return AttributeSet object, even if there is no attribute of the given name
-(in that case the resulting set will be empty).
+(in that case the resulting set will be empty and frozen).
+
+If the attribute name is not given or it's +nil+ then the name of an attribute is taken from the
+name of a next method in the chain call.
 
 Example:
 
@@ -405,11 +542,16 @@ Instead of `filtered_attribute` you may also use one of the aliases:
   * `the_attribute`, `is_the_attribute`, `are_attributes`,     
     `are_the_attributes`
 
+#### `filtered_attribute_simple(attribute_name)` ####
+
+The `filtered_attribute_simple` method is a version of ``filtered_attribute` method that doesn't wrap the resulting
+object in a proxy object. The attribute name must be given.
+
 #### `attributes_to_sets` ####
 
 The [`attributes_to_sets`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:attributes_to_sets)
-method returns a hash containing **all filtered attributes and arrays of sets**
-that the attributes belong to. The hash is indexed by attribute names.
+method returns a meta set containing **all filtered attributes and sets that the attributes belong to**.
+The meta set is indexed by attribute names.
 
 Example:
 
@@ -448,6 +590,61 @@ Example:
   # => false
 ```
 
+You can also use one of the aliases:
+
+  * `invalid?`, `is_not_valid?`, `any_invalid?`, `are_not_valid?`, `not_valid?`, `is_any_invalid?`
+  * `valid?`, `is_valid?`, `are_valid?`, `all_valid?`, `are_all_valid?`
+
+#### `changed?` and `unchanged?` ####
+
+The `changed?` and `unchanged?` helpers allow you to test if **any** attribute listed in the set
+has changed its value (`changed?`) or if **all** attributes from a set remain unchanged (`unchanged?`).
+
+
+```ruby
+  u = User.first
+  u.username = ' '
+  # => " " 
+  
+  u.all_attributes.any_changed?
+  # => true 
+  
+  u.all_attributes.unchanged?
+  # => false
+```
+
+You can also use one of the aliases:
+
+  * `changed?`, `any_changed?`, `have_changed?`, `have_any_changed?`, `is_any_changed?`, `has_any_changed?`, `has_changed?`
+  * `unchanged?`, `none_changed?`, `nothing_changed?`, `is_unchanged?`, `are_all_unchanged?`, `all_unchanged?`, 
+    `havent_changed?`, `arent_changed?`, `are_not_changed?`, `none_changed?`, `not_changed?`
+
+#### `values` ####
+
+This method simply returns the values of all attributes in a set as an array.
+
+#### `to_set` ####
+
+This method simply produces an object that is a kind of Set and contains all attribute names.
+
+### `AttributeSet` enumerators ###
+
+The `AttributeSet` class is derived from `Hash` class. The keys are attributes,
+the values are usually `true` (`TrueClass`) or hashes (`Hash`) if there are any annotations attached
+to attribute name. All overriden enumerators are kind of `AttributeSet::Enumerator`.
+
+Let's see what are the differences from standard enumerators that can be found in the Hash class.
+
+  * `each` – works on keys and values (behaves like `each_pair`) but usable with just one argument in a block (key)
+  * `each_pair` – iterates throught key => value pairs
+  * `each_name_value(active_model_object, no_presence_check = false)` – iterates throught key => attribute value pairs
+  * `collect` (`map`) – produces array containg keys that may be altered by the given block
+  * `select` – selects new hash with elements for which the given block evaluates to +true+ (yields: keys, values)
+  * `select_accessible(active_model_object)` – same as `select` but picks the attributes which have accessors
+  * `reject` – reversed `select`
+  * `sort` – sorts AttributeSet object by keys
+  * `sort_by` – sorts AttributeSet object using the comparison method from a block
+
 ### Syntactic sugar for queries ###
 
 Querying attribute sets may be even more sweet when you add some syntactic sugar
@@ -493,6 +690,25 @@ in order to help you in creating nice looking method call chains like:
   User.first.attributes_that(:should_be_stripped).sort.list.present?
 ```
 
+##### Set & attribute names as methods #####
+
+It's possible to enter a set name or an attribute name as a name
+of next method in a call chain instead of passing them as a symbolic argument.
+It works with DSL instance methods `attribute_set(set_name)`
+and `filtered_attribute(attribute_name)`.
+
+Examples:
+
+```ruby
+  User.first.attributes_that.should_be_stripped   # same as User.first.attributes_that(:should_be_stripped)
+  User.first.attributes_that_are.required_to_use_app.present?
+  User.first.attributes_that.should_be_stripped.sort.list.present?
+  
+  User.first.the_attribute.username               # same as User.first.the_attribute(:username)
+  User.first.the_attribute.username.list.sets
+  User.first.the_attribute.username.valid?
+```
+
 ##### Neutral methods #####
 
 * **`are`**
@@ -557,7 +773,7 @@ Just imagine that:
 becomes:
 
 ```ruby
-  attributes_that(:should_be_stripped).all? { |attribute| attribute METHOD(ARGUMENTS) }
+  attributes_that(:should_be_stripped).all? { |attribute| attribute.METHOD(ARGUMENTS) }
 ```
 
 Another example, but with `any`:
@@ -567,6 +783,13 @@ Another example, but with `any`:
   # => true
 ```
 
+You also do:
+
+```ruby
+  User.first.attributes_that(:should_be_stripped).any.changed?
+  # => false
+```
+
 ##### Elements selectors #####
 
 * **`list`**
@@ -612,12 +835,72 @@ Examples:
   
   u.attributes_that(:should_be_stripped).list.valid?
   # => #<ActiveModel::AttributeSet: {"username", "email"}>
+  
+  User.first.attributes_that(:should_be_stripped).is.any.valid?
+  # => true
+  
+  User.first.are_attributes_that(:should_be_stripped).all.valid?
+  # => true
 ```
 
 Be aware that calling these methods causes model object to be validated. The required condition
 to use these methods is the ORM that has `errors` hash (Active Record has it).
 
-#### Querying attributes for set names ####
+##### Changes tracking helpers #####
+
+* **`changed?`**
+* **`unchanged?`**
+
+Syntactic sugar for changes tracking is used when calls to these methods
+are combined with selectors described above (presence selectors and elements selectors).
+
+Examples:
+
+```ruby
+  u = User.first
+  u.username = " "
+  
+  u.attributes_that(:should_be_stripped).all.changed?
+  # => false
+  
+  u.attributes_that(:should_be_stripped).any.changed?
+  # => true
+  
+  u.attributes_that(:should_be_stripped).list.changed?
+  # => #<ActiveModel::AttributeSet: {"username"}>
+  
+  User.first.all_attributes.is.any.unchanged?
+  # => true
+  
+  User.first.all_attributes.are.none.unchanged?
+  # => false
+```
+
+Be aware that the required condition to use these methods is the ORM that
+has `changes` hash (Active Record has it).
+
+##### Calling custom methods #####
+
+It's possible to call any other methods using selectors.
+Note that te method next to the given selector will be called **on a value** of each tested attribute.
+
+Examples:
+
+```ruby
+  u = User.first
+  
+  u.attributes_that(:should_be_stripped).all.is_a?(String)
+  # => false
+
+  u.attributes_that(:should_be_stripped).any.is_a?(String)
+  # => false
+  
+  u.attributes_that(:should_be_stripped).list.is_a?(String)
+  # => #<ActiveModel::AttributeSet: {"username", "email"}>
+```
+
+
+#### Querying attributes ####
 
 Querying attributes to know sets they belong to uses one
 instance method available in your models:
@@ -655,10 +938,14 @@ Example:
 
 ```ruby
   User.first.the_attribute(:username).list.sets
-  # => #<ActiveModel::AttributeSet: {:should_be_downcased, :should_be_stripped}>
+  # => {:should_be_downcased => true, :should_be_stripped => true}
+  
+  User.first.the_attribute(:username).list.sets.to_a
+  # => [:should_be_downcased, :should_be_stripped]
+
 ```
 
-##### Set membership testing #####
+##### Attribute membership querying #####
 
 * **`belongs_to?`**
 * **`in?`**
@@ -686,7 +973,7 @@ Example:
   # => true
 ```
 
-##### Set membership querying #####
+##### Attribute membership testing #####
 
 Membership querying has different syntax from simple testing.
 It uses set name with the question mark attached to it.
@@ -704,7 +991,7 @@ with question mark. Otherwise you may get false positives
 or a strange errors when trying to test if attribute belongs
 to a set. The real method call will override your check.
 
-##### Set accessibility querying #####
+##### Attribute accessibility testing #####
 
 * **`accessible?`**
 * **`inaccessible?`**
@@ -727,6 +1014,91 @@ Examples:
   # => true
 ```
 
+Be aware that this method requires that the used ORM has `accessible_attributes` and `protected_attributes` methods
+available in a model. This method works only if your Rails application supoorts accessible attributes (versions up to 3 support it).
+
+##### Attribute validity testing #####
+
+* **`valid?`**
+* **`invalid?`**
+* **`is_valid?`**
+* **`is_invalid?`**
+
+The methods above allow you to test if certain attribute that changed is valid or invalid.
+
+Examples:
+
+```ruby
+  u = User.first
+  u.username = ' '
+  u.the_attribute(:username).is.valid?
+  # => false
+  u.the_attribute(:username).is_valid?
+  # => false
+  u.the_attribute(:username).invalid?
+  # => true
+```
+
+Be aware that this method requires that the used ORM has `valid?` and `errors` methods that allow to validate
+model on demand. Also note that validations will run when using that methods.
+
+##### Attribute change testing #####
+
+* **`changed?`**
+* **`unchanged?`**
+* **`is_changed?`**
+* **`is_unchanged?`**
+* **`has_changed?`**
+* **`hasnt_changed?`**
+* **`not_changed?`**
+
+The methods above allow you to test if certain attribute changed recently or not.
+
+Examples:
+
+```ruby
+  u = User.first
+  u.username = ' '
+  u.the_attribute(:username).has_changed?
+  # => true
+  u.the_attribute(:id).unchanged?
+  # => true
+```
+
+Be aware that this method requires that the used ORM has `changes` method that allows to query a model for
+all changed attributes.
+
+##### Attribute virtuality testing #####
+
+* **`semi_real?`**
+* **`virtual?`**
+* **`is_semi_real?`**
+* **`is_virtual?`**
+
+The methods above allow to you to test if certain attribute is virtual or semi-real (explained later).
+
+```ruby
+  u = User.first
+  u.the_attribute(:id).is.virtual?
+  # => false
+  u.the_attribute(:id).is.semi_real?
+  # => false
+```
+
+##### Attribute value querying #####
+
+  * `value`
+
+Using the `value` method you can get the current value of an attribute.
+
+Example:
+
+```ruby
+  u = User.first
+  u.the_attribute.username.value
+  # => "admin"
+```
+
 Attribute filters
 -----------------
 
@@ -748,9 +1120,9 @@ class User < ActiveRecord::Base
 
   # Defining attribute sets
 
-  the_attribute real_name:  [ :should_be_stripped, :should_be_capitalized ]
-  the_attribute username:   [ :should_be_stripped, :should_be_downcased   ]
-  the_attribute email:      [ :should_be_stripped, :should_be_downcased   ]
+  its_attribute real_name:  [ :should_be_stripped, :should_be_capitalized ]
+  its_attribute username:   [ :should_be_stripped, :should_be_downcased   ]
+  its_attribute email:      [ :should_be_stripped, :should_be_downcased   ]
 
   # Registering filtering callback methods
 
@@ -760,6 +1132,10 @@ class User < ActiveRecord::Base
 
   # Defining filtering methods
 
+  has_filtering_method :downcase_names,   :should_be_downcased
+  has_filtering_method :capitalize_names, :should_be_capitalized
+  has_filtering_method :strip_names,      :should_be_stripped
+
   def downcase_names
     filter_attributes_that :should_be_downcased do |atr|
       atr.mb_chars.downcase.to_s
@@ -805,7 +1181,7 @@ The evaluated block can make use of the following arguments that are passed to i
 * `set_name` [Symbol] - a name of the processed attribute set
 * `args` [Array] - an optional arguments passed to the method
 
-By default only existing, changed and non-blank attributes are processed.
+By default only **existing, changed and non-blank** attributes are processed.
 You can change that behavior by adding a flags as the first arguments:
 
   * `:process_blank` – tells to also process attributes that are blank (empty or `nil`)
@@ -813,11 +1189,15 @@ You can change that behavior by adding a flags as the first arguments:
   * `:no_presence_check` – tells not to check for existence of each processed attribute when processing
     all attributes; increases performance but you must care about putting only the existing attributes into sets
 
+The checking mentioned in `:no_presence_check` flag description is done by querying internal Rails hashes
+containing known attributes and internal sets containing virtual attributes added by `attr_virtual` or
+`treats_as_real` keywords (described later).
+
 Example:
 
 ```ruby
   class User
-    attributes_that should_be_lolized: [ :username ]
+    has_attribute_that should_be_lolized: :username
     before_validation :lolize
 
     def lolize
@@ -825,6 +1205,7 @@ Example:
         [attribute_value, set_name.to_s, attribute_name, *args.flatten].join('-')
       end
     end
+    filtering_method :lolize, :should_be_lolized
   end
 
   u = User.new
@@ -869,12 +1250,18 @@ You can change that behavior by adding a flags as the first arguments:
   * `:process_all` - tells to process all attributes, not just the ones that has changed
   * `:no_presence_check` – tells not to check for existence of each processed attribute when processing
     all attributes; increases performance but you must care about putting only the existing attributes into sets
+  * `:include_missing` – includes attributes that does not exist in a resulting iteration (their values are
+    always `nil`); has the effect only when `:process_blank` and `:no_presence_check` are present
+
+The checking mentioned in `:no_presence_check` flag description is done by querying internal Rails hashes
+containing known attributes and internal sets containing virtual attributes added by `attr_virtual` or
+`treats_as_real` keywords (described later).
 
 Example:
 
 ```ruby
   class User
-    attributes_that should_be_lolized: [ :username ]
+    has_attribute_that should_be_lolized: :username
     before_validation :lolize
 
     def lolize
@@ -882,6 +1269,7 @@ Example:
         attribute_object << '-' << [set_name.to_s, attribute_name, *args.flatten].join('-')
       end
     end
+    filtering_method :lolize, :should_be_lolized
   end
 
   u = User.new
@@ -936,226 +1324,177 @@ if the filtering operation occured.
 
 There are cases that virtual attributes (the ones that does not really exist in a database)
 are to be filtered. By default it won't happen since all the filtering methods assume
-the presence of any processed attribute as 'a real' attribute. There are three ways
-to overcome that problem.
-
-#### Unconditional filtering ####
+the presence of any processed attribute as 'a real' attribute. There are different ways
+to overcome that problem. First two methods described below are recommended.
 
-The first way is to pass the `:no_presence_check` and `:process_all` flags to the filtering method.
-That causes filter to be executed for each attribute from a set without any conditions (no checking
-for presence of setter/getter method and no checking for changes).
+#### Marking as virtual ####
 
-Be aware that by doing that you take full responsibility for attribute set names added to your set.
-If you put a name of nonexistent attribute then you may get ugly error later.
+Since version 1.4.0 of Attribute Filters the **recommended way of dealing with
+virtual attributes** is to make use of Active Model's changes tracking.
+To do that look at your ORM's documentation and see 
+[`ActiveModel::Dirty`](http://api.rubyonrails.org/classes/ActiveModel/Dirty.html)
+and a method `attribute_will_change` that it contains. Just call that method from within
+your setter and you're done.
 
-With that approach you can filter virtual attributes that are inaccessible to controllers
-and don't show up when model is queried for known attributes. Using it may also cause some filters
-to be executed more often than needed, since the changes tracking is disabled (`process_all`).
+This approach can be easily used with predefined filters. The benefit of it,
+contrary to other methods, is that a filter will never be called redundantly.
 
-Example:
+You should use the built-in DSL keyword **`attr_virtual`** that will create
+setter and getter for you.
 
 ```ruby
-class User
+class User < ActiveRecord::Base
 
   # declare a virtual attribute
-  attr_accessor :real_name
+  attr_virtual :real_name
 
   # define a set
-  attributes_that :should_be_splitted => [ :real_name ]
+  has_attributes_that :should_be_splitted => [ :real_name ]
 
   # register a callback method
   before_validation :split_attributes
 
   # create a filtering method
   def split_attributes
-    for_attributes_that(:should_be_splitted, :no_presence_check, :process_all) do |value|
+    for_attributes_that(:should_be_splitted) do |value|
       names = value.split(' ')
-      self.first_name = names[0]  # assuming first_name exists in a database
-      self.last_name  = names[1]  # assuming last_name exists in a database
+      self.first_name = names[0]
+      self.last_name  = names[1]
     end
   end
+  filtering_method :split_attributes, :should_be_splitted
 
 end
 ```
 
-#### Marking as semi-real ####
-
-The second way is to use `treat_attributes_as_real` (or simply `treat_as_real`) clause in your model
-(available from version 1.2.0 of Attribute Filters). That approach may be applied to attributes
-that aren't (may not or should not be) tracked for changes and aren't (may not or should not be) accessible
-(to a controller) nor marked as protected.
-
-There are two main differences from the unconditional filtering. First is that marking attribute
-as real causes it to be added to the list of all known attributes that is returned by `all_attributes_set`
-(a.k.a `all_attributes`). The second is that nothing ugly will happen if there will be non-existent
-attributes in a set when filtering method kicks in. That's because the filtering method doesn't require
-`:no_presence_check` flag to pick up such attributes. Attributes that could not be handled are simply ignored.
-
-The `:process_all` flag is also not needed since all virtual attributes marked as real are by default
-not checked for changes.
+Note that for Rails version 3 you may need to declare attribute as accessible using `attr_accessible`
+if you want controllers to be able to update its value through assignment passed to model.
 
-Example:
+You may change the setter and getter for vitrtual attribute on you own, but it should be done
+somewhere in the code **before** the `attr_virtual` clause. That will allow `attr_virtual`
+to wrap you methods and enable tracking of changes for the attribute.
 
 ```ruby
-class User
-
-  # declare a virtual attribute
-  attr_accessor :real_name
-
-  # mark the attribute as real
-  treat_as_real :real_name
+class User < ActiveRecord::Base
 
   # define a set
-  attributes_that :should_be_splitted => [ :real_name ]
+  has_attributes_that :should_be_splitted => [ :real_name ]
 
   # register a callback method
-  before_validation :split_attributes
+  before_validation :split_attributes   # you could also use :filter_attributes here
 
   # create a filtering method
   def split_attributes
     for_attributes_that(:should_be_splitted) do |value|
       names = value.split(' ')
-      self.first_name = names[0]  # assuming first_name exists in a database
-      self.last_name  = names[1]  # assuming last_name exists in a database
+      self.first_name = names[0]
+      self.last_name  = names[1]
     end
   end
+  filtering_method :split_attributes, :should_be_splitted
 
-end
-```
-
-Be aware that the virtual attributes declared that way will always be filtered
-since there is no way to know whether they have changed or not.
-That may lead to strange results under some circumstances, e.g. in case of
-cutting some part of a string stored in a virtual attribute by using a filter
-registered with `before_save`; if such operation will be performed
-more than once then the filtering will be performed more than once too.
-
-The presence of virtual attributes is tested by checking if both, a setter and a getter,
-methods exist, unless the `no_presence_check` flag is passed to a filtering method.
-If both accessors don't exist then the attribute is not processed.
+  # own setter
+  def real_name=(val)
+    # do somehing specific here (or not)
+    @real_name = val
+  end
 
-This approach can be easily used with predefined filters.
+  # own getter
+  def real_name
+    # do somehing specific here (or not)
+    @real_name
+  end
 
-#### Marking as trackable ####
+  attr_virtual :real_name
 
-Since version 1.4.0 of Attribute Filters the **recommended way of dealing with
-virtual attributes** is to make use of changes tracking available in Active Model.
-To do that look at your ORM's documentation and see 
-[`ActiveModel::Dirty`](http://api.rubyonrails.org/classes/ActiveModel/Dirty.html)
-and a method `attribute_will_change` that it contains. Just call that method from within
-your setter and you're done.
+end
+```
 
-This approach can be easily used with predefined filters.
+#### Unconditional filtering ####
 
-Conditions:
+The next way to filter virtual attribute is to pass the `:no_presence_check` and `:process_all` flags
+to the filtering method. That causes filter to be executed for each attribute from a set without
+any conditions (no checking for presence of setter/getter method and no checking for changes).
 
-* Use `attr_accessible` or `attr_protected` to mark the attribute as known
-* Use your own setter for notifying that attribute value has changed or `attr_virtual`
+Be aware that by doing that you take full responsibility for attribute set names added to your set.
+If you put a name of nonexistent attribute then you may get ugly error later.
 
-The benefit of that approach is that a filter will never be called redundantly contrary
-to previous methods.
+With that approach you can filter virtual attributes that are inaccessible to controllers
+and don't show up when model is queried for known attributes. Using it may also cause some filters
+to be executed more often than needed, since the changes tracking is disabled (`process_all`).
 
 Example:
 
 ```ruby
-class User < ActiveRecord::Base
-
-  # declare a virtual attribute
-  attr_reader       :real_name
-  attr_accessible   :real_name
+class User
 
   # define a set
-  attributes_that :should_be_splitted => [ :real_name ]
+  has_attributes_that :should_be_splitted => [ :real_name ]
 
   # register a callback method
-  before_validation :split_attributes
-
-  # create writer that notifies Active Model about changes
-  def real_name=(val)
-    attribute_will_change!('real_name') if val != real_name
-    @real_name = val
-  end
+  before_validation :split_attributes   # you could also use :filter_attributes here
 
   # create a filtering method
   def split_attributes
-    for_attributes_that(:should_be_splitted) do |value|
+    for_attributes_that(:should_be_splitted, :no_presence_check, :process_all) do |value|
       names = value.split(' ')
       self.first_name = names[0]  # assuming first_name exists in a database
       self.last_name  = names[1]  # assuming last_name exists in a database
     end
   end
+  filtering_method :split_attributes, :should_be_splitted
 
 end
 ```
 
-You can also use built-in DSL keyword **`attr_virtual`** that will create setter and getter
-for you:
-
-```ruby
-class User < ActiveRecord::Base
-
-  # declare a virtual attribute
-  attr_virtual      :real_name
-  attr_accessible   :real_name
-
-  # define a set
-  attributes_that :should_be_splitted => [ :real_name ]
-
-  # register a callback method
-  before_validation :split_attributes
-
-  # create a filtering method
-  def split_attributes
-    for_attributes_that(:should_be_splitted) do |value|
-      names = value.split(' ')
-      self.first_name = names[0]
-      self.last_name  = names[1]
-    end
-  end
+#### Marking as semi-real ####
 
-end
-```
+There is also a way that bases on using `treats_attributes_as_real` (or simply `treats_as_real`) clause in your model
+(available from version 1.2.0 of Attribute Filters). That approach may be applied to attributes
+that aren't (may not or should not be) tracked for changes and aren't (may not or should not be) accessible
+(to a controller) nor marked as protected (if using Rails version <= 3).
 
-#### Marking as trackable and semi-real ####
+There are two main differences from the unconditional filtering. First is that marking attribute
+as real causes it to be added to the list of all known attributes that is returned by `all_attributes_set`
+(a.k.a `all_attributes`). The second is that nothing ugly will happen if there will be non-existent
+attributes in a set when filtering method kicks in. That's because the filtering method doesn't require
+`:no_presence_check` flag to pick up such attributes. Attributes that cannot be handled are simply ignored.
 
-That's a variant of the recommended way of dealing with virtual attributes. It may be useful
-if you don't want to (or cannot) add virtual attributes to access lists using `attr_accessible`
-or `attr_protected`.
+The `:process_all` flag is also not needed since all attributes marked as semi-real are by default
+not checked for changes.
 
 Example:
 
 ```ruby
-class User < ActiveRecord::Base
-
-  # declare a virtual attribute
-  attr_virtual    :real_name
+class User
 
   # mark the attribute as real
-  treat_as_real   :real_name
-
-  # tell the engine that all virtual attributes
-  # are tracked for changes and it should pick from changed
-  # not from all
-  virtual_attributes_are_tracked
+  treats_as_real :real_name
 
   # define a set
-  attributes_that :should_be_splitted => [ :real_name ]
+  has_attributes_that :should_be_splitted => [ :real_name ]
 
   # register a callback method
-  before_validation :split_attributes
+  before_validation :split_attributes   # you could also use :filter_attributes here
 
   # create a filtering method
   def split_attributes
     for_attributes_that(:should_be_splitted) do |value|
       names = value.split(' ')
-      self.first_name = names[0]
-      self.last_name  = names[1]
+      self.first_name = names[0]  # assuming first_name exists in a database
+      self.last_name  = names[1]  # assuming last_name exists in a database
     end
   end
+  filtering_method :split_attributes, :should_be_splitted
 
 end
 ```
 
+Instead of `treat_as_real` you may also use one of its aliases:
+
+  * `attribute_filters_semi_real`, `treat_attribute_as_real`,  `treat_attributes_as_real`,
+    `treats_attribute_as_real`, `treats_attributes_as_real`, `treats_as_real`,             
+
 Annotations
 -----------
 
@@ -1189,7 +1528,7 @@ Example:
     # Annotation key:   some_key
     # Annotation value: some value
 
-    attributes_that_are cool: { :email => { :some_key => "some value" } }
+    has_attributes_that_are cool: { :email => { :some_key => "some value" } }
   end
 ```
 
@@ -1198,7 +1537,7 @@ You can mix annotated attributes with unannotated; just put the last ones in fro
 
 ```ruby
   class User
-    attributes_that_are cool: [ :some_unannotated, { :email => { :some_key => "some value" } } ]
+    has_attributes_that_are cool: [ :some_unannotated, { :email => { :some_key => "some value" } } ]
   end
 ```
 
@@ -1206,7 +1545,7 @@ or
 
 ```ruby
   class User
-    attributes_that_are :cool => [ :some_unannotated, { :email => { :some_key => "some value" } } ]
+    has_attributes_that_are :cool => [ :some_unannotated, { :email => { :some_key => "some value" } } ]
   end
 ```
 
@@ -1220,15 +1559,23 @@ To create annotations for class-level sets use the [`annotate_attribute_set`](ht
 * **`annotate_attributes_for`**  
 * **`annotate_attributes_set`** 
 * **`annotate_properties_that`**   
-* **`annotate_attributes`**   
+* **`annotate_attributes`**
+* **`annotates_attributes_that_are`**
+* **`annotates_attributes_that`**
+* **`annotates_attributes_are`** 
+* **`annotates_attributes_for`**  
+* **`annotates_attributes_set`** 
+* **`annotates_properties_that`**   
+* **`annotates_attributes`**
+* **`attribute_set_annotate`**
 
 Example:
 
 ```ruby
   class User
-    attributes_that_are cool: [ :some_unannotated, :email, :username ]
-    annotate_attributes_that_are cool: [ :email, :some_key, "some value" ]
-    annotate_attributes_that_are :cool => { :username => { :some_key => "some value", :other_k => 'other v' } }
+    has_attributes_that_are cool: [ :some_unannotated, :email, :username ]
+    annotates_attributes_that_are cool: [ :email, :some_key, "some value" ]
+    annotates_attributes_that_are :cool => { :username => { :some_key => "some value", :other_k => 'other v' } }
   end
 ```
 
@@ -1262,48 +1609,52 @@ Be aware that using these method to delete annotations from class-level sets won
 That's because you'll always get a copy when querying these sets. However there are methods that
 will work in a model:
 
-* **`delete_annotations_from_set(set_name, attribute, *annotation_keys)`** - to delete annotation keys for the given attribute
-* **`delete_annotations_from_set(set_name, attribute)`** - to delete all annotation keys for the given attribute
-* **`delete_annotations_from_set(set_name => *attributes)`** - to delete all annotation keys for the given attribute
-* **`delete_annotations_from_set(set_name => { attribute => keys})`** - to delete specified annotation keys for the given attributes
+* **`delete_annotation_from_set(set_name, attribute, *annotation_keys)`** - to delete annotation keys for the given attribute
+* **`delete_annotation_from_set(set_name, attribute)`** - to delete all annotation keys for the given attribute
+* **`delete_annotation_from_set(set_name => *attributes)`** - to delete all annotation keys for the given attribute
+* **`delete_annotation_from_set(set_name => { attribute => keys})`** - to delete specified annotation keys for the given attributes
+
+Instead of `delete_annotation_from_set` you may use the aliases:
+
+  * `delete_annotations_from_set`, `delete_annotation_from_set`, `deletes_annotations_from_set`
 
 Example:
 
 ```ruby
   class User
-    attributes_that_are cool: [ :some_unannotated, :email ]
+    has_attributes_that_are cool: [ :some_unannotated, :email ]
 
     # That will work
-    delete_annotations_from_set cool: :email
-    delete_annotations_from_set cool: [ :email, :key_one ]
-    delete_annotation_from_set cool: { :email => [:key_one, :other_key], :name => :some_key }
+    deletes_annotations_from_set  cool: :email
+    deletes_annotations_from_set  cool: [ :email, :key_one ]
+    deletes_annotation_from_set   cool: { :email => [:key_one, :other_key], :name => :some_key }
 
     # That won't affect the global set called 'cool'
-    # since we have its copy here, not the original.
+    # since we have its copy, not the original.
     def some_method
       attributes_that_are(:cool).delete_annotation(:email)
     end
 
     # That won't affect the global set called 'cool'
-    # since we have its copy here, not the original.
+    # since the method returns its copy, not the original.
     attributes_that_are(:cool).delete_annotation(:email)
   end
 ```
 
 ### Updating annotations ###
 
-Calling `annotate` method again on a set or redefining set at a class-level allows to add annotations
-or modify their keys.
+Calling `annotate` method again on a set or redefining set at the class-level allows to add annotations
+or to modify their keys.
 
 Example:
 
 ```ruby
   class User
-    attributes_that_are :cool => { :email => { :some_key => "some value"  } }
-    attributes_that_are cool: { :email => { :other_key => "other_value"   } }
-    attributes_that_are cool: { :email => { :some_key  => "another_value" } }
-    annotate_attributes_that_are :cool, :email, :some_key => "x"
-    delete_annotation_from_set :cool => { :email => :other_key }
+    has_attributes_that_are :cool => { :email => { :some_key => "some value"  } }
+    has_attributes_that_are cool: { :email => { :other_key => "other_value"   } }
+    has_attributes_that_are cool: { :email => { :some_key  => "another_value" } }
+    annotates_attributes_that_are :cool, :email, :some_key => "x"
+    deletes_annotation_from_set :cool => { :email => :other_key }
   end
   
   # In the result there will be only one annotation key left;
@@ -1319,7 +1670,7 @@ a copy when querying these sets.
 
 ```ruby
   class User
-    attributes_that_are :cool => { :email => { :some_key => "some value"  } }
+    has_attributes_that_are :cool => { :email => { :some_key => "some value"  } }
     
     # Calling `some_method` won't work on 'cool' global set.
     def some_method
@@ -1339,8 +1690,8 @@ To check if a set has any annotations you can use one of the methods:
 
 To read annotations you can use :
 
-* **`annotation(attribute_name)`** - gets a hash of annotations or returns nil
-* **`annotation(attribute_name, *keys)`** - gets an array annotation values for the given keys (puts nils if key is missing) or returns nil
+* **`annotation(attribute_name)`** - gets a hash of annotations or returns `nil`
+* **`annotation(attribute_name, *keys)`** - gets an array annotation values for the given keys (puts `nil`s if key is missing) or returns `nil`
 
 Example:
 
@@ -1362,38 +1713,51 @@ Example:
   end
 ```
 
+To read **all annotations** use `annotations` method called on an attribute set. For instance:
+
+```ruby
+  User.first.attributes_that(:should_be_splitted).annotations
+  # => {"some_name"=>{:split_into=>[:first_part, :second_part]}}
+```
+
+As you can see it returns a hash with attribute names as keys and annotations as values.
+If some attribute from a set doesn't have any annotations then it's not included in the results.
+
 Predefined filters
 ------------------
 
-Predefined filters are ready-to-use methods
-for filtering attributes. You just have to call them
+Predefined filters are ready-to-use methods for filtering attributes. You just have to call them
 or register them as [callbacks](http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html).
 
 To use all predefined filters you have to manually
 include the [`ActiveModel::AttributeFilters::Common`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common)
 module. That will include **all available filtering methods** into your model.
 
+Predefined filters work by utilizing global attribute sets with predetermined names. For example,
+a common filter that downcases attributes will use the set called `:should_be_downcased`.
+
 Example:
 
 ```ruby
 class User < ActiveRecord::Base
   include ActiveModel::AttributeFilters::Common
 
-  the_attribute name:   [:should_be_downcased, :should_be_titleized ]
+  its_attribute name:   [:should_be_downcased, :should_be_titleized ]
 
   before_validation :downcase_attributes
   before_validation :titleize_attributes
 end
 ```
 
-If you don't want to include portions of code that you'll never use, you can include some filters selectively. To do that include just a submodule containing certain filtering method:
+If you don't want to include portions of code that you'll never use in your model classes, you may
+want to include some filters selectively. To do that just include a submodule containing needed filtering method:
 
 ```ruby
 class User < ActiveRecord::Base
   include ActiveModel::AttributeFilters::Common::Downcase
   include ActiveModel::AttributeFilters::Common::Titleize
 
-  the_attribute name:   [:should_be_downcased, :should_be_titleized ]
+  its_attribute name:   [:should_be_downcased, :should_be_titleized ]
 
   before_validation :downcase_attributes
   before_validation :titleize_attributes
@@ -1411,28 +1775,36 @@ For example, to squeeze attributes `name` and `email` you can write:
 ```ruby
 class User < ActiveRecord::Base
   include ActiveModel::AttributeFilters::Common::Squeeze
-  attributes_that should_be_sqeezed: [:email, :name]
+  has_attributes_that should_be_squeezed: [:email, :name]
   before_validation :squeeze_attributes
 end
 ```
 
+### Filtering keywords ###
+
 The filtering methods usually come with class-level DSL methods
-that are a simple wrappers calling `the_attribute`. So you can
-also write:
+that are helpful wrappers. They are simply calling `the_attribute`
+method to add some attributes to a proper set for you.
+
+So you can also write:
 
 ```ruby
 class User < ActiveRecord::Base
   include ActiveModel::AttributeFilters::Common::Squeeze
-  squeeze_attributes :email, :name
-  before_validation :squeeze_attributes
+  squeezes_attributes :email, :name
+  before_validation   :squeeze_attributes
 end
 ```
 
-### Calling all at once ###
+Some of these helpers are doing some extra work to make things syntactically easier
+than with using pure sets. Check the list if common filters for more information.
+
+### Calling all filters ###
 
 There is a special method called
-[`filter_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters.html#filter_attributes-instance_method) that can be registered as a callback. It will call all possible (known) filtering methods
-in a predetermined order.
+[`filter_attributes`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters.html#filter_attributes-instance_method) that can be registered as a callback. It will call all filtering methods which sets (that they're assigned to)
+are non-empty. In other words it will run specific filtering method for each global attribute set if the set exists
+and contains at least one element. The calling order is the same as the order of adding sets in your model class.
 
 Example:
 
@@ -1441,615 +1813,143 @@ class User < ActiveRecord::Base
   include ActiveModel::AttributeFilters::Common::Squeeze
   include ActiveModel::AttributeFilters::Common::Capitalize
 
-  squeeze_attributes :email, :name
-  capitalize_attributes :name
+  squeezes_attributes   :email, :name
+  capitalizes_attribute :name
 
   before_validation :filter_attributes
 end
 ```
 
-Use this method if you're really lazy.
-You can also create your own method like that and call all needed filters there:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Squeeze
-  include ActiveModel::AttributeFilters::Common::Capitalize
-
-  squeeze_attributes :email, :name
-  capitalize_attributes :name
-
-  before_validation :my_total_filtering_method
-
-  def my_total_filtering_method
-    squeeze_attributes
-    capitalize_attributes
-  end
-end
-```
-
-But to increase readability you should go with the old-fashion way and register
-each filtering callback method separately.
-
-### Data types ###
-
-The common filters are aware and can operate on attributes that
-are arrays or hashes. If an array or a hash is detected then
-the filtering is made **recursively** for each element (or for each value in case
-of a hash) and the produced structure is returned. If the attribute has an
-unknown type then its value is not altered at all and left intact.
-
-Some of the common filters may treat arrays and hashes in a slight different
-way (e.g. joining and splitting filters do that).
-
-The common filters are aware of multibyte strings so string
-operations should handle diacritics properly.
-
-### List of filters ###
-
-* **`capitalize_attributes`**
-* **`fully_capitalize_attributes`**
-* **`titleize_attributes`**
-* **`downcase_attributes`**
-* **`upcase_attributes`**
-* **`strip_attributes`**
-* **`squeeze_attributes`**
-* **`squish_attributes`**
-
-See the
-[`ActiveModel::AttributeFilters::Common`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common)
-for detailed descriptions.
-
-#### Case ####
-
-* Submodule: [`Case`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common/Case.html)
-
-##### `capitalize_attributes` #####
-
-Capitalizes attributes.
-
-* Callback method: `capitalize_attributes`
-* Class-level helper: `capitalize_attributes(*attribute_names)`
-* Uses set: `:should_be_capitalized`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
-
-Example:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  capitalize_attributes   :name
-  before_validation       :capitalize_attributes
-end
-```
-
-or
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  attributes_that     :should_be_capitalized => [ :name ]
-  before_validation   :capitalize_attributes
-end
-```
-
-Then:
-
-> `"some name"`
-
-will become:
-
-> `"Some name"`
-
-##### `fully_capitalize_attributes` #####
-
-Capitalizes attributes and squeezes spaces that separate strings.
-
-* Callback method: `fully_capitalize_attributes`
-* Class-level helper: `fully_capitalize_attributes(*attribute_names)`
-* Uses set: `:should_be_fully_capitalized` and `:should_be_titleized`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
-
-Example:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  fully_capitalize_attributes   :name
-  before_validation             :fully_capitalize_attributes
-end
-```
-
-or
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  attributes_that     :should_be_fully_capitalized => [ :name ]
-  before_validation   :fully_capitalize_attributes
-end
-```
-
-Then:
-
-> `"some      name"`
-
-will become:
-
-> `"Some Name"`
-
-##### `titleize_attributes` #####
-
-Titleizes attributes.
-
-* Callback method: `titleize_attributes`
-* Class-level helper: `titleize_attributes(*attribute_names)`
-* Uses set: `:should_be_titleized`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
-
-Example:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  titleize_attributes   :name
-  before_validation     :titleize_attributes
-end
-```
-
-or
+Or even more simpler (but it will include all common filters):
 
 ```ruby
 class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  attributes_that     :should_be_titleized => [ :name ]
-  before_validation   :titleize_attributes
-end
-```
-
-Then:
-
-> `"some name"`
-
-will become:
-
-> `"Some Name"`
-
-##### `upcase_attributes` #####
-
-Upcases attributes.
-
-* Callback method: `upcase_attributes`
-* Class-level helper: `upcase_attributes(*attribute_names)`
-* Uses set: `:should_be_upcased`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
-
-Example:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  upcase_attributes   :name
-  before_validation   :upcase_attributes
-end
-```
-
-or
+  include ActiveModel::AttributeFilters::Common
 
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
+  squeezes_attributes    :email, :name
+  capitalizes_attribute :name
 
-  attributes_that     :should_be_upcased => [ :name ]
-  before_validation   :upcase_attributes
+  before_validation :filter_attributes
 end
 ```
 
-Then:
-
-> `"some name"`
-
-will become:
-
-> `"SOME NAME"`
-
-##### `downcase_attributes` #####
-
-Downcases attributes.
+The method of using common filters presented in he example above
+is the easiest and the most consistent one.
 
-* Callback method: `downcase_attributes`
-* Class-level helper: `downcase_attributes(*attribute_names)`
-* Uses set: `:should_be_downcased`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
-
-Example:
+Of course the `filter_attributes` will also work if the sets are
+specified explicitly:
 
 ```ruby
 class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
-
-  downcase_attributes :name
-  before_validation   :downcase_attributes
-end
-```
-
-or
+  include ActiveModel::AttributeFilters::Common
 
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Case
+  has_attributes_that :should_be_squeezed     =>  [ :email, :name ]
+  has_attributes_that :should_be_capitalized  => :name
 
-  attributes_that     :should_be_downcased => [ :name ]
-  before_validation   :downcase_attributes
+  before_validation :filter_attributes
 end
 ```
 
-Then:
-
-> `"SOME NAME"`
-
-will become:
-
-> `"some name"`
-
-#### Strip ####
-
-* Submodule: [`Strip`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common/Strip.html)
-
-##### `strip_attributes` #####
+To know which methods are known to `filter_attributes`
+use the `filtering_methods` instance method
+available in your model. It returns a meta set containing
+attributes set names as keys and the methods assigned
+to them as values (both are symbols).
 
-Strips attributes of leading and trailing spaces.
-
-* Callback method: `strip_attributes`
-* Class-level helper: `strip_attributes(*attribute_names)`
-* Uses set: `:should_be_stripped`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
-
-Example:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Strip
-
-  strip_attributes    :name
-  before_validation   :strip_attributes
-end
-```
-
-or
+Note that the method above returns **all** known
+methods marked as filtering methods, including those
+that might not be called until a proper set will
+be defined. To check what methods will actually be
+called (at a given time) use:
 
 ```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Strip
-
-  attributes_that     :should_be_stripped => [ :name ]
-  before_validation   :strip_attributes
-end
+  (attribute_sets & filtering_methods).values
 ```
 
-Then:
-
-> `"    Some Name    "`
-
-will become:
-
-> `"Some Name"`
+### Custom filtering order ###
 
-#### Squeeze ####
-
-* Submodule: [`Squeeze`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common/Squeeze.html)
-
-##### `squeeze_attributes` #####
-
-Squeezes attributes (squeezes repeating spaces into one).
-
-* Callback method: `squeeze_attributes`
-* Class-level helper: `squeeze_attributes(*attribute_names)`
-* Uses set: `:should_be_squeezed`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
-
-Example:
+Instead of relaying on `filter_attributes` you may create
+your own callback method containing invocations of your
+filtering methods in the desired order (independent from
+the "natural" order, based on adding the sets to model class):
 
 ```ruby
 class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Squeeze
+  include ActiveModel::AttributeFilters::Common
 
-  squeeze_attributes  :name
-  before_validation   :squeeze_attributes
-end
-```
+  has_attributes_that :should_be_squeezed     =>  [ :email, :name ]
+  has_attribute_that  :should_be_capitalized  => :name
 
-or
+  before_validation :prepare_attributes
 
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Squeeze
-
-  attributes_that     :should_be_squeezed => [ :name ]
-  before_validation   :squeeze_attributes
+  def prepare_attributes
+    capitalize_attributes   # common filter that uses the set called :should_be_capitalized
+    squeeze_attributes      # common filter that uses the set called :should_be_squeezed
+  end
 end
 ```
 
-Then:
-
-> `"Some    Name"`
+Or you can just register multiple callbacks to achieve the same
+result.
 
-will become:
+### Custom filtering methods ###
 
-> `"Some Name"`
+You can create your own filtering methods and they will be called
+among others by `filter_attributes`. You just have to use special
+DSL class method called `filtering_method` to mark your method
+and assign its name to some global attribute set (not used by
+any other filtering method).
 
-##### `squish_attributes` #####
+Synopsis:
 
-Squishes attributes (removes all whitespace characters on both ends of the string, and then changes remaining consecutive whitespace groups into one space each).
+  * `filtering_method(method_name, set_name)`
 
-* Callback method: `squish_attributes`
-* Class-level helper: `squish_attributes(*attribute_names)`
-* Uses set: `:should_be_squished`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: no
+The global set of the given name will be looked up when callback
+method `filter_attributes` will be called and if non-empty then
+the registered method will be called (among others).
 
 Example:
 
 ```ruby
 class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Squeeze
-
-  squish_attributes   :name
-  before_validation   :squish_attributes
-end
-```
-
-or
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Squeeze
-
-  attributes_that     :should_be_squished => [ :name ]
-  before_validation   :squish_attributes
-end
-```
-
-Then:
-
-> `"    Some    Name"`
-
-will become:
-
-> `"Some Name"`
-
-#### Split ####
-
-* Submodule: [`Split`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common/Split.html)
-
-##### `split_attributes` #####
-
-Splits attributes into arrays and puts the results into other attributes or into the same attributes.
-
-* Callback methods: `split_attributes`
-* Class-level helpers:
- * `split_attributes(attribute_name, parameters_hash)`
- * `split_attributes(attribute_name)`
-* Uses set: `:should_be_splitted`
-* Operates on: strings, arrays of strings, hashes of strings (as values)
-* Uses annotations: yes
- * `split_pattern` - a pattern passed to [`split`](http://www.ruby-doc.org/core/String.html#method-i-split) method (optional)
- * `split_limit` - a limit passed to `split` method (optional)
- * `split_into` - attribute names used as destinations for parts
- * `split_flatten` - flag that causes resulting array to be flattened
- 
-If some source attribute is an array or a hash then the filter will recursively traverse it and
-operate on each element. The filter works the same way as the `split` method from the `String` class
-of Ruby's standard library. If the filter encounters an object which is not a string nor an array or a hash,
-it simply leaves it as is.
-
-You can set `:pattern` (`:split_pattern`) and `:limit` (`:split_limit`) arguments passed to
-`split` method but note that **a limit is applied to each processed string separately**,
-not to the resulting array **(if the processed attribute is an array)**. For instance,
-if there is a string containing 3 words (`'A B C'`) and the limit is set to 2 then the last two words
-will be left intact and placed in a second element of the resulting array (`['A', 'B C']`).
-If the source is an array (`['A', 'B B B B', 'C']`) the result of this operation will be array of arrays
-(`[ ['A'], ['B B'], ['C'] ]`); as you can see the limit will be applied to its second element.
-
-If there are no destination attributes defined (`:into` or `:split_into` option) then
-the resulting array will be written to a current attribute. If there are destination attributes
-given then the resulting array will be written into them (each subsequent element into each next attribute).
-The elements that don't fit in the collection are simply ignored.
-
-There is also `flatten` (or `:split_flatten`) parameter that causes the resulting array to be
-flattened. Note that it doesn't change how the limits work; they still will be applied but to a single
-split results, not to the whole resulting array (in case of array of arrays).
-
-Examples:
-
-```ruby
-class User < ActiveRecord::Base
-  # Including common filter for splitting
-  include ActiveModel::AttributeFilters::Common::Split
-
-  # Registering virtual attribute
-  attr_virtual      :real_name
-  attr_accessible   :real_name
-
-  # Adding attribute name to :should_be_splitted set
-  split_attributes  :real_name
-
-  # Registering callback method
-  # Warning: it will be executed each time model object is validated
-  #          (the nice thing is that it allows to validate the results, not the unsplitted data)
-  before_validation :split_attributes
-end
-```
-
-or without a `split_attributes` helper:
-
-```ruby
-class User < ActiveRecord::Base
-  # Including common filter for splitting
-  include ActiveModel::AttributeFilters::Common::Split
-
-  # Registering virtual attribute
-  attr_virtual      :real_name
-  attr_accessible   :real_name
-
-  # Adding attribute name to :should_be_splitted set (by hand)
-  attributes_that   :should_be_splitted => :real_name
-
-  # Registering callback method
-  before_validation :split_attributes
-end
-```
-
-The result of executing the filter above will be replacement of a string by an array containing
-words (each one in a separate element). The `real_name` attribute is a virtual attribute in this example
-but it could be real attribute. The result will be written as an array into the same attribute since there
-are no destination attributes given. So `'Paul Wolf'` will become `['Paul', 'Wolf']`.
-
-Using limit:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Split
-
-  attr_virtual      :real_name
-  attr_accessible   :real_name
-  split_attributes  :real_name, :limit => 2
-  before_validation :split_attributes
-end
-```
-
-or without a `split_attributes` keyword:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Split
-
-  attr_virtual      :real_name
-  attr_accessible   :real_name
-
-  attributes_that   :should_be_splitted => { :real_name => { :split_limit => 2 } }
-  before_validation :split_attributes
-end
-```
-
-The result of the above example will be the same as the previous one with the difference that any
-reduntant elements will be left intact and placed as the last element of an array. So for data:
-
-> `'Paul Thomas Wolf'`
-
-the array will be:
-
-> `[ 'Paul', 'Thomas Wolf' ]`
-
-Another example, let's write results to some attributes:
+  include ActiveModel::AttributeFilters::Common
 
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Split
+  has_attributes_that should_be_happy: [ :username, :real_name ]
+  before_validation :filter_attributes
 
-  attr_virtual      :real_name
-  attr_accessible   :real_name
-  split_attributes  :real_name, :limit => 2, :into => [ :first_name, :last_name ], :pattern => ' '
-  before_validation :split_attributes
+  def happify
+    filter_attributes_that(:should_be_happy) do |v, o|
+      v + "-happy"
+    end
+  end
+  filtering_method :happify, :should_be_happy
 end
 ```
 
-(The `:pattern` is given here but you may skip it if it's a space.)
-
-This will split a value of the `real_name` attribute and place the results in the attributes
-called `first_name` and `last_name`, so for:
-
-> `'Paul Thomas Wolf'`
-
-the result will be:
-
-```
-  first_name: 'Paul'
-  last_name:  'Thomas Wolf'
-```
-
-If you remove the limit, then it will be quite different:
-
-```
-  first_name: 'Paul'
-  last_name:  'Thomas'
-```
-
-That's because there are more results than attributes they fit into. You just have to keep in mind
-that this filter behaves like the String's split method with the difference when the results are written
-into other attributes. In that case the limit causes redundant data to be placed in the last element (if a limit
-is lower or is the same as the count of destination attributes) and its lack causes some of the resulting data to
-be ignored (if there are more slices than receiving attributes).
-
-The pattern parameter (`:pattern` when using `split_attributes` or `:split_pattern` when directly
-annotating attribute in a set) should be a string.
-
-#### Join ####
-
-* Submodule: [`Join`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common/Join.html)
-
-##### `join_attributes` #####
-
-Joins attributes and places the results into other attributes or into the same attributes as strings.
+Of course, you can set your own method as a callback explicitly
+instead of using the `filter_attributes`.
 
-* Callback method: `join_attributes`
-* Class-level helpers:
- * `join_attributes(attribute_name, parameters_hash)` (a.k.a `joint_attribute`)
- * `join_attributes(attribute_name)` (a.k.a `joint_attribute`)
-* Uses set: `:should_be_joined`
-* Operates on: strings, arrays of strings
-* Uses annotations: yes
- * `join_separator` - a pattern passed to [`join`](http://www.ruby-doc.org/core/Array.html#method-i-join) method (optional)
- * `join_compact` - compact flag; if true then an array is compacted before it's joined (optional)
- * `join_from` - attribute names used as sources for joins
-
-The join filter uses `join` instance method of the `Array` class to produce single string from multiple strings.
-These strings may be values of other attributes (source attributes), values of an array stored in an attribute
-or mix of it. If the `:compact` (`:join_compact` in case of manually annotating a set) parameter is given
-and it's not `false` nor `nil` then results are compacted during processing. That means any slices equals to `nil` are 
-removed.
-
-If the parameter `:from` (or annotation key `:join_from`) was not given then a currently processed attribute
-is treated as a source (it should be an array).
-
-Examples:
+### Data types ###
 
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Join
+The common filters are aware of different kinds of data and can operate
+on attributes that are arrays or hashes. If an array or a hash is detected then
+the filtering is made **recursively** for each element (or for each value in case
+of a hash) and the produced value is returned. If the attribute has an
+unknown type then its value is not altered at all and left intact.
 
-  attr_virtual            :first_name, :last_name
-  attr_accessible         :first_name, :last_name
-  join_attributes_into    :real_name, :from => [ :first_name, :last_name ]
-  before_validation       :join_attributes
-end
-```
+Some of the common filters may treat arrays and hashes in a slight different
+way (e.g. joining and splitting filters do that).
 
-you can also switch source with destination:
+The common filters are aware of multibyte strings so string
+operations should handle diacritics properly.
 
-```ruby
-  join_attributes         [ :first_name, :last_name ] => :real_name
-```
+### List of filters ###
 
-or add a descriptive keyword `:into`:
+See the [COMMON-FILTERS](http://rubydoc.info/gems/attribute-filters/file/docs/COMMON-FILTERS.md) for detailed descriptions and usage examples.
 
-```ruby
-  join_attributes         [ :first_name, :last_name ], :into => :real_name
-```
+See the
+[`ActiveModel::AttributeFilters::Common`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common)
+for descriptions of common filtering modules.
 
 Custom applications
 -------------------
@@ -2064,16 +1964,16 @@ Example:
 ```ruby
 class User < ActiveRecord::Base
 
-  attributes_that_are required_to_trade: [ :username, :email, :real_name, :address, :account ]
+  has_attributes_that_are required_to_trade: [ :username, :email, :real_name, :address, :account ]
 
   def is_able_to_trade?
-    are_attributes_that_are(:required_to_trade).all.present? and
-    are_attributes_that_are(:required_to_trade).all.valid?
+    are_attributes_that_are.required_to_trade.all.present? and
+    are_attributes_that_are.required_to_trade.all.valid?
   end
 
   def attributes_missing_to_trade
-    attributes_that_are(:required_to_trade).list.blank? +
-    attributes_that_are(:required_to_trade).list.invalid?
+    attributes_that_are.required_to_trade.list.blank? +
+    attributes_that_are.required_to_trade.list.invalid?
   end
 end
 ```