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


-- | Processing HTTP Content-Type and Accept headers
--   
--   This library is intended to be a comprehensive solution to parsing and
--   selecting quality-indexed values in HTTP headers. It is capable of
--   parsing both media types and language parameters from the Accept and
--   Content header families, and can be extended to match against other
--   accept headers as well. Selecting the appropriate header value is
--   achieved by comparing a list of server options against the
--   quality-indexed values supplied by the client.
--   
--   In the following example, the Accept header is parsed and then matched
--   against a list of server options to serve the appropriate media using
--   <a>mapAcceptMedia</a>:
--   
--   <pre>
--   getHeader &gt;&gt;= maybe send406Error sendResourceWith . mapAcceptMedia
--       [ ("text/html",        asHtml)
--       , ("application/json", asJson)
--       ]
--   </pre>
--   
--   Similarly, the Content-Type header can be used to produce a parser for
--   request bodies based on the given content type with
--   <a>mapContentMedia</a>:
--   
--   <pre>
--   getContentType &gt;&gt;= maybe send415Error readRequestBodyWith . mapContentMedia
--       [ ("application/json", parseJson)
--       , ("text/plain",       parseText)
--       ]
--   </pre>
--   
--   The API is agnostic to your choice of server.
@package http-media
@version 0.7.1


-- | Defines the <a>RenderHeader</a> type class, with the
--   <a>renderHeader</a> method. <a>renderHeader</a> can be used to render
--   basic header values (acting as identity on <a>ByteString</a>s), but it
--   will also work on lists of quality values, which provides the
--   necessary interface for rendering the full possibilities of Accept
--   headers.
module Network.HTTP.Media.RenderHeader

-- | A class for header values, so they may be rendered to their
--   <a>ByteString</a> representation. Lists of header values and
--   quality-marked header values will render appropriately.
class RenderHeader h

-- | Render a header value to a UTF-8 <a>ByteString</a>.
renderHeader :: RenderHeader h => h -> ByteString
instance Network.HTTP.Media.RenderHeader.RenderHeader Data.ByteString.Internal.ByteString
instance Network.HTTP.Media.RenderHeader.RenderHeader h => Network.HTTP.Media.RenderHeader.RenderHeader [h]


-- | Defines the <a>Accept</a> type class, designed to unify types on the
--   matching functions in the Media module.
module Network.HTTP.Media.Accept

-- | Defines methods for a type whose values can be matched against each
--   other in terms of an HTTP Accept-* header.
--   
--   This allows functions to work on both the standard Accept header and
--   others such as Accept-Language that still may use quality values.
class Show a => Accept a where hasExtensionParameters _ = False

-- | Specifies how to parse an Accept-* header after quality has been
--   handled.
parseAccept :: Accept a => ByteString -> Maybe a

-- | Evaluates whether either the left argument matches the right one.
--   
--   This relation must be a total order, where more specific terms on the
--   left can produce a match, but a less specific term on the left can
--   never produce a match. For instance, when matching against media types
--   it is important that if the client asks for a general type then we can
--   choose a more specific offering from the server, but if a client asks
--   for a specific type and the server only offers a more general form,
--   then we cannot generalise. In this case, the server types will be the
--   left argument, and the client types the right.
--   
--   For types with no concept of specificity, this operation is just
--   equality.
matches :: Accept a => a -> a -> Bool

-- | Evaluates whether the left argument is more specific than the right.
--   
--   This relation must be irreflexive and transitive. For types with no
--   concept of specificity, this is the empty relation (always false).
moreSpecificThan :: Accept a => a -> a -> Bool

-- | Indicates whether extension parameters are permitted after the weight
--   parameter when this type appears in an Accept header. Defaults to
--   false.
hasExtensionParameters :: Accept a => Proxy a -> Bool

-- | Evaluates to whichever argument is more specific. Left biased.
mostSpecific :: Accept a => a -> a -> a
instance Network.HTTP.Media.Accept.Accept Data.ByteString.Internal.ByteString


-- | Defines the <a>Language</a> accept header with an <tt>Accept</tt>
--   instance for use in language negotiation.
module Network.HTTP.Media.Language

-- | Suitable for HTTP language-ranges as defined in <a>RFC2616</a>.
--   
--   Specifically:
--   
--   <pre>
--   language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
--   </pre>
data Language

-- | Converts <a>Language</a> to a list of its language parts. The wildcard
--   produces an empty list.
toParts :: Language -> [CI ByteString]


-- | Defines the <a>MediaType</a> accept header with an <tt>Accept</tt>
--   instance for use in content-type negotiation.
module Network.HTTP.Media.MediaType

-- | An HTTP media type, consisting of the type, subtype, and parameters.
data MediaType

-- | <a>MediaType</a> parameters.
type Parameters = Map (CI ByteString) (CI ByteString)

