libghc-hsemail-doc 1.7.2-2build1 / usr / share / doc / libghc-hsemail-doc / html / hsemail.txt

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


-- | Internet Message Parsers
--   
--   Parsers for the syntax defined in RFC2821 and 2822
@package hsemail
@version 1.7.2


-- | This module provides parsers for the grammar defined in RFC2234,
--   "Augmented BNF for Syntax Specifications: ABNF",
--   <a>http://www.faqs.org/rfcs/rfc2234.html</a>. The terminal called
--   <tt>char</tt> in the RFC is called <a>character</a> here to avoid
--   conflicts with Parsec's <a>char</a> function.
module Text.ParserCombinators.Parsec.Rfc2234

-- | Case-insensitive variant of Parsec's <a>char</a> function.
caseChar :: Char -> CharParser st Char

-- | Case-insensitive variant of Parsec's <a>string</a> function.
caseString :: String -> CharParser st ()

-- | Match a parser at least <tt>n</tt> times.
manyN :: Int -> GenParser a b c -> GenParser a b [c]

-- | Match a parser at least <tt>n</tt> times, but no more than <tt>m</tt>
--   times.
manyNtoM :: Int -> Int -> GenParser a b c -> GenParser a b [c]

-- | Helper function to generate <a>Parser</a>-based instances for the
--   <a>Read</a> class.
parsec2read :: Parser a -> String -> [(a, String)]

-- | Match any character of the alphabet.
alpha :: CharParser st Char

-- | Match either "1" or "0".
bit :: CharParser st Char

-- | Match any 7-bit US-ASCII character except for NUL (ASCII value 0, that
--   is).
character :: CharParser st Char

-- | Match the carriage return character <tt>\r</tt>.
cr :: CharParser st Char

-- | Match returns the linefeed character <tt>\n</tt>.
lf :: CharParser st Char

-- | Match the Internet newline <tt>\r\n</tt>.
crlf :: CharParser st String

-- | Match any US-ASCII control character. That is any character with a
--   decimal value in the range of [0..31,127].
ctl :: CharParser st Char

-- | Match the double quote character "<tt>"</tt>".
dquote :: CharParser st Char

-- | Match any character that is valid in a hexadecimal number; ['0'..'9']
--   and ['A'..'F','a'..'f'] that is.
hexdig :: CharParser st Char

-- | Match the tab ("<tt>\t</tt>") character.
htab :: CharParser st Char

-- | Match "linear white-space". That is any number of consecutive
--   <a>wsp</a>, optionally followed by a <a>crlf</a> and (at least) one
--   more <a>wsp</a>.
lwsp :: CharParser st String

-- | Match <i>any</i> character.
octet :: CharParser st Char

-- | Match the space.
sp :: CharParser st Char

-- | Match any printable ASCII character. (The "v" stands for "visible".)
--   That is any character in the decimal range of [33..126].
vchar :: CharParser st Char

-- | Match either <a>sp</a> or <a>htab</a>.
wsp :: CharParser st Char

-- | Match a "quoted pair". Any characters (excluding CR and LF) may be
--   quoted.
quoted_pair :: CharParser st String

-- | Match a quoted string. The specials "<tt>\</tt>" and "<tt>"</tt>" must
--   be escaped inside a quoted string; CR and LF are not allowed at all.
quoted_string :: CharParser st String


-- | This module exports parser combinators for the grammar described in
--   RFC2821, "Simple Mail Transfer Protocol",
--   <a>http://www.faqs.org/rfcs/rfc2821.html</a>.
module Text.ParserCombinators.Parsec.Rfc2821
data SessionState
Unknown :: SessionState
HaveHelo :: SessionState
HaveMailFrom :: SessionState
HaveRcptTo :: SessionState
HaveData :: SessionState
HaveQuit :: SessionState
data Event

-- | reserved for the user
Greeting :: Event
SayHelo :: String -> Event
SayHeloAgain :: String -> Event
SayEhlo :: String -> Event
SayEhloAgain :: String -> Event
SetMailFrom :: Mailbox -> Event
AddRcptTo :: Mailbox -> Event
StartData :: Event

-- | reserved for the user
Deliver :: Event
NeedHeloFirst :: Event
NeedMailFromFirst :: Event
NeedRcptToFirst :: Event

-- | <a>Turn</a>, <a>Send</a>, <a>Soml</a>, <a>Saml</a>, <a>Vrfy</a>, and
--   <a>Expn</a>.
NotImplemened :: Event
ResetState :: Event

-- | Triggered in case of <a>Noop</a> or when <a>Rset</a> is used before we
--   even have a state.
SayOK :: Event

-- | The parameter may be <tt>[]</tt>.
SeeksHelp :: String -> Event
Shutdown :: Event
SyntaxErrorIn :: String -> Event
Unrecognized :: String -> Event
type SmtpdFSM = State SessionState Event

-- | Parse a line of SMTP dialogue and run <a>handleSmtpCmd</a> to
--   determine the <a>Event</a>. In case of syntax errors,
--   <a>SyntaxErrorIn</a> or <a>Unrecognized</a> will be returned. Inputs
--   must be terminated with <a>crlf</a>. See <a>fixCRLF</a>.
smtpdFSM :: String -> SmtpdFSM

