-- 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.
--   
--   This package defines typeclasses used for converting Haskell data
--   types to and from HTTP API data.
--   
--   Please see README.md
@package http-api-data
@version 0.3.8


-- | Convert Haskell values to and from HTTP API data such as URL pieces,
--   headers and query parameters.
module Web.Internal.HttpApiData

-- | Convert value to HTTP API data.
--   
--   <b>WARNING</b>: Do not derive this using <tt>DeriveAnyClass</tt> as
--   the generated instance will loop indefinitely.
class ToHttpApiData a

-- | Convert to URL path piece.
toUrlPiece :: ToHttpApiData a => a -> Text

-- | Convert to a URL path piece, making sure to encode any special chars.
--   The default definition uses <a>encodePathSegmentsRelative</a>, but
--   this may be overriden with a more efficient version.
toEncodedUrlPiece :: ToHttpApiData a => a -> Builder

-- | 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.
--   
--   <b>WARNING</b>: Do not derive this using <tt>DeriveAnyClass</tt> as
--   the generated instance will loop indefinitely.
class FromHttpApiData a

-- | 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.
--   
--   <pre>
--   &gt;&gt;&gt; toUrlPieces [1, 2, 3] :: [Text]
--   ["1","2","3"]
--   </pre>
toUrlPieces :: (Functor t, ToHttpApiData a) => t a -> t Text

-- | Parse multiple URL pieces.
--   
--   <pre>
--   &gt;&gt;&gt; parseUrlPieces ["true", "false"] :: Either Text [Bool]
--   Right [True,False]
--   
--   &gt;&gt;&gt; parseUrlPieces ["123", "hello", "world"] :: Either Text [Int]
--   Left "could not parse: `hello' (input does not start with a digit)"
--   </pre>
parseUrlPieces :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)

-- | Convert multiple values to a list of query parameter values.
--   
--   <pre>
--   &gt;&gt;&gt; toQueryParams [fromGregorian 2015 10 03, fromGregorian 2015 12 01] :: [Text]
--   ["2015-10-03","2015-12-01"]
--   </pre>
toQueryParams :: (Functor t, ToHttpApiData a) => t a -> t Text

-- | Parse multiple query parameters.
--   
--   <pre>
--   &gt;&gt;&gt; parseQueryParams ["1", "2", "3"] :: Either Text [Int]
--   Right [1,2,3]
--   
--   &gt;&gt;&gt; parseQueryParams ["64", "128", "256"] :: Either Text [Word8]
--   Left "out of bounds: `256' (should be between 0 and 255)"
--   </pre>
parseQueryParams :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)

-- | Parse URL path piece in a <tt><a>Maybe</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseUrlPieceMaybe "12" :: Maybe Int
--   Just 12
--   </pre>
parseUrlPieceMaybe :: FromHttpApiData a => Text -> Maybe a

-- | Parse HTTP header value in a <tt><a>Maybe</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseHeaderMaybe "hello" :: Maybe Text
--   Just "hello"
--   </pre>
parseHeaderMaybe :: FromHttpApiData a => ByteString -> Maybe a

-- | Parse query param value in a <tt><a>Maybe</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseQueryParamMaybe "true" :: Maybe Bool
--   Just True
--   </pre>
parseQueryParamMaybe :: FromHttpApiData a => Text -> Maybe a

-- | Default parsing error.
defaultParseError :: Text -> Either Text a

-- | Convert <tt><a>Maybe</a></tt> parser into <tt><a>Either</a>
--   <a>Text</a></tt> parser with default error message.
parseMaybeTextData :: (Text -> Maybe a) -> (Text -> Either Text a)

-- | <i>Lower case</i>.
--   
--   Convert to URL piece using <tt><a>Show</a></tt> instance. The result
--   is always lower cased.
--   
--   <pre>
--   &gt;&gt;&gt; showTextData True
--   "true"
--   </pre>
--   
--   This can be used as a default implementation for enumeration types:
--   
--   <pre>
--   &gt;&gt;&gt; data MyData = Foo | Bar | Baz deriving (Show)
--   
--   &gt;&gt;&gt; instance ToHttpApiData MyData where toUrlPiece = showTextData
--   
--   &gt;&gt;&gt; toUrlPiece Foo
--   "foo"
--   </pre>
showTextData :: Show a => a -> Text

-- | Like <tt><a>show</a></tt>, but returns <tt><a>Text</a></tt>.
showt :: Show a => a -> Text

-- | <i>Case insensitive</i>.
--   
--   Parse given text case insensitive and then parse the rest of the input
--   using <tt><a>parseUrlPiece</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseUrlPieceWithPrefix "Just " "just 10" :: Either Text Int
--   Right 10
--   
--   &gt;&gt;&gt; parseUrlPieceWithPrefix "Left " "left" :: Either Text Bool
--   Left "could not parse: `left'"
--   </pre>
--   
--   This can be used to implement <tt><a>FromHttpApiData</a></tt> for
--   single field constructors:
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo Int deriving (Show)
--   
--   &gt;&gt;&gt; instance FromHttpApiData Foo where parseUrlPiece s = Foo &lt;$&gt; parseUrlPieceWithPrefix "Foo " s
--   
--   &gt;&gt;&gt; parseUrlPiece "foo 1" :: Either Text Foo
--   Right (Foo 1)
--   </pre>
parseUrlPieceWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a

