attribute-filters 1.3.2 → 1.4.0

data/Manifest.txt

@@ -20,10 +20,18 @@ init.rb
 lib/attribute-filters.rb
 lib/attribute-filters/active_model_insert.rb
 lib/attribute-filters/attribute_set.rb
+lib/attribute-filters/attribute_set_annotations.rb
 lib/attribute-filters/attribute_set_attrquery.rb
 lib/attribute-filters/attribute_set_enum.rb
 lib/attribute-filters/attribute_set_query.rb
+lib/attribute-filters/backports.rb
 lib/attribute-filters/common_filters.rb
+lib/attribute-filters/common_filters/case.rb
+lib/attribute-filters/common_filters/join.rb
+lib/attribute-filters/common_filters/split.rb
+lib/attribute-filters/common_filters/squeeze.rb
+lib/attribute-filters/common_filters/strip.rb
+lib/attribute-filters/dsl_attr_virtual.rb
 lib/attribute-filters/dsl_filters.rb
 lib/attribute-filters/dsl_sets.rb
 lib/attribute-filters/helpers.rb

data/README.md

@@ -1,7 +1,7 @@
 Attribute Filters for Rails
 ===========================
 
-**attribute-filters version `1.3`** (**`Reliable Sausage`**)
+**attribute-filters version `1.4`** (**`Fried Meerkat`**)
 
 * https://rubygems.org/gems/attribute-filters
 * https://github.com/siefca/attribute-filters/tree
@@ -23,12 +23,13 @@ You may want to try it when your Rails application often modifies
 attribute values that changed recently and uses callbacks to do that.
 
 When the number of attributes that are altered in such a way increases,
-you can observe the same thing happening with your filtering
+you can observe that the same thing is happening with your filtering
 methods. That's because each one is tied to some attribute.
 
 To refine that process you may write more generic methods
 for altering attributes. They should be designed to handle
 common operations and not be tied to certain attributes.
+Attribute Filters helps you do that.
 
 Let's see that in action.
 
