-- 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
--   mapAcceptMedia:
--   
--   
--   getHeader >>= maybe send406Error sendResourceWith . mapAcceptMedia
--       [ ("text/html",        asHtml)
--       , ("application/json", asJson)
--       ]
--   
--   
--   Similarly, the Content-Type header can be used to produce a parser for
--   request bodies based on the given content type with
--   mapContentMedia:
--   
--   
--   getContentType >>= maybe send415Error readRequestBodyWith . mapContentMedia
--       [ ("application/json", parseJson)
--       , ("text/plain",       parseText)
--       ]
--   
--   
--   The API is agnostic to your choice of server.
@package http-media
@version 0.8.1.1

-- | Defines the Accept 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

-- | 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
instance Network.HTTP.Media.Accept.Accept Data.ByteString.Internal.Type.ByteString

-- | Defines the RenderHeader type class, with the
--   renderHeader method. renderHeader can be used to render
--   basic header values (acting as identity on ByteStrings), 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
--   ByteString representation. Lists of header values and
--   quality-marked header values will render appropriately.
class RenderHeader h

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

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

-- | Suitable for HTTP language-ranges as defined in RFC4647.
--   
--   Specifically:
--   
--   
--   language-range = (1*8ALPHA *("-" 1*8alphanum)) / "*"
--   
data Language

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

-- | Defines the MediaType accept header with an Accept
--   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

-- | MediaType parameters.
type Parameters = Map CI ByteString CI ByteString

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

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

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

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

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

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

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

-- | Defines the Encoding accept header with an Accept
--   instance for use in encoding negotiation.
module Network.HTTP.Media.Encoding

-- | Suitable for HTTP encoding as defined in RFC7231.
--   
--   Specifically:
--   
--   
--   codings = content-coding / "identity" / "*"
--   
data Encoding

-- | Defines the Charset accept header with an Accept
--   instance for use in encoding negotiation.
module Network.HTTP.Media.Charset

-- | Suitable for HTTP charset as defined in RFC7231.
--   
--   Specifically:
--   
--   
--   charset = token / "*"
--   
data Charset

-- | 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 MediaType without parameters. Can produce an error if
--   either type is invalid.
(//) :: ByteString -> ByteString -> MediaType

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

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

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

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

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

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

-- | Suitable for HTTP charset as defined in RFC7231.
--   
--   Specifically:
--   
--   
--   charset = token / "*"
--   
data Charset

-- | Suitable for HTTP encoding as defined in RFC7231.
--   
--   Specifically:
--   
--   
--   codings = content-coding / "identity" / "*"
--   
data Encoding

-- | Suitable for HTTP language-ranges as defined in RFC4647.
--   
--   Specifically:
--   
--   
--   language-range = (1*8ALPHA *("-" 1*8alphanum)) / "*"
--   
data Language

-- | Converts Language 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
--   Nothing 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 Accept type class allows the application of
--   either MediaType for the standard Accept header or
--   ByteString for any other Accept header which can be marked with
--   a quality value.
--   
--   
--   matchAccept ["text/html", "application/json"] <$> getHeader
--   
--   
--   For more information on the matching process see RFC 2616, section
--   14.1-4.
matchAccept :: Accept a => [a] -> ByteString -> Maybe a

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

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

-- | A specialisation of mapAccept that only takes Charset as
--   its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   
--   getHeader >>= maybe render406Error renderResource . mapAcceptCharset
--       [ ("utf-8",    inUtf8)
--       , ("us-ascii", inAscii)
--       ]
--   
mapAcceptCharset :: [(Charset, b)] -> ByteString -> Maybe b

-- | A specialisation of mapAccept that only takes Encoding
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   
--   getHeader >>= maybe render406Error renderResource . mapAcceptEncoding
--       [ ("compress", compress)
--       , ("identity", id)
--       ]
--   
mapAcceptEncoding :: [(Encoding, b)] -> ByteString -> Maybe b

-- | A specialisation of mapAccept that only takes Language
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   
--   getHeader >>= maybe render406Error renderResource . mapAcceptLanguage
--       [ ("en-gb", inBritishEnglish)
--       , ("fr",    inFrench)
--       ]
--   
mapAcceptLanguage :: [(Language, b)] -> ByteString -> Maybe b

-- | A specialisation of mapAccept that only takes ByteString
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   
--   getHeader >>= maybe render406Error encodeResourceWith . mapAcceptBytes
--       [ ("abc", abc)
--       , ("xyz", xyz)
--       ]
--   
mapAcceptBytes :: [(ByteString, b)] -> ByteString -> Maybe b

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

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

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

-- | A specialisation of mapContent that only takes Charset
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   
--   getContentCharset >>=
--       maybe send415Error readRequestBodyWith . mapContentCharset
--           [ ("utf-8",    parseUtf8)
--           , ("us-ascii", parseAscii)
--           ]
--   
mapContentCharset :: [(Charset, b)] -> ByteString -> Maybe b

-- | A specialisation of mapContent that only takes Encoding
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   
--   getContentEncoding >>=
--       maybe send415Error readRequestBodyWith . mapContentEncoding
--           [ ("compress", decompress)
--           , ("identity", id)
--           ]
--   
mapContentEncoding :: [(Encoding, b)] -> ByteString -> Maybe b

-- | A specialisation of mapContent that only takes Language
--   as its input, to avoid ambiguous-type errors when using string literal
--   overloading.
--   
--   
--   getContentLanguage >>=
--       maybe send415Error readRequestBodyWith . mapContentLanguage
--           [ ("en-gb", parseBritishEnglish)
--           , ("fr",    parseFrench)
--           ]
--   
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

-- | An opaque ordered representation of quality values without attached
--   data.
data QualityOrder

-- | Remove the attached data from a quality value, retaining only the
--   priority of the quality parameter.
qualityOrder :: Quality a -> QualityOrder

-- | Whether the quality value is greater than zero; otherwise the value
--   should never be accepted, even when no other options are available.
isAcceptable :: Quality a -> Bool

-- | 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
--   Nothing 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 Accept type class allows the application of
--   either MediaType for the standard Accept header or
--   ByteString for any other Accept header which can be marked with
--   a quality value.
--   
--   
--   matchQuality ["text/html", "application/json"] <$> parseQuality header
--   
--   
--   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 matchQuality above, except the resulting
--   choice is mapped to another value. Convenient for specifying how to
--   translate the resource into each of its available formats.
--   
--   
--   parseQuality header >>= maybe render406Error renderResource . mapQuality
--       [ ("text" // "html",        asHtml)
--       , ("application" // "json", asJson)
--       ]
--   
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

-- | 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
--   ByteString representation. Lists of header values and
--   quality-marked header values will render appropriately.
class RenderHeader h

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