-- | Parse given bytestring then parse the rest of the input using
--   <tt><a>parseHeader</a></tt>.
--   
--   <pre>
--   data BasicAuthToken = BasicAuthToken Text deriving (Show)
--   
--   instance FromHttpApiData BasicAuthToken where
--     parseHeader h     = BasicAuthToken &lt;$&gt; parseHeaderWithPrefix "Basic " h
--     parseQueryParam p = BasicAuthToken &lt;$&gt; parseQueryParam p
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseHeader "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" :: Either Text BasicAuthToken
--   Right (BasicAuthToken "QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
--   </pre>
parseHeaderWithPrefix :: FromHttpApiData a => ByteString -> ByteString -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse given text case insensitive and then parse the rest of the input
--   using <tt><a>parseQueryParam</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseQueryParamWithPrefix "z" "z10" :: Either Text Int
--   Right 10
--   </pre>
parseQueryParamWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on <tt><a>Show</a></tt>
--   instance.
--   
--   <pre>
--   &gt;&gt;&gt; parseBoundedTextData "true" :: Either Text Bool
--   Right True
--   
--   &gt;&gt;&gt; parseBoundedTextData "FALSE" :: Either Text Bool
--   Right False
--   </pre>
--   
--   This can be used as a default implementation for enumeration types:
--   
--   <pre>
--   &gt;&gt;&gt; data MyData = Foo | Bar | Baz deriving (Show, Bounded, Enum)
--   
--   &gt;&gt;&gt; instance FromHttpApiData MyData where parseUrlPiece = parseBoundedTextData
--   
--   &gt;&gt;&gt; parseUrlPiece "foo" :: Either Text MyData
--   Right Foo
--   </pre>
parseBoundedTextData :: (Show a, Bounded a, Enum a) => Text -> Either Text a

-- | Lookup values based on a precalculated mapping of their
--   representations.
lookupBoundedEnumOf :: (Bounded a, Enum a, Eq b) => (a -> b) -> b -> Maybe a

-- | Parse values based on a precalculated mapping of their
--   <tt><a>Text</a></tt> representation.
--   
--   <pre>
--   &gt;&gt;&gt; parseBoundedEnumOf toUrlPiece "true" :: Either Text Bool
--   Right True
--   </pre>
--   
--   For case sensitive parser see <a>parseBoundedEnumOfI</a>.
parseBoundedEnumOf :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on a precalculated mapping of
--   their <tt><a>Text</a></tt> representations.
--   
--   <pre>
--   &gt;&gt;&gt; parseBoundedEnumOfI toUrlPiece "FALSE" :: Either Text Bool
--   Right False
--   </pre>
--   
--   For case sensitive parser see <a>parseBoundedEnumOf</a>.
parseBoundedEnumOfI :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on <tt><a>ToHttpApiData</a></tt>
--   instance. Uses <tt><a>toUrlPiece</a></tt> to get possible values.
parseBoundedUrlPiece :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on <tt><a>ToHttpApiData</a></tt>
--   instance. Uses <tt><a>toQueryParam</a></tt> to get possible values.
parseBoundedQueryParam :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a

-- | Parse values based on <tt><a>ToHttpApiData</a></tt> instance. Uses
--   <tt><a>toHeader</a></tt> to get possible values.
parseBoundedHeader :: (ToHttpApiData a, Bounded a, Enum a) => ByteString -> Either Text a

-- | Parse URL piece using <tt><a>Read</a></tt> instance.
--   
--   Use for types which do not involve letters:
--   
--   <pre>
--   &gt;&gt;&gt; readTextData "1991-06-02" :: Either Text Day
--   Right 1991-06-02
--   </pre>
--   
--   This parser is case sensitive and will not match
--   <tt><a>showTextData</a></tt> in presence of letters:
--   
--   <pre>
--   &gt;&gt;&gt; readTextData (showTextData True) :: Either Text Bool
--   Left "could not parse: `true'"
--   </pre>
--   
--   See <tt><a>parseBoundedTextData</a></tt>.
readTextData :: Read a => Text -> Either Text a

-- | Run <tt><a>Reader</a></tt> as HTTP API data parser.
runReader :: Reader a -> Text -> Either Text a

-- | Run <tt><a>Reader</a></tt> to parse bounded integral value with bounds
--   checking.
--   
--   <pre>
--   &gt;&gt;&gt; parseBounded decimal "256" :: Either Text Word8
--   Left "out of bounds: `256' (should be between 0 and 255)"
--   </pre>
parseBounded :: forall a. (Bounded a, Integral a) => Reader Integer -> Text -> Either Text a

-- | Convert to a URL-encoded path piece using <a>toUrlPiece</a>.
--   <i>Note</i>: this function does not check if the result contains
--   unescaped characters! This function can be used to override
--   <a>toEncodedUrlPiece</a> as a more efficient implementation when the
--   resulting URL piece <i>never</i> has to be escaped.
unsafeToEncodedUrlPiece :: ToHttpApiData a => a -> Builder

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece ()
--   "_"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece (Version [1, 2, 3] [])
--   "1.2.3"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece (fromGregorian 2015 10 03)
--   "2015-10-03"
--   </pre>
timeToUrlPiece :: FormatTime t => String -> t -> Text

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece $ TimeOfDay 14 55 23.1
--   "14:55:23.1"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece $ LocalTime (fromGregorian 2015 10 03) (TimeOfDay 14 55 21.687)
--   "2015-10-03T14:55:21.687"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece $ ZonedTime (LocalTime (fromGregorian 2015 10 03) (TimeOfDay 14 55 51.001)) utc
--   "2015-10-03T14:55:51.001+0000"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece $ UTCTime (fromGregorian 2015 10 03) 864.5
--   "2015-10-03T00:14:24.5Z"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece (Just "Hello")
--   "just Hello"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; toUrlPiece (Left "err" :: Either String Int)
--   "left err"
--   
--   &gt;&gt;&gt; toUrlPiece (Right 3 :: Either String Int)
--   "right 3"
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; parseUrlPiece "_" :: Either Text ()
--   Right ()
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; showVersion &lt;$&gt; parseUrlPiece "1.2.3"
--   Right "1.2.3"
--   </pre>

-- | Parsing a <tt><a>Void</a></tt> value is always an error, considering
--   <tt><a>Void</a></tt> as a data type with no constructors.

-- | <pre>
--   &gt;&gt;&gt; toGregorian &lt;$&gt; parseUrlPiece "2016-12-01"
--   Right (2016,12,1)
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; parseUrlPiece "14:55:01.333" :: Either Text TimeOfDay
--   Right 14:55:01.333
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; parseUrlPiece "2015-10-03T14:55:01" :: Either Text LocalTime
--   Right 2015-10-03 14:55:01
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; parseUrlPiece "2015-10-03T14:55:01+0000" :: Either Text ZonedTime
--   Right 2015-10-03 14:55:01 +0000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseQueryParam "2016-12-31T01:00:00Z" :: Either Text ZonedTime
--   Right 2016-12-31 01:00:00 +0000
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; parseUrlPiece "2015-10-03T00:14:24Z" :: Either Text UTCTime
--   Right 2015-10-03 00:14:24 UTC
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; parseUrlPiece "Just 123" :: Either Text (Maybe Int)
--   Right (Just 123)
--   </pre>

-- | <pre>
--   &gt;&gt;&gt; parseUrlPiece "Right 123" :: Either Text (Either String Int)
--   Right (Right 123)
--   </pre>

-- | Lenient parameters. <a>FromHttpApiData</a> combinators always return
--   <a>Right</a>.
newtype LenientData a
LenientData :: Either Text a -> LenientData a
[getLenientData] :: LenientData a -> Either Text a
runAtto :: Parser a -> Text -> Either Text a
instance Data.Traversable.Traversable Web.Internal.HttpApiData.LenientData
instance Data.Foldable.Foldable Web.Internal.HttpApiData.LenientData
instance GHC.Base.Functor Web.Internal.HttpApiData.LenientData
instance Data.Data.Data a => Data.Data.Data (Web.Internal.HttpApiData.LenientData a)
instance GHC.Read.Read a => GHC.Read.Read (Web.Internal.HttpApiData.LenientData a)
instance GHC.Show.Show a => GHC.Show.Show (Web.Internal.HttpApiData.LenientData a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Web.Internal.HttpApiData.LenientData a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Web.Internal.HttpApiData.LenientData a)
instance Web.Internal.HttpApiData.FromHttpApiData a => Web.Internal.HttpApiData.FromHttpApiData (Web.Internal.HttpApiData.LenientData a)
instance Web.Internal.HttpApiData.FromHttpApiData ()
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Types.Char
instance Web.Internal.HttpApiData.FromHttpApiData Data.Version.Version
instance Web.Internal.HttpApiData.FromHttpApiData Data.Void.Void
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Natural.Natural
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Types.Bool
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Types.Ordering
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Types.Double
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Types.Float
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Types.Int
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Int.Int8
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Int.Int16
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Int.Int32
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Int.Int64
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Integer.Type.Integer
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Types.Word
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Word.Word8
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Word.Word16
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Word.Word32
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Word.Word64
instance Web.Internal.HttpApiData.FromHttpApiData GHC.Base.String
instance Web.Internal.HttpApiData.FromHttpApiData Data.Text.Internal.Text
instance Web.Internal.HttpApiData.FromHttpApiData Data.Text.Internal.Lazy.Text
instance Web.Internal.HttpApiData.FromHttpApiData Data.Time.Calendar.Days.Day
instance Web.Internal.HttpApiData.FromHttpApiData Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Web.Internal.HttpApiData.FromHttpApiData Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Web.Internal.HttpApiData.FromHttpApiData Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Web.Internal.HttpApiData.FromHttpApiData Data.Time.Clock.Internal.UTCTime.UTCTime
instance Web.Internal.HttpApiData.FromHttpApiData Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Web.Internal.HttpApiData.FromHttpApiData Data.Monoid.All
instance Web.Internal.HttpApiData.FromHttpApiData Data.Monoid.Any
instance Web.Internal.HttpApiData.FromHttpApiData a => Web.Internal.HttpApiData.FromHttpApiData (Data.Monoid.Dual a)
instance Web.Internal.HttpApiData.FromHttpApiData a => Web.Internal.HttpApiData.FromHttpApiData (Data.Monoid.Sum a)
instance Web.Internal.HttpApiData.FromHttpApiData a => Web.Internal.HttpApiData.FromHttpApiData (Data.Monoid.Product a)
instance Web.Internal.HttpApiData.FromHttpApiData a => Web.Internal.HttpApiData.FromHttpApiData (Data.Monoid.First a)
instance Web.Internal.HttpApiData.FromHttpApiData a => Web.Internal.HttpApiData.FromHttpApiData (Data.Monoid.Last a)
instance Web.Internal.HttpApiData.FromHttpApiData a => Web.Internal.HttpApiData.FromHttpApiData (GHC.Base.Maybe a)
instance (Web.Internal.HttpApiData.FromHttpApiData a, Web.Internal.HttpApiData.FromHttpApiData b) => Web.Internal.HttpApiData.FromHttpApiData (Data.Either.Either a b)
instance Web.Internal.HttpApiData.FromHttpApiData Data.UUID.Types.Internal.UUID
instance Web.Internal.HttpApiData.ToHttpApiData ()
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Types.Char
instance Web.Internal.HttpApiData.ToHttpApiData Data.Version.Version
instance Web.Internal.HttpApiData.ToHttpApiData Data.Void.Void
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Natural.Natural
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Types.Bool
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Types.Ordering
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Types.Double
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Types.Float
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Types.Int
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Int.Int8
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Int.Int16
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Int.Int32
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Int.Int64
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Integer.Type.Integer
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Types.Word
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Word.Word8
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Word.Word16
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Word.Word32
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Word.Word64
instance Web.Internal.HttpApiData.ToHttpApiData Data.Time.Calendar.Days.Day
instance Web.Internal.HttpApiData.ToHttpApiData Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Web.Internal.HttpApiData.ToHttpApiData Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Web.Internal.HttpApiData.ToHttpApiData Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Web.Internal.HttpApiData.ToHttpApiData Data.Time.Clock.Internal.UTCTime.UTCTime
instance Web.Internal.HttpApiData.ToHttpApiData Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Web.Internal.HttpApiData.ToHttpApiData GHC.Base.String
instance Web.Internal.HttpApiData.ToHttpApiData Data.Text.Internal.Text
instance Web.Internal.HttpApiData.ToHttpApiData Data.Text.Internal.Lazy.Text
instance Web.Internal.HttpApiData.ToHttpApiData Data.Monoid.All
instance Web.Internal.HttpApiData.ToHttpApiData Data.Monoid.Any
instance Web.Internal.HttpApiData.ToHttpApiData a => Web.Internal.HttpApiData.ToHttpApiData (Data.Monoid.Dual a)
instance Web.Internal.HttpApiData.ToHttpApiData a => Web.Internal.HttpApiData.ToHttpApiData (Data.Monoid.Sum a)
instance Web.Internal.HttpApiData.ToHttpApiData a => Web.Internal.HttpApiData.ToHttpApiData (Data.Monoid.Product a)
instance Web.Internal.HttpApiData.ToHttpApiData a => Web.Internal.HttpApiData.ToHttpApiData (Data.Monoid.First a)
instance Web.Internal.HttpApiData.ToHttpApiData a => Web.Internal.HttpApiData.ToHttpApiData (Data.Monoid.Last a)
instance Web.Internal.HttpApiData.ToHttpApiData a => Web.Internal.HttpApiData.ToHttpApiData (GHC.Base.Maybe a)
instance (Web.Internal.HttpApiData.ToHttpApiData a, Web.Internal.HttpApiData.ToHttpApiData b) => Web.Internal.HttpApiData.ToHttpApiData (Data.Either.Either a b)
instance Web.Internal.HttpApiData.ToHttpApiData Data.UUID.Types.Internal.UUID

module Web.Internal.FormUrlEncoded

-- | Typeclass for types that can be used as keys in a <a>Form</a>-like
--   container (like <a>Map</a>).
class ToFormKey k

-- | Render a key for a <a>Form</a>.
toFormKey :: ToFormKey k => k -> Text

-- | Typeclass for types that can be parsed from keys of a <a>Form</a>.
--   This is the reverse of <a>ToFormKey</a>.
class FromFormKey k

-- | Parse a key of a <a>Form</a>.
parseFormKey :: FromFormKey k => Text -> Either Text k

-- | The contents of a form, not yet URL-encoded.
--   
--   <a>Form</a> can be URL-encoded with <a>urlEncodeForm</a> and
--   URL-decoded with <a>urlDecodeForm</a>.
newtype Form
Form :: HashMap Text [Text] -> Form
[unForm] :: Form -> HashMap Text [Text]

-- | _NOTE:_ <a>toList</a> is unstable and may result in different key
--   order (but not values). For a stable conversion use
--   <a>toListStable</a>.

-- | A stable version of <a>toList</a>.
toListStable :: Form -> [(Text, Text)]

-- | Convert a value into <a>Form</a>.
--   
--   An example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedLists #-}
--   
--   data Person = Person
--     { name :: String
--     , age  :: Int }
--   
--   instance <a>ToForm</a> Person where
--     <a>toForm</a> person =
--       [ ("name", <a>toQueryParam</a> (name person))
--       , ("age", <a>toQueryParam</a> (age person)) ]
--   </pre>
--   
--   Instead of manually writing <tt><a>ToForm</a></tt> instances you can
--   use a default generic implementation of <tt><a>toForm</a></tt>.
--   
--   To do that, simply add <tt>deriving <a>Generic</a></tt> clause to your
--   datatype and declare a <a>ToForm</a> instance for your datatype
--   without giving definition for <a>toForm</a>.
--   
--   For instance, the previous example can be simplified into this:
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   
--   instance <a>ToForm</a> Person
--   </pre>
--   
--   The default implementation of <a>toForm</a> is <a>genericToForm</a>.
class ToForm a

-- | Convert a value into <a>Form</a>.
toForm :: ToForm a => a -> Form

-- | Convert a value into <a>Form</a>.
toForm :: (ToForm a, Generic a, GToForm a (Rep a)) => a -> Form

-- | Convert a list of entries groupped by key into a <a>Form</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fromEntriesByKey [("name",["Nick"]),("color",["red","blue"])]
--   fromList [("color","red"),("color","blue"),("name","Nick")]
--   </pre>
fromEntriesByKey :: (ToFormKey k, ToHttpApiData v) => [(k, [v])] -> Form
data Proxy3 a b c
Proxy3 :: Proxy3 a b c

-- | A <a>Generic</a>-based implementation of <a>toForm</a>. This is used
--   as a default implementation in <a>ToForm</a>.
--   
--   Note that this only works for records (i.e. product data types with
--   named fields):
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   </pre>
--   
--   In this implementation each field's value gets encoded using
--   <a>toQueryParam</a>. Two field types are exceptions:
--   
--   <ul>
--   <li>for values of type <tt><a>Maybe</a> a</tt> an entry is added to
--   the <a>Form</a> only when it is <tt><a>Just</a> x</tt> and the encoded
--   value is <tt><a>toQueryParam</a> x</tt>; <a>Nothing</a> values are
--   omitted from the <a>Form</a>;</li>
--   <li>for values of type <tt>[a]</tt> (except <tt>[<a>Char</a>]</tt>) an
--   entry is added for every item in the list; if the list is empty no
--   entries are added to the <a>Form</a>;</li>
--   </ul>
--   
--   Here's an example:
--   
--   <pre>
--   data Post = Post
--     { title    :: String
--     , subtitle :: Maybe String
--     , comments :: [String]
--     } deriving (<a>Generic</a>, <a>Show</a>)
--   
--   instance <a>ToForm</a> Post
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeAsFormStable Post { title = "Test", subtitle = Nothing, comments = ["Nice post!", "+1"] }
--   "comments=Nice%20post%21&amp;comments=%2B1&amp;title=Test"
--   </pre>
genericToForm :: forall a. (Generic a, GToForm a (Rep a)) => FormOptions -> a -> Form
class GToForm t (f :: * -> *)
gToForm :: GToForm t f => Proxy t -> FormOptions -> f x -> Form

-- | Parse <a>Form</a> into a value.
--   
--   An example type and instance:
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int }
--   
--   instance <a>FromForm</a> Person where
--     <a>fromForm</a> f = Person
--       <a>&lt;$&gt;</a> <a>parseUnique</a> "name" f
--       <a>&lt;*&gt;</a> <a>parseUnique</a> "age"  f
--   </pre>
--   
--   Instead of manually writing <tt><a>FromForm</a></tt> instances you can
--   use a default generic implementation of <tt><a>fromForm</a></tt>.
--   
--   To do that, simply add <tt>deriving <a>Generic</a></tt> clause to your
--   datatype and declare a <a>FromForm</a> instance for your datatype
--   without giving definition for <a>fromForm</a>.
--   
--   For instance, the previous example can be simplified into this:
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   
--   instance <a>FromForm</a> Person
--   </pre>
--   
--   The default implementation of <a>fromForm</a> is
--   <a>genericFromForm</a>. It only works for records and it will use
--   <a>parseQueryParam</a> for each field's value.
class FromForm a