@@ -68,6 +69,37 @@ The filtering code is not reusable since it operates on specific attributes.
 
 ### After ###
 
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common
+
+  strip_attributes    :username, :email, :real_name
+  downcase_attributes :username, :email
+  titleize_attribute  :real_name
+
+  before_validation :filter_attributes
+end
+```
+
+or if you want to have more control:
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Strip
+  include ActiveModel::AttributeFilters::Common::Downcase
+  include ActiveModel::AttributeFilters::Common::Titleize  
+
+  attributes_that should_be_stripped:   [ :username, :email, :real_name ]
+  attributes_that should_be_downcased:  [ :username, :email ]
+  attributes_that should_be_titleized:  [ :real_name ]
+
+  before_validation :strip_attributes
+  before_validation :downcase_attributes
+  before_validation :titleize_attributes
+end
+```
+
+or if you would like to create filtering methods on your own:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -97,26 +129,18 @@ class User < ActiveRecord::Base
 end
 ```
 
-or even shorter:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Strip
-  include ActiveModel::AttributeFilters::Common::Downcase
-  include ActiveModel::AttributeFilters::Common::Titleize  
-
-  attributes_that should_be_stripped:   [ :username, :email, :real_name ]
-  attributes_that should_be_downcased:  [ :username, :email ]
-  attributes_that should_be_titleized:  [ :real_name ]
+Attributes that should be altered may be simply added
+to the attribute sets that you define and then filtered
+with generic methods that operate on that sets. You can share
+these methods across all of your models by putting them into your own
+handy module that will be included in models that needs it.
 
-  before_validation :strip_attributes
-  before_validation :downcase_attributes
-  before_validation :titleize_attributes
-end
-```
+Alternatively (as presented at the beginning) you can use predefined filtering methods from `ActiveModel::AttributeFilters::Common` module and its submodules. They contain filters
+for changing the case, stripping, squishng, squeezing, joining, splitting
+[and more](http://rubydoc.info/gems/attribute-filters/file/docs/USAGE.md#Predefined_filters).
 
-If you would rather like to group filters by attribute names then
-the alternative syntax may be helpful:
+If you would rather like to group filters by attribute names while
+registering them then the alternative syntax may be helpful:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -126,20 +150,10 @@ class User < ActiveRecord::Base
 end
 ```
 
-Attributes that should be altered may be simply added
-to the attribute sets that you define and then filtered
-with generic methods. You can use these methods in all
-your models if you wish.
-
-The last action can be performed by putting the filtering methods into
-some base class that all your models inherit form or (better) into your own
-handy module that is included in all your models. Alternatively you can
-use predefined filters from `ActiveModel::AttributeFilters::Common` module.
-
 Usage and more examples
 -----------------------
 
-You can use it to filter attributes (as presented above) but you can also
+You can use Attribute Filters to filter attributes (as presented above) but you can also
 use it to express some logic
 [on your own](http://rubydoc.info/gems/attribute-filters/file/docs/USAGE.md#Custom_applications).
 

data/attribute-filters.gemspec

@@ -2,16 +2,16 @@
 
 Gem::Specification.new do |s|
   s.name = "attribute-filters"
-  s.version = "1.3.2.20120805175249"
+  s.version = "1.4.0.20120824020319"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Pawe\u{142} Wilk"]
   s.cert_chain = ["/Users/siefca/.gem/gem-public_cert.pem"]
-  s.date = "2012-08-05"
+  s.date = "2012-08-24"
   s.description = "Concise way of filtering model attributes in Rails."
   s.email = ["pw@gnu.org"]
   s.extra_rdoc_files = ["Manifest.txt"]
-  s.files = [".rspec", ".yardopts", "ChangeLog", "Gemfile", "Gemfile.lock", "LGPL-LICENSE", "Manifest.txt", "README.md", "Rakefile", "attribute-filters.gemspec", "docs/COPYING", "docs/HISTORY", "docs/LEGAL", "docs/LGPL-LICENSE", "docs/TODO", "docs/USAGE.md", "docs/rdoc.css", "docs/yard-tpl/default/fulldoc/html/css/common.css", "init.rb", "lib/attribute-filters.rb", "lib/attribute-filters/active_model_insert.rb", "lib/attribute-filters/attribute_set.rb", "lib/attribute-filters/attribute_set_attrquery.rb", "lib/attribute-filters/attribute_set_enum.rb", "lib/attribute-filters/attribute_set_query.rb", "lib/attribute-filters/common_filters.rb", "lib/attribute-filters/dsl_filters.rb", "lib/attribute-filters/dsl_sets.rb", "lib/attribute-filters/helpers.rb", "lib/attribute-filters/railtie.rb", "lib/attribute-filters/version.rb", "spec/attribute-filters_spec.rb", "spec/spec_helper.rb", ".gemtest"]
+  s.files = [".rspec", ".yardopts", "ChangeLog", "Gemfile", "Gemfile.lock", "LGPL-LICENSE", "Manifest.txt", "README.md", "Rakefile", "attribute-filters.gemspec", "docs/COPYING", "docs/HISTORY", "docs/LEGAL", "docs/LGPL-LICENSE", "docs/TODO", "docs/USAGE.md", "docs/rdoc.css", "docs/yard-tpl/default/fulldoc/html/css/common.css", "init.rb", "lib/attribute-filters.rb", "lib/attribute-filters/active_model_insert.rb", "lib/attribute-filters/attribute_set.rb", "lib/attribute-filters/attribute_set_annotations.rb", "lib/attribute-filters/attribute_set_attrquery.rb", "lib/attribute-filters/attribute_set_enum.rb", "lib/attribute-filters/attribute_set_query.rb", "lib/attribute-filters/backports.rb", "lib/attribute-filters/common_filters.rb", "lib/attribute-filters/common_filters/case.rb", "lib/attribute-filters/common_filters/join.rb", "lib/attribute-filters/common_filters/split.rb", "lib/attribute-filters/common_filters/squeeze.rb", "lib/attribute-filters/common_filters/strip.rb", "lib/attribute-filters/dsl_attr_virtual.rb", "lib/attribute-filters/dsl_filters.rb", "lib/attribute-filters/dsl_sets.rb", "lib/attribute-filters/helpers.rb", "lib/attribute-filters/railtie.rb", "lib/attribute-filters/version.rb", "spec/attribute-filters_spec.rb", "spec/spec_helper.rb", ".gemtest"]
   s.homepage = "https://rubygems.org/gems/attribute-filters/"
   s.rdoc_options = ["--title", "Attribute::Filters Documentation", "--quiet"]
   s.require_paths = ["lib"]

data/docs/HISTORY

@@ -1,3 +1,44 @@
+=== 1.4.0 / 2012-08-24
+
+* major enhancements
+
+  * Added annotations support
+  * Added Split and Join common filters
+  * Improved virtual attributes handling (added attr_virtual keyword)
+  * All common filters can now handle arrays and hashes
+  * API change: additional yeld params changed for DSL instance methods:
+    * `for_each_attr_from_set`
+    * `filter_attrs_from_set`
+    * `operate_on_attrs_from_set`
+  * API change: class methods return copies of sets, not originals
+
+* minor enhancements
+
+  * Added `values` and `values_hash` methods to `AttributeSet::Query` for reading values
+  * Added `value` method to `AttributeSet::AttrQuery` for reading value
+  * Added `each` iterator to custom enumerators
+  * Added `attribute_set_simple` instance DSL method for bypassing proxies
+  * Added `filter_attributes` instance DSL method for running all predefined filters
+  * Added calls forwarding in proxy classes for `instance_eval` and `instance_exec` methods
+  * `AttributeSetEnumerable` is now `AttributeSet::Enumerable`
+  * `AttirbuteSetEnumerator` is now `AttributeSet::Enumerator`
+  * Modified filtering methods so they return specialized enumerator when called whithout a block
+    * `for_each_attr_from_set`
+    * `filter_attrs_from_set`
+
+* major bugfixes
+
+  * In `AttributeSet::Query`: separated instance level data from class level by adding `dup` where needed
+  * In `AttributeSet`: separated instance level data from class level by adding `dup` where needed
+
+* minor bugfixes
+
+  * In `AttributeFilters::Common`: `Squish` submodule included in `Common` module
+  * In `AttributeSet::Query`: replaced calls to `send` by calls to `public_send`
+  * In `AttributeSet::Query`: replaced calls to `method` by calls to `public_method`
+  * In `AttributeSet::AttrQuery`: replaced call to `method` by call to `public_method`
+  * In `AttributeFilters::operate_on_attrs_from_set`: replaced calls to `send` by calls to `public_send`
+
 === 1.3.2 / 2012-08-05
 
 * minor bugfixes
@@ -8,8 +49,8 @@
 
 * major enhancements
 
-  * Added accessible?, inaccessible?, protected? attribute checks
-  * Added all_accessible_attributes, all_protected_attributes, all_inaccessible_attributes
+  * Added `accessible?`, `inaccessible?`, `protected?` attribute checks
+  * Added `all_accessible_attributes`, `all_protected_attributes`, `all_inaccessible_attributes`
 
 * minor enhancements
 
@@ -19,17 +60,12 @@
 
 * major bugfixes
 
-  * In AttributeSet::Query proxy class: proxy now uses send() to get attribute values
+  * In `AttributeSet::Query`: proxy now uses `send` to get attribute values
 
 * major enhancements
 
-  * Added valid? and invalid? DSL instance methods
-  * Added all_attributes instance method
-
-* minor enhancements
-
-  * Added is_a?() overrides in proxy classes
-  * Method attributes_to_filter now also takes attribute set as an argument
+  * Added `valid?` and `invalid?` DSL instance methods
+  * Added `all_attributes` instance method
 
 === 1.2.2 / 2012-08-03
 
@@ -39,8 +75,8 @@
 
 * minor enhancements
 
-  * Added is_a?() overrides in proxy classes
-  * Method attributes_to_filter now also takes attribute set as an argument
+  * Added `is_a?` overrides to proxy classes
+  * Method `attributes_to_filter` can now take attribute set as an argument
 
 === 1.2.1 / 2012-07-09
 
@@ -52,43 +88,43 @@
 
 * major bugfixes
 
-  * In AttributeSet::Query proxy class: removed typo that caused incorrect processing
+  * In `AttributeSet::Query`: removed typo that caused incorrect processing
 
 * minor bugfixes
 
-  * Added missing respond_to? definitions to proxy classes
+  * Added missing `respond_to?` definitions to proxy classes
 
 * major enhancements
 
-  * Added enumerators (AttributeSetEnumerable and AttributeSetEnumerator)
+  * Added enumerators (`AttributeSetEnumerable` and `AttributeSetEnumerator`)
   * Added predefined filtering methods
   * Added virtual attributes support in filters
   * Written the usage instructions
 
 * minor enhancements
 
-  * Removed the show DSL method from AttrQuery proxy class
+  * Removed the show DSL method from `AttrQuery` proxy class
   * Added checking of model methods that are needed for a proper operation
-  * Proxy class Query is now viral and tries to wrap the results in its own instances
-  * Added 'none' and 'one' presence selectors to AttributeSet::Query class
-  * Added from_attributes_that as the alias for attribute_set instance method
+  * Proxy class `AttributeSet::Query` is now viral and tries to wrap the results in its own instances
+  * Added `none` and `one` presence selectors to `AttributeSet::Query` class
+  * Added `from_attributes_that` as an alias for the `attribute_set` instance method
 
 === 1.1.2 / 2012-06-30
 
 * major bugfixes
 
-  * In operate_on_attrs_from_set: replaced self[attr] and method(attr) calls with send (to be ORM agnostic)
-  * In attributes_to_filter: inefficient respond_to? calls replaced by the attributes method call
+  * In `operate_on_attrs_from_set`: replaced `self[attr]` and `method(attr)` calls with `send` (to be ORM agnostic)
+  * In `attributes_to_filter`: inefficient `respond_to?` calls replaced by the attributes method call
 
 * major enhancements
 
-  * AttributeFilters module can be now used without full Rails stack, just with Active Model loaded
+  * `AttributeFilters` module can be now used without full Rails stack, just with Active Model loaded
 
 * minor enhancements
 
   * Documentation updated
-  * Added attribute-filters/helpers.rb containing AttributeFiltersHelpers module
-  * Flags parsing method attr_filter_process_flags moved to AttributeFiltersHelpers as process_flags
+  * Added `attribute-filters/helpers.rb` containing `AttributeFiltersHelpers` module
+  * Flags parsing method `attr_filter_process_flags` moved to `AttributeFiltersHelpers` as `process_flags`
   * Added SuperModel and ActiveRecord dependencies for testing purposes
   * Added first RSpec example
 
@@ -96,12 +132,12 @@
 
 * major enhancement
 
-  * API changed; call_attrs_from_set name changed to for_each_attr_from_set, caching removed
+  * API changed; `call_attrs_from_set` name changed to `for_each_attr_from_set`, caching removed
 
 * minor enhancements
 
   * Optimized code for attributes filtering
-  * Namespace organized (AttributeFilters completely moved under ActiveModel)
+  * Namespace organized (`AttributeFilters` moved completely under `ActiveModel` namespace)
   * Prepared for testing with RSpec
   * Added custom CSS file for YARD formatter
 
@@ -110,7 +146,7 @@
 * minor enhancements
 
   * Documentation updated
-  * Extended arguments parsing for DSL class method attribute_set
+  * Extended arguments parsing for DSL class method `attribute_set`
 
 === 1.0.1 / 2012-06-28
 

data/docs/TODO

@@ -1,5 +1,20 @@
-* add more rspec examples
+* add more rspec examples (+ nil and boolean attributes)
 
-* document changed behaviour of attribute_set instance method
+* add parameter support to squeeze common filter
 
+* 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
+  -- sanitize_url
+  -- sanitize_string
+  -- sanitize_name
+  -- sanitize_country
+  -- sanitize_iban (future, in a gem attribute-filters-common-iban)

data/docs/USAGE.md

@@ -16,10 +16,14 @@ on all attributes that are listed in a set.
 
 Attribute sets are instances of
 [`ActiveModel::AttributeSet`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeSet)
-class. They are stored within your model as [class instance variables](http://blog.codegram.com/2011/4/understanding-class-instance-variables-in-ruby).
-You cannot and should not interact with them directly
+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.
+
+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.
-These methods will allow you to read or write some data from/to attribute sets.
+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
@@ -33,15 +37,26 @@ Note that when sets are returned the convention is that:
   * **attribute names are strings**
   * **set names 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**.
+
 ### Defining the 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.
+ 
 #### `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**.
+(a.k.a `attributes_that`) class method allows to **create or update a set** that will be
+tied to a model.
 
 Example:
 
@@ -106,15 +121,15 @@ end
 
 ### Querying sets in models ###
 
-When your attribute sets are defined then you can use couple
-of class methods to query them, e.g. to check their contents.
+When your "global" attribute sets are defined, you can use couple
+of class methods to query them.
 
 #### `attribute_set(set_name)` ####
 
 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 an `AttributeSet` instance, even if there is not set of 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).
 
 Example:
 
