Class IS_EMAIL

object --+    
         |    
 Validator --+
             |
            IS_EMAIL

Checks if field's value is a valid email address. Can be set to disallow
or force addresses from certain domain(s).

Email regex adapted from
http://haacked.com/archive/2007/08/21/i-knew-how-to-validate-an-email-address-until-i.aspx,
generally following the RFCs, except that we disallow quoted strings
and permit underscores and leading numerics in subdomain labels

Arguments:

- banned: regex text for disallowed address domains
- forced: regex text for required address domains

Both arguments can also be custom objects with a match(value) method.

Examples::

    #Check for valid email address:
    INPUT(_type='text', _name='name',
        requires=IS_EMAIL())

    #Check for valid email address that can't be from a .com domain:
    INPUT(_type='text', _name='name',
        requires=IS_EMAIL(banned='^.*\.com(|\..*)$'))

    #Check for valid email address that must be from a .edu domain:
    INPUT(_type='text', _name='name',
        requires=IS_EMAIL(forced='^.*\.edu(|\..*)$'))

    >>> IS_EMAIL()('a@b.com')
    ('a@b.com', None)
    >>> IS_EMAIL()('abc@def.com')
    ('abc@def.com', None)
    >>> IS_EMAIL()('abc@3def.com')
    ('abc@3def.com', None)
    >>> IS_EMAIL()('abc@def.us')
    ('abc@def.us', None)
    >>> IS_EMAIL()('abc@d_-f.us')
    ('abc@d_-f.us', None)
    >>> IS_EMAIL()('@def.com')           # missing name
    ('@def.com', 'enter a valid email address')
    >>> IS_EMAIL()('"abc@def".com')      # quoted name
    ('"abc@def".com', 'enter a valid email address')
    >>> IS_EMAIL()('abc+def.com')        # no @
    ('abc+def.com', 'enter a valid email address')
    >>> IS_EMAIL()('abc@def.x')          # one-char TLD
    ('abc@def.x', 'enter a valid email address')
    >>> IS_EMAIL()('abc@def.12')         # numeric TLD
    ('abc@def.12', 'enter a valid email address')
    >>> IS_EMAIL()('abc@def..com')       # double-dot in domain
    ('abc@def..com', 'enter a valid email address')
    >>> IS_EMAIL()('abc@.def.com')       # dot starts domain
    ('abc@.def.com', 'enter a valid email address')
    >>> IS_EMAIL()('abc@def.c_m')        # underscore in TLD
    ('abc@def.c_m', 'enter a valid email address')
    >>> IS_EMAIL()('NotAnEmail')         # missing @
    ('NotAnEmail', 'enter a valid email address')
    >>> IS_EMAIL()('abc@NotAnEmail')     # missing TLD
    ('abc@NotAnEmail', 'enter a valid email address')
    >>> IS_EMAIL()('customer/department@example.com')
    ('customer/department@example.com', None)
    >>> IS_EMAIL()('$A12345@example.com')
    ('$A12345@example.com', None)
    >>> IS_EMAIL()('!def!xyz%abc@example.com')
    ('!def!xyz%abc@example.com', None)
    >>> IS_EMAIL()('_Yosemite.Sam@example.com')
    ('_Yosemite.Sam@example.com', None)
    >>> IS_EMAIL()('~@example.com')
    ('~@example.com', None)
    >>> IS_EMAIL()('.wooly@example.com')       # dot starts name
    ('.wooly@example.com', 'enter a valid email address')
    >>> IS_EMAIL()('wo..oly@example.com')      # adjacent dots in name
    ('wo..oly@example.com', 'enter a valid email address')
    >>> IS_EMAIL()('pootietang.@example.com')  # dot ends name
    ('pootietang.@example.com', 'enter a valid email address')
    >>> IS_EMAIL()('.@example.com')            # name is bare dot
    ('.@example.com', 'enter a valid email address')
    >>> IS_EMAIL()('Ima.Fool@example.com')
    ('Ima.Fool@example.com', None)
    >>> IS_EMAIL()('Ima Fool@example.com')     # space in name
    ('Ima Fool@example.com', 'enter a valid email address')
    >>> IS_EMAIL()('localguy@localhost')       # localhost as domain
    ('localguy@localhost', None)