-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Picklers for de/serialising Generic data types to and from query strings
--   
--   Type classes, pickling combinators, and GHC.Generics implementations
--   for Query Strings
@package querystring-pickle
@version 0.1.4

module Network.HTTP.QueryString.Pickle

-- | A type that has a pairing of pickler + unpickler.
--   
--   Using the <tt>DeriveGeneric</tt> language extension, this class
--   specifies a default generic implementation using
--   <a>genericQueryPickler</a>.
--   
--   For example:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Foo { fooIntX :: Int, fooIntY :: Int } deriving (Generic)
--   
--   instance IsQuery Foo
--   </pre>
--   
--   Note that you can parameterise some of the options to
--   <a>genericQueryPickler</a> by specifying an implementation instead of
--   using <tt>DefaultSignatures</tt>.
--   
--   The previous example:
--   
--   <pre>
--   instance IsQuery Foo where
--       queryPickler = <a>genericQueryPickler</a> <a>defaultQueryOptions</a>
--   </pre>
--   
--   More examples of creating <a>queryPickler</a> implementations can be
--   found in the <tt>README</tt> or in the <tt>tests</tt>.
class IsQuery a where queryPickler = genericQueryPickler defaultQueryOptions
queryPickler :: IsQuery a => PU a

-- | Pickle a data type with an <a>IsQuery</a> instance to an association
--   list.
toQuery :: IsQuery a => a -> [(ByteString, ByteString)]

-- | Unpickle an association list to an <a>IsQuery</a> type, returning an
--   error message when unpickling fails.
fromQuery :: IsQuery a => [(ByteString, ByteString)] -> Either String a

-- | Helper to encode an association list as a single canonical query
--   string.
encodeQuery :: (ByteString -> ByteString) -> [(ByteString, ByteString)] -> ByteString

-- | Helper to decode a query string to an association list.
decodeQuery :: (ByteString -> ByteString) -> ByteString -> [(ByteString, ByteString)]

-- | Internal tree representation for queries.
data Query
List :: [Query] -> Query
Pair :: ByteString -> Query -> Query
Value :: ByteString -> Query

-- | Pairing of pickler to unpickler.
data QueryPU a
QueryPU :: (a -> Query) -> (Query -> Either String a) -> QueryPU a
pickle :: QueryPU a -> a -> Query
unpickle :: QueryPU a -> Query -> Either String a

-- | Options for <a>genericQueryPickler</a> to parameterise how constructor
--   and record field labels are un/pickled.
--   
--   For example:
--   
--   <pre>
--   import GHC.Generics
--   
--   data Bar { barThisIsAByteString :: ByteString } deriving (Generic)
--   
--   instance IsQuery Foo where
--        queryPickler = <a>genericQueryPickler</a> $ Options
--            { queryCtorModifier  = id
--            , queryFieldModifier = dropWhile isLower
--            }
--   </pre>
--   
--   Would remove <tt>bar</tt> from the record field
--   <tt>barThisIsAByteString</tt> so the resulting pair for that field in
--   the association list would be <tt>(ThisIsAByteString, n :: Int)</tt>.
--   
--   The above example is how <a>defaultQueryOptions</a> behaves.
data QueryOptions
QueryOptions :: (String -> String) -> (String -> String) -> QueryOptions

-- | Function applied to constructor tags.
queryCtorModifier :: QueryOptions -> String -> String

-- | Function applied to record field labels.
queryFieldModifier :: QueryOptions -> String -> String

-- | Strips lowercase prefixes from record fields.
defaultQueryOptions :: QueryOptions

-- | Strips lowercase prefixes from record fields and subsequently
--   lowercases the remaining identifier.
loweredQueryOptions :: QueryOptions
genericQueryPickler :: (Generic x, GIsQuery (Rep x)) => QueryOptions -> PU x
qpWrap :: (a -> b, b -> a) -> PU a -> PU b
qpElem :: ByteString -> PU a -> PU a
qpPair :: PU a -> PU b -> PU (a, b)
qpLift :: a -> PU a
qpPrim :: (Read a, Show a) => PU a
qpOption :: PU a -> PU (Maybe a)
qpDefault :: a -> PU a -> PU a
qpSum :: PU (f r) -> PU (g r) -> PU ((f :+: g) r)
qpEither :: PU a -> PU b -> PU (Either a b)
qpOrdinalList :: PU a -> PU [a]
qpList :: PU a -> PU [a]
instance [overlap ok] Eq Query
instance [overlap ok] Show Query
instance [overlap ok] IsQuery ByteString
instance [overlap ok] IsQuery Integer
instance [overlap ok] IsQuery Int
instance [overlap ok] And True False False
instance [overlap ok] And False True False
instance [overlap ok] And False False False
instance [overlap ok] And True True True
instance [overlap ok] AllNullary U1 True
instance [overlap ok] AllNullary (K1 i c) False
instance [overlap ok] AllNullary (a :*: b) False
instance [overlap ok] AllNullary a allNullary => AllNullary (M1 i c a) allNullary
instance [overlap ok] (AllNullary a allNullaryL, AllNullary b allNullaryR, And allNullaryL allNullaryR allNullary) => AllNullary (a :+: b) allNullary
instance [overlap ok] IsRecord U1 False
instance [overlap ok] IsRecord (K1 i c) True
instance [overlap ok] IsRecord f isRecord => IsRecord (M1 S c f) isRecord
instance [overlap ok] IsRecord (M1 S NoSelector f) False
instance [overlap ok] IsRecord f isRecord => IsRecord (f :*: g) isRecord
instance [overlap ok] (Selector s, IsQuery a) => RecIsQuery (S1 s (K1 i (Maybe a)))
instance [overlap ok] (Selector s, GIsQuery a) => RecIsQuery (S1 s a)
instance [overlap ok] (RecIsQuery a, RecIsQuery b) => RecIsQuery (a :*: b)
instance [overlap ok] GIsQuery f => CtorIsQuery' f False
instance [overlap ok] RecIsQuery f => CtorIsQuery' f True
instance [overlap ok] (IsRecord f isRecord, CtorIsQuery' f isRecord) => CtorIsQuery f
instance [overlap ok] Constructor c => SumIsQuery (C1 c U1)
instance [overlap ok] (SumIsQuery a, SumIsQuery b) => SumIsQuery (a :+: b)
instance [overlap ok] SumIsQuery (a :+: b) => NullIsQuery (a :+: b) True
instance [overlap ok] (AllNullary (a :+: b) allNullary, NullIsQuery (a :+: b) allNullary) => GIsQuery (a :+: b)
instance [overlap ok] CtorIsQuery a => GIsQuery (C1 c a)
instance [overlap ok] GIsQuery a => GIsQuery (M1 i d a)
instance [overlap ok] GIsQuery U1
instance [overlap ok] IsQuery a => GIsQuery (K1 i a)
instance [overlap ok] Monoid Query
instance [overlap ok] Ord Query