@@ -123,6 +138,8 @@ Example:
   # => #<ActiveModel::AttributeSet: {"real_name"}>
 ```
 
+Note that the returned set will be a copy of the original set stored within your model.
+
 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`,   
@@ -152,6 +169,8 @@ Instead of `attribute_sets` you may also use one of the aliases:
 
   * `attributes_sets`, `properties_sets`
 
+Note that the returned sets will be copies of the original sets stored within your model.
+
 #### `attribute_set` ####
 
 The [`attribute_set`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods:attribute_set)
@@ -207,7 +226,7 @@ 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.
 
-### Querying sets in objects ###
+### Querying sets in model objects ###
 
 It is possible to access attribute sets from within the ActiveModel (or ORM, like ActiveRecord) objects.
 To do that you may use instance methods that are designed for that purpose.
@@ -215,7 +234,7 @@ 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)
-method called withount an argument **returns the attribute set containing all attributes for a current object**.
+instance method called withount an argument **returns the attribute set object containing all attributes known in a current object**.
 
 Example:
 
@@ -229,9 +248,9 @@ It works the same as the `all_attributes` method.
 #### `attribute_set(set_name)` ####
 
 The [`attribute_set`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters:attribute_set)
-(a.k.a `attributes_that`) method called with a single argument **returns the attribute set
+(a.k.a `attributes_that`) instance method called with a single argument **returns a copy of the attribute set
 of the given name**. It won't return the exact set object but a duplicate.