-- | Builds a <a>MediaType</a> without parameters. Can produce an error if
--   either type is invalid.
(//) :: ByteString -> ByteString -> MediaType

-- | Adds a parameter to a <a>MediaType</a>. Can produce an error if either
--   string is invalid.
(/:) :: MediaType -> (ByteString, ByteString) -> MediaType

-- | Retrieves the main type of a <a>MediaType</a>.
mainType :: MediaType -> CI ByteString

-- | Retrieves the sub type of a <a>MediaType</a>.
subType :: MediaType -> CI ByteString

-- | Retrieves the parameters of a <a>MediaType</a>.
parameters :: MediaType -> Parameters

-- | Evaluates if a <a>MediaType</a> has a parameter of the given name.
(/?) :: MediaType -> ByteString -> Bool

-- | Retrieves a parameter from a <a>MediaType</a>.
(/.) :: MediaType -> ByteString -> Maybe (CI ByteString)


-- | A framework for parsing HTTP media type headers.
module Network.HTTP.Media

-- | An HTTP media type, consisting of the type, subtype, and parameters.
data MediaType

-- | Builds a <a>MediaType</a> without parameters. Can produce an error if
--   either type is invalid.
(//) :: ByteString -> ByteString -> MediaType

-- | Adds a parameter to a <a>MediaType</a>. Can produce an error if either
--   string is invalid.
(/:) :: MediaType -> (ByteString, ByteString) -> MediaType

-- | Retrieves the main type of a <a>MediaType</a>.
mainType :: MediaType -> CI ByteString

-- | Retrieves the sub type of a <a>MediaType</a>.
subType :: MediaType -> CI ByteString

-- | Retrieves the parameters of a <a>MediaType</a>.
parameters :: MediaType -> Parameters

-- | Evaluates if a <a>MediaType</a> has a parameter of the given name.
(/?) :: MediaType -> ByteString -> Bool

-- | Retrieves a parameter from a <a>MediaType</a>.
(/.) :: MediaType -> ByteString -> Maybe (CI ByteString)

-- | Suitable for HTTP language-ranges as defined in <a>RFC2616</a>.
--   
--   Specifically:
--   
--   <pre>
--   language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
--   </pre>
data Language

-- | Converts <a>Language</a> to a list of its language parts. The wildcard
--   produces an empty list.
toParts :: Language -> [CI ByteString]

-- | Matches a list of server-side resource options against a
--   quality-marked list of client-side preferences. A result of
--   <a>Nothing</a> means that nothing matched (which should indicate a 406
--   error). If two or more results arise with the same quality level and
--   specificity, then the first one in the server list is chosen.
--   
--   The use of the <a>Accept</a> type class allows the application of
--   either <a>MediaType</a> for the standard Accept header or
--   <a>ByteString</a> for any other Accept header which can be marked with
--   a quality value.
--   
--   <pre>
--   matchAccept ["text/html", "application/json"] &lt;$&gt; getHeader
--   </pre>
--   
--   For more information on the matching process see RFC 2616, section
--   14.1-4.
matchAccept :: Accept a => [a] -> ByteString -> Maybe a

-- | The equivalent of <a>matchAccept</a> above, except the resulting
--   choice is mapped to another value. Convenient for specifying how to
--   translate the resource into each of its available formats.
--   
--   <pre>
--   getHeader &gt;&gt;= maybe render406Error renderResource . mapAccept
--       [ ("text" // "html",        asHtml)
--       , ("application" // "json", asJson)
--       ]
--   </pre>
mapAccept :: Accept a => [(a, b)] -> ByteString -> Maybe b

-- | A specialisation of <a>mapAccept</a> that only takes <a>MediaType</a>
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   <pre>
--   getHeader &gt;&gt;= maybe render406Error renderResource . mapAcceptMedia
--       [ ("text/html",        asHtml)
--       , ("application/json", asJson)
--       ]
--   </pre>
mapAcceptMedia :: [(MediaType, b)] -> ByteString -> Maybe b

-- | A specialisation of <a>mapAccept</a> that only takes <a>Language</a>
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   <pre>
--   getHeader &gt;&gt;= maybe render406Error renderResource . mapAcceptLanguage
--       [ ("text/html",        asHtml)
--       , ("application/json", asJson)
--       ]
--   </pre>
mapAcceptLanguage :: [(Language, b)] -> ByteString -> Maybe b

-- | A specialisation of <a>mapAccept</a> that only takes <a>ByteString</a>
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   <pre>
--   getHeader &gt;&gt;= maybe render406Error encodeResourceWith . mapAcceptBytes
--       [ ("compress", compress)
--       , ("gzip",     gzip)
--       ]
--   </pre>
mapAcceptBytes :: [(ByteString, b)] -> ByteString -> Maybe b

-- | Matches a list of server-side parsing options against a the
--   client-side content value. A result of <a>Nothing</a> means that
--   nothing matched (which should indicate a 415 error).
--   
--   <pre>
--   matchContent ["application/json", "text/plain"] &lt;$&gt; getContentType
--   </pre>
--   
--   For more information on the matching process see RFC 2616, section
--   14.17.
matchContent :: Accept a => [a] -> ByteString -> Maybe a

-- | The equivalent of <a>matchContent</a> above, except the resulting
--   choice is mapped to another value.
--   
--   <pre>
--   getContentType &gt;&gt;= maybe send415Error readRequestBodyWith . mapContent
--       [ ("application" // "json", parseJson)
--       , ("text" // "plain",       parseText)
--       ]
--   </pre>
mapContent :: Accept a => [(a, b)] -> ByteString -> Maybe b

-- | A specialisation of <a>mapContent</a> that only takes <a>MediaType</a>
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   <pre>
--   getContentType &gt;&gt;=
--       maybe send415Error readRequestBodyWith . mapContentMedia
--           [ ("application/json", parseJson)
--           , ("text/plain",       parseText)
--           ]
--   </pre>
mapContentMedia :: [(MediaType, b)] -> ByteString -> Maybe b

-- | A specialisation of <a>mapContent</a> that only takes <a>Language</a>
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   <pre>
--   getContentType &gt;&gt;=
--       maybe send415Error readRequestBodyWith . mapContentLanguage
--           [ ("application/json", parseJson)
--           , ("text/plain",       parseText)
--           ]
--   </pre>
mapContentLanguage :: [(Language, b)] -> ByteString -> Maybe b

-- | Attaches a quality value to data.
data Quality a

-- | Manually construct a quality value.
quality :: a -> ByteString -> Quality a

-- | Attaches the quality value '1'.
maxQuality :: a -> Quality a

-- | Attaches the quality value '0'.
minQuality :: a -> Quality a

-- | Parses a full Accept header into a list of quality-valued media types.
parseQuality :: Accept a => ByteString -> Maybe [Quality a]

-- | Matches a list of server-side resource options against a pre-parsed
--   quality-marked list of client-side preferences. A result of
--   <a>Nothing</a> means that nothing matched (which should indicate a 406
--   error). If two or more results arise with the same quality level and
--   specificity, then the first one in the server list is chosen.
--   
--   The use of the <a>Accept</a> type class allows the application of
--   either <a>MediaType</a> for the standard Accept header or
--   <a>ByteString</a> for any other Accept header which can be marked with
--   a quality value.
--   
--   <pre>
--   matchQuality ["text/html", "application/json"] &lt;$&gt; parseQuality header
--   </pre>
--   
--   For more information on the matching process see RFC 2616, section
--   14.1-4.
matchQuality :: Accept a => [a] -> [Quality a] -> Maybe a

-- | The equivalent of <a>matchQuality</a> above, except the resulting
--   choice is mapped to another value. Convenient for specifying how to
--   translate the resource into each of its available formats.
--   
--   <pre>
--   parseQuality header &gt;&gt;= maybe render406Error renderResource . mapQuality
--       [ ("text" // "html",        asHtml)
--       , ("application" // "json", asJson)
--       ]
--   </pre>
mapQuality :: Accept a => [(a, b)] -> [Quality a] -> Maybe b

-- | Defines methods for a type whose values can be matched against each
--   other in terms of an HTTP Accept-* header.
--   
--   This allows functions to work on both the standard Accept header and
--   others such as Accept-Language that still may use quality values.
class Show a => Accept a where hasExtensionParameters _ = False

-- | Specifies how to parse an Accept-* header after quality has been
--   handled.
parseAccept :: Accept a => ByteString -> Maybe a

-- | Evaluates whether either the left argument matches the right one.
--   
--   This relation must be a total order, where more specific terms on the
--   left can produce a match, but a less specific term on the left can
--   never produce a match. For instance, when matching against media types
--   it is important that if the client asks for a general type then we can
--   choose a more specific offering from the server, but if a client asks
--   for a specific type and the server only offers a more general form,
--   then we cannot generalise. In this case, the server types will be the
--   left argument, and the client types the right.
--   
--   For types with no concept of specificity, this operation is just
--   equality.
matches :: Accept a => a -> a -> Bool

-- | Evaluates whether the left argument is more specific than the right.
--   
--   This relation must be irreflexive and transitive. For types with no
--   concept of specificity, this is the empty relation (always false).
moreSpecificThan :: Accept a => a -> a -> Bool

-- | Indicates whether extension parameters are permitted after the weight
--   parameter when this type appears in an Accept header. Defaults to
--   false.
hasExtensionParameters :: Accept a => Proxy a -> Bool

-- | A class for header values, so they may be rendered to their
--   <a>ByteString</a> representation. Lists of header values and
--   quality-marked header values will render appropriately.
class RenderHeader h

-- | Render a header value to a UTF-8 <a>ByteString</a>.
renderHeader :: RenderHeader h => h -> ByteString