-- | Parse <a>Form</a> into a value.
fromForm :: FromForm a => Form -> Either Text a

-- | Parse <a>Form</a> into a value.
fromForm :: (FromForm a, Generic a, GFromForm a (Rep a)) => Form -> Either Text a

-- | _NOTE:_ this conversion is unstable and may result in different key
--   order (but not values).

-- | Parse a <a>Form</a> into a list of entries groupped by key.
--   
--   _NOTE:_ this conversion is unstable and may result in different key
--   order (but not values). For a stable encoding see
--   <a>toEntriesByKeyStable</a>.
toEntriesByKey :: (FromFormKey k, FromHttpApiData v) => Form -> Either Text [(k, [v])]

-- | Parse a <a>Form</a> into a list of entries groupped by key.
--   
--   <pre>
--   &gt;&gt;&gt; toEntriesByKeyStable [("name", "Nick"), ("color", "red"), ("color", "white")] :: Either Text [(Text, [Text])]
--   Right [("color",["red","white"]),("name",["Nick"])]
--   </pre>
--   
--   For an unstable (but faster) conversion see <a>toEntriesByKey</a>.
toEntriesByKeyStable :: (Ord k, FromFormKey k, FromHttpApiData v) => Form -> Either Text [(k, [v])]

-- | A <a>Generic</a>-based implementation of <a>fromForm</a>. This is used
--   as a default implementation in <a>FromForm</a>.
--   
--   Note that this only works for records (i.e. product data types with
--   named fields):
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   </pre>
--   
--   In this implementation each field's value gets decoded using
--   <a>parseQueryParam</a>. Two field types are exceptions:
--   
--   <ul>
--   <li>for values of type <tt><a>Maybe</a> a</tt> an entry is parsed if
--   present in the <a>Form</a> and the is decoded with
--   <a>parseQueryParam</a>; if no entry is present result is
--   <a>Nothing</a>;</li>
--   <li>for values of type <tt>[a]</tt> (except <tt>[<a>Char</a>]</tt>)
--   all entries are parsed to produce a list of parsed values;</li>
--   </ul>
--   
--   Here's an example:
--   
--   <pre>
--   data Post = Post
--     { title    :: String
--     , subtitle :: Maybe String
--     , comments :: [String]
--     } deriving (<a>Generic</a>, <a>Show</a>)
--   
--   instance <a>FromForm</a> Post
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeAsForm "comments=Nice%20post%21&amp;comments=%2B1&amp;title=Test" :: Either Text Post
--   Right (Post {title = "Test", subtitle = Nothing, comments = ["Nice post!","+1"]})
--   </pre>
genericFromForm :: forall a. (Generic a, GFromForm a (Rep a)) => FormOptions -> Form -> Either Text a
class GFromForm t (f :: * -> *)
gFromForm :: GFromForm t f => Proxy t -> FormOptions -> Form -> Either Text (f x)

-- | Encode a <a>Form</a> to an <tt>application/x-www-form-urlencoded</tt>
--   <a>ByteString</a>.
--   
--   _NOTE:_ this encoding is unstable and may result in different key
--   order (but not values). For a stable encoding see
--   <a>urlEncodeFormStable</a>.
urlEncodeForm :: Form -> ByteString