-It will always return an `AttributeSet` instance, even if there is not set of the given name
+It will always return an `AttributeSet` instance, even if there is no set of the given name defined for a model
 (in that case the resulting set will be empty).
 
 Example:
@@ -241,6 +260,24 @@ Example:
   # =>  #<ActiveModel::AttributeSet: {"real_name", "username", "email"}>
 ```
 
+The returned object in transparently wrapped in a proxy class instance that allows you
+to apply additional methods and keywords to it. See the section
+['Syntactic sugar for queries'](http://rubydoc.info/gems/attribute-filters/file/docs/USAGE.md#Syntactic_sugar_for_queries)
+for more info.
+
+There are also variants of this method that differ in a kind of taken argument:
+
+* `attribute_set(set_object)`
+
+> Allows to wrap an existing attribute set instance (e.g. created locally) with transparent proxy instance.
+> The resulting object will look like the same set but will be decorated with additional syntactic sugar.
+
+* `attribute_set(any_object)`
+
+> Allows to create local set that will be initialized with the given object (usually an array) that may not
+> be a `String`, a `Symbol` or an `AttributeSet` (these are reserved for the variants above). The resulting
+> object (a new `AttributeSet` instance) is also wrapped in a proxy.
+
 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`,   
@@ -252,7 +289,8 @@ Instead of `attribute_set` you may also use one of the aliases:
 
 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.