-- | For those who want to parse the <a>SmtpCmd</a> themselves. Calling
--   this function in <a>HaveQuit</a> or <a>HaveData</a> will fail an
--   assertion. If <a>assert</a> is disabled, it will return respectively
--   <a>Shutdown</a> and <a>StartData</a> again.
handleSmtpCmd :: SmtpCmd -> SmtpdFSM

-- | The <a>smtpCmd</a> parser will create this data type from a string.
--   Note that <i>all</i> command parsers expect their input to be
--   terminated with <a>crlf</a>.
data SmtpCmd
Helo :: String -> SmtpCmd
Ehlo :: String -> SmtpCmd

-- | Might be <a>nullPath</a>.
MailFrom :: Mailbox -> SmtpCmd

-- | Might be <a>postmaster</a>.
RcptTo :: Mailbox -> SmtpCmd
Data :: SmtpCmd
Rset :: SmtpCmd
Send :: Mailbox -> SmtpCmd
Soml :: Mailbox -> SmtpCmd
Saml :: Mailbox -> SmtpCmd
Vrfy :: String -> SmtpCmd
Expn :: String -> SmtpCmd

-- | Might be <tt>[]</tt>.
Help :: String -> SmtpCmd

-- | Optional argument ignored.
Noop :: SmtpCmd
Quit :: SmtpCmd
Turn :: SmtpCmd

-- | When a valid command has been recognized, but the argument parser
--   fails, then this type will be returned. The <a>String</a> contains the
--   name of the command (in all upper-case) and the <a>ParseError</a> is,
--   obviously, the error description.
WrongArg :: String -> ParseError -> SmtpCmd

-- | The most general e-mail address has the form:
--   <tt>&lt;[@route,...:]user@domain&gt;</tt>. This type, too, supports
--   <a>show</a> and <a>read</a>. Note that a "shown" address is
--   <i>always</i> enclosed in angular brackets. When comparing two
--   mailboxes for equality, the hostname is case-insensitive.
data Mailbox
Mailbox :: [String] -> String -> String -> Mailbox

-- | <tt>nullPath</tt> <tt>=</tt> <tt><a>Mailbox</a> [] "" "" =
--   "&lt;&gt;"</tt>
nullPath :: Mailbox

-- | <tt>postmaster</tt> <tt>=</tt> <tt><a>Mailbox</a> [] "postmaster" "" =
--   "&lt;postmaster&gt;"</tt>
postmaster :: Mailbox

-- | An SMTP reply is a three-digit return code plus some waste of
--   bandwidth called "comments". This is what the list of strings is for;
--   one string per line in the reply. <a>show</a> will append an
--   "<tt>\r\n</tt>" end-of-line marker to each entry in that list, so that
--   the resulting string is ready to be sent back to the peer.
--   
--   Here is an example:
--   
--   <pre>
--   *Rfc2821&gt; print $ Reply (Code Success MailSystem 0)
--                       ["worked", "like", "a charm" ]
--   250-worked
--   250-like
--   250 a charm
--   </pre>
--   
--   If the message is <tt>[]</tt>, you'll get a really helpful default
--   text.
data SmtpReply
Reply :: SmtpCode -> [String] -> SmtpReply
data SmtpCode
Code :: SuccessCode -> Category -> Int -> SmtpCode
data SuccessCode
Unused0 :: SuccessCode
PreliminarySuccess :: SuccessCode
Success :: SuccessCode
IntermediateSuccess :: SuccessCode
TransientFailure :: SuccessCode
PermanentFailure :: SuccessCode
data Category
Syntax :: Category
Information :: Category
Connection :: Category
Unspecified3 :: Category
Unspecified4 :: Category
MailSystem :: Category

-- | Construct a <a>Reply</a>. Fails <a>assert</a> if invalid numbers are
--   given.
reply :: Int -> Int -> Int -> [String] -> SmtpReply

-- | A reply constitutes "success" if the status code is any of
--   <a>PreliminarySuccess</a>, <a>Success</a>, or
--   <a>IntermediateSuccess</a>.
isSuccess :: SmtpReply -> Bool

-- | A reply constitutes "failure" if the status code is either
--   <a>PermanentFailure</a> or <a>TransientFailure</a>.
isFailure :: SmtpReply -> Bool

-- | The replies <tt>221</tt> and <tt>421</tt> signify <a>Shutdown</a>.
isShutdown :: SmtpReply -> Bool

-- | The SMTP parsers defined here correspond to the commands specified in
--   RFC2821, so I won't document them individually.
type SmtpParser st = CharParser st SmtpCmd

-- | This parser recognizes any of the SMTP commands defined below. Note
--   that <i>all</i> command parsers expect their input to be terminated
--   with <a>crlf</a>.
smtpCmd :: SmtpParser st

-- | The parser name "data" was taken.
smtpData :: SmtpParser st
rset :: SmtpParser st
mail :: SmtpParser st
ehlo :: SmtpParser st
helo :: SmtpParser st
turn :: SmtpParser st
quit :: SmtpParser st
rcpt :: SmtpParser st
expn :: SmtpParser st
vrfy :: SmtpParser st
saml :: SmtpParser st
soml :: SmtpParser st
send :: SmtpParser st
help :: SmtpParser st

