| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Web.HttpApiData
Description
Convert Haskell values to and from HTTP API data such as URL pieces, headers and query parameters.
Synopsis
- class ToHttpApiData a where
- toUrlPiece :: a -> Text
- toEncodedUrlPiece :: a -> Builder
- toHeader :: a -> ByteString
- toQueryParam :: a -> Text
- toEncodedQueryParam :: a -> Builder
- class FromHttpApiData a where
- parseUrlPiece :: Text -> Either Text a
- parseHeader :: ByteString -> Either Text a
- parseQueryParam :: Text -> Either Text a
- parseUrlPieceMaybe :: FromHttpApiData a => Text -> Maybe a
- parseHeaderMaybe :: FromHttpApiData a => ByteString -> Maybe a
- parseQueryParamMaybe :: FromHttpApiData a => Text -> Maybe a
- parseUrlPieceWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a
- parseHeaderWithPrefix :: FromHttpApiData a => ByteString -> ByteString -> Either Text a
- parseQueryParamWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a
- toUrlPieces :: (Functor t, ToHttpApiData a) => t a -> t Text
- parseUrlPieces :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)
- toQueryParams :: (Functor t, ToHttpApiData a) => t a -> t Text
- parseQueryParams :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)
- parseBoundedUrlPiece :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a
- parseBoundedQueryParam :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a
- parseBoundedHeader :: (ToHttpApiData a, Bounded a, Enum a) => ByteString -> Either Text a
- parseBoundedEnumOf :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a
- parseBoundedEnumOfI :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a
- parseBoundedTextData :: (Show a, Bounded a, Enum a) => Text -> Either Text a
- newtype LenientData a = LenientData {
- getLenientData :: Either Text a
- showTextData :: Show a => a -> Text
- readTextData :: Read a => Text -> Either Text a
Examples
Booleans:
>>>toUrlPiece True"true">>>parseUrlPiece "false" :: Either Text BoolRight False>>>parseUrlPieces ["true", "false", "undefined"] :: Either Text [Bool]Left "could not parse: `undefined'"
Numbers:
>>>toQueryParam 45.2"45.2">>>parseQueryParam "452" :: Either Text IntRight 452>>>toQueryParams [1..5] :: [Text]["1","2","3","4","5"]>>>parseQueryParams ["127", "255"] :: Either Text [Int8]Left "out of bounds: `255' (should be between -128 and 127)"
Strings:
>>>toHeader "hello""hello">>>parseHeader "world" :: Either Text StringRight "world"
Calendar day:
>>>toQueryParam (fromGregorian 2015 10 03)"2015-10-03">>>toGregorian <$> parseQueryParam "2016-12-01"Right (2016,12,1)
Classes
class ToHttpApiData a where Source #
Convert value to HTTP API data.
WARNING: Do not derive this using DeriveAnyClass as the generated
instance will loop indefinitely.
Minimal complete definition
Methods
toUrlPiece :: a -> Text Source #
Convert to URL path piece.
toEncodedUrlPiece :: a -> Builder Source #
Convert to a URL path piece, making sure to encode any special chars.
The default definition uses urlEncodeBuilder False
toHeader :: a -> ByteString Source #
Convert to HTTP header value.
toQueryParam :: a -> Text Source #
Convert to query param value.
toEncodedQueryParam :: a -> Builder Source #
Convert to URL query param,
The default definition uses urlEncodeBuilder True
Since: 0.5.1
Instances
class FromHttpApiData a where Source #
Parse value from HTTP API data.
WARNING: Do not derive this using DeriveAnyClass as the generated
instance will loop indefinitely.
Minimal complete definition
Methods
parseUrlPiece :: Text -> Either Text a Source #
Parse URL path piece.
parseHeader :: ByteString -> Either Text a Source #
Parse HTTP header value.
parseQueryParam :: Text -> Either Text a Source #
Parse query param value.
Instances
Maybe
MaybeparseUrlPieceMaybe :: FromHttpApiData a => Text -> Maybe a Source #
Parse URL path piece in a Maybe
>>>parseUrlPieceMaybe "12" :: Maybe IntJust 12
parseHeaderMaybe :: FromHttpApiData a => ByteString -> Maybe a Source #
Parse HTTP header value in a Maybe
>>>parseHeaderMaybe "hello" :: Maybe TextJust "hello"
parseQueryParamMaybe :: FromHttpApiData a => Text -> Maybe a Source #
Parse query param value in a Maybe
>>>parseQueryParamMaybe "true" :: Maybe BoolJust True
Prefix parsers
parseUrlPieceWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a Source #
Case insensitive.
Parse given text case insensitive and then parse the rest of the input
using parseUrlPiece
>>>parseUrlPieceWithPrefix "Just " "just 10" :: Either Text IntRight 10>>>parseUrlPieceWithPrefix "Left " "left" :: Either Text BoolLeft "could not parse: `left'"
This can be used to implement FromHttpApiData
>>>data Foo = Foo Int deriving (Show)>>>instance FromHttpApiData Foo where parseUrlPiece s = Foo <$> parseUrlPieceWithPrefix "Foo " s>>>parseUrlPiece "foo 1" :: Either Text FooRight (Foo 1)
parseHeaderWithPrefix :: FromHttpApiData a => ByteString -> ByteString -> Either Text a Source #
Parse given bytestring then parse the rest of the input using parseHeader
data BasicAuthToken = BasicAuthToken Text deriving (Show) instance FromHttpApiData BasicAuthToken where parseHeader h = BasicAuthToken <$> parseHeaderWithPrefix "Basic " h parseQueryParam p = BasicAuthToken <$> parseQueryParam p
>>>parseHeader "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" :: Either Text BasicAuthTokenRight (BasicAuthToken "QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
parseQueryParamWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a Source #
Case insensitive.
Parse given text case insensitive and then parse the rest of the input
using parseQueryParam
>>>parseQueryParamWithPrefix "z" "z10" :: Either Text IntRight 10
Multiple URL pieces
toUrlPieces :: (Functor t, ToHttpApiData a) => t a -> t Text Source #
Convert multiple values to a list of URL pieces.
>>>toUrlPieces [1, 2, 3] :: [Text]["1","2","3"]
parseUrlPieces :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a) Source #
Parse multiple URL pieces.
>>>parseUrlPieces ["true", "false"] :: Either Text [Bool]Right [True,False]>>>parseUrlPieces ["123", "hello", "world"] :: Either Text [Int]Left "could not parse: `hello' (input does not start with a digit)"
Multiple query params
toQueryParams :: (Functor t, ToHttpApiData a) => t a -> t Text Source #
Convert multiple values to a list of query parameter values.
>>>toQueryParams [fromGregorian 2015 10 03, fromGregorian 2015 12 01] :: [Text]["2015-10-03","2015-12-01"]
parseQueryParams :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a) Source #
Parse multiple query parameters.
>>>parseQueryParams ["1", "2", "3"] :: Either Text [Int]Right [1,2,3]>>>parseQueryParams ["64", "128", "256"] :: Either Text [Word8]Left "out of bounds: `256' (should be between 0 and 255)"
Parsers for BoundedEnum
BoundedEnumparseBoundedUrlPiece :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a Source #
Case insensitive.
Parse values case insensitively based on ToHttpApiDatatoUrlPiece
parseBoundedQueryParam :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a Source #
Case insensitive.
Parse values case insensitively based on ToHttpApiDatatoQueryParam
parseBoundedHeader :: (ToHttpApiData a, Bounded a, Enum a) => ByteString -> Either Text a Source #
Parse values based on ToHttpApiDatatoHeader
parseBoundedEnumOf :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a Source #
Parse values based on a precalculated mapping of their Text
>>>parseBoundedEnumOf toUrlPiece "true" :: Either Text BoolRight True
For case insensitive parser see parseBoundedEnumOfI.
parseBoundedEnumOfI :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a Source #
Case insensitive.
Parse values case insensitively based on a precalculated mapping
of their Text
>>>parseBoundedEnumOfI toUrlPiece "FALSE" :: Either Text BoolRight False
For case sensitive parser see parseBoundedEnumOf.
parseBoundedTextData :: (Show a, Bounded a, Enum a) => Text -> Either Text a Source #
Case insensitive.
Parse values case insensitively based on Show
>>>parseBoundedTextData "true" :: Either Text BoolRight True>>>parseBoundedTextData "FALSE" :: Either Text BoolRight 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 = parseBoundedTextData>>>parseUrlPiece "foo" :: Either Text MyDataRight Foo
Lenient data
newtype LenientData a Source #
Lenient parameters. FromHttpApiData combinators always return Right.
Since: 0.3.5
Constructors
| LenientData | |
Fields
| |
Instances
Other helpers
showTextData :: Show a => a -> Text Source #
Lower case.
Convert to URL piece using Show
>>>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"
readTextData :: Read a => Text -> Either Text a Source #
Parse URL piece using Read
Use for types which do not involve letters:
>>>readTextData "1991-06-02" :: Either Text DayRight 1991-06-02
This parser is case sensitive and will not match showTextData
>>>readTextData (showTextData True) :: Either Text BoolLeft "could not parse: `true'"
See parseBoundedTextData