-It won't return the exact internal hash but a duplicate.
+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.
 
 Example:
 
@@ -382,6 +420,7 @@ Example:
 
 Note that the returned hash will have a default value set to instance of the `AttributeSet`.
 It won't return the exact internal hash but a duplicate.
+
 If you'll try to get the value of an element that doesn't exist **the empty set will be returned**.
 
 Instead of `attributes_to_sets` you may also use one of the aliases:
@@ -423,8 +462,9 @@ practice there are two groups of methods with two sets of DSL features.
 
 First group (querying attribute sets):
 
-* [`attribute_set`](#attribute_set_set_name_0) and aliases
-* [`attributes_to_filter`](#attributes_to_filter_set_name_____)
+* [`attribute_set`](#attribute_set0) and aliases
+* [`attribute_set(set_name)`](#attribute_set_set_name_1) and aliases
+* [`attributes_to_filter`](#attributes_to_filter_set_____)
 
 Second group (querying attributes for sets they belong to):
 
@@ -435,8 +475,9 @@ Second group (querying attributes for sets they belong to):
 Querying attribute sets uses two instance methods available
 in your models:
 
-* [`attribute_set`](#attribute_set_set_name_0) and aliases
-* [`attributes_to_filter`](#attributes_to_filter_set_name_____)
+* [`attribute_set`](#attribute_set0) and aliases
+* [`attribute_set(set_name)`](#attribute_set_set_name_1) and aliases
+* [`attributes_to_filter`](#attributes_to_filter_set_____)
 
 The output of calling these methods is an `AttributeSet` instance
 wrapped within a transparent proxy class instance
@@ -489,7 +530,7 @@ Let's do it without any fancy DSL methods:
 ```ruby
   u = User.first
   u.attributes_that(:should_be_stripped).all? do |attribute_name|
-    u.send(attribute_name).present?
+    u.public_send(attribute_name).present?
   end
   # => false
 ```
@@ -745,9 +786,9 @@ for altering attribute values: `for_attributes_that` and
 
 Filtering attributes basically means calling a proper
 method that will collect the attributes (matching certain
-criteria and belonging to the given set) and call some code block
-used that will either produce their new values or just call
-some method on each of them.
+criteria and belonging to the given set) and calling some code block
+that will either produce new values or just call some method on each
+of current attribute value and name.
 
 #### `filter_attrs_from_set(set_name,...)` ####
 
@@ -756,6 +797,14 @@ The [`filter_attrs_from_set`](http://rubydoc.info/gems/attribute-filters/ActiveM
 It takes optional arguments and a block. The result of evaluating a block will become a new value for a processed
 attribute. Optional arguments will be passed as the last arguments of a block.
 
+The evaluated block can make use of the following arguments that are passed to it:
+
+* `attribute_value` [Object] - current attribute value that should be altered
+* `attribute_name` [String] - a name of currently processed attribute
+* `set_object` [Object] - currently processed set that attribute belongs to
+* `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.
 You can change that behavior by adding a flags as the first arguments:
 
@@ -772,7 +821,7 @@ Example:
     before_validation :lolize
 
     def lolize
-      filter_attributes_that(:should_be_lolized, "lol") do |attribute_value, set_name, attribute_name, *args|
+      filter_attributes_that(:should_be_lolized, "lol") do |attribute_value, attribute_name, set_object, set_name, *args|
         [attribute_value, set_name.to_s, attribute_name, *args.flatten].join('-')
       end
     end
@@ -785,6 +834,12 @@ Example:
   # => "john-should_be_lolized-username-lol"
 ```
 
+You can pass a set object (`AttributeSet` instance) instead of set name as an argument. The method
+will then work on that local data with one difference: the `set_name` passed to a block will be set to `nil`.
+
+If the block is not given then the method returns an enumerator which can be used to query method later
+(when the block is present).
+
 Instead of `filter_attrs_from_set` you may also use one of the aliases:
 
   * `attribute_filter_for_set`, `filter_attributes_which`,       
@@ -799,6 +854,14 @@ It takes optional arguments and a block. The result of evaluating the given bloc
 but you can interact with the attribute object from within a block.
 Optional arguments will be passed as the last arguments of a block.
 
+The evaluated block can make use of the following arguments that are passed to it:
+
+* `attribute_value` [Object] - current attribute value that should be altered
+* `attribute_name` [String] - a name of currently processed attribute
+* `set_object` [Object] - currently processed set that attribute belongs to
+* `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.
 You can change that behavior by adding a flags as the first arguments:
 
@@ -815,7 +878,7 @@ Example:
     before_validation :lolize
 
     def lolize
-      for_attributes_that(:should_be_lolized, :process_blank, "lol") do |attribute_object, set_name, attribute_name, *args|
+      for_attributes_that(:should_be_lolized, :process_blank, "lol") do |attribute_value, attribute_name, set_object, set_name, *args|
         attribute_object << '-' << [set_name.to_s, attribute_name, *args.flatten].join('-')
       end
     end
@@ -828,6 +891,12 @@ Example:
   # => "john-should_be_lolized-username-lol"
 ```
 
+You can pass a set object (`AttributeSet` instance) instead of set name as an argument. The method
+will then work on that local data with one difference: the `set_name` passed to a block will be set to `nil`.
+
+If the block is not given then the method returns an enumerator which can be used to query method later
+(when the block is present).
+
 Instead of `filter_attrs_from_set` you may also use one of the aliases:
 
   * `attribute_call_for_set`, `call_attrs_from_set`,       
@@ -867,107 +936,1121 @@ 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 "the real" attribute. There are three ways
+the presence of any processed attribute as 'a real' attribute. There are three ways
 to overcome that problem.
 
-First (the messy one) is to add/update a virtual attribute in `attributes` hash each time
-a setter for your attribute is called. It interacts with the Rails internals so
-use it at your own risk. You should also register attribute as changed if any changes
-are made on it. To do that look at your ORM's documentation and see
-[`ActiveModel::Dirty`](http://api.rubyonrails.org/classes/ActiveModel/Dirty.html).
+#### Unconditional filtering ####
+
+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).
+
+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.
+
+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
+
+  # declare a virtual attribute
+  attr_accessor :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, :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
+
+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.
+
+Example:
+
+```ruby
+class User
+
+  # declare a virtual attribute
+  attr_accessor :real_name
+
+  # mark the attribute as real
+  treat_as_real :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]  # assuming first_name exists in a database
+      self.last_name  = names[1]  # assuming last_name exists in a database
+    end
+  end
+
+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.
+
+This approach can be easily used with predefined filters.
+
+#### Marking as trackable ####
+
+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.
+
+This approach can be easily used with predefined filters.
+
+Conditions:
+
+* 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`
+
+The benefit of that approach is that a filter will never be called redundantly contrary
+to previous methods.
+
+Example:
+
+```ruby
+class User < ActiveRecord::Base
+
+  # declare a virtual attribute
+  attr_reader       :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 writer that notifies Active Model about changes
+  def real_name=(val)
+    attribute_will_change!('real_name') if val != real_name
+    @real_name = val
+  end
+
+  # 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
+    end
+  end
+
+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
+
+end
+```
+
+#### Marking as trackable and semi-real ####
+
+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`.
+
+Example:
+
+```ruby
+class User < ActiveRecord::Base
+
+  # declare a virtual attribute
+  attr_virtual    :real_name
+
+  # 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
+
+  # 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
+
+end
+```
+
+Annotations
+-----------
+
+Annotations are portions of data that you can bind to attribute names residing within attribute sets.
+What for? To store something that is related to the specific attribute and that should be memorized within
+a set and/or its copies (if any). You can annotate each attribute name using key -> value pairs where the key is always a symbol and value is any kind of object you want. Only existing attributes can be annotated and deleting attribute
+will remove annotations that are assigned to it.
+
+When you copy a set, create difference or intersection of attribute sets, any existing annotations are also copied.
+If the operation creates a sum or joins sets then the annotations are mixed too.
+
+The annotations are used by some of the predefined filters described later to precise operations that have
+to be taken (e.g. specifying separator string for attribute joining filter and so on).
+
+### Creating annotations ###
+
+You can create annotations during defining a set or you can add them later with `annotate_attribute_set`.
+In case of local sets you can also use a method called `annotate`.
+
+#### When defining sets ####
+
+When using the first method just replace attrbute name with a hash, where attribute name is a key
+and annotations are another hash containing keys and values.
+
+Example:
+
+```ruby
+  class User
+    # Set name:         cool
+    # Attribute name:   email
+    # Annotation key:   some_key
+    # Annotation value: some value
+
+    attributes_that_are cool: { :email => { :some_key => "some value" } }
+  end
+```
+
+The above will annotate `email` attribute within a set `should_be_something` with `some_key` => "some value" pair.
+You can mix annotated attributes with unannotated; just put the last ones in front of an array:
 
-The second way is to pass the `:no_presence_check` and `process_all` flags to the filtering method.
-Be aware that by doing that you take full responsibility for attribute set defined in your model.
-If you put a name of nonexistent attribute to the set then later you may get ugly error.
+```ruby
+  class User
+    attributes_that_are cool: [ :some_unannotated, { :email => { :some_key => "some value" } } ]
+  end
+```
+
+or
+
+```ruby
+  class User
+    attributes_that_are :cool => [ :some_unannotated, { :email => { :some_key => "some value" } } ]
+  end
+```
+
+#### After defining sets ####
+
+To create annotations for class-level sets use the [`annotate_attribute_set`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/ClassMethods.html#annotate_attribute_set-instance_method) method (an its aliases):
+
+* **`annotate_attributes_that_are`**
+* **`annotate_attributes_that`**
+* **`annotate_attributes_are`** 
+* **`annotate_attributes_for`**  
+* **`annotate_attributes_set`** 
+* **`annotate_properties_that`**   
+* **`annotate_attributes`**   
+
+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' } }
+  end
+```
+
+Caution: Annotating attributes that aren't present in a set
+with `annotate_attribute_set` will raise an error.
+
+#### Annotating local sets ####
+
+* **`annotate`**
+
+Example:
+
+```ruby
+  class User
+    def some_method
+      s = ActiveModel::AttributeSet.new([:first_element, :second_element])
+      s.annotate(:first_element, :key, 'value')
+    end
+  end
+```
+
+### Removing annotations ###
 
-The third 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's **the preferred one**.
+To remove annotations locally (from sets that are not directly bound to models) you can use:
 
-Just add your virtual attributes to the model like that:
+* **`delete_annotation(attribute_name, annotation_key)`** - to delete specified annotation key for the given attribute
+* **`delete_annotations(attribute_name)`** - to delete all annotations for an attribute of the given name
+* **`remove_annotations()`** - to remove all annotations from a set
+
+Be aware that using these method to delete annotations from class-level sets won't work.
+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
+
+Example:
+
+```ruby
+  class User
+    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 }
+
+    # That won't affect the global set called 'cool'
+    # since we have its copy here, 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.
+    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.
+
+Example:
 
 ```ruby
   class User
-    treat_as_real :some, :virtual, :attributes
+    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 }
   end
+  
+  # In the result there will be only one annotation key left;
+  # :some_key with the value of "x"
 ```
 
-Be aware that the virtual attributes will always be filtered regardless of `process_all` flag,
-since there is no way to know whether they have changed or not. If you are somehow updating
-`changes` (or `changed_attributes` hash) on your own then you can modify that behavior
-for specific model by putting `filter_virtual_attributes_that_have_changed` keyword into it:
+Caution: Annotating attributes that aren't present in a set
+with `annotate_attribute_set` or by using `annotate` method will raise an error.
+
+Be aware that updating annotations directly (using `annotate` method) won't work on sets
+defined directly in classes describing models. That's because you'll always get
+a copy when querying these sets.
 
 ```ruby
   class User
-    filter_virtual_attributes_that_have_changed
-    treat_as_real :some, :virtual, :attributes
+    attributes_that_are :cool => { :email => { :some_key => "some value"  } }
+    
+    # Calling `some_method` won't work on 'cool' global set.
+    def some_method
+      attributes_that_are(:cool).delete_annotation(:email, :other_key)
+    end
   end
 ```
 
-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.
+## Querying annotations ###
+
+To check if a set has any annotations you can use one of the methods:
+
+* **`has_annotation?`** - checks if a set has any annotations
+* **`has_annotations?`** - checks if a set has any annotations
+* **`has_annotation?(attribute_name)`** - checks if a set has any annotations for the given attribute 
+* **`has_annotation?(attribute_name, *annotation_keys)`** - checks if a set has any annotation key for the given attribute
+
+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
+
+Example:
+
+```ruby
+  class User
+    attributes_that_are cool: [ :some_unannotated, :email => { :x => :y } ]
+
+    def q
+      attributes_that_are(:cool).annotation(:email, :x, :z)
+    end
+
+    def qq
+      attributes_that_are(:cool).annotation(:nope, :x, :z)
+    end
+
+    # Calling q will return an array: [:y, nil]
+    # Calling qq will return nil since attribute is not present (or not annotated)
+
+  end
+```
 
 Predefined filters
 ------------------
 
 Predefined filters are ready-to-use methods
 for filtering attributes. You just have to call them
-or pass their names to callback hooks.
+or register them as [callbacks](http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html).
 
-To use predefined filters you have to manually
+To use all predefined filters you have to manually
 include the [`ActiveModel::AttributeFilters::Common`](http://rubydoc.info/gems/attribute-filters/ActiveModel/AttributeFilters/Common)
-module. If you don't want to include portions of code that you'll never use, you can also include some filters selectively. To do that just include just a submodule containing certain filtering method.
-
-Here is a list of the predefined filtering methods:
-
-* `capitalize_attributes` (submodule: `Capitalize`)
-* `fully_capitalize_attributes` (submodule: `Capitalize`)
-* `titleize_attributes` (submodule: `Titleize`)
-* `downcase_attributes` (submodule: `Downcase` or `Case`)
-* `upcase_attributes` (submodule: `Upcase` or `Case`)
-* `strip_attributes` (submodule: `Strip`)
-* `squeeze_attributes` (submodule: `Squeeze`)
-* `squish_attributes` (submodule: `Squish`)
+module. That will include **all available filtering methods** into your model.
 
 Example:
 
 ```ruby
 class User < ActiveRecord::Base
   include ActiveModel::AttributeFilters::Common
-  
-  the_attribute user:   [:should_be_squished, :should_be_downcased  ]
-  the_attribute email:  [:should_be_squished, :should_be_downcased  ]
-  the_attribute name:   [:should_be_squished, :should_be_downcased, :should_be_titleized ]
-  
-  before_validation :squish_attributes
+
+  the_attribute name:   [:should_be_downcased, :should_be_titleized ]
+
   before_validation :downcase_attributes
   before_validation :titleize_attributes
 end
 ```
 
-or (better):
+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:
 
 ```ruby
 class User < ActiveRecord::Base
-  include ActiveModel::AttributeFilters::Common::Squish
   include ActiveModel::AttributeFilters::Common::Downcase
   include ActiveModel::AttributeFilters::Common::Titleize
-  
-  the_attribute user:   [:should_be_squished, :should_be_downcased  ]
-  the_attribute email:  [:should_be_squished, :should_be_downcased  ]
-  the_attribute name:   [:should_be_squished, :should_be_downcased, :should_be_titleized ]
-  
-  before_validation :squished_attributes
+
+  the_attribute name:   [:should_be_downcased, :should_be_titleized ]
+
   before_validation :downcase_attributes
   before_validation :titleize_attributes
 end
 ```
 
+As you can see, to use any filter you should include a proper submodule, add attribute
+names to a proper set and register a callback. The name of a set
+that a filtering method will use is predetermined and follows the
+convention that it should correspond to the name of a filter. So the
+set used by squeezing filter will be named `should_be_squeezed`.
+
+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]
+  before_validation :squeeze_attributes
+end
+```
+
+The filtering methods usually come with class-level DSL methods
+that are a simple wrappers calling `the_attribute`. So you can
+also write:
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Squeeze
+  squeeze_attributes :email, :name
+  before_validation :squeeze_attributes
+end
+```
+
+### Calling all at once ###
+
+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.
+
+Example:
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Squeeze
+  include ActiveModel::AttributeFilters::Common::Capitalize
+
+  squeeze_attributes :email, :name
+  capitalize_attributes :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
+
+```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
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Case
+
+  attributes_that     :should_be_upcased => [ :name ]
+  before_validation   :upcase_attributes
+end
+```
+
+Then:
+
+> `"some name"`
+
+will become:
+
+> `"SOME NAME"`
+
+##### `downcase_attributes` #####
+
+Downcases attributes.
+
+* 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:
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Case
+
+  downcase_attributes :name
+  before_validation   :downcase_attributes
+end
+```
+
+or
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Case
+
+  attributes_that     :should_be_downcased => [ :name ]
+  before_validation   :downcase_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` #####
+
+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
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Strip
+
+  attributes_that     :should_be_stripped => [ :name ]
+  before_validation   :strip_attributes
+end
+```
+
+Then:
+
+> `"    Some Name    "`
+
+will become:
+
+> `"Some Name"`
+
+#### 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:
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Squeeze
+
+  squeeze_attributes  :name
+  before_validation   :squeeze_attributes
+end
+```
+
+or
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Squeeze
+
+  attributes_that     :should_be_squeezed => [ :name ]
+  before_validation   :squeeze_attributes
+end
+```
+
+Then:
+
+> `"Some    Name"`
+
+will become:
+
+> `"Some Name"`
+
+##### `squish_attributes` #####
+
+Squishes attributes (removes all whitespace characters on both ends of the string, and then changes remaining consecutive whitespace groups into one space each).
+
+* 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
+
+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:
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Split
+
+  attr_virtual      :real_name
+  attr_accessible   :real_name
+  split_attributes  :real_name, :limit => 2, :into => [ :first_name, :last_name ], :pattern => ' '
+  before_validation :split_attributes
+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.
+
+* 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:
+
+```ruby
+class User < ActiveRecord::Base
+  include ActiveModel::AttributeFilters::Common::Join
+
+  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
+```
+
+you can also switch source with destination:
+
+```ruby
+  join_attributes         [ :first_name, :last_name ] => :real_name
+```
+
+or add a descriptive keyword `:into`:
+
+```ruby
+  join_attributes         [ :first_name, :last_name ], :into => :real_name
+```
+
 Custom applications
 -------------------
 
@@ -984,11 +2067,13 @@ class User < ActiveRecord::Base
   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?
+    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.blank? +
+    attributes_that_are(:required_to_trade).list.invalid?
   end
 end
 ```