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


-- | Parsing and rendering of email and MIME headers
--   
@package email-header
@version 0.2.0


-- | Email header types.
module Network.Email.Header.Types

-- | A set of email headers.
type Headers = [(HeaderName, HeaderField)]

-- | An email header name.
type HeaderName = CI ByteString

-- | The email header field.
type HeaderField = ByteString

-- | An email address.
newtype Address
Address :: ByteString -> Address

-- | A <a>Mailbox</a> receives mail.
data Mailbox
Mailbox :: Maybe Text -> Address -> Mailbox
displayName :: Mailbox -> Maybe Text
mailboxAddress :: Mailbox -> Address

-- | A <a>Recipient</a> is used to indicate senders and recipients of
--   messages. It may either be an individual <a>Mailbox</a>, or a named
--   group of <tt><a>Mailbox</a>es</tt>.
data Recipient
Individual :: Mailbox -> Recipient
Group :: Text -> [Mailbox] -> Recipient

-- | A message identifier, which has a similar format to an email address.
newtype MessageID
MessageID :: ByteString -> MessageID

-- | A MIME type.
data MimeType
MimeType :: CI ByteString -> CI ByteString -> MimeType
mimeType :: MimeType -> CI ByteString
mimeSubtype :: MimeType -> CI ByteString

-- | MIME content type parameters.
type Parameters = Map (CI ByteString) ByteString
instance Eq Address
instance Ord Address
instance Show Address
instance Eq Mailbox
instance Show Mailbox
instance Eq Recipient
instance Show Recipient
instance Eq MessageID
instance Ord MessageID
instance Show MessageID
instance Eq MimeType
instance Ord MimeType
instance Show MimeType


-- | A layout that keeps track of line positions.
module Network.Email.Header.Layout

-- | An abstract type representing a lazy layout.
data Layout a

-- | Run a layout with an initial position.
layout :: Monoid a => Int -> Layout a -> a

-- | Layout an element of a given length.
span :: Monoid a => Int -> a -> Layout a

-- | Layout a new line and set the initial position.
break :: Int -> Layout a

-- | Use the current line position to produce a layout.
position :: (Int -> Layout a) -> Layout a

-- | Choose the first layout if the first line fits within the given
--   length, and the second otherwise.
nicest :: Int -> Layout a -> Layout a -> Layout a
instance Monoid (Layout a)


-- | Charset conversions.
module Network.Email.Charset

-- | A charset. Charset names are compared fuzzily e.g. <tt>UTF-8</tt> is
--   equivalent to <tt>utf8</tt>.
data Charset

-- | The name of a charset.
charsetName :: Charset -> String

-- | All canonical charset names and aliases.
charsets :: Set Charset

-- | Lookup a charset from a name or alias, or <a>Nothing</a> if no such
--   charset exists.
lookupCharset :: String -> Maybe Charset

-- | The default charset, UTF-8.
defaultCharset :: Charset

-- | Convert a Unicode string into a codepage string.
fromUnicode :: Charset -> Text -> ByteString

-- | Convert a codepage string into a Unicode string.
toUnicode :: Charset -> ByteString -> Text
instance Show Charset
instance Ord Charset
instance Eq Charset


-- | Header formatting and pretty-printing.
module Network.Email.Header.Doc

-- | Rendering options.
data RenderOptions
RenderOptions :: Int -> Int -> Charset -> Encoding -> RenderOptions

-- | The maximum line width.
lineWidth :: RenderOptions -> Int

-- | The indent of each line, in spaces.
indent :: RenderOptions -> Int

-- | The charset used to encode text outside US-ASCII range.
charset :: RenderOptions -> Charset

-- | The header encoding used for encoded words.
encoding :: RenderOptions -> Encoding

-- | The encoding used for binary characters in an encoded word.
data Encoding

-- | Quoted-printable encoding. Spaces are represented with underscores,
--   and undisplayable characters are represented as hex pairs.
QP :: Encoding

-- | Base 64 encoding of all characters.
Base64 :: Encoding

-- | Default rendering options, which uses a line width of 80, and indent
--   of 2, and utf-8 quated-printable encoding.
defaultRenderOptions :: RenderOptions

-- | A formatted email header.
data Doc

-- | Render a document with the given options and initial position.
render :: RenderOptions -> Int -> Doc -> Builder

-- | Construct a primitive document from a layout function. The function
--   takes two parameters: the rendering options, and a <a>Bool</a> which
--   indicates whether the containing group is laid out horizontally
--   instead of vertically.
prim :: (RenderOptions -> Bool -> Layout Builder) -> Doc