-- | Encode a <a>Form</a> to an <tt>application/x-www-form-urlencoded</tt>
--   <a>ByteString</a>.
--   
--   For an unstable (but faster) encoding see <a>urlEncodeForm</a>.
--   
--   Key-value pairs get encoded to <tt>key=value</tt> and separated by
--   <tt>&amp;</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("name", "Julian"), ("lastname", "Arni")]
--   "lastname=Arni&amp;name=Julian"
--   </pre>
--   
--   Keys with empty values get encoded to just <tt>key</tt> (without the
--   <tt>=</tt> sign):
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("is_test", "")]
--   "is_test"
--   </pre>
--   
--   Empty keys are allowed too:
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("", "foobar")]
--   "=foobar"
--   </pre>
--   
--   However, if both key and value are empty, the key-value pair is
--   ignored. (This prevents <tt><a>urlDecodeForm</a> .
--   <a>urlEncodeFormStable</a></tt> from being a true isomorphism).
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("", "")]
--   ""
--   </pre>
--   
--   Everything is escaped with <tt><tt>escapeURIString</tt>
--   <tt>isUnreserved</tt></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("fullname", "Andres Löh")]
--   "fullname=Andres%20L%C3%B6h"
--   </pre>
urlEncodeFormStable :: Form -> ByteString

-- | Encode a list of key-value pairs to an
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>.
--   
--   See also <a>urlEncodeFormStable</a>.
urlEncodeParams :: [(Text, Text)] -> ByteString

-- | Decode an <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>
--   to a <a>Form</a>.
--   
--   Key-value pairs get decoded normally:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "name=Greg&amp;lastname=Weber"
--   Right (fromList [("lastname","Weber"),("name","Greg")])
--   </pre>
--   
--   Keys with no values get decoded to pairs with empty values.
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "is_test"
--   Right (fromList [("is_test","")])
--   </pre>
--   
--   Empty keys are allowed:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "=foobar"
--   Right (fromList [("","foobar")])
--   </pre>
--   
--   The empty string gets decoded into an empty <a>Form</a>:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm ""
--   Right (fromList [])
--   </pre>
--   
--   Everything is un-escaped with <tt>unEscapeString</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "fullname=Andres%20L%C3%B6h"
--   Right (fromList [("fullname","Andres L\246h")])
--   </pre>
--   
--   Improperly formed strings result in an error:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "this=has=too=many=equals"
--   Left "not a valid pair: this=has=too=many=equals"
--   </pre>
urlDecodeForm :: ByteString -> Either Text Form

-- | Decode an <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>
--   to a list of key-value pairs.
--   
--   See also <a>urlDecodeForm</a>.
urlDecodeParams :: ByteString -> Either Text [(Text, Text)]

-- | This is a convenience function for decoding a
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a> directly
--   to a datatype that has an instance of <a>FromForm</a>.
--   
--   This is effectively <tt><a>fromForm</a> <a>&lt;=&lt;</a>
--   <a>urlDecodeForm</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeAsForm "name=Dennis&amp;age=22" :: Either Text Person
--   Right (Person {name = "Dennis", age = 22})
--   </pre>
urlDecodeAsForm :: FromForm a => ByteString -> Either Text a

-- | This is a convenience function for encoding a datatype that has
--   instance of <a>ToForm</a> directly to a
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>.
--   
--   This is effectively <tt><a>urlEncodeForm</a> . <a>toForm</a></tt>.
--   
--   _NOTE:_ this encoding is unstable and may result in different key
--   order (but not values). For a stable encoding see
--   <a>urlEncodeAsFormStable</a>.
urlEncodeAsForm :: ToForm a => a -> ByteString

-- | This is a convenience function for encoding a datatype that has
--   instance of <a>ToForm</a> directly to a
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>.
--   
--   This is effectively <tt><a>urlEncodeFormStable</a> .
--   <a>toForm</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeAsFormStable Person {name = "Dennis", age = 22}
--   "age=22&amp;name=Dennis"
--   </pre>
urlEncodeAsFormStable :: ToForm a => a -> ByteString

-- | Find all values corresponding to a given key in a <a>Form</a>.
--   
--   <pre>
--   &gt;&gt;&gt; lookupAll "name" []
--   []
--   
--   &gt;&gt;&gt; lookupAll "name" [("name", "Oleg")]
--   ["Oleg"]
--   
--   &gt;&gt;&gt; lookupAll "name" [("name", "Oleg"), ("name", "David")]
--   ["Oleg","David"]
--   </pre>
lookupAll :: Text -> Form -> [Text]

-- | Lookup an optional value for a key. Fail if there is more than one
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; lookupMaybe "name" []
--   Right Nothing
--   
--   &gt;&gt;&gt; lookupMaybe "name" [("name", "Oleg")]
--   Right (Just "Oleg")
--   
--   &gt;&gt;&gt; lookupMaybe "name" [("name", "Oleg"), ("name", "David")]
--   Left "Duplicate key \"name\""
--   </pre>
lookupMaybe :: Text -> Form -> Either Text (Maybe Text)

-- | Lookup a unique value for a key. Fail if there is zero or more than
--   one value.
--   
--   <pre>
--   &gt;&gt;&gt; lookupUnique "name" []
--   Left "Could not find key \"name\""
--   
--   &gt;&gt;&gt; lookupUnique "name" [("name", "Oleg")]
--   Right "Oleg"
--   
--   &gt;&gt;&gt; lookupUnique "name" [("name", "Oleg"), ("name", "David")]
--   Left "Duplicate key \"name\""
--   </pre>
lookupUnique :: Text -> Form -> Either Text Text

-- | Lookup all values for a given key in a <a>Form</a> and parse them with
--   <a>parseQueryParams</a>.
--   
--   <pre>
--   &gt;&gt;&gt; parseAll "age" [] :: Either Text [Word8]
--   Right []
--   
--   &gt;&gt;&gt; parseAll "age" [("age", "8"), ("age", "seven")] :: Either Text [Word8]
--   Left "could not parse: `seven' (input does not start with a digit)"
--   
--   &gt;&gt;&gt; parseAll "age" [("age", "8"), ("age", "777")] :: Either Text [Word8]
--   Left "out of bounds: `777' (should be between 0 and 255)"
--   
--   &gt;&gt;&gt; parseAll "age" [("age", "12"), ("age", "25")] :: Either Text [Word8]
--   Right [12,25]
--   </pre>
parseAll :: FromHttpApiData v => Text -> Form -> Either Text [v]

-- | Lookup an optional value for a given key and parse it with
--   <a>parseQueryParam</a>. Fail if there is more than one value for the
--   key.
--   
--   <pre>
--   &gt;&gt;&gt; parseMaybe "age" [] :: Either Text (Maybe Word8)
--   Right Nothing
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "12"), ("age", "25")] :: Either Text (Maybe Word8)
--   Left "Duplicate key \"age\""
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "seven")] :: Either Text (Maybe Word8)
--   Left "could not parse: `seven' (input does not start with a digit)"
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "777")] :: Either Text (Maybe Word8)
--   Left "out of bounds: `777' (should be between 0 and 255)"
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "7")] :: Either Text (Maybe Word8)
--   Right (Just 7)
--   </pre>
parseMaybe :: FromHttpApiData v => Text -> Form -> Either Text (Maybe v)

-- | Lookup a unique value for a given key and parse it with
--   <a>parseQueryParam</a>. Fail if there is zero or more than one value
--   for the key.
--   
--   <pre>
--   &gt;&gt;&gt; parseUnique "age" [] :: Either Text Word8
--   Left "Could not find key \"age\""
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "12"), ("age", "25")] :: Either Text Word8
--   Left "Duplicate key \"age\""
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "seven")] :: Either Text Word8
--   Left "could not parse: `seven' (input does not start with a digit)"
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "777")] :: Either Text Word8
--   Left "out of bounds: `777' (should be between 0 and 255)"
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "7")] :: Either Text Word8
--   Right 7
--   </pre>
parseUnique :: FromHttpApiData v => Text -> Form -> Either Text v

-- | <a>Generic</a>-based deriving options for <a>ToForm</a> and
--   <a>FromForm</a>.
--   
--   A common use case for non-default <a>FormOptions</a> is to strip a
--   prefix off of field labels:
--   
--   <pre>
--   data Project = Project
--     { projectName :: String
--     , projectSize :: Int
--     } deriving (<a>Generic</a>, <a>Show</a>)
--   
--   myOptions :: <a>FormOptions</a>
--   myOptions = <a>FormOptions</a>
--    { <a>fieldLabelModifier</a> = <a>map</a> <tt>toLower</tt> . <a>drop</a> (<a>length</a> "project") }
--   
--   instance <a>ToForm</a> Project where
--     <a>toForm</a> = <a>genericToForm</a> myOptions
--   
--   instance <a>FromForm</a> Project where
--     <a>fromForm</a> = <a>genericFromForm</a> myOptions
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeAsFormStable Project { projectName = "http-api-data", projectSize = 172 }
--   "name=http-api-data&amp;size=172"
--   
--   &gt;&gt;&gt; urlDecodeAsForm "name=http-api-data&amp;size=172" :: Either Text Project
--   Right (Project {projectName = "http-api-data", projectSize = 172})
--   </pre>
data FormOptions
FormOptions :: (String -> String) -> FormOptions

