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


-- | Simple http queries
--   
--   Simple web API queries returning JSON.
@package http-query
@version 0.1.2


-- | A small library for querying a Web API.
--   
--   <pre>
--   import Data.Text.IO as T
--   import Network.HTTP.Query
--   
--   main = do
--     let api = "<a>http://www.example.com/api/1"</a>
--         endpoint = api +/+ "search"
--     res &lt;- webAPIQuery endpoint $ makeKey "q" "needle"
--     T.putStrLn $
--       case lookupKey "results" res of
--         Nothing -&gt;
--           fromMaybe "search failed" $ lookupKey "error" res
--         Just results -&gt;
--           lookupKey' "location" results
--   </pre>
module Network.HTTP.Query

-- | Query.
--   
--   General form: <tt>a=b&amp;c=d</tt>, but if the value is Nothing, it
--   becomes <tt>a&amp;c=d</tt>.
type Query = [QueryItem]

-- | Query item
type QueryItem = (ByteString, Maybe ByteString)

-- | Maybe create a query key
maybeKey :: String -> Maybe String -> Query

-- | Make a singleton key-value Query
makeKey :: String -> String -> Query

-- | Make a key-value QueryItem
makeItem :: String -> String -> QueryItem

-- | Combine two path segments with a slash
--   
--   <pre>
--   "abc" +/+ "def" == "abc/def"
--   "abc/" +/+ "def" == "abc/def"
--   "abc" +/+ "/def" == "abc/def"
--   </pre>
(+/+) :: String -> String -> String
infixr 5 +/+

-- | Low-level web api query
webAPIQuery :: (MonadIO m, FromJSON a) => String -> Query -> m a

-- | Get the URI for a web query
apiQueryURI :: String -> Query -> URI

-- | Look up key in object
lookupKey :: FromJSON a => Text -> Object -> Maybe a

-- | Like lookupKey but returns error message if not found
lookupKeyEither :: FromJSON a => Text -> Object -> Either String a

-- | Like lookupKey but raises an error if no key found
lookupKey' :: FromJSON a => Text -> Object -> a