-- | May have an optional <a>word</a> argument, but it is ignored.
noop :: SmtpParser st
from_path :: CharParser st Mailbox
to_path :: CharParser st Mailbox
path :: CharParser st Mailbox
mailbox :: CharParser st Mailbox
local_part :: CharParser st String
domain :: CharParser st String
a_d_l :: CharParser st [String]
at_domain :: CharParser st String

-- | <i>TODO</i>: Add IPv6 address and general literals
address_literal :: CharParser st String
ipv4_literal :: CharParser st String
ipv4addr :: CharParser st String
subdomain :: CharParser st String
dot_string :: CharParser st String
atom :: CharParser a String
snum :: CharParser st String
number :: CharParser st String

-- | This is a useful addition: The parser accepts an <a>atom</a> or a
--   <a>quoted_string</a>.
word :: CharParser st String

-- | Make the string <a>crlf</a> terminated no matter what. '<tt>\n</tt>'
--   is expanded, otherwise <a>crlf</a> is appended. Note that if the
--   string was terminated incorrectly before, it still is. This function
--   is useful when reading input with <a>hGetLine</a> which removes the
--   end-of-line delimiter.
fixCRLF :: String -> String

-- | Construct a parser for a command without arguments. Expects
--   <a>crlf</a>!
mkCmd0 :: String -> a -> CharParser st a

-- | Construct a parser for a command with an argument, which the given
--   parser will handle. The result of the argument parser will be applied
--   to the type constructor before it is returned. Expects <a>crlf</a>!
mkCmd1 :: String -> (a -> SmtpCmd) -> CharParser st a -> CharParser st SmtpCmd
tokenList :: CharParser st String -> Char -> CharParser st String
instance Enum SessionState
instance Bounded SessionState
instance Eq SessionState
instance Ord SessionState
instance Show SessionState
instance Eq Event
instance Show Event
instance Enum SuccessCode
instance Bounded SuccessCode
instance Eq SuccessCode
instance Ord SuccessCode
instance Show SuccessCode
instance Enum Category
instance Bounded Category
instance Eq Category
instance Ord Category
instance Show Category
instance Show SmtpCode
instance Show SmtpReply
instance Read Mailbox
instance Show Mailbox
instance Eq Mailbox
instance Show SmtpCmd


-- | This module provides parsers for the grammar defined in RFC2822,
--   "Internet Message Format",
--   <a>http://www.faqs.org/rfcs/rfc2822.html</a>.
--   
--   <i>Please note:</i> The module is not particularly well tested.
module Text.ParserCombinators.Parsec.Rfc2822

-- | Return <tt>Nothing</tt> if the given parser doesn't match. This
--   combinator is included in the latest parsec distribution as
--   <tt>optionMaybe</tt>, but ghc-6.6.1 apparently doesn't have it.
maybeOption :: GenParser tok st a -> GenParser tok st (Maybe a)

-- | <tt>unfold</tt> <tt>=</tt> <tt>between (optional cfws) (optional
--   cfws)</tt>
unfold :: CharParser a b -> CharParser a b

-- | Construct a parser for a message header line from the header's name
--   and a parser for the body.
header :: String -> CharParser a b -> CharParser a b

-- | Like <a>header</a>, but allows the obsolete white-space rules.
obs_header :: String -> CharParser a b -> CharParser a b

-- | Match any US-ASCII non-whitespace control character.
no_ws_ctl :: CharParser a Char

-- | Match any US-ASCII character except for <tt>r</tt>, <tt>n</tt>.
text :: CharParser a Char

-- | Match any of the RFC's "special" characters:
--   <tt>()&lt;&gt;[]:;@,.\"</tt>.
specials :: CharParser a Char

-- | Match a "quoted pair". All characters matched by <a>text</a> may be
--   quoted. Note that the parsers returns <i>both</i> characters, the
--   backslash and the actual content.
quoted_pair :: CharParser a String

-- | Match "folding whitespace". That is any combination of <a>wsp</a> and
--   <a>crlf</a> followed by <a>wsp</a>.
fws :: CharParser a String

-- | Match any non-whitespace, non-control character except for
--   "<tt>(</tt>", "<tt>)</tt>", and "<tt>\</tt>". This is used to describe
--   the legal content of <a>comment</a>s.
--   
--   <i>Note</i>: This parser accepts 8-bit characters, even though this is
--   not legal according to the RFC. Unfortunately, 8-bit content in
--   comments has become fairly common in the real world, so we'll just
--   accept the fact.
ctext :: CharParser a Char

-- | Match a "comments". That is any combination of <a>ctext</a>,
--   <a>quoted_pair</a>s, and <a>fws</a> between brackets. Comments may
--   nest.
comment :: CharParser a String

-- | Match any combination of <a>fws</a> and <a>comments</a>.
cfws :: CharParser a String

-- | Match any US-ASCII character except for control characters,
--   <a>specials</a>, or space. <a>atom</a> and <a>dot_atom</a> are made up
--   of this.
atext :: CharParser a Char