-- | Function applied to field labels. Handy for removing common record
--   prefixes for example.
[fieldLabelModifier] :: FormOptions -> String -> String

-- | Default encoding <a>FormOptions</a>.
--   
--   <pre>
--   <a>FormOptions</a>
--   { <a>fieldLabelModifier</a> = id
--   }
--   </pre>
defaultFormOptions :: FormOptions
sortOn :: Ord b => (a -> b) -> [a] -> [a]
instance GHC.Base.Monoid Web.Internal.FormUrlEncoded.Form
instance Data.Semigroup.Semigroup Web.Internal.FormUrlEncoded.Form
instance GHC.Generics.Generic Web.Internal.FormUrlEncoded.Form
instance GHC.Read.Read Web.Internal.FormUrlEncoded.Form
instance GHC.Classes.Eq Web.Internal.FormUrlEncoded.Form
instance Web.Internal.FormUrlEncoded.ToForm Web.Internal.FormUrlEncoded.Form
instance (Web.Internal.FormUrlEncoded.ToFormKey k, Web.Internal.HttpApiData.ToHttpApiData v) => Web.Internal.FormUrlEncoded.ToForm [(k, v)]
instance (Web.Internal.FormUrlEncoded.ToFormKey k, Web.Internal.HttpApiData.ToHttpApiData v) => Web.Internal.FormUrlEncoded.ToForm (Data.Map.Internal.Map k [v])
instance (Web.Internal.FormUrlEncoded.ToFormKey k, Web.Internal.HttpApiData.ToHttpApiData v) => Web.Internal.FormUrlEncoded.ToForm (Data.HashMap.Base.HashMap k [v])
instance Web.Internal.HttpApiData.ToHttpApiData v => Web.Internal.FormUrlEncoded.ToForm (Data.IntMap.Internal.IntMap [v])
instance forall k (t :: k) (f :: * -> *) (g :: * -> *). Web.Internal.FormUrlEncoded.NotSupported Web.Internal.FormUrlEncoded.ToForm t "is a sum type" => Web.Internal.FormUrlEncoded.GToForm t (f GHC.Generics.:+: g)
instance forall k (t :: k) (f :: * -> *) (g :: * -> *). (Web.Internal.FormUrlEncoded.GToForm t f, Web.Internal.FormUrlEncoded.GToForm t g) => Web.Internal.FormUrlEncoded.GToForm t (f GHC.Generics.:*: g)
instance forall k (t :: k) (f :: * -> *) (x :: GHC.Generics.Meta). Web.Internal.FormUrlEncoded.GToForm t f => Web.Internal.FormUrlEncoded.GToForm t (GHC.Generics.M1 GHC.Generics.D x f)
instance forall k (t :: k) (f :: * -> *) (x :: GHC.Generics.Meta). Web.Internal.FormUrlEncoded.GToForm t f => Web.Internal.FormUrlEncoded.GToForm t (GHC.Generics.M1 GHC.Generics.C x f)
instance forall k (s :: GHC.Generics.Meta) c (t :: k) i. (GHC.Generics.Selector s, Web.Internal.HttpApiData.ToHttpApiData c) => Web.Internal.FormUrlEncoded.GToForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i c))
instance forall k (s :: GHC.Generics.Meta) c (t :: k) i. (GHC.Generics.Selector s, Web.Internal.HttpApiData.ToHttpApiData c) => Web.Internal.FormUrlEncoded.GToForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i (GHC.Base.Maybe c)))
instance forall k (s :: GHC.Generics.Meta) c (t :: k) i. (GHC.Generics.Selector s, Web.Internal.HttpApiData.ToHttpApiData c) => Web.Internal.FormUrlEncoded.GToForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i [c]))
instance forall k (s :: GHC.Generics.Meta) (t :: k) i. GHC.Generics.Selector s => Web.Internal.FormUrlEncoded.GToForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i GHC.Base.String))
instance Web.Internal.FormUrlEncoded.FromForm Web.Internal.FormUrlEncoded.Form
instance (Web.Internal.FormUrlEncoded.FromFormKey k, Web.Internal.HttpApiData.FromHttpApiData v) => Web.Internal.FormUrlEncoded.FromForm [(k, v)]
instance (GHC.Classes.Ord k, Web.Internal.FormUrlEncoded.FromFormKey k, Web.Internal.HttpApiData.FromHttpApiData v) => Web.Internal.FormUrlEncoded.FromForm (Data.Map.Internal.Map k [v])
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k, Web.Internal.FormUrlEncoded.FromFormKey k, Web.Internal.HttpApiData.FromHttpApiData v) => Web.Internal.FormUrlEncoded.FromForm (Data.HashMap.Base.HashMap k [v])
instance Web.Internal.HttpApiData.FromHttpApiData v => Web.Internal.FormUrlEncoded.FromForm (Data.IntMap.Internal.IntMap [v])
instance forall k (t :: k) (f :: * -> *) (g :: * -> *). Web.Internal.FormUrlEncoded.NotSupported Web.Internal.FormUrlEncoded.FromForm t "is a sum type" => Web.Internal.FormUrlEncoded.GFromForm t (f GHC.Generics.:+: g)
instance forall k (t :: k) (f :: * -> *) (g :: * -> *). (Web.Internal.FormUrlEncoded.GFromForm t f, Web.Internal.FormUrlEncoded.GFromForm t g) => Web.Internal.FormUrlEncoded.GFromForm t (f GHC.Generics.:*: g)
instance forall k (t :: k) (f :: * -> *) (x :: GHC.Generics.Meta). Web.Internal.FormUrlEncoded.GFromForm t f => Web.Internal.FormUrlEncoded.GFromForm t (GHC.Generics.M1 GHC.Generics.D x f)
instance forall k (t :: k) (f :: * -> *) (x :: GHC.Generics.Meta). Web.Internal.FormUrlEncoded.GFromForm t f => Web.Internal.FormUrlEncoded.GFromForm t (GHC.Generics.M1 GHC.Generics.C x f)
instance forall k (s :: GHC.Generics.Meta) c (t :: k) i. (GHC.Generics.Selector s, Web.Internal.HttpApiData.FromHttpApiData c) => Web.Internal.FormUrlEncoded.GFromForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i c))
instance forall k (s :: GHC.Generics.Meta) c (t :: k) i. (GHC.Generics.Selector s, Web.Internal.HttpApiData.FromHttpApiData c) => Web.Internal.FormUrlEncoded.GFromForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i (GHC.Base.Maybe c)))
instance forall k (s :: GHC.Generics.Meta) c (t :: k) i. (GHC.Generics.Selector s, Web.Internal.HttpApiData.FromHttpApiData c) => Web.Internal.FormUrlEncoded.GFromForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i [c]))
instance forall k (s :: GHC.Generics.Meta) (t :: k) i. GHC.Generics.Selector s => Web.Internal.FormUrlEncoded.GFromForm t (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i GHC.Base.String))
instance GHC.Show.Show Web.Internal.FormUrlEncoded.Form
instance GHC.Exts.IsList Web.Internal.FormUrlEncoded.Form
instance Web.Internal.FormUrlEncoded.FromFormKey ()
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Types.Char
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Types.Bool
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Types.Ordering
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Types.Double
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Types.Float
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Types.Int
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Int.Int8
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Int.Int16
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Int.Int32
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Int.Int64
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Integer.Type.Integer
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Types.Word
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Word.Word8
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Word.Word16
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Word.Word32
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Word.Word64
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Time.Calendar.Days.Day
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Time.Clock.Internal.UTCTime.UTCTime
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Base.String
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Text.Internal.Text
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Text.Internal.Lazy.Text
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Monoid.All
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Monoid.Any
instance Web.Internal.FormUrlEncoded.FromFormKey a => Web.Internal.FormUrlEncoded.FromFormKey (Data.Monoid.Dual a)
instance Web.Internal.FormUrlEncoded.FromFormKey a => Web.Internal.FormUrlEncoded.FromFormKey (Data.Monoid.Sum a)
instance Web.Internal.FormUrlEncoded.FromFormKey a => Web.Internal.FormUrlEncoded.FromFormKey (Data.Monoid.Product a)
instance Web.Internal.FormUrlEncoded.FromFormKey Data.Void.Void
instance Web.Internal.FormUrlEncoded.FromFormKey GHC.Natural.Natural
instance Web.Internal.FormUrlEncoded.ToFormKey ()
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Types.Char
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Types.Bool
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Types.Ordering
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Types.Double
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Types.Float
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Types.Int
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Int.Int8
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Int.Int16
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Int.Int32
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Int.Int64
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Integer.Type.Integer
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Types.Word
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Word.Word8
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Word.Word16
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Word.Word32
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Word.Word64
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Time.Calendar.Days.Day
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Time.Clock.Internal.UTCTime.UTCTime
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Base.String
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Text.Internal.Text
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Text.Internal.Lazy.Text
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Monoid.All
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Monoid.Any
instance Web.Internal.FormUrlEncoded.ToFormKey a => Web.Internal.FormUrlEncoded.ToFormKey (Data.Monoid.Dual a)
instance Web.Internal.FormUrlEncoded.ToFormKey a => Web.Internal.FormUrlEncoded.ToFormKey (Data.Monoid.Sum a)
instance Web.Internal.FormUrlEncoded.ToFormKey a => Web.Internal.FormUrlEncoded.ToFormKey (Data.Monoid.Product a)
instance Web.Internal.FormUrlEncoded.ToFormKey Data.Void.Void
instance Web.Internal.FormUrlEncoded.ToFormKey GHC.Natural.Natural


