-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Wrapper around email-validate library adding instances for common type classes.
--   
--   Please see README.md
@package emailaddress
@version 0.2.0.0


-- | This module is a wrapper around <a>Text.Email.Validate</a> from
--   <a>email-validate</a>.
--   
--   This module exports <a>EmailAddress</a>, a newtype wrapper around
--   <a>Text.Email.Validate.EmailAddress</a>. Additional instances are
--   defined for our new <a>EmailAddress</a>, including <a>ToJSON</a> and
--   <a>FromJSON</a>. This is done so that no orphan instances need to be
--   used.
--   
--   If you would like additional instances to be defined, please send a
--   <a>pull request</a>. Additional instances will be accepted for any
--   typeclass from any package available on stackage.
module Text.EmailAddress

-- | Type to represent an email address. Newtype wrapper around
--   <a>EmailAddress</a> with additional typeclass instances.
newtype EmailAddress
EmailAddress :: EmailAddress -> EmailAddress
[unEmailAddress] :: EmailAddress -> EmailAddress

-- | Wrapper around <a>emailAddress</a>.
--   
--   Similar to <a>validate</a>, but returns <a>Nothing</a> if the email
--   address fails to parse.
--   
--   <pre>
--   &gt;&gt;&gt; emailAddress "foo@gmail.com"
--   Just "foo@gmail.com"
--   
--   &gt;&gt;&gt; emailAddress "not an email address"
--   Nothing
--   </pre>
emailAddress :: ByteString -> Maybe EmailAddress

-- | Wrapper around <a>validate</a>.
--   
--   <pre>
--   &gt;&gt;&gt; validate "foo@gmail.com"
--   Right "foo@gmail.com"
--   
--   &gt;&gt;&gt; import Data.Either (isLeft)
--   
--   &gt;&gt;&gt; isLeft $ validate "not an email address"
--   True
--   </pre>
validate :: ByteString -> Either String EmailAddress

-- | Create an <a>EmailAddress</a> from a <a>Text</a> value. See
--   <a>emailAddress</a>.
emailAddressFromText :: Text -> Maybe EmailAddress

-- | Create an <a>EmailAddress</a> from a <a>Text</a> value. See
--   <a>validate</a>.
validateFromText :: Text -> Either String EmailAddress

-- | Create an <a>EmailAddress</a> from a <a>String</a> value. See
--   <a>emailAddress</a>.
emailAddressFromString :: String -> Maybe EmailAddress

-- | Create an <a>EmailAddress</a> from a <a>String</a> value. See
--   <a>validate</a>.
validateFromString :: String -> Either String EmailAddress

-- | Validates whether a particular string is an email address according to
--   RFC5322.
isValid :: ByteString -> Bool

-- | Convert an email address to <a>Text</a>.
--   
--   This assumes the <a>EmailAddress</a> is UTF8-encoded.
--   
--   <pre>
--   &gt;&gt;&gt; let email = unsafeEmailAddress "foo" "gmail.com"
--   
--   &gt;&gt;&gt; email
--   "foo@gmail.com"
--   
--   &gt;&gt;&gt; toText email
--   "foo@gmail.com"
--   </pre>
toText :: EmailAddress -> Text

-- | Wrapper around <a>toByteString</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let email = unsafeEmailAddress "foo" "gmail.com"
--   
--   &gt;&gt;&gt; email
--   "foo@gmail.com"
--   
--   &gt;&gt;&gt; toByteString email
--   "foo@gmail.com"
--   </pre>
toByteString :: EmailAddress -> ByteString

-- | Wrapper around <a>localPart</a>.
--   
--   Extracts the local part from an email address.
--   
--   For example, in the email address <tt>foo@gmail.com</tt>, the local
--   part is <tt>foo</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let email = unsafeEmailAddress "foo" "gmail.com"
--   
--   &gt;&gt;&gt; email
--   "foo@gmail.com"
--   
--   &gt;&gt;&gt; localPart email
--   "foo"
--   </pre>
localPart :: EmailAddress -> ByteString

-- | Wrapper around <a>domainPart</a>.
--   
--   Extracts the domain part from an email address.
--   
--   For example, in the email address <tt>foo@gmail.com</tt>, the domain
--   part is <tt>gmail.com</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let email = unsafeEmailAddress "foo" "gmail.com"
--   
--   &gt;&gt;&gt; email
--   "foo@gmail.com"
--   
--   &gt;&gt;&gt; domainPart email
--   "gmail.com"
--   </pre>
domainPart :: EmailAddress -> ByteString

-- | Checks that an email is valid and returns a version of it where
--   comments and whitespace have been removed.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; canonicalizeEmail "spaces. are. allowed@example.com"
--   Just "spaces.are.allowed@example.com"
--   </pre>
canonicalizeEmail :: ByteString -> Maybe ByteString

-- | Wrapper around <a>unsafeEmailAddress</a>.
--   
--   Unsafely create an <a>EmailAddress</a> from a local part and a domain
--   part. The first argument is the local part, and the second argument is
--   the domain part.
--   
--   For example, in the email address <tt>foo@gmail.com</tt>, the local
--   part is <tt>foo</tt> and the domain part is <tt>gmail.com</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; unsafeEmailAddress "foo" "gmail.com"
--   "foo@gmail.com"
--   </pre>
unsafeEmailAddress :: ByteString -> ByteString -> EmailAddress