-- | Match one or more <a>atext</a> characters and skip any preceeding or
--   trailing <a>cfws</a>.
atom :: CharParser a String

-- | Match <a>dot_atom_text</a> and skip any preceeding or trailing
--   <a>cfws</a>.
dot_atom :: CharParser a String

-- | Match two or more <a>atext</a>s interspersed by dots.
dot_atom_text :: CharParser a String

-- | Match any non-whitespace, non-control US-ASCII character except for
--   "<tt>\</tt>" and "<tt>"</tt>".
qtext :: CharParser a Char

-- | Match either <a>qtext</a> or <a>quoted_pair</a>.
qcontent :: CharParser a String

-- | Match any number of <a>qcontent</a> between double quotes. Any
--   <a>cfws</a> preceeding or following the "atom" is skipped
--   automatically.
quoted_string :: CharParser a String

-- | Match either <a>atom</a> or <a>quoted_string</a>.
word :: CharParser a String

-- | Match either one or more <a>word</a>s or an <a>obs_phrase</a>.
phrase :: CharParser a [String]

-- | Match any non-whitespace, non-control US-ASCII character except for
--   "<tt>\</tt>" and "<tt>"</tt>".
utext :: CharParser a Char

-- | Match any number of <a>utext</a> tokens.
--   
--   "Unstructured text" is used in free text fields such as
--   <a>subject</a>. Please note that any comments or whitespace that
--   prefaces or follows the actual <a>utext</a> is <i>included</i> in the
--   returned string.
unstructured :: CharParser a String

-- | Parse a date and time specification of the form
--   
--   <pre>
--   Thu, 19 Dec 2002 20:35:46 +0200
--   </pre>
--   
--   where the weekday specification "<tt>Thu,</tt>" is optional. The
--   parser returns a <a>CalendarTime</a>, which is set to the appropriate
--   values. Note, though, that not all fields of <a>CalendarTime</a> will
--   necessarily be set correctly! Obviously, when no weekday has been
--   provided, the parser will set this field to <a>Monday</a> - regardless
--   of whether the day actually is a monday or not. Similarly, the day of
--   the year will always be returned as <tt>0</tt>. The timezone name will
--   always be empty: <tt>""</tt>.
--   
--   Nor will the <a>date_time</a> parser perform <i>any</i> consistency
--   checking. It will accept
--   
--   <pre>
--   40 Apr 2002 13:12 +0100
--   </pre>
--   
--   as a perfectly valid date.
--   
--   In order to get all fields set to meaningful values, and in order to
--   verify the date's consistency, you will have to feed it into any of
--   the conversion routines provided in <a>System.Time</a>, such as
--   <a>toClockTime</a>. (When doing this, keep in mind that most functions
--   return <i>local time</i>. This will not necessarily be the time you're
--   expecting.)
date_time :: CharParser a CalendarTime

-- | This parser will match a <a>day_name</a>, optionally wrapped in
--   folding whitespace, or an <a>obs_day_of_week</a> and return it's
--   <a>Day</a> value.
day_of_week :: CharParser a Day

-- | This parser will the abbreviated weekday names ("<tt>Mon</tt>",
--   "<tt>Tue</tt>", ...) and return the appropriate <a>Day</a> value.
day_name :: CharParser a Day

-- | This parser will match a date of the form "<tt>dd:mm:yyyy</tt>" and
--   return a tripple of the form (Int,Month,Int) - corresponding to
--   (year,month,day).
date :: CharParser a (Int, Month, Int)

-- | This parser will match a four digit number and return it's integer
--   value. No range checking is performed.
year :: CharParser a Int

-- | This parser will match a <a>month_name</a>, optionally wrapped in
--   folding whitespace, or an <a>obs_month</a> and return it's
--   <a>Month</a> value.
month :: CharParser a Month

-- | This parser will the abbreviated month names ("<tt>Jan</tt>",
--   "<tt>Feb</tt>", ...) and return the appropriate <a>Month</a> value.
month_name :: CharParser a Month

-- | Match either an <a>obs_day</a>, or a one or two digit number and
--   return it.
day :: CharParser a Int

-- | This parser will match a <a>time_of_day</a> specification followed by
--   a <a>zone</a>. It returns the tuple (TimeDiff,Int) corresponding to
--   the return values of either parser.
time :: CharParser a (TimeDiff, Int)

-- | This parser will match a time-of-day specification of "<tt>hh:mm</tt>"
--   or "<tt>hh:mm:ss</tt>" and return the corrsponding time as a
--   <a>TimeDiff</a>.
time_of_day :: CharParser a TimeDiff

-- | This parser will match a two-digit number and return it's integer
--   value. No range checking is performed.
hour :: CharParser a Int

-- | This parser will match a two-digit number and return it's integer
--   value. No range checking is performed.
minute :: CharParser a Int

-- | This parser will match a two-digit number and return it's integer
--   value. No range checking takes place.
second :: CharParser a Int

-- | This parser will match a timezone specification of the form
--   "<tt>+hhmm</tt>" or "<tt>-hhmm</tt>" and return the zone's offset to
--   UTC in seconds as an integer. <a>obs_zone</a> is matched as well.
zone :: CharParser a Int

