README.md
CanonicalEmails
==============
[![Gem Version](http://img.shields.io/gem/v/canonical-emails.svg)](http://badge.fury.io/rb/canonical-emails)
[![Build Status](http://img.shields.io/travis/dblock/canonical-emails.svg)](https://travis-ci.org/dblock/canonical-emails)
[![Dependency Status](https://gemnasium.com/dblock/canonical-emails.svg)](https://gemnasium.com/dblock/canonical-emails)
[![Code Climate](https://codeclimate.com/github/dblock/canonical-emails.svg)](https://codeclimate.com/github/dblock/canonical-emails)
Combine email validation and transformations to produce canonical email addresses. For example, parse and transform `Donald Duck <donald.duck@gmail.com>` into `donaldduck@gmail.com`, for `@gmail.com` addresses only. Patches instances of `Mail::Address`.
### Install
Add `canonical-emails` to your Gemfile.
```
gem 'canonical-emails'
```
### Use
``` ruby
class User
include CanonicalEmails::Extensions
attr_accessor :email
canonical_email :email, CanonicalEmails::GMail
end
user = User.new
user.email = "Donald Duck <Donald.Duck@gmail.com>"
user.canonical_email.class # Mail::Address
user.canonical_email.to_s # "Donald Duck <donaldduck@gmail.com>"
user.canonical_email.address # "donaldduck@gmail.com"
```
### Transform
#### CanonicalEmails::Downcase
Replaces the address and domain portion of the email by its lowercase equivalent.
``` ruby
email = CanonicalEmails::Downcase.transform("Donald Duck <DoNaLD.DuCK@eXaMPLe.CoM>")
email.to_s # "Donald Duck <donald.duck@example.com>"
email.address # "donald.duck@example.com"
```
#### CanonicalEmails::GMail
Gmail.com e-mail addresses ignore periods and aren't case-sensitive. The canonical version removes them and changes the address portion to lowercase.
``` ruby
email = CanonicalEmails::GMail.transform("Donald Duck <donald.duck@gmail.com>")
email.to_s # "Donald Duck <donaldduck@gmail.com>"
email.local # "donaldduck"
email.address # "donaldduck@gmail.com"
```
### Multiple Transformations
Combine multiple transformations, executed from left to right.
```
canonical_email :email, CanonicalEmails::GMail, CanonicalEmails::...
```
### Custom Transformations
A transformation is a module that has a single `transform` method that returns a `Mail::Address` instance. This library patches internal methods of the `Mail::Address` class.
``` ruby
module CanonicalEmails
module ReverseName
def self.transform(value)
Mail::Address.new(value).tap do |email|
email.instance_eval do
def name
super.reverse
end
end
end
end
end
end
email = CanonicalEmails::ReverseName.transform("Donald Duck <donald@example.org>")
email.name # "kcuD dlanoD"
```
### Contribute
See [CONTRIBUTING](CONTRIBUTING.md).
### Copyright and License
Copyright Daniel Doubrovkine and Contributors, [Artsy](https://artsy.net), 2013-2014
[MIT License](LICENSE.md)