Web.HttpApiData.Internal

Convert Haskell values to and from HTTP API data such as URL pieces, headers and query parameters.

Documentation

class ToHttpApiData a where

Convert value to HTTP API data.

Minimal complete definition

toUrlPiece | toQueryParam

Methods

toUrlPiece :: a -> Text

Convert to URL path piece.

toHeader :: a -> ByteString

Convert to HTTP header value.

toQueryParam :: a -> Text

Convert to query param value.

Instances

ToHttpApiData Bool

ToHttpApiData Char

ToHttpApiData Double

ToHttpApiData Float

ToHttpApiData Int

ToHttpApiData Int8

ToHttpApiData Int16

ToHttpApiData Int32

ToHttpApiData Int64

ToHttpApiData Integer

ToHttpApiData Ordering

ToHttpApiData Word

ToHttpApiData Word8

ToHttpApiData Word16

ToHttpApiData Word32

ToHttpApiData Word64

ToHttpApiData String

ToHttpApiData ()

>>> toUrlPiece ()
"_"

ToHttpApiData Void

ToHttpApiData Version

>>> toUrlPiece (Version [1, 2, 3] [])
"1.2.3"

ToHttpApiData All

ToHttpApiData Any

ToHttpApiData Text

ToHttpApiData Text

ToHttpApiData Day

ToHttpApiData a => ToHttpApiData (Dual a)

ToHttpApiData a => ToHttpApiData (Sum a)

ToHttpApiData a => ToHttpApiData (Product a)

ToHttpApiData a => ToHttpApiData (First a)

ToHttpApiData a => ToHttpApiData (Last a)

ToHttpApiData a => ToHttpApiData (Maybe a)

>>> toUrlPiece (Just "Hello")
"just Hello"

(ToHttpApiData a, ToHttpApiData b) => ToHttpApiData (Either a b)

>>> toUrlPiece (Left "err" :: Either String Int)
"left err"
>>> toUrlPiece (Right 3 :: Either String Int)
"right 3"

class FromHttpApiData a where

Parse value from HTTP API data.

Minimal complete definition

parseUrlPiece | parseQueryParam

Methods

parseUrlPiece :: Text -> Either Text a

Parse URL path piece.

parseHeader :: ByteString -> Either Text a

Parse HTTP header value.

parseQueryParam :: Text -> Either Text a

Parse query param value.

Instances

FromHttpApiData Bool

FromHttpApiData Char

FromHttpApiData Double

FromHttpApiData Float

FromHttpApiData Int

FromHttpApiData Int8

FromHttpApiData Int16

FromHttpApiData Int32

FromHttpApiData Int64

FromHttpApiData Integer

FromHttpApiData Ordering

FromHttpApiData Word

FromHttpApiData Word8

FromHttpApiData Word16

FromHttpApiData Word32

FromHttpApiData Word64

FromHttpApiData String

FromHttpApiData ()

>>> parseUrlPiece "_" :: Either Text ()
Right ()

FromHttpApiData Void

FromHttpApiData Version

>>> showVersion <$> parseUrlPiece "1.2.3"
Right "1.2.3"

FromHttpApiData All

FromHttpApiData Any

FromHttpApiData Text

FromHttpApiData Text

FromHttpApiData Day

FromHttpApiData a => FromHttpApiData (Dual a)

FromHttpApiData a => FromHttpApiData (Sum a)

FromHttpApiData a => FromHttpApiData (Product a)

FromHttpApiData a => FromHttpApiData (First a)

FromHttpApiData a => FromHttpApiData (Last a)

FromHttpApiData a => FromHttpApiData (Maybe a)

>>> parseUrlPiece "Just 123" :: Either Text (Maybe Int)
Right (Just 123)

(FromHttpApiData a, FromHttpApiData b) => FromHttpApiData (Either a b)

>>> parseUrlPiece "Right 123" :: Either Text (Either String Int)
Right (Right 123)

parseUrlPieceMaybe :: FromHttpApiData a => Text -> Maybe a

Parse URL path piece in a Maybe.

>>> parseUrlPieceMaybe "12" :: Maybe Int
Just 12

parseHeaderMaybe :: FromHttpApiData a => ByteString -> Maybe a

Parse HTTP header value in a Maybe.

>>> parseHeaderMaybe "hello" :: Maybe Text
Just "hello"

parseQueryParamMaybe :: FromHttpApiData a => Text -> Maybe a

Parse query param value in a Maybe.

>>> parseQueryParamMaybe "true" :: Maybe Bool
Just True

defaultParseError :: Text -> Either Text a

Default parsing error.

parseMaybeTextData :: (Text -> Maybe a) -> Text -> Either Text a

Convert Maybe parser into Either Text parser with default error message.

showTextData :: Show a => a -> Text

Convert to URL piece using Show instance. The result is always lower cased.

>>> showTextData True
"true"

This can be used as a default implementation for enumeration types:

>>> data MyData = Foo | Bar | Baz deriving (Show)
>>> instance ToHttpApiData MyData where toUrlPiece = showTextData
>>> toUrlPiece Foo
"foo"

showt :: Show a => a -> Text

Like show, but returns Text.

parseUrlPieceWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a

Parse given text case insensitive and return the rest of the input.

>>> parseUrlPieceWithPrefix "Just " "just 10" :: Either Text Int
Right 10
>>> parseUrlPieceWithPrefix "Left " "left" :: Either Text Bool
Left "could not parse: `left'"

This can be used to implement FromHttpApiData for single field constructors:

>>> data Foo = Foo Int deriving (Show)
>>> instance FromHttpApiData Foo where parseUrlPiece s = Foo <$> parseUrlPieceWithPrefix "Foo " s
>>> parseUrlPiece "foo 1" :: Either Text Foo
Right (Foo 1)

parseBoundedCaseInsensitiveTextData :: forall a. (Show a, Bounded a, Enum a) => Text -> Either Text a

Parse values case insensitively based on Show instance.

>>> parseBoundedCaseInsensitiveTextData "true" :: Either Text Bool
Right True
>>> parseBoundedCaseInsensitiveTextData "FALSE" :: Either Text Bool
Right False

This can be used as a default implementation for enumeration types:

>>> data MyData = Foo | Bar | Baz deriving (Show, Bounded, Enum)
>>> instance FromHttpApiData MyData where parseUrlPiece = parseBoundedCaseInsensitiveTextData
>>> parseUrlPiece "foo" :: Either Text MyData
Right Foo

readMaybeTextData :: Read a => Text -> Maybe a

Parse URL piece using Read instance.

readEitherTextData :: Read a => Text -> Either Text a

Parse URL piece using Read instance.

runReader :: Reader a -> Text -> Either Text a

Run Reader as HTTP API data parser.

parseBounded :: forall a. (Bounded a, Integral a) => Reader Integer -> Text -> Either Text a

Run Reader to parse bounded integral value with bounds checking.

>>> parseBounded decimal "256" :: Either Text Word8
Left "out of bounds: `256' (should be between 0 and 255)"