-- | A NameAddr is composed of an optional realname a mandatory e-mail
--   <a>address</a>.
data NameAddr
NameAddr :: Maybe String -> String -> NameAddr
nameAddr_name :: NameAddr -> Maybe String
nameAddr_addr :: NameAddr -> String

-- | Parse a single <a>mailbox</a> or an address <a>group</a> and return
--   the address(es).
address :: CharParser a [NameAddr]

-- | Parse a <a>name_addr</a> or an <a>addr_spec</a> and return the
--   address.
mailbox :: CharParser a NameAddr

-- | Parse an <a>angle_addr</a>, optionally prefaced with a
--   <a>display_name</a>, and return the address.
name_addr :: CharParser a NameAddr

-- | Parse an <a>angle_addr</a> or an <a>obs_angle_addr</a> and return the
--   address.
angle_addr :: CharParser a String

-- | Parse a "group" of addresses. That is a <a>display_name</a>, followed
--   by a colon, optionally followed by a <a>mailbox_list</a>, followed by
--   a semicolon. The found address(es) are returned - what may be none.
--   Here is an example:
--   
--   <pre>
--   parse group "" "my group: user1@example.org, user2@example.org;"
--   </pre>
--   
--   This input comes out as:
--   
--   <pre>
--   Right ["user1@example.org","user2@example.org"]
--   </pre>
group :: CharParser a [NameAddr]

-- | Parse and return a <a>phrase</a>.
display_name :: CharParser a String

-- | Parse a list of <a>mailbox</a> addresses, every two addresses being
--   separated by a comma, and return the list of found address(es).
mailbox_list :: CharParser a [NameAddr]

-- | Parse a list of <a>address</a> addresses, every two addresses being
--   separated by a comma, and return the list of found address(es).
address_list :: CharParser a [NameAddr]

-- | Parse an "address specification". That is a <a>local_part</a>,
--   followed by an "<tt>@</tt>" character, followed by a <a>domain</a>.
--   Return the complete address as <a>String</a>, ignoring any whitespace
--   or any comments.
addr_spec :: CharParser a String

-- | Parse and return a "local part" of an <a>addr_spec</a>. That is either
--   a <a>dot_atom</a> or a <a>quoted_string</a>.
local_part :: CharParser a String

-- | Parse and return a "domain part" of an <a>addr_spec</a>. That is
--   either a <a>dot_atom</a> or a <a>domain_literal</a>.
domain :: CharParser a String

-- | Parse a "domain literal". That is a "<tt>[</tt>" character, followed
--   by any amount of <a>dcontent</a>, followed by a terminating
--   "<tt>]</tt>" character. The complete string is returned verbatim.
domain_literal :: CharParser a String

-- | Parse and return any characters that are legal in a
--   <a>domain_literal</a>. That is <a>dtext</a> or a <a>quoted_pair</a>.
dcontent :: CharParser a String

-- | Parse and return any ASCII characters except "<tt>[</tt>",
--   "<tt>]</tt>", and "<tt>\</tt>".
dtext :: CharParser a Char

-- | This data type repesents a parsed Internet Message as defined in this
--   RFC. It consists of an arbitrary number of header lines, represented
--   in the <a>Field</a> data type, and a message body, which may be empty.
data GenericMessage a
Message :: [Field] -> a -> GenericMessage a
type Message = GenericMessage String

-- | Parse a complete message as defined by this RFC and it broken down
--   into the separate header fields and the message body. Header lines,
--   which contain syntax errors, will not cause the parser to abort.
--   Rather, these headers will appear as <a>OptionalField</a>s (which are
--   unparsed) in the resulting <a>Message</a>. A message must be really,
--   really badly broken for this parser to fail.
--   
--   This behaviour was chosen because it is impossible to predict what the
--   user of this module considers to be a fatal error; traditionally,
--   parsers are very forgiving when it comes to Internet messages.
--   
--   If you want to implement a really strict parser, you'll have to put
--   the appropriate parser together yourself. You'll find that this is
--   rather easy to do. Refer to the <a>fields</a> parser for further
--   details.
message :: CharParser a Message

-- | This parser will return a message body as specified by this RFC; that
--   is basically any number of <a>text</a> characters, which may be
--   divided into separate lines by <a>crlf</a>.
body :: CharParser a String

-- | This data type represents any of the header fields defined in this
--   RFC. Each of the various instances contains with the return value of
--   the corresponding parser.
data Field
OptionalField :: String -> String -> Field
From :: [NameAddr] -> Field
Sender :: NameAddr -> Field
ReturnPath :: String -> Field
ReplyTo :: [NameAddr] -> Field
To :: [NameAddr] -> Field
Cc :: [NameAddr] -> Field
Bcc :: [NameAddr] -> Field
MessageID :: String -> Field
InReplyTo :: [String] -> Field
References :: [String] -> Field
Subject :: String -> Field
Comments :: String -> Field
Keywords :: [[String]] -> Field
Date :: CalendarTime -> Field
ResentDate :: CalendarTime -> Field
ResentFrom :: [NameAddr] -> Field
ResentSender :: NameAddr -> Field
ResentTo :: [NameAddr] -> Field
ResentCc :: [NameAddr] -> Field
ResentBcc :: [NameAddr] -> Field
ResentMessageID :: String -> Field
ResentReplyTo :: [NameAddr] -> Field
Received :: ([(String, String)], CalendarTime) -> Field
ObsReceived :: [(String, String)] -> Field