-- | Convert Haskell values to and from
--   <tt>application/xxx-form-urlencoded</tt> format.
module Web.FormUrlEncoded

-- | Convert a value into <a>Form</a>.
--   
--   An example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedLists #-}
--   
--   data Person = Person
--     { name :: String
--     , age  :: Int }
--   
--   instance <a>ToForm</a> Person where
--     <a>toForm</a> person =
--       [ ("name", <a>toQueryParam</a> (name person))
--       , ("age", <a>toQueryParam</a> (age person)) ]
--   </pre>
--   
--   Instead of manually writing <tt><a>ToForm</a></tt> instances you can
--   use a default generic implementation of <tt><a>toForm</a></tt>.
--   
--   To do that, simply add <tt>deriving <a>Generic</a></tt> clause to your
--   datatype and declare a <a>ToForm</a> instance for your datatype
--   without giving definition for <a>toForm</a>.
--   
--   For instance, the previous example can be simplified into this:
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   
--   instance <a>ToForm</a> Person
--   </pre>
--   
--   The default implementation of <a>toForm</a> is <a>genericToForm</a>.
class ToForm a

-- | Convert a value into <a>Form</a>.
toForm :: ToForm a => a -> Form

-- | Convert a value into <a>Form</a>.
toForm :: (ToForm a, Generic a, GToForm a (Rep a)) => a -> Form

-- | Parse <a>Form</a> into a value.
--   
--   An example type and instance:
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int }
--   
--   instance <a>FromForm</a> Person where
--     <a>fromForm</a> f = Person
--       <a>&lt;$&gt;</a> <a>parseUnique</a> "name" f
--       <a>&lt;*&gt;</a> <a>parseUnique</a> "age"  f
--   </pre>
--   
--   Instead of manually writing <tt><a>FromForm</a></tt> instances you can
--   use a default generic implementation of <tt><a>fromForm</a></tt>.
--   
--   To do that, simply add <tt>deriving <a>Generic</a></tt> clause to your
--   datatype and declare a <a>FromForm</a> instance for your datatype
--   without giving definition for <a>fromForm</a>.
--   
--   For instance, the previous example can be simplified into this:
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   
--   instance <a>FromForm</a> Person
--   </pre>
--   
--   The default implementation of <a>fromForm</a> is
--   <a>genericFromForm</a>. It only works for records and it will use
--   <a>parseQueryParam</a> for each field's value.
class FromForm a

-- | Parse <a>Form</a> into a value.
fromForm :: FromForm a => Form -> Either Text a

-- | Parse <a>Form</a> into a value.
fromForm :: (FromForm a, Generic a, GFromForm a (Rep a)) => Form -> Either Text a

-- | Typeclass for types that can be used as keys in a <a>Form</a>-like
--   container (like <a>Map</a>).
class ToFormKey k

-- | Render a key for a <a>Form</a>.
toFormKey :: ToFormKey k => k -> Text

-- | Typeclass for types that can be parsed from keys of a <a>Form</a>.
--   This is the reverse of <a>ToFormKey</a>.
class FromFormKey k

-- | Parse a key of a <a>Form</a>.
parseFormKey :: FromFormKey k => Text -> Either Text k

-- | The contents of a form, not yet URL-encoded.
--   
--   <a>Form</a> can be URL-encoded with <a>urlEncodeForm</a> and
--   URL-decoded with <a>urlDecodeForm</a>.
newtype Form
Form :: HashMap Text [Text] -> Form
[unForm] :: Form -> HashMap Text [Text]

-- | This is a convenience function for encoding a datatype that has
--   instance of <a>ToForm</a> directly to a
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>.
--   
--   This is effectively <tt><a>urlEncodeForm</a> . <a>toForm</a></tt>.
--   
--   _NOTE:_ this encoding is unstable and may result in different key
--   order (but not values). For a stable encoding see
--   <a>urlEncodeAsFormStable</a>.
urlEncodeAsForm :: ToForm a => a -> ByteString

-- | This is a convenience function for encoding a datatype that has
--   instance of <a>ToForm</a> directly to a
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>.
--   
--   This is effectively <tt><a>urlEncodeFormStable</a> .
--   <a>toForm</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeAsFormStable Person {name = "Dennis", age = 22}
--   "age=22&amp;name=Dennis"
--   </pre>
urlEncodeAsFormStable :: ToForm a => a -> ByteString

-- | This is a convenience function for decoding a
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a> directly
--   to a datatype that has an instance of <a>FromForm</a>.
--   
--   This is effectively <tt><a>fromForm</a> <a>&lt;=&lt;</a>
--   <a>urlDecodeForm</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeAsForm "name=Dennis&amp;age=22" :: Either Text Person
--   Right (Person {name = "Dennis", age = 22})
--   </pre>
urlDecodeAsForm :: FromForm a => ByteString -> Either Text a

-- | Encode a <a>Form</a> to an <tt>application/x-www-form-urlencoded</tt>
--   <a>ByteString</a>.
--   
--   _NOTE:_ this encoding is unstable and may result in different key
--   order (but not values). For a stable encoding see
--   <a>urlEncodeFormStable</a>.
urlEncodeForm :: Form -> ByteString

-- | Encode a <a>Form</a> to an <tt>application/x-www-form-urlencoded</tt>
--   <a>ByteString</a>.
--   
--   For an unstable (but faster) encoding see <a>urlEncodeForm</a>.
--   
--   Key-value pairs get encoded to <tt>key=value</tt> and separated by
--   <tt>&amp;</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("name", "Julian"), ("lastname", "Arni")]
--   "lastname=Arni&amp;name=Julian"
--   </pre>
--   
--   Keys with empty values get encoded to just <tt>key</tt> (without the
--   <tt>=</tt> sign):
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("is_test", "")]
--   "is_test"
--   </pre>
--   
--   Empty keys are allowed too:
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("", "foobar")]
--   "=foobar"
--   </pre>
--   
--   However, if both key and value are empty, the key-value pair is
--   ignored. (This prevents <tt><a>urlDecodeForm</a> .
--   <a>urlEncodeFormStable</a></tt> from being a true isomorphism).
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("", "")]
--   ""
--   </pre>
--   
--   Everything is escaped with <tt><tt>escapeURIString</tt>
--   <tt>isUnreserved</tt></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeFormStable [("fullname", "Andres Löh")]
--   "fullname=Andres%20L%C3%B6h"
--   </pre>
urlEncodeFormStable :: Form -> ByteString

-- | Decode an <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>
--   to a <a>Form</a>.
--   
--   Key-value pairs get decoded normally:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "name=Greg&amp;lastname=Weber"
--   Right (fromList [("lastname","Weber"),("name","Greg")])
--   </pre>
--   
--   Keys with no values get decoded to pairs with empty values.
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "is_test"
--   Right (fromList [("is_test","")])
--   </pre>
--   
--   Empty keys are allowed:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "=foobar"
--   Right (fromList [("","foobar")])
--   </pre>
--   
--   The empty string gets decoded into an empty <a>Form</a>:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm ""
--   Right (fromList [])
--   </pre>
--   
--   Everything is un-escaped with <tt>unEscapeString</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "fullname=Andres%20L%C3%B6h"
--   Right (fromList [("fullname","Andres L\246h")])
--   </pre>
--   
--   Improperly formed strings result in an error:
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeForm "this=has=too=many=equals"
--   Left "not a valid pair: this=has=too=many=equals"
--   </pre>
urlDecodeForm :: ByteString -> Either Text Form

-- | A <a>Generic</a>-based implementation of <a>toForm</a>. This is used
--   as a default implementation in <a>ToForm</a>.
--   
--   Note that this only works for records (i.e. product data types with
--   named fields):
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   </pre>
--   
--   In this implementation each field's value gets encoded using
--   <a>toQueryParam</a>. Two field types are exceptions:
--   
--   <ul>
--   <li>for values of type <tt><a>Maybe</a> a</tt> an entry is added to
--   the <a>Form</a> only when it is <tt><a>Just</a> x</tt> and the encoded
--   value is <tt><a>toQueryParam</a> x</tt>; <a>Nothing</a> values are
--   omitted from the <a>Form</a>;</li>
--   <li>for values of type <tt>[a]</tt> (except <tt>[<a>Char</a>]</tt>) an
--   entry is added for every item in the list; if the list is empty no
--   entries are added to the <a>Form</a>;</li>
--   </ul>
--   
--   Here's an example:
--   
--   <pre>
--   data Post = Post
--     { title    :: String
--     , subtitle :: Maybe String
--     , comments :: [String]
--     } deriving (<a>Generic</a>, <a>Show</a>)
--   
--   instance <a>ToForm</a> Post
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeAsFormStable Post { title = "Test", subtitle = Nothing, comments = ["Nice post!", "+1"] }
--   "comments=Nice%20post%21&amp;comments=%2B1&amp;title=Test"
--   </pre>
genericToForm :: forall a. (Generic a, GToForm a (Rep a)) => FormOptions -> a -> Form