-- | Specify an alternative layout with all line breaks flattened.
group :: Doc -> Doc

-- | Construct a <a>Doc</a> from a <a>Builder</a> and a length.
builder :: Int -> Builder -> Doc

-- | Construct a <a>Doc</a> from a <a>String</a>.
string :: String -> Doc

-- | Construct a <a>Doc</a> from a <a>ByteString</a>.
byteString :: ByteString -> Doc

-- | Construct a <a>Builder</a> from a <a>Text</a>.
text :: Text -> Doc

-- | A space layout.
space :: Layout Builder

-- | A newline layout. This will emit a <tt>CRLF</tt> pair, break to a new
--   line, and indent.
newline :: RenderOptions -> Layout Builder

-- | A line break. If undone, behaves like a space.
line :: Doc

-- | A line break. If undone, behaves like <a>mempty</a>.
linebreak :: Doc

-- | A space if the remaining layout fits, and a line break otherwise.
softline :: Doc

-- | <a>mempty</a> if the remaining layout fits, and a line break
--   otherwise.
softbreak :: Doc

-- | Concatenate with a <a>softline</a> in between.
(</>) :: Doc -> Doc -> Doc

-- | Separate a list with spaces if it fits. Otherwise, separate with
--   lines.
sep :: [Doc] -> Doc

-- | <tt>punctuate p xs</tt> appends <tt>p</tt> to every element of
--   <tt>xs</tt> but the last.
punctuate :: Monoid a => a -> [a] -> [a]
instance Eq Encoding
instance Ord Encoding
instance Read Encoding
instance Show Encoding
instance Enum Encoding
instance Bounded Encoding
instance Eq RenderOptions
instance Show RenderOptions
instance IsString Doc
instance Monoid Doc


-- | Header parsers. Most exported parsers (with the exception of
--   <a>fws</a>, <a>cfws</a>, and <a>unstructured</a>) are for parsing
--   structured header fields. They expect no leading space and will eat an
--   trailing white space.
module Network.Email.Header.Parser

-- | Skip folding whitespace.
fws :: Parser ()

-- | Skip any comments or folding whitespace.
cfws :: Parser ()

-- | Parse a value followed by whitespace.
lexeme :: Parser a -> Parser a

-- | Parse a character followed by whitespace.
symbol :: Char -> Parser Char

-- | Parse a list of elements, separated by commas.
commaSep :: Parser a -> Parser [a]

-- | Parse a date and time. TODO: non-numeric timezones (such as "PDT") are
--   considered equivalent to UTC time.
dateTime :: Parser ZonedTime

-- | Parse an email address.
address :: Parser Address

-- | Parse a <a>Mailbox</a>.
mailbox :: Parser Mailbox

-- | Parse a list of <tt><a>Mailbox</a>es</tt>.
mailboxList :: Parser [Mailbox]

-- | Parse a <a>Recipient</a>.
recipient :: Parser Recipient

-- | Parse a list of <tt><a>Recipient</a>s</tt>.
recipientList :: Parser [Recipient]

-- | Parse a message identifier.
messageID :: Parser MessageID

-- | Parse a list of message identifiers.
messageIDList :: Parser [MessageID]

-- | Parse a phrase. Adjacent encoded words are concatenated. White space
--   is reduced to a single space, except when quoted or part of an encoded
--   word.
phrase :: Parser Text

-- | Parse a comma-separated list of phrases.
phraseList :: Parser [Text]

-- | Parse unstructured text. Adjacent encoded words are concatenated.
--   White space is reduced to a single space, except when part of an
--   encoded word.
unstructured :: Parser Text

-- | Parse the MIME version (which should be 1.0).
mimeVersion :: Parser (Int, Int)

-- | Parse the content type.
contentType :: Parser (MimeType, Parameters)

-- | Parse the content transfer encoding.
contentTransferEncoding :: Parser (CI ByteString)


-- | Reading common header fields. This module is intended to be imported
--   qualified:
--   
--   <pre>
--   import qualified Network.Email.Header.Read as H
--   </pre>
module Network.Email.Header.Read

-- | Lookup and parse a header with a parser.
field :: HeaderName -> Parser a -> Headers -> Maybe a

-- | Lookup and parse a structured header with a parser. This skips initial
--   comments and folding white space, and ensures that the entire body is
--   consumed by the parser.
structuredField :: HeaderName -> Parser a -> Headers -> Maybe a

