Safe Haskell	Safe
Language	Haskell2010

Network.HTTP.Media

Contents

Media types
Languages
Accept matching
Content matching
Quality values
Accept
Rendering

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 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
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
mapContentLanguage :: [(Language, b)] -> ByteString -> Maybe b
data Quality a
quality :: a -> ByteString -> Quality a
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
class RenderHeader h where

Media types

data MediaType Source #

An HTTP media type, consisting of the type, subtype, and parameters.

Instances

Eq MediaType Source #
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods (==) :: MediaType -> MediaType -> Bool # (/=) :: MediaType -> MediaType -> Bool #
Ord MediaType Source #
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods compare :: MediaType -> MediaType -> Ordering # (<) :: MediaType -> MediaType -> Bool # (<=) :: MediaType -> MediaType -> Bool # (>) :: MediaType -> MediaType -> Bool # (>=) :: MediaType -> MediaType -> Bool # max :: MediaType -> MediaType -> MediaType # min :: MediaType -> MediaType -> MediaType #
Show MediaType Source #
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods showsPrec :: Int -> MediaType -> ShowS # show :: MediaType -> String # showList :: [MediaType] -> ShowS #
IsString MediaType Source #
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods fromString :: String -> MediaType #
Accept MediaType Source #
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods parseAccept :: ByteString -> Maybe MediaType Source # matches :: MediaType -> MediaType -> Bool Source # moreSpecificThan :: MediaType -> MediaType -> Bool Source # hasExtensionParameters :: Proxy MediaType -> Bool Source #
RenderHeader MediaType Source #
Instance details 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.

mainType :: MediaType -> CI ByteString Source #

Retrieves the main type of a MediaType.

subType :: MediaType -> CI ByteString Source #

Retrieves the sub type of a MediaType.

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.

Languages

data Language Source #

Suitable for HTTP language-ranges as defined in RFC2616.

Specifically:

language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )

Instances

Eq Language Source #
Instance details Defined in Network.HTTP.Media.Language.Internal Methods (==) :: Language -> Language -> Bool # (/=) :: Language -> Language -> Bool #
Ord Language Source #
Instance details Defined in Network.HTTP.Media.Language.Internal Methods compare :: Language -> Language -> Ordering # (<) :: Language -> Language -> Bool # (<=) :: Language -> Language -> Bool # (>) :: Language -> Language -> Bool # (>=) :: Language -> Language -> Bool # max :: Language -> Language -> Language # min :: Language -> Language -> Language #
Show Language Source #
Instance details Defined in Network.HTTP.Media.Language.Internal Methods showsPrec :: Int -> Language -> ShowS # show :: Language -> String # showList :: [Language] -> ShowS #
IsString Language Source #
Instance details Defined in Network.HTTP.Media.Language.Internal Methods fromString :: String -> Language #
Accept Language Source #
Instance details Defined in Network.HTTP.Media.Language.Internal Methods parseAccept :: ByteString -> Maybe Language Source # matches :: Language -> Language -> Bool Source # moreSpecificThan :: Language -> Language -> Bool Source # hasExtensionParameters :: Proxy Language -> Bool Source #
RenderHeader Language Source #
Instance details 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

matchAccept Source #

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.

mapAccept Source #

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)
    ]

mapAcceptMedia Source #

Arguments

:: [(MediaType, b)]	The map of server-side preferences to values
-> ByteString	The client-side header value
-> 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)
    ]

mapAcceptLanguage Source #

Arguments

:: [(Language, b)]	The map of server-side preferences to values
-> ByteString	The client-side header value
-> 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
    [ ("text/html",        asHtml)
    , ("application/json", asJson)
    ]

mapAcceptBytes Source #

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
    [ ("compress", compress)
    , ("gzip",     gzip)
    ]

Content matching

matchContent Source #

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.

mapContent Source #

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)
    ]

mapContentMedia Source #

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)
        ]

mapContentLanguage Source #

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.

getContentType >>=
    maybe send415Error readRequestBodyWith . mapContentLanguage
        [ ("application/json", parseJson)
        , ("text/plain",       parseText)
        ]

Quality values

data Quality a Source #

Attaches a quality value to data.

Instances

Eq a => Eq (Quality a) Source #
Instance details Defined in Network.HTTP.Media.Quality Methods (==) :: Quality a -> Quality a -> Bool # (/=) :: Quality a -> Quality a -> Bool #
Ord a => Ord (Quality a) Source #
Instance details Defined in Network.HTTP.Media.Quality Methods compare :: Quality a -> Quality a -> Ordering # (<) :: Quality a -> Quality a -> Bool # (<=) :: Quality a -> Quality a -> Bool # (>) :: Quality a -> Quality a -> Bool # (>=) :: Quality a -> Quality a -> Bool # max :: Quality a -> Quality a -> Quality a # min :: Quality a -> Quality a -> Quality a #
RenderHeader a => Show (Quality a) Source #
Instance details Defined in Network.HTTP.Media.Quality Methods showsPrec :: Int -> Quality a -> ShowS # show :: Quality a -> String # showList :: [Quality a] -> ShowS #
RenderHeader h => RenderHeader (Quality h) Source #
Instance details Defined in Network.HTTP.Media.Quality Methods renderHeader :: Quality h -> ByteString Source #

quality :: a -> ByteString -> Quality a Source #

Manually construct a quality value.

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.

matchQuality Source #

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.

mapQuality Source #

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

parseAccept, matches, moreSpecificThan

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 #
Instance details Defined in Network.HTTP.Media.Accept Methods parseAccept :: ByteString -> Maybe ByteString Source # matches :: ByteString -> ByteString -> Bool Source # moreSpecificThan :: ByteString -> ByteString -> Bool Source # hasExtensionParameters :: Proxy ByteString -> Bool Source #
Accept Language Source #
Instance details Defined in Network.HTTP.Media.Language.Internal Methods parseAccept :: ByteString -> Maybe Language Source # matches :: Language -> Language -> Bool Source # moreSpecificThan :: Language -> Language -> Bool Source # hasExtensionParameters :: Proxy Language -> Bool Source #
Accept MediaType Source #
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods parseAccept :: ByteString -> Maybe MediaType Source # matches :: MediaType -> MediaType -> Bool Source # moreSpecificThan :: MediaType -> MediaType -> Bool Source # hasExtensionParameters :: Proxy MediaType -> Bool Source #

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.

Minimal complete definition

renderHeader

Methods

renderHeader :: h -> ByteString Source #

Render a header value to a UTF-8 ByteString.

Instances

RenderHeader ByteString Source #
Instance details Defined in Network.HTTP.Media.RenderHeader Methods renderHeader :: ByteString -> ByteString Source #
RenderHeader Language Source #
Instance details Defined in Network.HTTP.Media.Language.Internal Methods renderHeader :: Language -> ByteString Source #
RenderHeader MediaType Source #
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods renderHeader :: MediaType -> ByteString Source #
RenderHeader h => RenderHeader [h] Source #
Instance details Defined in Network.HTTP.Media.RenderHeader Methods renderHeader :: [h] -> ByteString Source #
RenderHeader h => RenderHeader (Quality h) Source #
Instance details Defined in Network.HTTP.Media.Quality Methods renderHeader :: Quality h -> ByteString Source #