-- | A <a>Generic</a>-based implementation of <a>fromForm</a>. This is used
--   as a default implementation in <a>FromForm</a>.
--   
--   Note that this only works for records (i.e. product data types with
--   named fields):
--   
--   <pre>
--   data Person = Person
--     { name :: String
--     , age  :: Int
--     } deriving (<a>Generic</a>)
--   </pre>
--   
--   In this implementation each field's value gets decoded using
--   <a>parseQueryParam</a>. Two field types are exceptions:
--   
--   <ul>
--   <li>for values of type <tt><a>Maybe</a> a</tt> an entry is parsed if
--   present in the <a>Form</a> and the is decoded with
--   <a>parseQueryParam</a>; if no entry is present result is
--   <a>Nothing</a>;</li>
--   <li>for values of type <tt>[a]</tt> (except <tt>[<a>Char</a>]</tt>)
--   all entries are parsed to produce a list of parsed values;</li>
--   </ul>
--   
--   Here's an example:
--   
--   <pre>
--   data Post = Post
--     { title    :: String
--     , subtitle :: Maybe String
--     , comments :: [String]
--     } deriving (<a>Generic</a>, <a>Show</a>)
--   
--   instance <a>FromForm</a> Post
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; urlDecodeAsForm "comments=Nice%20post%21&amp;comments=%2B1&amp;title=Test" :: Either Text Post
--   Right (Post {title = "Test", subtitle = Nothing, comments = ["Nice post!","+1"]})
--   </pre>
genericFromForm :: forall a. (Generic a, GFromForm a (Rep a)) => FormOptions -> Form -> Either Text a

-- | <a>Generic</a>-based deriving options for <a>ToForm</a> and
--   <a>FromForm</a>.
--   
--   A common use case for non-default <a>FormOptions</a> is to strip a
--   prefix off of field labels:
--   
--   <pre>
--   data Project = Project
--     { projectName :: String
--     , projectSize :: Int
--     } deriving (<a>Generic</a>, <a>Show</a>)
--   
--   myOptions :: <a>FormOptions</a>
--   myOptions = <a>FormOptions</a>
--    { <a>fieldLabelModifier</a> = <a>map</a> <tt>toLower</tt> . <a>drop</a> (<a>length</a> "project") }
--   
--   instance <a>ToForm</a> Project where
--     <a>toForm</a> = <a>genericToForm</a> myOptions
--   
--   instance <a>FromForm</a> Project where
--     <a>fromForm</a> = <a>genericFromForm</a> myOptions
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; urlEncodeAsFormStable Project { projectName = "http-api-data", projectSize = 172 }
--   "name=http-api-data&amp;size=172"
--   
--   &gt;&gt;&gt; urlDecodeAsForm "name=http-api-data&amp;size=172" :: Either Text Project
--   Right (Project {projectName = "http-api-data", projectSize = 172})
--   </pre>
data FormOptions
FormOptions :: (String -> String) -> FormOptions

-- | Function applied to field labels. Handy for removing common record
--   prefixes for example.
[fieldLabelModifier] :: FormOptions -> String -> String

-- | Default encoding <a>FormOptions</a>.
--   
--   <pre>
--   <a>FormOptions</a>
--   { <a>fieldLabelModifier</a> = id
--   }
--   </pre>
defaultFormOptions :: FormOptions

-- | A stable version of <a>toList</a>.
toListStable :: Form -> [(Text, Text)]

-- | Parse a <a>Form</a> into a list of entries groupped by key.
--   
--   _NOTE:_ this conversion is unstable and may result in different key
--   order (but not values). For a stable encoding see
--   <a>toEntriesByKeyStable</a>.
toEntriesByKey :: (FromFormKey k, FromHttpApiData v) => Form -> Either Text [(k, [v])]

-- | Parse a <a>Form</a> into a list of entries groupped by key.
--   
--   <pre>
--   &gt;&gt;&gt; toEntriesByKeyStable [("name", "Nick"), ("color", "red"), ("color", "white")] :: Either Text [(Text, [Text])]
--   Right [("color",["red","white"]),("name",["Nick"])]
--   </pre>
--   
--   For an unstable (but faster) conversion see <a>toEntriesByKey</a>.
toEntriesByKeyStable :: (Ord k, FromFormKey k, FromHttpApiData v) => Form -> Either Text [(k, [v])]

-- | Convert a list of entries groupped by key into a <a>Form</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fromEntriesByKey [("name",["Nick"]),("color",["red","blue"])]
--   fromList [("color","red"),("color","blue"),("name","Nick")]
--   </pre>
fromEntriesByKey :: (ToFormKey k, ToHttpApiData v) => [(k, [v])] -> Form

-- | Find all values corresponding to a given key in a <a>Form</a>.
--   
--   <pre>
--   &gt;&gt;&gt; lookupAll "name" []
--   []
--   
--   &gt;&gt;&gt; lookupAll "name" [("name", "Oleg")]
--   ["Oleg"]
--   
--   &gt;&gt;&gt; lookupAll "name" [("name", "Oleg"), ("name", "David")]
--   ["Oleg","David"]
--   </pre>
lookupAll :: Text -> Form -> [Text]

-- | Lookup an optional value for a key. Fail if there is more than one
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; lookupMaybe "name" []
--   Right Nothing
--   
--   &gt;&gt;&gt; lookupMaybe "name" [("name", "Oleg")]
--   Right (Just "Oleg")
--   
--   &gt;&gt;&gt; lookupMaybe "name" [("name", "Oleg"), ("name", "David")]
--   Left "Duplicate key \"name\""
--   </pre>
lookupMaybe :: Text -> Form -> Either Text (Maybe Text)

-- | Lookup a unique value for a key. Fail if there is zero or more than
--   one value.
--   
--   <pre>
--   &gt;&gt;&gt; lookupUnique "name" []
--   Left "Could not find key \"name\""
--   
--   &gt;&gt;&gt; lookupUnique "name" [("name", "Oleg")]
--   Right "Oleg"
--   
--   &gt;&gt;&gt; lookupUnique "name" [("name", "Oleg"), ("name", "David")]
--   Left "Duplicate key \"name\""
--   </pre>
lookupUnique :: Text -> Form -> Either Text Text

-- | Lookup all values for a given key in a <a>Form</a> and parse them with
--   <a>parseQueryParams</a>.
--   
--   <pre>
--   &gt;&gt;&gt; parseAll "age" [] :: Either Text [Word8]
--   Right []
--   
--   &gt;&gt;&gt; parseAll "age" [("age", "8"), ("age", "seven")] :: Either Text [Word8]
--   Left "could not parse: `seven' (input does not start with a digit)"
--   
--   &gt;&gt;&gt; parseAll "age" [("age", "8"), ("age", "777")] :: Either Text [Word8]
--   Left "out of bounds: `777' (should be between 0 and 255)"
--   
--   &gt;&gt;&gt; parseAll "age" [("age", "12"), ("age", "25")] :: Either Text [Word8]
--   Right [12,25]
--   </pre>
parseAll :: FromHttpApiData v => Text -> Form -> Either Text [v]

-- | Lookup an optional value for a given key and parse it with
--   <a>parseQueryParam</a>. Fail if there is more than one value for the
--   key.
--   
--   <pre>
--   &gt;&gt;&gt; parseMaybe "age" [] :: Either Text (Maybe Word8)
--   Right Nothing
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "12"), ("age", "25")] :: Either Text (Maybe Word8)
--   Left "Duplicate key \"age\""
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "seven")] :: Either Text (Maybe Word8)
--   Left "could not parse: `seven' (input does not start with a digit)"
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "777")] :: Either Text (Maybe Word8)
--   Left "out of bounds: `777' (should be between 0 and 255)"
--   
--   &gt;&gt;&gt; parseMaybe "age" [("age", "7")] :: Either Text (Maybe Word8)
--   Right (Just 7)
--   </pre>
parseMaybe :: FromHttpApiData v => Text -> Form -> Either Text (Maybe v)

-- | Lookup a unique value for a given key and parse it with
--   <a>parseQueryParam</a>. Fail if there is zero or more than one value
--   for the key.
--   
--   <pre>
--   &gt;&gt;&gt; parseUnique "age" [] :: Either Text Word8
--   Left "Could not find key \"age\""
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "12"), ("age", "25")] :: Either Text Word8
--   Left "Duplicate key \"age\""
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "seven")] :: Either Text Word8
--   Left "could not parse: `seven' (input does not start with a digit)"
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "777")] :: Either Text Word8
--   Left "out of bounds: `777' (should be between 0 and 255)"
--   
--   &gt;&gt;&gt; parseUnique "age" [("age", "7")] :: Either Text Word8
--   Right 7
--   </pre>
parseUnique :: FromHttpApiData v => Text -> Form -> Either Text v

-- | Encode a list of key-value pairs to an
--   <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>.
--   
--   See also <a>urlEncodeFormStable</a>.
urlEncodeParams :: [(Text, Text)] -> ByteString