-- | Get the value of the <tt>Date:</tt> field.
date :: Headers -> Maybe ZonedTime

-- | Get the value of the <tt>From:</tt> field.
from :: Headers -> Maybe [Mailbox]

-- | Get the value of the <tt>Sender:</tt> field.
sender :: Headers -> Maybe Mailbox

-- | Get the value of the <tt>Reply-To:</tt> field.
replyTo :: Headers -> Maybe [Recipient]

-- | Get the value of the <tt>To:</tt> field.
to :: Headers -> Maybe [Recipient]

-- | Get the value of the <tt>Cc:</tt> field.
cc :: Headers -> Maybe [Recipient]

-- | Get the value of the <tt>Bcc:</tt> field.
bcc :: Headers -> Maybe (Maybe [Recipient])

-- | Get the value of the <tt>Message-ID:</tt> field.
messageID :: Headers -> Maybe MessageID

-- | Get the value of the <tt>In-Reply-To:</tt> field.
inReplyTo :: Headers -> Maybe [MessageID]

-- | Get the value of the <tt>References:</tt> field.
references :: Headers -> Maybe [MessageID]

-- | Get the value of the <tt>Subject:</tt> field.
subject :: Headers -> Maybe Text

-- | Get the value of the <tt>Comments:</tt> field.
comments :: Headers -> Maybe Text

-- | Get the value of the <tt>Keywords:</tt> field.
keywords :: Headers -> Maybe [Text]

-- | Get the value of the <tt>Resent-Date:</tt> field.
resentDate :: Headers -> Maybe ZonedTime

-- | Get the value of the <tt>Resent-From:</tt> field.
resentFrom :: Headers -> Maybe [Mailbox]

-- | Get the value of the <tt>Resent-Sender:</tt> field.
resentSender :: Headers -> Maybe Mailbox

-- | Get the value of the <tt>Resent-To:</tt> field.
resentTo :: Headers -> Maybe [Recipient]

-- | Get the value of the <tt>Resent-Cc:</tt> field.
resentCc :: Headers -> Maybe [Recipient]

-- | Get the value of the <tt>Resent-Bcc:</tt> field.
resentBcc :: Headers -> Maybe (Maybe [Recipient])

-- | Get the value of the <tt>Resent-Message-ID:</tt> field.
resentMessageID :: Headers -> Maybe MessageID

-- | Get the value of the <tt>MIME-Version:</tt> field.
mimeVersion :: Headers -> Maybe (Int, Int)

-- | Get the value of the <tt>Content-Type:</tt> field.
contentType :: Headers -> Maybe (MimeType, Parameters)

-- | Get the value of the <tt>Content-Transfer-Encoding:</tt> field.
contentTransferEncoding :: Headers -> Maybe (CI ByteString)

-- | Get the value of the <tt>Content-ID:</tt> field.
contentID :: Headers -> Maybe MessageID


-- | Formatting and pretty-printing header types.
module Network.Email.Header.Pretty

-- | Separate a group with commas.
commaSep :: (a -> Doc) -> [a] -> Doc

-- | Format a date and time.
dateTime :: ZonedTime -> Doc

-- | Format an address.
address :: Address -> Doc

-- | Format a <a>Mailbox</a>.
mailbox :: Mailbox -> Doc

-- | Format a list of <a>Mailbox</a>es.
mailboxList :: [Mailbox] -> Doc

-- | Format a <a>Recipient</a>.
recipient :: Recipient -> Doc

-- | Format a list of <a>Recipient</a>s.
recipientList :: [Recipient] -> Doc

-- | Format a message identifier
messageID :: MessageID -> Doc

-- | Format a list of message identifiers.
messageIDList :: [MessageID] -> Doc

-- | Format a phrase. The text is encoded as is, unless:
--   
--   <ul>
--   <li>The text contains leading or trailing whitespace, or more than one
--   space between words</li>
--   <li>Any word begins with <tt>=?</tt></li>
--   <li>Any word contains illegal characters</li>
--   </ul>
phrase :: Text -> Doc

-- | Format a list of phrases.
phraseList :: [Text] -> Doc

-- | Format unstructured text. The text is encoded as is, unless:
--   
--   <ul>
--   <li>The text contains leading or trailing whitespace, or more than one
--   space between words</li>
--   <li>Any word begins with <tt>=?</tt></li>
--   <li>Any word contains illegal characters</li>
--   </ul>
unstructured :: Text -> Doc

