| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Network.HTTP.Media
Description
A framework for parsing HTTP media type headers.
Synopsis
- data MediaType
- (//) :: ByteString -> ByteString -> MediaType
- (/:) :: MediaType -> ( ByteString , ByteString ) -> MediaType
- mainType :: MediaType -> CI ByteString
- subType :: MediaType -> CI ByteString
- parameters :: MediaType -> Parameters
- (/?) :: MediaType -> ByteString -> Bool
- (/.) :: MediaType -> ByteString -> Maybe ( CI ByteString )
- data Charset
- data Encoding
- data Language
- toParts :: Language -> [ CI ByteString ]
- matchAccept :: Accept a => [a] -> ByteString -> Maybe a
- mapAccept :: Accept a => [(a, b)] -> ByteString -> Maybe b
- mapAcceptMedia :: [( MediaType , b)] -> ByteString -> Maybe b
- mapAcceptCharset :: [( Charset , b)] -> ByteString -> Maybe b
- mapAcceptEncoding :: [( Encoding , b)] -> ByteString -> Maybe b
- mapAcceptLanguage :: [( Language , b)] -> ByteString -> Maybe b
- mapAcceptBytes :: [( ByteString , b)] -> ByteString -> Maybe b
- matchContent :: Accept a => [a] -> ByteString -> Maybe a
- mapContent :: Accept a => [(a, b)] -> ByteString -> Maybe b
- mapContentMedia :: [( MediaType , b)] -> ByteString -> Maybe b
- mapContentCharset :: [( Charset , b)] -> ByteString -> Maybe b
- mapContentEncoding :: [( Encoding , b)] -> ByteString -> Maybe b
- mapContentLanguage :: [( Language , b)] -> ByteString -> Maybe b
- data Quality a
- quality :: a -> ByteString -> Quality a
- data QualityOrder
- qualityOrder :: Quality a -> QualityOrder
- maxQuality :: a -> Quality a
- minQuality :: a -> Quality a
- parseQuality :: Accept a => ByteString -> Maybe [ Quality a]
- matchQuality :: Accept a => [a] -> [ Quality a] -> Maybe a
- mapQuality :: Accept a => [(a, b)] -> [ Quality a] -> Maybe b
-
class
Show
a =>
Accept
a
where
- parseAccept :: ByteString -> Maybe a
- matches :: a -> a -> Bool
- moreSpecificThan :: a -> a -> Bool
- hasExtensionParameters :: Proxy a -> Bool
-
class
RenderHeader
h
where
- renderHeader :: h -> ByteString
Media types
An HTTP media type, consisting of the type, subtype, and parameters.
Instances
| Eq MediaType Source # | |
| Ord MediaType Source # | |
|
Defined in Network.HTTP.Media.MediaType.Internal Methods compare :: MediaType -> MediaType -> Ordering Source # (<) :: MediaType -> MediaType -> Bool Source # (<=) :: MediaType -> MediaType -> Bool Source # (>) :: MediaType -> MediaType -> Bool Source # (>=) :: MediaType -> MediaType -> Bool Source # |
|
| Show MediaType Source # | |
| IsString MediaType Source # | |
|
Defined in Network.HTTP.Media.MediaType.Internal Methods fromString :: String -> MediaType Source # |
|
| Accept MediaType Source # | |
|
Defined in Network.HTTP.Media.MediaType.Internal |
|
| RenderHeader MediaType Source # | |
|
Defined in Network.HTTP.Media.MediaType.Internal Methods renderHeader :: MediaType -> ByteString Source # |
|
(//) :: ByteString -> ByteString -> MediaType Source #
Builds a
MediaType
without parameters. Can produce an error if
either type is invalid.
(/:) :: MediaType -> ( ByteString , ByteString ) -> MediaType Source #
Adds a parameter to a
MediaType
. Can produce an error if either
string is invalid.
parameters :: MediaType -> Parameters Source #
Retrieves the parameters of a
MediaType
.
(/?) :: MediaType -> ByteString -> Bool Source #
Evaluates if a
MediaType
has a parameter of the given name.
(/.) :: MediaType -> ByteString -> Maybe ( CI ByteString ) Source #
Retrieves a parameter from a
MediaType
.
Charsets
Instances
| Eq Charset Source # | |
| Ord Charset Source # | |
|
Defined in Network.HTTP.Media.Charset.Internal |
|
| Show Charset Source # | |
| IsString Charset Source # | |
|
Defined in Network.HTTP.Media.Charset.Internal Methods fromString :: String -> Charset Source # |
|
| Accept Charset Source # | |
|
Defined in Network.HTTP.Media.Charset.Internal |
|
| RenderHeader Charset Source # | |
|
Defined in Network.HTTP.Media.Charset.Internal Methods renderHeader :: Charset -> ByteString Source # |
|
Encodings
Suitable for HTTP encoding as defined in RFC7231 .
Specifically:
codings = content-coding / "identity" / "*"
Instances
| Eq Encoding Source # | |
| Ord Encoding Source # | |
|
Defined in Network.HTTP.Media.Encoding.Internal |
|
| Show Encoding Source # | |
| IsString Encoding Source # | |
|
Defined in Network.HTTP.Media.Encoding.Internal Methods fromString :: String -> Encoding Source # |
|
| Accept Encoding Source # | |
|
Defined in Network.HTTP.Media.Encoding.Internal |
|
| RenderHeader Encoding Source # | |
|
Defined in Network.HTTP.Media.Encoding.Internal Methods renderHeader :: Encoding -> ByteString Source # |
|
Languages
Suitable for HTTP language-ranges as defined in RFC4647 .
Specifically:
language-range = (1*8ALPHA *("-" 1*8alphanum)) / "*"
Instances
| Eq Language Source # | |
| Ord Language Source # | |
|
Defined in Network.HTTP.Media.Language.Internal |
|
| Show Language Source # | |
| IsString Language Source # | |
|
Defined in Network.HTTP.Media.Language.Internal Methods fromString :: String -> Language Source # |
|
| Accept Language Source # | |
|
Defined in Network.HTTP.Media.Language.Internal |
|
| RenderHeader Language Source # | |
|
Defined in Network.HTTP.Media.Language.Internal Methods renderHeader :: Language -> ByteString Source # |
|
toParts :: Language -> [ CI ByteString ] Source #
Converts
Language
to a list of its language parts. The wildcard
produces an empty list.
Accept matching
Arguments
| :: Accept a | |
| => [a] |
The server-side options |
| -> ByteString |
The client-side header value |
| -> Maybe a |
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.
Arguments
| :: Accept a | |
| => [(a, b)] |
The map of server-side preferences to values |
| -> ByteString |
The client-side header value |
| -> Maybe b |
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)
]
Arguments
| :: [( MediaType , b)] |
The map of server-side preferences to values |
| -> ByteString |
The client-side header value |
| -> Maybe b |
Arguments
| :: [( Charset , b)] |
The map of server-side preferences to values |
| -> ByteString |
The client-side header value |
| -> Maybe b |
Arguments
| :: [( Encoding , b)] |
The map of server-side preferences to values |
| -> ByteString |
The client-side header value |
| -> Maybe b |
Arguments
| :: [( Language , b)] |
The map of server-side preferences to values |
| -> ByteString |
The client-side header value |
| -> Maybe b |
Arguments
| :: [( ByteString , b)] |
The map of server-side preferences to values |
| -> ByteString |
The client-side header value |
| -> 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)
]
Content matching
Arguments
| :: Accept a | |
| => [a] |
The server-side response options |
| -> ByteString |
The client's request value |
| -> Maybe a |
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.
Arguments
| :: Accept a | |
| => [(a, b)] |
The map of server-side responses |
| -> ByteString |
The client request's header value |
| -> Maybe b |
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)
]
Arguments
| :: [( MediaType , b)] |
The map of server-side responses |
| -> ByteString |
The client request's header value |
| -> 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)
]
Arguments
| :: [( Charset , b)] |
The map of server-side responses |
| -> ByteString |
The client request's header value |
| -> 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)
]
Arguments
| :: [( Encoding , b)] |
The map of server-side responses |
| -> ByteString |
The client request's header value |
| -> 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)
]
Arguments
| :: [( Language , b)] |
The map of server-side responses |
| -> ByteString |
The client request's header value |
| -> 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)
]
Quality values
Attaches a quality value to data.
Instances
| Functor Quality Source # | |
| Eq a => Eq ( Quality a) Source # | |
| Ord a => Ord ( Quality a) Source # | |
|
Defined in Network.HTTP.Media.Quality Methods compare :: Quality a -> Quality a -> Ordering Source # (<) :: Quality a -> Quality a -> Bool Source # (<=) :: Quality a -> Quality a -> Bool Source # (>) :: Quality a -> Quality a -> Bool Source # (>=) :: Quality a -> Quality a -> Bool Source # |
|
| RenderHeader a => Show ( Quality a) Source # | |
| RenderHeader h => RenderHeader ( Quality h) Source # | |
|
Defined in Network.HTTP.Media.Quality Methods renderHeader :: Quality h -> ByteString Source # |
|
quality :: a -> ByteString -> Quality a Source #
Manually construct a quality value.
data QualityOrder Source #
An opaque ordered representation of quality values without attached data.
Instances
| Eq QualityOrder Source # | |
|
Defined in Network.HTTP.Media.Quality Methods (==) :: QualityOrder -> QualityOrder -> Bool Source # (/=) :: QualityOrder -> QualityOrder -> Bool Source # |
|
| Ord QualityOrder Source # | |
|
Defined in Network.HTTP.Media.Quality Methods compare :: QualityOrder -> QualityOrder -> Ordering Source # (<) :: QualityOrder -> QualityOrder -> Bool Source # (<=) :: QualityOrder -> QualityOrder -> Bool Source # (>) :: QualityOrder -> QualityOrder -> Bool Source # (>=) :: QualityOrder -> QualityOrder -> Bool Source # max :: QualityOrder -> QualityOrder -> QualityOrder Source # min :: QualityOrder -> QualityOrder -> QualityOrder Source # |
|
qualityOrder :: Quality a -> QualityOrder Source #
Remove the attached data from a quality value, retaining only the priority of the quality parameter.
maxQuality :: a -> Quality a Source #
Attaches the quality value '1'.
minQuality :: a -> Quality a Source #
Attaches the quality value '0'.
parseQuality :: Accept a => ByteString -> Maybe [ Quality a] Source #
Parses a full Accept header into a list of quality-valued media types.
Arguments
| :: Accept a | |
| => [a] |
The server-side options |
| -> [ Quality a] |
The pre-parsed client-side header value |
| -> Maybe 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.
Arguments
| :: Accept a | |
| => [(a, b)] |
The map of server-side preferences to values |
| -> [ Quality a] |
The client-side header value |
| -> Maybe b |
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)
]
Accept
class Show a => Accept a where Source #
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.
Minimal complete definition
Methods
parseAccept :: ByteString -> Maybe a Source #
Specifies how to parse an Accept-* header after quality has been handled.
matches :: a -> a -> Bool Source #
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.
moreSpecificThan :: a -> a -> Bool Source #
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).
hasExtensionParameters :: Proxy a -> Bool Source #
Indicates whether extension parameters are permitted after the weight parameter when this type appears in an Accept header. Defaults to false.
Instances
| Accept ByteString Source # | |
|
Defined in Network.HTTP.Media.Accept Methods parseAccept :: ByteString -> Maybe ByteString Source # matches :: ByteString -> ByteString -> Bool Source # moreSpecificThan :: ByteString -> ByteString -> Bool Source # |
|
| Accept Language Source # | |
|
Defined in Network.HTTP.Media.Language.Internal |
|
| Accept MediaType Source # | |
|
Defined in Network.HTTP.Media.MediaType.Internal |
|
| Accept Encoding Source # | |
|
Defined in Network.HTTP.Media.Encoding.Internal |
|
| Accept Charset Source # | |
|
Defined in Network.HTTP.Media.Charset.Internal |
|
Rendering
class RenderHeader h where Source #
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.
Instances
| RenderHeader ByteString Source # | |
|
Defined in Network.HTTP.Media.RenderHeader Methods renderHeader :: ByteString -> ByteString Source # |
|
| RenderHeader Language Source # | |
|
Defined in Network.HTTP.Media.Language.Internal Methods renderHeader :: Language -> ByteString Source # |
|
| RenderHeader MediaType Source # | |
|
Defined in Network.HTTP.Media.MediaType.Internal Methods renderHeader :: MediaType -> ByteString Source # |
|
| RenderHeader Encoding Source # | |
|
Defined in Network.HTTP.Media.Encoding.Internal Methods renderHeader :: Encoding -> ByteString Source # |
|
| RenderHeader Charset Source # | |
|
Defined in Network.HTTP.Media.Charset.Internal Methods renderHeader :: Charset -> ByteString Source # |
|
| RenderHeader h => RenderHeader [h] Source # | |
|
Defined in Network.HTTP.Media.RenderHeader Methods renderHeader :: [h] -> ByteString Source # |
|
| RenderHeader h => RenderHeader ( Quality h) Source # | |
|
Defined in Network.HTTP.Media.Quality Methods renderHeader :: Quality h -> ByteString Source # |
|