-- | This parser will parse an arbitrary number of header fields as defined
--   in this RFC. For each field, an appropriate <a>Field</a> value is
--   created, all of them making up the <a>Field</a> list that this parser
--   returns.
--   
--   If you look at the implementation of this parser, you will find that
--   it uses Parsec's <a>try</a> modifier around <i>all</i> of the fields.
--   The idea behind this is that fields, which contain syntax errors, fall
--   back to the catch-all <a>optional_field</a>. Thus, this parser will
--   hardly ever return a syntax error -- what conforms with the idea that
--   any message that can possibly be accepted <i>should</i> be.
fields :: CharParser a [Field]

-- | Parse a "<tt>Date:</tt>" header line and return the date it contains a
--   <a>CalendarTime</a>.
orig_date :: CharParser a CalendarTime

-- | Parse a "<tt>From:</tt>" header line and return the
--   <a>mailbox_list</a> address(es) contained in it.
from :: CharParser a [NameAddr]

-- | Parse a "<tt>Sender:</tt>" header line and return the <a>mailbox</a>
--   address contained in it.
sender :: CharParser a NameAddr

-- | Parse a "<tt>Reply-To:</tt>" header line and return the
--   <a>address_list</a> address(es) contained in it.
reply_to :: CharParser a [NameAddr]

-- | Parse a "<tt>To:</tt>" header line and return the <a>address_list</a>
--   address(es) contained in it.
to :: CharParser a [NameAddr]

-- | Parse a "<tt>Cc:</tt>" header line and return the <a>address_list</a>
--   address(es) contained in it.
cc :: CharParser a [NameAddr]

-- | Parse a "<tt>Bcc:</tt>" header line and return the <a>address_list</a>
--   address(es) contained in it.
bcc :: CharParser a [NameAddr]

-- | Parse a "<tt>Message-Id:</tt>" header line and return the
--   <a>msg_id</a> contained in it.
message_id :: CharParser a String

-- | Parse a "<tt>In-Reply-To:</tt>" header line and return the list of
--   <a>msg_id</a>s contained in it.
in_reply_to :: CharParser a [String]

-- | Parse a "<tt>References:</tt>" header line and return the list of
--   <a>msg_id</a>s contained in it.
references :: CharParser a [String]

-- | Parse a "<tt>message ID:</tt>" and return it. A message ID is almost
--   identical to an <a>angle_addr</a>, but with stricter rules about
--   folding and whitespace.
msg_id :: CharParser a String

-- | Parse a "left ID" part of a <a>msg_id</a>. This is almost identical to
--   the <a>local_part</a> of an e-mail address, but with stricter rules
--   about folding and whitespace.
id_left :: CharParser a String

-- | Parse a "right ID" part of a <a>msg_id</a>. This is almost identical
--   to the <a>domain</a> of an e-mail address, but with stricter rules
--   about folding and whitespace.
id_right :: CharParser a String

-- | Parse one or more occurences of <a>qtext</a> or <a>quoted_pair</a> and
--   return the concatenated string. This makes up the <a>id_left</a> of a
--   <a>msg_id</a>.
no_fold_quote :: CharParser a String

-- | Parse one or more occurences of <a>dtext</a> or <a>quoted_pair</a> and
--   return the concatenated string. This makes up the <a>id_right</a> of a
--   <a>msg_id</a>.
no_fold_literal :: CharParser a String

-- | Parse a "<tt>Subject:</tt>" header line and return it's contents
--   verbatim.
subject :: CharParser a String

-- | Parse a "<tt>Comments:</tt>" header line and return it's contents
--   verbatim.
comments :: CharParser a String

-- | Parse a "<tt>Keywords:</tt>" header line and return the list of
--   <a>phrase</a>s found. Please not that each phrase is again a list of
--   <a>atom</a>s, as returned by the <a>phrase</a> parser.
keywords :: CharParser a [[String]]

-- | Parse a "<tt>Resent-Date:</tt>" header line and return the date it
--   contains as <a>CalendarTime</a>.
resent_date :: CharParser a CalendarTime

-- | Parse a "<tt>Resent-From:</tt>" header line and return the
--   <a>mailbox_list</a> address(es) contained in it.
resent_from :: CharParser a [NameAddr]

-- | Parse a "<tt>Resent-Sender:</tt>" header line and return the
--   <a>mailbox_list</a> address(es) contained in it.
resent_sender :: CharParser a NameAddr

-- | Parse a "<tt>Resent-To:</tt>" header line and return the
--   <a>mailbox</a> address contained in it.
resent_to :: CharParser a [NameAddr]

-- | Parse a "<tt>Resent-Cc:</tt>" header line and return the
--   <a>address_list</a> address(es) contained in it.
resent_cc :: CharParser a [NameAddr]

-- | Parse a "<tt>Resent-Bcc:</tt>" header line and return the
--   <a>address_list</a> address(es) contained in it. (This list may be
--   empty.)
resent_bcc :: CharParser a [NameAddr]