-- | Format the MIME version.
mimeVersion :: Int -> Int -> Doc

-- | Format the content type and parameters.
contentType :: MimeType -> Parameters -> Doc

-- | Format the content transfer encoding.
contentTransferEncoding :: CI ByteString -> Doc


-- | Rendering common header fields. This module is intended to be imported
--   qualified:
--   
--   <pre>
--   import qualified Network.Email.Header.Render as R
--   </pre>
module Network.Email.Header.Render

-- | Rendering options.
data RenderOptions
RenderOptions :: Int -> Int -> Charset -> Encoding -> RenderOptions

-- | The maximum line width.
lineWidth :: RenderOptions -> Int

-- | The indent of each line, in spaces.
indent :: RenderOptions -> Int

-- | The charset used to encode text outside US-ASCII range.
charset :: RenderOptions -> Charset

-- | The header encoding used for encoded words.
encoding :: RenderOptions -> Encoding

-- | The encoding used for binary characters in an encoded word.
data Encoding

-- | Quoted-printable encoding. Spaces are represented with underscores,
--   and undisplayable characters are represented as hex pairs.
QP :: Encoding

-- | Base 64 encoding of all characters.
Base64 :: Encoding

-- | Default rendering options, which uses a line width of 80, and indent
--   of 2, and utf-8 quated-printable encoding.
defaultRenderOptions :: RenderOptions

-- | A formatted email header.
data Doc

-- | Render a list of headers.
renderHeaders :: RenderOptions -> [(HeaderName, Doc)] -> Headers

-- | Create a <tt>Date:</tt> field.
date :: ZonedTime -> (HeaderName, Doc)

-- | Create a <tt>From:</tt> field.
from :: [Mailbox] -> (HeaderName, Doc)

-- | Create a <tt>Sender:</tt> field.
sender :: Mailbox -> (HeaderName, Doc)

-- | Create a <tt>Reply-To:</tt> field.
replyTo :: [Recipient] -> (HeaderName, Doc)

-- | Create a <tt>To:</tt> field.
to :: [Recipient] -> (HeaderName, Doc)

-- | Create a <tt>Cc:</tt> field.
cc :: [Recipient] -> (HeaderName, Doc)

-- | Create a <tt>Bcc:</tt> field.
bcc :: Maybe [Recipient] -> (HeaderName, Doc)

-- | Create a <tt>Message-ID:</tt> field.
messageID :: MessageID -> (HeaderName, Doc)

-- | Create a <tt>In-Reply-To:</tt> field.
inReplyTo :: [MessageID] -> (HeaderName, Doc)

-- | Create a <tt>References:</tt> field.
references :: [MessageID] -> (HeaderName, Doc)

-- | Create a <tt>Subject:</tt> field.
subject :: Text -> (HeaderName, Doc)

-- | Create a <tt>Comments:</tt> field.
comments :: Text -> (HeaderName, Doc)

-- | Create a <tt>Keywords:</tt> field.
keywords :: [Text] -> (HeaderName, Doc)

-- | Create a <tt>Resent-Date:</tt> field.
resentDate :: ZonedTime -> (HeaderName, Doc)

-- | Create a <tt>Resent-From:</tt> field.
resentFrom :: [Mailbox] -> (HeaderName, Doc)

-- | Create a <tt>Resent-Sender:</tt> field.
resentSender :: Mailbox -> (HeaderName, Doc)

-- | Create a <tt>Resent-To:</tt> field.
resentTo :: [Recipient] -> (HeaderName, Doc)

-- | Create a <tt>Resent-Cc:</tt> field.
resentCc :: [Recipient] -> (HeaderName, Doc)

-- | Create a <tt>Resent-Bcc:</tt> field.
resentBcc :: Maybe [Recipient] -> (HeaderName, Doc)

-- | Create a <tt>Resent-Message-ID:</tt> field.
resentMessageID :: MessageID -> (HeaderName, Doc)

-- | Create a <tt>MIME-Version:</tt> field.
mimeVersion :: Int -> Int -> (HeaderName, Doc)

-- | Create a <tt>Content-Type:</tt> field.
contentType :: MimeType -> Parameters -> (HeaderName, Doc)

-- | Create a <tt>Content-Transfer-Encoding:</tt> field.
contentTransferEncoding :: CI ByteString -> (HeaderName, Doc)

-- | Create a <tt>Content-ID:</tt> field.
contentID :: MessageID -> (HeaderName, Doc)