-- | Decode an <tt>application/x-www-form-urlencoded</tt> <a>ByteString</a>
--   to a list of key-value pairs.
--   
--   See also <a>urlDecodeForm</a>.
urlDecodeParams :: ByteString -> Either Text [(Text, Text)]


-- | 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.
--   
--   <b>WARNING</b>: Do not derive this using <tt>DeriveAnyClass</tt> as
--   the generated instance will loop indefinitely.
class ToHttpApiData a

-- | Convert to URL path piece.
toUrlPiece :: ToHttpApiData a => a -> Text

-- | Convert to a URL path piece, making sure to encode any special chars.
--   The default definition uses <a>encodePathSegmentsRelative</a>, but
--   this may be overriden with a more efficient version.
toEncodedUrlPiece :: ToHttpApiData a => a -> Builder

-- | 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.
--   
--   <b>WARNING</b>: Do not derive this using <tt>DeriveAnyClass</tt> as
--   the generated instance will loop indefinitely.
class FromHttpApiData a

-- | 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 <tt><a>Maybe</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseUrlPieceMaybe "12" :: Maybe Int
--   Just 12
--   </pre>
parseUrlPieceMaybe :: FromHttpApiData a => Text -> Maybe a

-- | Parse HTTP header value in a <tt><a>Maybe</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseHeaderMaybe "hello" :: Maybe Text
--   Just "hello"
--   </pre>
parseHeaderMaybe :: FromHttpApiData a => ByteString -> Maybe a

-- | Parse query param value in a <tt><a>Maybe</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseQueryParamMaybe "true" :: Maybe Bool
--   Just True
--   </pre>
parseQueryParamMaybe :: FromHttpApiData a => Text -> Maybe a

-- | <i>Case insensitive</i>.
--   
--   Parse given text case insensitive and then parse the rest of the input
--   using <tt><a>parseUrlPiece</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseUrlPieceWithPrefix "Just " "just 10" :: Either Text Int
--   Right 10
--   
--   &gt;&gt;&gt; parseUrlPieceWithPrefix "Left " "left" :: Either Text Bool
--   Left "could not parse: `left'"
--   </pre>
--   
--   This can be used to implement <tt><a>FromHttpApiData</a></tt> for
--   single field constructors:
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo Int deriving (Show)
--   
--   &gt;&gt;&gt; instance FromHttpApiData Foo where parseUrlPiece s = Foo &lt;$&gt; parseUrlPieceWithPrefix "Foo " s
--   
--   &gt;&gt;&gt; parseUrlPiece "foo 1" :: Either Text Foo
--   Right (Foo 1)
--   </pre>
parseUrlPieceWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a

-- | Parse given bytestring then parse the rest of the input using
--   <tt><a>parseHeader</a></tt>.
--   
--   <pre>
--   data BasicAuthToken = BasicAuthToken Text deriving (Show)
--   
--   instance FromHttpApiData BasicAuthToken where
--     parseHeader h     = BasicAuthToken &lt;$&gt; parseHeaderWithPrefix "Basic " h
--     parseQueryParam p = BasicAuthToken &lt;$&gt; parseQueryParam p
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseHeader "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" :: Either Text BasicAuthToken
--   Right (BasicAuthToken "QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
--   </pre>
parseHeaderWithPrefix :: FromHttpApiData a => ByteString -> ByteString -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse given text case insensitive and then parse the rest of the input
--   using <tt><a>parseQueryParam</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; parseQueryParamWithPrefix "z" "z10" :: Either Text Int
--   Right 10
--   </pre>
parseQueryParamWithPrefix :: FromHttpApiData a => Text -> Text -> Either Text a

-- | Convert multiple values to a list of URL pieces.
--   
--   <pre>
--   &gt;&gt;&gt; toUrlPieces [1, 2, 3] :: [Text]
--   ["1","2","3"]
--   </pre>
toUrlPieces :: (Functor t, ToHttpApiData a) => t a -> t Text

-- | Parse multiple URL pieces.
--   
--   <pre>
--   &gt;&gt;&gt; parseUrlPieces ["true", "false"] :: Either Text [Bool]
--   Right [True,False]
--   
--   &gt;&gt;&gt; parseUrlPieces ["123", "hello", "world"] :: Either Text [Int]
--   Left "could not parse: `hello' (input does not start with a digit)"
--   </pre>
parseUrlPieces :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)

-- | Convert multiple values to a list of query parameter values.
--   
--   <pre>
--   &gt;&gt;&gt; toQueryParams [fromGregorian 2015 10 03, fromGregorian 2015 12 01] :: [Text]
--   ["2015-10-03","2015-12-01"]
--   </pre>
toQueryParams :: (Functor t, ToHttpApiData a) => t a -> t Text

-- | Parse multiple query parameters.
--   
--   <pre>
--   &gt;&gt;&gt; parseQueryParams ["1", "2", "3"] :: Either Text [Int]
--   Right [1,2,3]
--   
--   &gt;&gt;&gt; parseQueryParams ["64", "128", "256"] :: Either Text [Word8]
--   Left "out of bounds: `256' (should be between 0 and 255)"
--   </pre>
parseQueryParams :: (Traversable t, FromHttpApiData a) => t Text -> Either Text (t a)

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on <tt><a>ToHttpApiData</a></tt>
--   instance. Uses <tt><a>toUrlPiece</a></tt> to get possible values.
parseBoundedUrlPiece :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on <tt><a>ToHttpApiData</a></tt>
--   instance. Uses <tt><a>toQueryParam</a></tt> to get possible values.
parseBoundedQueryParam :: (ToHttpApiData a, Bounded a, Enum a) => Text -> Either Text a

-- | Parse values based on <tt><a>ToHttpApiData</a></tt> instance. Uses
--   <tt><a>toHeader</a></tt> to get possible values.
parseBoundedHeader :: (ToHttpApiData a, Bounded a, Enum a) => ByteString -> Either Text a

-- | Parse values based on a precalculated mapping of their
--   <tt><a>Text</a></tt> representation.
--   
--   <pre>
--   &gt;&gt;&gt; parseBoundedEnumOf toUrlPiece "true" :: Either Text Bool
--   Right True
--   </pre>
--   
--   For case sensitive parser see <a>parseBoundedEnumOfI</a>.
parseBoundedEnumOf :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on a precalculated mapping of
--   their <tt><a>Text</a></tt> representations.
--   
--   <pre>
--   &gt;&gt;&gt; parseBoundedEnumOfI toUrlPiece "FALSE" :: Either Text Bool
--   Right False
--   </pre>
--   
--   For case sensitive parser see <a>parseBoundedEnumOf</a>.
parseBoundedEnumOfI :: (Bounded a, Enum a) => (a -> Text) -> Text -> Either Text a

-- | <i>Case insensitive</i>.
--   
--   Parse values case insensitively based on <tt><a>Show</a></tt>
--   instance.
--   
--   <pre>
--   &gt;&gt;&gt; parseBoundedTextData "true" :: Either Text Bool
--   Right True
--   
--   &gt;&gt;&gt; parseBoundedTextData "FALSE" :: Either Text Bool
--   Right False
--   </pre>
--   
--   This can be used as a default implementation for enumeration types:
--   
--   <pre>
--   &gt;&gt;&gt; data MyData = Foo | Bar | Baz deriving (Show, Bounded, Enum)
--   
--   &gt;&gt;&gt; instance FromHttpApiData MyData where parseUrlPiece = parseBoundedTextData
--   
--   &gt;&gt;&gt; parseUrlPiece "foo" :: Either Text MyData
--   Right Foo
--   </pre>
parseBoundedTextData :: (Show a, Bounded a, Enum a) => Text -> Either Text a

-- | Lenient parameters. <a>FromHttpApiData</a> combinators always return
--   <a>Right</a>.
newtype LenientData a
LenientData :: Either Text a -> LenientData a
[getLenientData] :: LenientData a -> Either Text a

-- | <i>Lower case</i>.
--   
--   Convert to URL piece using <tt><a>Show</a></tt> instance. The result
--   is always lower cased.
--   
--   <pre>
--   &gt;&gt;&gt; showTextData True
--   "true"
--   </pre>
--   
--   This can be used as a default implementation for enumeration types:
--   
--   <pre>
--   &gt;&gt;&gt; data MyData = Foo | Bar | Baz deriving (Show)
--   
--   &gt;&gt;&gt; instance ToHttpApiData MyData where toUrlPiece = showTextData
--   
--   &gt;&gt;&gt; toUrlPiece Foo
--   "foo"
--   </pre>
showTextData :: Show a => a -> Text

-- | Parse URL piece using <tt><a>Read</a></tt> instance.
--   
--   Use for types which do not involve letters:
--   
--   <pre>
--   &gt;&gt;&gt; readTextData "1991-06-02" :: Either Text Day
--   Right 1991-06-02
--   </pre>
--   
--   This parser is case sensitive and will not match
--   <tt><a>showTextData</a></tt> in presence of letters:
--   
--   <pre>
--   &gt;&gt;&gt; readTextData (showTextData True) :: Either Text Bool
--   Left "could not parse: `true'"
--   </pre>
--   
--   See <tt><a>parseBoundedTextData</a></tt>.
readTextData :: Read a => Text -> Either Text a