http-kinder-0.2.0.0: Generic kinds and types for working with HTTP

Safe HaskellNone
LanguageHaskell2010

Network.HTTP.Kinder.Header.Serialization

Contents

Description

HeaderNames define semantics for Text values seen in HTTP headers over the wire. This module provides classes to map both to and from these reprsentations.

Synopsis

Classes for encoding and decoding

class HeaderEncode n a where Source

Determines a Text representation for some value to be encoded as a value of a given HeaderName. Any proxy can be passed as the first argument, although Sing is a nice one to choose. Encodings may choose to not be represented on the wire at all as desired by returning Nothing. This implies default behavior.

Methods

headerEncode :: sing n -> a -> Maybe Text Source

Instances

class HeaderDecode n a where Source

Interprets a (possibly missing) Text representation for some value taking semantics at a given HeaderName. Any proxy can be passed as the first argument, although Sing is a nice one to choose. If a value is expected and no representation is provided then Nothing can be passed seeking a default value (should one exist).

Methods

headerDecode :: sing n -> Maybe Text -> Either String a Source

Instances

HeaderDecode ContentType MediaType Source 
HeaderDecode h t => HeaderDecode h (Maybe t) Source

Any value may be only optionally captured as desired

HeaderDecode n (Raw Text) Source

Returns the raw header value

HeaderDecode Accept [Quality MediaType] Source 

Listing constraints to type-level lists

type family AllHeaderEncodes hs :: Constraint Source

For a given concrete type a, a list of pairs ts satisfies AllHeaderEncode a ts if each (n, a) in ts has HeaderEncode n a.

Equations

AllHeaderEncodes `[]` = () 
AllHeaderEncodes (`(n, a)` : hs) = (HeaderEncode n a, AllHeaderEncodes hs) 

type family AllHeaderDecodes hs :: Constraint Source

For a given concrete type a, a list of pairs ts satisfies AllHeaderDecode a ts if each (n, a) in ts has HeaderDecode n a.

Equations

AllHeaderDecodes `[]` = () 
AllHeaderDecodes (`(n, a)` : hs) = (HeaderDecode n a, AllHeaderDecodes hs) 

Extra serialization utilities

headerEncodePair :: forall a n. HeaderEncode n a => Sing n -> a -> Maybe (CI ByteString, ByteString) Source

Encode a HeaderName singleton and a HeaderEncode-represented value as a pair of name and representation, ready to be sent over the wire.

headerEncodeBS :: HeaderEncode n a => sing n -> a -> Maybe ByteString Source

While the semantics of HTTP headers are built off of Text-like values, usually we require a ByteString for emission. This helper function converts a header value directly to a ByteString.

headerDecodeBS :: HeaderDecode n a => sing n -> Maybe ByteString -> Either String a Source

While HTTP header semantics are built off of Text-like values, we usually read a raw ByteString from the wire. This helper function combines a HeaderDecode with a UTF-8 decode so as to attempt to deserialize header values directly from a ByteString.

Utilities for writing serialization instances

displaySetOpt :: Set Text -> Maybe Text Source

Output a set of text items as a comma-delimited list OR return nothing if the set is empty

uniqueSet :: (Ord v, HeaderEncode n (Set v)) => sing n -> [v] -> Maybe Text Source

Extend a HeaderEncode instance on Set v to [v].

required :: (Text -> Either String a) -> Maybe Text -> Either String a Source

Fail to decode if there is no header. For headers which lack default values. If a header lacks a natural default then avoiding failure should be explicitly requested in the types by wrapping it with a Maybe.

withDefault :: a -> (Text -> Either String a) -> Maybe Text -> Either String a Source

For headers with natural notions of default values.