-- | Parse a "<tt>Resent-Message-ID:</tt>" header line and return the
--   <a>msg_id</a> contained in it.
resent_msg_id :: CharParser a String
return_path :: CharParser a String
path :: CharParser a String
received :: CharParser a ([(String, String)], CalendarTime)
name_val_list :: CharParser a [(String, String)]
name_val_pair :: CharParser a (String, String)
item_name :: CharParser a String
item_value :: CharParser a String

-- | Parse an arbitrary header field and return a tuple containing the
--   <a>field_name</a> and <a>unstructured</a> text of the header. The name
--   will <i>not</i> contain the terminating colon.
optional_field :: CharParser a (String, String)

-- | Parse and return an arbitrary header field name. That is one or more
--   <a>ftext</a> characters.
field_name :: CharParser a String

-- | Match and return any ASCII character except for control characters,
--   whitespace, and "<tt>:</tt>".
ftext :: CharParser a Char

-- | Match the obsolete "quoted pair" syntax, which - unlike
--   <a>quoted_pair</a> - allowed <i>any</i> ASCII character to be
--   specified when quoted. The parser will return both, the backslash and
--   the actual character.
obs_qp :: CharParser a String

-- | Match the obsolete "text" syntax, which - unlike <a>text</a> - allowed
--   "carriage returns" and "linefeeds". This is really weird; you better
--   consult the RFC for details. The parser will return the complete
--   string, including those special characters.
obs_text :: CharParser a String

-- | Match and return the obsolete "char" syntax, which - unlike
--   <a>character</a> - did not allow "carriage return" and "linefeed".
obs_char :: CharParser a Char

-- | Match and return the obsolete "utext" syntax, which is identical to
--   <a>obs_text</a>.
obs_utext :: CharParser a String

-- | Match the obsolete "phrase" syntax, which - unlike <a>phrase</a> -
--   allows dots between tokens.
obs_phrase :: CharParser a [String]

-- | Match a "phrase list" syntax and return the list of <a>String</a>s
--   that make up the phrase. In contrast to a <a>phrase</a>, the
--   <a>obs_phrase_list</a> separates the individual words by commas. This
--   syntax is - as you will have guessed - obsolete.
obs_phrase_list :: CharParser a [String]

-- | Parse and return an "obsolete fws" token. That is at least one
--   <a>wsp</a> character, followed by an arbitrary number (including zero)
--   of <a>crlf</a> followed by at least one more <a>wsp</a> character.
obs_fws :: CharParser a String

-- | Parse a <a>day_name</a> but allow for the obsolete folding syntax.
obs_day_of_week :: CharParser a Day

-- | Parse a <a>year</a> but allow for a two-digit number (obsolete) and
--   the obsolete folding syntax.
obs_year :: CharParser a Int

-- | Parse a <a>month_name</a> but allow for the obsolete folding syntax.
obs_month :: CharParser a Month

-- | Parse a <a>day</a> but allow for the obsolete folding syntax.
obs_day :: CharParser a Int

-- | Parse a <a>hour</a> but allow for the obsolete folding syntax.
obs_hour :: CharParser a Int

-- | Parse a <a>minute</a> but allow for the obsolete folding syntax.
obs_minute :: CharParser a Int

-- | Parse a <a>second</a> but allow for the obsolete folding syntax.
obs_second :: CharParser a Int

-- | Match the obsolete zone names and return the appropriate offset.
obs_zone :: CharParser a Int

-- | This parser will match the "obsolete angle address" syntax. This
--   construct used to be known as a "route address" in earlier RFCs. There
--   are two differences between this construct and the <a>angle_addr</a>:
--   For one - as usual -, the obsolete form allows for more liberal
--   insertion of folding whitespace and comments.
--   
--   Secondly, and more importantly, angle addresses used to allow the
--   (optional) specification of a "route". The newer version does not.
--   Such a routing address looks like this:
--   
--   <pre>
--   &lt;@example1.org,@example2.org:simons@example.org&gt;
--   </pre>
--   
--   The parser will return a tuple that - in case of the above address -
--   looks like this:
--   
--   <pre>
--   (["example1.org","example2.org"],"simons@example.org")
--   </pre>
--   
--   The first part contains a list of hosts that constitute the route
--   part. This list may be empty! The second part of the tuple is the
--   actual <a>addr_spec</a> address.
obs_angle_addr :: CharParser a String

-- | This parser parses the "route" part of <a>obs_angle_addr</a> and
--   returns the list of <a>String</a>s that make up this route. Relies on
--   <a>obs_domain_list</a> for the actual parsing.
obs_route :: CharParser a [String]

-- | This parser parses a list of domain names, each of them prefaced with
--   an "at". Multiple names are separated by a comma. The list of
--   <a>domain</a>s is returned - and may be empty.
obs_domain_list :: CharParser a [String]

-- | Parse the obsolete syntax of a <a>local_part</a>, which allowed for
--   more liberal insertion of folding whitespace and comments. The actual
--   string is returned.
obs_local_part :: CharParser a String

-- | Parse the obsolete syntax of a <a>domain</a>, which allowed for more
--   liberal insertion of folding whitespace and comments. The actual
--   string is returned.
obs_domain :: CharParser a String

