-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Converting to/from HTTP API data like URL pieces, headers and query parameters.
--
-- Please see README.md
@package http-api-data
@version 0.2.1
-- | Convert Haskell values to and from HTTP API data such as URL pieces,
-- headers and query parameters.
module Web.HttpApiData.Internal
-- | Convert value to HTTP API data.
class ToHttpApiData a where toUrlPiece = toQueryParam toHeader = encodeUtf8 . toUrlPiece toQueryParam = toUrlPiece
-- | Convert to URL path piece.
toUrlPiece :: ToHttpApiData a => a -> Text
-- | Convert to HTTP header value.
toHeader :: ToHttpApiData a => a -> ByteString
-- | Convert to query param value.
toQueryParam :: ToHttpApiData a => a -> Text
-- | Parse value from HTTP API data.
class FromHttpApiData a where parseUrlPiece = parseQueryParam parseHeader = parseUrlPiece . decodeUtf8 parseQueryParam = parseUrlPiece
-- | Parse URL path piece.
parseUrlPiece :: FromHttpApiData a => Text -> Either Text a
-- | Parse HTTP header value.
parseHeader :: FromHttpApiData a => ByteString -> Either Text a
-- | Parse query param value.
parseQueryParam :: FromHttpApiData a => Text -> Either Text a
-- | Convert multiple values to a list of URL pieces.
--
--
-- >>> toUrlPieces [1, 2, 3]
-- ["1","2","3"]
--
toUrlPieces :: (Functor t, ToHttpApiData a) => t a -> t Text
-- | 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)"
--
parseUrlPieces :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)
-- | Convert multiple values to a list of query parameter values.
--
--
-- >>> toQueryParams [fromGregorian 2015 10 03, fromGregorian 2015 12 01]
-- ["2015-10-03","2015-12-01"]
--
toQueryParams :: (Functor t, ToHttpApiData a) => t a -> t Text
-- | 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)"
--
parseQueryParams :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)
-- | Parse URL path piece in a Maybe.
--
--
-- >>> parseUrlPieceMaybe "12" :: Maybe Int
-- Just 12
--
parseUrlPieceMaybe :: FromHttpApiData a => Text -> Maybe a
-- | Parse HTTP header value in a Maybe.
--
--
-- >>> parseHeaderMaybe "hello" :: Maybe Text
-- Just "hello"
--
parseHeaderMaybe :: FromHttpApiData a => ByteString -> Maybe a
-- | Parse query param value in a Maybe.
--
--
-- >>> parseQueryParamMaybe "true" :: Maybe Bool
-- Just True
--
parseQueryParamMaybe :: FromHttpApiData a => Text -> Maybe a
-- | Default parsing error.
defaultParseError :: Text -> Either Text a
-- | Convert Maybe parser into Either
-- Text parser with default error message.
parseMaybeTextData :: (Text -> Maybe a) -> (Text -> Either Text a)
-- | Lower case.
--
-- 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"
--
showTextData :: Show a => a -> Text
-- | Like show, but returns Text.
showt :: Show a => a -> Text
-- | Case insensitive.
--
-- Parse given text case insensitive and then parse the rest of the input
-- using parseUrlPiece.
--
--
-- >>> 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)
--
parseUrlPieceWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a
-- | 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 BasicAuthToken
-- Right (BasicAuthToken "QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
--
parseHeaderWithPrefix :: FromHttpApiData a => ByteString -> ByteString -> Either Text a
-- | Case insensitive.
--
-- Parse given text case insensitive and then parse the rest of the input
-- using parseQueryParam.
--
--
-- >>> parseQueryParamWithPrefix "z" "z10" :: Either Text Int
-- Right 10
--
parseQueryParamWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a
-- | Case insensitive.
--
-- Parse values case insensitively based on Show
-- instance.
--
--
-- >>> parseBoundedTextData "true" :: Either Text Bool
-- Right True
--
-- >>> parseBoundedTextData "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 = parseBoundedTextData
--
-- >>> parseUrlPiece "foo" :: Either Text MyData
-- Right Foo
--
parseBoundedTextData :: (Show a, Bounded a, Enum a) => Text -> Either Text a
-- | Parse URL piece using Read instance.
--
-- Use for types which do not involve letters:
--
--
-- >>> readTextData "1991-06-02" :: Either Text Day
-- Right 1991-06-02
--
--
-- This parser is case sensitive and will not match
-- showTextData in presense of letters:
--
--
-- >>> readTextData (showTextData True) :: Either Text Bool
-- Left "could not parse: `true'"
--
--
-- See parseBoundedTextData.
readTextData :: Read a => Text -> Either Text a
-- | Run Reader as HTTP API data parser.
runReader :: Reader a -> 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)"
--
parseBounded :: (Bounded a, Integral a) => Reader Integer -> Text -> Either Text a
-- |
-- >>> toUrlPiece ()
-- "_"
--
-- |
-- >>> toUrlPiece (Version [1, 2, 3] [])
-- "1.2.3"
--
-- |
-- >>> toUrlPiece (fromGregorian 2015 10 03)
-- "2015-10-03"
--
-- |
-- >>> toUrlPiece (Just "Hello")
-- "just Hello"
--
-- |
-- >>> toUrlPiece (Left "err" :: Either String Int)
-- "left err"
--
-- >>> toUrlPiece (Right 3 :: Either String Int)
-- "right 3"
--
-- |
-- >>> parseUrlPiece "_" :: Either Text ()
-- Right ()
--
-- |
-- >>> showVersion <$> parseUrlPiece "1.2.3"
-- Right "1.2.3"
--
-- | Parsing a Void value is always an error, considering
-- Void as a data type with no constructors.
-- |
-- >>> toGregorian <$> parseUrlPiece "2016-12-01"
-- Right (2016,12,1)
--
-- |
-- >>> parseUrlPiece "Just 123" :: Either Text (Maybe Int)
-- Right (Just 123)
--
-- |
-- >>> parseUrlPiece "Right 123" :: Either Text (Either String Int)
-- Right (Right 123)
--
instance Web.HttpApiData.Internal.ToHttpApiData ()
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Types.Char
instance Web.HttpApiData.Internal.ToHttpApiData Data.Version.Version
instance Web.HttpApiData.Internal.ToHttpApiData Data.Void.Void
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Types.Bool
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Types.Ordering
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Types.Double
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Types.Float
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Types.Int
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Int.Int8
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Int.Int16
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Int.Int32
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Int.Int64
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Integer.Type.Integer
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Types.Word
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Word.Word8
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Word.Word16
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Word.Word32
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Word.Word64
instance Web.HttpApiData.Internal.ToHttpApiData Data.Time.Calendar.Days.Day
instance Web.HttpApiData.Internal.ToHttpApiData GHC.Base.String
instance Web.HttpApiData.Internal.ToHttpApiData Data.Text.Internal.Text
instance Web.HttpApiData.Internal.ToHttpApiData Data.Text.Internal.Lazy.Text
instance Web.HttpApiData.Internal.ToHttpApiData Data.Monoid.All
instance Web.HttpApiData.Internal.ToHttpApiData Data.Monoid.Any
instance Web.HttpApiData.Internal.ToHttpApiData a => Web.HttpApiData.Internal.ToHttpApiData (Data.Monoid.Dual a)
instance Web.HttpApiData.Internal.ToHttpApiData a => Web.HttpApiData.Internal.ToHttpApiData (Data.Monoid.Sum a)
instance Web.HttpApiData.Internal.ToHttpApiData a => Web.HttpApiData.Internal.ToHttpApiData (Data.Monoid.Product a)
instance Web.HttpApiData.Internal.ToHttpApiData a => Web.HttpApiData.Internal.ToHttpApiData (Data.Monoid.First a)
instance Web.HttpApiData.Internal.ToHttpApiData a => Web.HttpApiData.Internal.ToHttpApiData (Data.Monoid.Last a)
instance Web.HttpApiData.Internal.ToHttpApiData a => Web.HttpApiData.Internal.ToHttpApiData (GHC.Base.Maybe a)
instance (Web.HttpApiData.Internal.ToHttpApiData a, Web.HttpApiData.Internal.ToHttpApiData b) => Web.HttpApiData.Internal.ToHttpApiData (Data.Either.Either a b)
instance Web.HttpApiData.Internal.FromHttpApiData ()
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Types.Char
instance Web.HttpApiData.Internal.FromHttpApiData Data.Version.Version
instance Web.HttpApiData.Internal.FromHttpApiData Data.Void.Void
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Types.Bool
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Types.Ordering
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Types.Double
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Types.Float
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Types.Int
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Int.Int8
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Int.Int16
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Int.Int32
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Int.Int64
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Integer.Type.Integer
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Types.Word
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Word.Word8
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Word.Word16
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Word.Word32
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Word.Word64
instance Web.HttpApiData.Internal.FromHttpApiData GHC.Base.String
instance Web.HttpApiData.Internal.FromHttpApiData Data.Text.Internal.Text
instance Web.HttpApiData.Internal.FromHttpApiData Data.Text.Internal.Lazy.Text
instance Web.HttpApiData.Internal.FromHttpApiData Data.Time.Calendar.Days.Day
instance Web.HttpApiData.Internal.FromHttpApiData Data.Monoid.All
instance Web.HttpApiData.Internal.FromHttpApiData Data.Monoid.Any
instance Web.HttpApiData.Internal.FromHttpApiData a => Web.HttpApiData.Internal.FromHttpApiData (Data.Monoid.Dual a)
instance Web.HttpApiData.Internal.FromHttpApiData a => Web.HttpApiData.Internal.FromHttpApiData (Data.Monoid.Sum a)
instance Web.HttpApiData.Internal.FromHttpApiData a => Web.HttpApiData.Internal.FromHttpApiData (Data.Monoid.Product a)
instance Web.HttpApiData.Internal.FromHttpApiData a => Web.HttpApiData.Internal.FromHttpApiData (Data.Monoid.First a)
instance Web.HttpApiData.Internal.FromHttpApiData a => Web.HttpApiData.Internal.FromHttpApiData (Data.Monoid.Last a)
instance Web.HttpApiData.Internal.FromHttpApiData a => Web.HttpApiData.Internal.FromHttpApiData (GHC.Base.Maybe a)
instance (Web.HttpApiData.Internal.FromHttpApiData a, Web.HttpApiData.Internal.FromHttpApiData b) => Web.HttpApiData.Internal.FromHttpApiData (Data.Either.Either a b)
-- | Convert Haskell values to and from HTTP API data such as URL pieces,
-- headers and query parameters.
module Web.HttpApiData
-- | Convert value to HTTP API data.
class ToHttpApiData a where toUrlPiece = toQueryParam toHeader = encodeUtf8 . toUrlPiece toQueryParam = toUrlPiece
-- | Convert to URL path piece.
toUrlPiece :: ToHttpApiData a => a -> Text
-- | Convert to HTTP header value.
toHeader :: ToHttpApiData a => a -> ByteString
-- | Convert to query param value.
toQueryParam :: ToHttpApiData a => a -> Text
-- | Parse value from HTTP API data.
class FromHttpApiData a where parseUrlPiece = parseQueryParam parseHeader = parseUrlPiece . decodeUtf8 parseQueryParam = parseUrlPiece
-- | Parse URL path piece.
parseUrlPiece :: FromHttpApiData a => Text -> Either Text a
-- | Parse HTTP header value.
parseHeader :: FromHttpApiData a => ByteString -> Either Text a
-- | Parse query param value.
parseQueryParam :: FromHttpApiData a => Text -> Either Text a
-- | Parse URL path piece in a Maybe.
--
--
-- >>> parseUrlPieceMaybe "12" :: Maybe Int
-- Just 12
--
parseUrlPieceMaybe :: FromHttpApiData a => Text -> Maybe a
-- | Parse HTTP header value in a Maybe.
--
--
-- >>> parseHeaderMaybe "hello" :: Maybe Text
-- Just "hello"
--
parseHeaderMaybe :: FromHttpApiData a => ByteString -> Maybe a
-- | Parse query param value in a Maybe.
--
--
-- >>> parseQueryParamMaybe "true" :: Maybe Bool
-- Just True
--
parseQueryParamMaybe :: FromHttpApiData a => Text -> Maybe a
-- | Case insensitive.
--
-- Parse given text case insensitive and then parse the rest of the input
-- using parseUrlPiece.
--
--
-- >>> 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)
--
parseUrlPieceWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a
-- | 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 BasicAuthToken
-- Right (BasicAuthToken "QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
--
parseHeaderWithPrefix :: FromHttpApiData a => ByteString -> ByteString -> Either Text a
-- | Case insensitive.
--
-- Parse given text case insensitive and then parse the rest of the input
-- using parseQueryParam.
--
--
-- >>> parseQueryParamWithPrefix "z" "z10" :: Either Text Int
-- Right 10
--
parseQueryParamWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a
-- | Convert multiple values to a list of URL pieces.
--
--
-- >>> toUrlPieces [1, 2, 3]
-- ["1","2","3"]
--
toUrlPieces :: (Functor t, ToHttpApiData a) => t a -> t Text
-- | 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)"
--
parseUrlPieces :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)
-- | Convert multiple values to a list of query parameter values.
--
--
-- >>> toQueryParams [fromGregorian 2015 10 03, fromGregorian 2015 12 01]
-- ["2015-10-03","2015-12-01"]
--
toQueryParams :: (Functor t, ToHttpApiData a) => t a -> t Text
-- | 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)"
--
parseQueryParams :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)
-- | Lower case.
--
-- 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"
--
showTextData :: Show a => a -> Text
-- | Parse URL piece using Read instance.
--
-- Use for types which do not involve letters:
--
--
-- >>> readTextData "1991-06-02" :: Either Text Day
-- Right 1991-06-02
--
--
-- This parser is case sensitive and will not match
-- showTextData in presense of letters:
--
--
-- >>> readTextData (showTextData True) :: Either Text Bool
-- Left "could not parse: `true'"
--
--
-- See parseBoundedTextData.
readTextData :: Read a => Text -> Either Text a
-- | Case insensitive.
--
-- Parse values case insensitively based on Show
-- instance.
--
--
-- >>> parseBoundedTextData "true" :: Either Text Bool
-- Right True
--
-- >>> parseBoundedTextData "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 = parseBoundedTextData
--
-- >>> parseUrlPiece "foo" :: Either Text MyData
-- Right Foo
--
parseBoundedTextData :: (Show a, Bounded a, Enum a) => Text -> Either Text a