-- | This parser will match the obsolete syntax for a <a>mailbox_list</a>.
--   This one is quite weird: An <a>obs_mbox_list</a> contains an arbitrary
--   number of <a>mailbox</a>es - including none -, which are separated by
--   commas. But you may have multiple consecutive commas without giving a
--   <a>mailbox</a>. You may also have a valid <a>obs_mbox_list</a> that
--   contains <i>no</i> <a>mailbox</a> at all. On the other hand, you
--   <i>must</i> have at least one comma.
--   
--   So, this input is perfectly valid:
--   
--   <pre>
--   ","
--   </pre>
--   
--   But this one is - contrary to all intuition - not:
--   
--   <pre>
--   "simons@example.org"
--   </pre>
--   
--   Strange, isn't it?
obs_mbox_list :: CharParser a [NameAddr]

-- | This parser is identical to <a>obs_mbox_list</a> but parses a list of
--   <a>address</a>es rather than <a>mailbox</a>es. The main difference is
--   that an <a>address</a> may contain <a>group</a>s. Please note that as
--   of now, the parser will return a simple list of addresses; the
--   grouping information is lost.
obs_addr_list :: CharParser a [NameAddr]
obs_fields :: GenParser Char a [Field]

-- | Parse a <a>date</a> header line but allow for the obsolete folding
--   syntax.
obs_orig_date :: CharParser a CalendarTime

-- | Parse a <a>from</a> header line but allow for the obsolete folding
--   syntax.
obs_from :: CharParser a [NameAddr]

-- | Parse a <a>sender</a> header line but allow for the obsolete folding
--   syntax.
obs_sender :: CharParser a NameAddr

-- | Parse a <a>reply_to</a> header line but allow for the obsolete folding
--   syntax.
obs_reply_to :: CharParser a [NameAddr]

-- | Parse a <a>to</a> header line but allow for the obsolete folding
--   syntax.
obs_to :: CharParser a [NameAddr]

-- | Parse a <a>cc</a> header line but allow for the obsolete folding
--   syntax.
obs_cc :: CharParser a [NameAddr]

-- | Parse a <a>bcc</a> header line but allow for the obsolete folding
--   syntax.
obs_bcc :: CharParser a [NameAddr]

-- | Parse a <a>message_id</a> header line but allow for the obsolete
--   folding syntax.
obs_message_id :: CharParser a String

-- | Parse an <a>in_reply_to</a> header line but allow for the obsolete
--   folding and the obsolete phrase syntax.
obs_in_reply_to :: CharParser a [String]

-- | Parse a <a>references</a> header line but allow for the obsolete
--   folding and the obsolete phrase syntax.
obs_references :: CharParser a [String]

-- | Parses the "left part" of a message ID, but allows the obsolete
--   syntax, which is identical to a <a>local_part</a>.
obs_id_left :: CharParser a String

-- | Parses the "right part" of a message ID, but allows the obsolete
--   syntax, which is identical to a <a>domain</a>.
obs_id_right :: CharParser a String

-- | Parse a <a>subject</a> header line but allow for the obsolete folding
--   syntax.
obs_subject :: CharParser a String

-- | Parse a <a>comments</a> header line but allow for the obsolete folding
--   syntax.
obs_comments :: CharParser a String

-- | Parse a <a>keywords</a> header line but allow for the obsolete folding
--   syntax. Also, this parser accepts <a>obs_phrase_list</a>.
obs_keywords :: CharParser a [String]

-- | Parse a <a>resent_from</a> header line but allow for the obsolete
--   folding syntax.
obs_resent_from :: CharParser a [NameAddr]

-- | Parse a <a>resent_sender</a> header line but allow for the obsolete
--   folding syntax.
obs_resent_send :: CharParser a NameAddr

-- | Parse a <a>resent_date</a> header line but allow for the obsolete
--   folding syntax.
obs_resent_date :: CharParser a CalendarTime

-- | Parse a <a>resent_to</a> header line but allow for the obsolete
--   folding syntax.
obs_resent_to :: CharParser a [NameAddr]

-- | Parse a <a>resent_cc</a> header line but allow for the obsolete
--   folding syntax.
obs_resent_cc :: CharParser a [NameAddr]

-- | Parse a <a>resent_bcc</a> header line but allow for the obsolete
--   folding syntax.
obs_resent_bcc :: CharParser a [NameAddr]

-- | Parse a <a>resent_msg_id</a> header line but allow for the obsolete
--   folding syntax.
obs_resent_mid :: CharParser a String

-- | Parse a <tt>Resent-Reply-To</tt> header line but allow for the
--   obsolete folding syntax.
obs_resent_reply :: CharParser a [NameAddr]
obs_return :: CharParser a [Char]
obs_received :: CharParser a [(String, String)]

-- | Match <a>obs_angle_addr</a>.
obs_path :: CharParser a String

-- | This parser is identical to <a>optional_field</a> but allows the more
--   liberal line-folding syntax between the "field_name" and the "field
--   text".
obs_optional :: CharParser a (String, String)
instance Show NameAddr
instance Eq NameAddr
instance Show Field
instance Show a => Show (GenericMessage a)