-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A family of combinators for defining webservices APIs
--
@package servant
@version 0.4.2
module Servant.Common.Text
-- | For getting values from url captures and query string parameters
-- Instances should obey: > fromText (toText a) == Just a
class FromText a
fromText :: FromText a => Text -> Maybe a
-- | For putting values in paths and query string parameters Instances
-- should obey: > fromText (toText a) == Just a
class ToText a
toText :: ToText a => a -> Text
instance ToText Float
instance FromText Float
instance ToText Double
instance FromText Double
instance ToText Integer
instance FromText Integer
instance ToText Word64
instance FromText Word64
instance ToText Word32
instance FromText Word32
instance ToText Word16
instance FromText Word16
instance ToText Word8
instance FromText Word8
instance ToText Word
instance FromText Word
instance ToText Int64
instance FromText Int64
instance ToText Int32
instance FromText Int32
instance ToText Int16
instance FromText Int16
instance ToText Int8
instance FromText Int8
instance ToText Int
instance FromText Int
instance ToText Bool
instance FromText Bool
instance ToText String
instance FromText String
instance ToText Text
instance FromText Text
module Servant.API.Raw
-- | Endpoint for plugging in your own Wai Applications.
--
-- The given Application will get the request as received by the
-- server, potentially with a modified (stripped) pathInfo if
-- the Application is being routed with :>.
--
-- In addition to just letting you plug in your existing WAI
-- Applications, this can also be used with
-- serveDirectory to serve static files stored in a particular
-- directory on your filesystem
data Raw
instance Typeable Raw
-- | A collection of basic Content-Types (also known as Internet Media
-- Types, or MIME types). Additionally, this module provides classes that
-- encapsulate how to serialize or deserialize values to or from a
-- particular Content-Type.
--
-- Content-Types are used in ReqBody and the method combinators:
--
--
-- >>> type MyEndpoint = ReqBody '[JSON, PlainText] Book :> Get '[JSON, PlainText] :> Book
--
--
-- Meaning the endpoint accepts requests of Content-Type
-- application/json or text/plain;charset-utf8, and
-- returns data in either one of those formats (depending on the
-- Accept header).
--
-- If you would like to support Content-Types beyond those provided here,
-- then:
--
--
-- - Declare a new data type with no constructors (e.g. data
-- HTML).
-- - Make an instance of it for Accept.
-- - If you want to be able to serialize data *into* that Content-Type,
-- make an instance of it for MimeRender.
-- - If you want to be able to deserialize data *from* that
-- Content-Type, make an instance of it for MimeUnrender.
--
--
-- Note that roles are reversed in servant-server and
-- servant-client: to be able to serve (or even typecheck) a
-- Get '[JSON, XML] MyData, you'll need to have the appropriate
-- MimeRender instances in scope, whereas to query that endpoint
-- with servant-client, you'll need a MimeUnrender
-- instance in scope.
module Servant.API.ContentTypes
data JSON
data PlainText
data FormUrlEncoded
data OctetStream
-- | Instances of Accept represent mimetypes. They are used for
-- matching against the Accept HTTP header of the request, and
-- for setting the Content-Type header of the response
--
-- Example:
--
--
-- >>> import Network.HTTP.Media ((//), (/:))
--
-- >>> data HTML
--
-- >>> :{
-- instance Accept HTML where
-- contentType _ = "text" // "html" /: ("charset", "utf-8")
-- :}
--
class Accept ctype
contentType :: Accept ctype => Proxy ctype -> MediaType
-- | Instantiate this class to register a way of serializing a type based
-- on the Accept header.
--
-- Example:
--
--
-- data MyContentType
--
-- instance Accept MyContentType where
-- contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8")
--
-- instance Show a => MimeRender MyContentType where
-- mimeRender _ val = pack ("This is MINE! " ++ show val)
--
-- type MyAPI = "path" :> Get '[MyContentType] Int
--
class Accept ctype => MimeRender ctype a
mimeRender :: MimeRender ctype a => Proxy ctype -> a -> ByteString
-- | Instantiate this class to register a way of deserializing a type based
-- on the request's Content-Type header.
--
--
-- >>> import Network.HTTP.Media hiding (Accept)
--
-- >>> import qualified Data.ByteString.Lazy.Char8 as BSC
--
-- >>> data MyContentType = MyContentType String
--
--
--
-- >>> :{
-- instance Accept MyContentType where
-- contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8")
-- :}
--
--
--
-- >>> :{
-- instance Read a => MimeUnrender MyContentType a where
-- mimeUnrender _ bs = case BSC.take 12 bs of
-- "MyContentType" -> return . read . BSC.unpack $ BSC.drop 12 bs
-- _ -> Left "didn't start with the magic incantation"
-- :}
--
--
--
-- >>> type MyAPI = "path" :> ReqBody '[MyContentType] Int :> Get '[JSON] Int
--
class Accept ctype => MimeUnrender ctype a
mimeUnrender :: MimeUnrender ctype a => Proxy ctype -> ByteString -> Either String a
newtype AcceptHeader
AcceptHeader :: ByteString -> AcceptHeader
class AllCTRender (list :: [*]) a
handleAcceptH :: AllCTRender list a => Proxy list -> AcceptHeader -> a -> Maybe (ByteString, ByteString)
class IsNonEmpty list => AllCTUnrender (list :: [*]) a
handleCTypeH :: AllCTUnrender list a => Proxy list -> ByteString -> ByteString -> Maybe (Either String a)
class AllMimeRender (list :: [*]) a
allMimeRender :: AllMimeRender list a => Proxy list -> a -> [(MediaType, ByteString)]
class AllMimeUnrender (list :: [*]) a
allMimeUnrender :: AllMimeUnrender list a => Proxy list -> ByteString -> [(MediaType, Either String a)]
-- | A type that can be converted from
-- application/x-www-form-urlencoded, with the possibility of
-- failure.
class FromFormUrlEncoded a
fromFormUrlEncoded :: FromFormUrlEncoded a => [(Text, Text)] -> Either String a
-- | A type that can be converted to
-- application/x-www-form-urlencoded
class ToFormUrlEncoded a
toFormUrlEncoded :: ToFormUrlEncoded a => a -> [(Text, Text)]
-- | Like eitherDecode but allows all JSON values instead of just
-- objects and arrays.
--
-- Will handle trailing whitespace, but not trailing junk. ie.
--
--
-- >>> eitherDecodeLenient "1 " :: Either String Int
-- Right 1
--
--
--
-- >>> eitherDecodeLenient "1 junk" :: Either String Int
-- Left "trailing junk after valid JSON: endOfInput"
--
eitherDecodeLenient :: FromJSON a => ByteString -> Either String a
instance Typeable JSON
instance Typeable PlainText
instance Typeable FormUrlEncoded
instance Typeable OctetStream
instance Eq AcceptHeader
instance Show AcceptHeader
instance FromFormUrlEncoded [(Text, Text)]
instance ToFormUrlEncoded [(Text, Text)]
instance MimeUnrender OctetStream ByteString
instance MimeUnrender OctetStream ByteString
instance MimeUnrender PlainText Text
instance MimeUnrender PlainText Text
instance FromFormUrlEncoded a => MimeUnrender FormUrlEncoded a
instance FromJSON a => MimeUnrender JSON a
instance MimeRender OctetStream ByteString
instance MimeRender OctetStream ByteString
instance MimeRender PlainText Text
instance MimeRender PlainText Text
instance ToFormUrlEncoded a => MimeRender FormUrlEncoded a
instance ToJSON a => MimeRender JSON a
instance (MimeUnrender ctyp a, AllMimeUnrender ctyps a) => AllMimeUnrender (ctyp : ctyps) a
instance AllMimeUnrender '[] a
instance AllMimeRender '[] a
instance (MimeRender ctyp a, AllMimeRender (ctyp' : ctyps) a) => AllMimeRender (ctyp : ctyp' : ctyps) a
instance MimeRender ctyp a => AllMimeRender '[ctyp] a
instance (AllMimeUnrender ctyps a, IsNonEmpty ctyps) => AllCTUnrender ctyps a
instance (AllMimeRender ctyps a, IsNonEmpty ctyps) => AllCTRender ctyps a
instance Accept OctetStream
instance Accept PlainText
instance Accept FormUrlEncoded
instance Accept JSON
module Servant.API.Patch
-- | Endpoint for PATCH requests. The type variable represents the type of
-- the response body (not the request body, use ReqBody for that).
--
-- If the HTTP response is empty, only () is supported.
--
-- Example:
--
--
-- >>> -- PATCH /books
--
-- >>> -- with a JSON encoded Book as the request body
--
-- >>> -- returning the just-created Book
--
-- >>> type MyApi = "books" :> ReqBody '[JSON] Book :> Patch '[JSON] Book
--
data Patch (contentTypes :: [*]) a
instance Typeable Patch
module Servant.API.Put
-- | Endpoint for PUT requests, usually used to update a ressource. The
-- type a is the type of the response body that's returned.
--
-- Example:
--
--
-- >>> -- PUT /books/:isbn
--
-- >>> -- with a Book as request body, returning the updated Book
--
-- >>> type MyApi = "books" :> Capture "isbn" Text :> ReqBody '[JSON] Book :> Put '[JSON] Book
--
data Put (contentTypes :: [*]) a
instance Typeable Put
module Servant.API.Delete
-- | Combinator for DELETE requests.
--
-- Example:
--
--
-- >>> -- DELETE /books/:isbn
--
-- >>> type MyApi = "books" :> Capture "isbn" Text :> Delete
--
data Delete (contentTypes :: [*]) a
instance Typeable Delete
module Servant.API.Post
-- | Endpoint for POST requests. The type variable represents the type of
-- the response body (not the request body, use ReqBody for that).
--
-- Example:
--
--
-- >>> -- POST /books
--
-- >>> -- with a JSON encoded Book as the request body
--
-- >>> -- returning the just-created Book
--
-- >>> type MyApi = "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book
--
data Post (contentTypes :: [*]) a
instance Typeable Post
module Servant.API.Get
-- | Endpoint for simple GET requests. Serves the result as JSON.
--
-- Example:
--
--
-- >>> type MyApi = "books" :> Get '[JSON] [Book]
--
data Get (contentTypes :: [*]) a
instance Typeable Get
module Servant.API.MatrixParam
-- | Lookup a potentially value-less matrix string parameter with boolean
-- semantics. If the param sym is there without any value, or if
-- it's there with value "true" or "1", it's interpreted as True.
-- Otherwise, it's interpreted as False.
--
-- Example:
--
--
-- >>> -- /books;published
--
-- >>> type MyApi = "books" :> MatrixFlag "published" :> Get '[JSON] [Book]
--
data MatrixFlag (sym :: Symbol)
-- | Lookup the value associated to the sym matrix string
-- parameter and try to extract it as a value of type a.
--
-- Example:
--
--
-- >>> -- /books;author=<author name>
--
-- >>> type MyApi = "books" :> MatrixParam "author" Text :> Get '[JSON] [Book]
--
data MatrixParam (sym :: Symbol) a
-- | Lookup the values associated to the sym matrix string
-- parameter and try to extract it as a value of type [a]. This
-- is typically meant to support matrix string parameters of the form
-- param[]=val1;param[]=val2 and so on. Note that servant
-- doesn't actually require the []s and will fetch the values
-- just fine with param=val1;param=val2, too.
--
-- Example:
--
--
-- >>> -- /books;authors[]=<author1>;authors[]=<author2>;...
--
-- >>> type MyApi = "books" :> MatrixParams "authors" Text :> Get '[JSON] [Book]
--
data MatrixParams (sym :: Symbol) a
instance Typeable MatrixParam
instance Typeable MatrixParams
instance Typeable MatrixFlag
module Servant.API.ReqBody
-- | Extract the request body as a value of type a.
--
-- Example:
--
--
-- >>> -- POST /books
--
-- >>> type MyApi = "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book
--
data ReqBody (contentTypes :: [*]) a
instance Typeable ReqBody
module Servant.API.QueryParam
-- | Lookup a potentially value-less query string parameter with boolean
-- semantics. If the param sym is there without any value, or if
-- it's there with value "true" or "1", it's interpreted as True.
-- Otherwise, it's interpreted as False.
--
-- Example:
--
--
-- >>> -- /books?published
--
-- >>> type MyApi = "books" :> QueryFlag "published" :> Get '[JSON] [Book]
--
data QueryFlag (sym :: Symbol)
-- | Lookup the value associated to the sym query string parameter
-- and try to extract it as a value of type a.
--
-- Example:
--
--
-- >>> -- /books?author=<author name>
--
-- >>> type MyApi = "books" :> QueryParam "author" Text :> Get '[JSON] [Book]
--
data QueryParam (sym :: Symbol) a
-- | Lookup the values associated to the sym query string
-- parameter and try to extract it as a value of type [a]. This
-- is typically meant to support query string parameters of the form
-- param[]=val1¶m[]=val2 and so on. Note that servant
-- doesn't actually require the []s and will fetch the values
-- just fine with param=val1¶m=val2, too.
--
-- Example:
--
--
-- >>> -- /books?authors[]=<author1>&authors[]=<author2>&...
--
-- >>> type MyApi = "books" :> QueryParams "authors" Text :> Get '[JSON] [Book]
--
data QueryParams (sym :: Symbol) a
instance Typeable QueryParam
instance Typeable QueryParams
module Servant.API.Header
-- | Extract the given header's value as a value of type a.
--
-- Example:
--
--
-- >>> newtype Referer = Referer Text deriving (Eq, Show)
--
-- >>>
--
-- >>> -- GET /view-my-referer
--
-- >>> type MyApi = "view-my-referer" :> Header "from" Referer :> Get '[JSON] Referer
--
data Header (sym :: Symbol) a
Header :: a -> Header a
MissingHeader :: Header a
UndecodableHeader :: ByteString -> Header a
instance Typeable Header
instance Eq a => Eq (Header sym a)
instance Show a => Show (Header sym a)
instance Functor (Header sym)
-- | This module provides facilities for adding headers to a response.
--
--
-- >>> let headerVal = addHeader "some-url" 5 :: Headers '[Header "Location" String] Int
--
--
-- The value is added to the header specified by the type
-- (Location in the example above).
module Servant.API.ResponseHeaders
-- | Response Header objects. You should never need to construct one
-- directly. Instead, use addHeader.
data Headers ls a
Headers :: a -> HList ls -> Headers ls a
-- | The underlying value of a Headers
getResponse :: Headers ls a -> a
-- | HList of headers.
getHeadersHList :: Headers ls a -> HList ls
class AddHeader h v orig new | h v orig -> new, new -> h, new -> v, new -> orig
addHeader :: AddHeader h v orig new => v -> orig -> new
class BuildHeadersTo hs
buildHeadersTo :: BuildHeadersTo hs => [Header] -> HList hs
class GetHeaders ls
getHeaders :: GetHeaders ls => ls -> [Header]
data HList a
HNil :: HList []
HCons :: Header h x -> HList xs -> HList (Header h x : xs)
instance [overlap ok] Functor (Headers ls)
instance [overlap ok] (KnownSymbol h, ToByteString v, new ~ Headers '[Header h v] a) => AddHeader h v a new
instance [overlap ok] (KnownSymbol h, ToByteString v, Contains h (fst : rest) ~ 'False) => AddHeader h v (Headers (fst : rest) a) (Headers (Header h v : fst : rest) a)
instance [overlap ok] (KnownSymbol h, GetHeaders (HList rest), ToByteString v) => GetHeaders (Headers (Header h v : rest) a)
instance [overlap ok] GetHeaders (Headers '[] a)
instance [overlap ok] (KnownSymbol h, ToByteString x, GetHeaders (HList xs)) => GetHeaders (HList (Header h x : xs))
instance [overlap ok] GetHeaders (HList '[])
instance [overlap ok] (FromByteString v, BuildHeadersTo xs, KnownSymbol h, Contains h xs ~ 'False) => BuildHeadersTo (Header h v : xs)
instance [overlap ok] BuildHeadersTo '[]
module Servant.API.Capture
-- | Capture a value from the request path under a certain type a.
--
-- Example:
--
--
-- >>> -- GET /books/:isbn
--
-- >>> type MyApi = "books" :> Capture "isbn" Text :> Get '[JSON] Book
--
data Capture (sym :: Symbol) a
instance Typeable Capture
module Servant.API.Alternative
-- | Union of two APIs, first takes precedence in case of overlap.
--
-- Example:
--
--
-- >>> :{
-- type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
-- :<|> "books" :> ReqBody '[JSON] Book :> Post '[JSON] () -- POST /books
-- :}
--
data (:<|>) a b
(:<|>) :: a -> b -> (:<|>) a b
instance Typeable (:<|>)
instance (Eq a, Eq b) => Eq (a :<|> b)
instance (Show a, Show b) => Show (a :<|> b)
instance (Monoid a, Monoid b) => Monoid (a :<|> b)
module Servant.API.Sub
-- | The contained API (second argument) can be found under ("/" ++
-- path) (path being the first argument).
--
-- Example:
--
--
-- >>> -- GET /hello/world
--
-- >>> -- returning a JSON encoded World value
--
-- >>> type MyApi = "hello" :> "world" :> Get '[JSON] World
--
data (:>) (path :: k) a
instance Typeable (:>)
-- | Type safe generation of internal links.
--
-- Given an API with a few endpoints:
--
--
-- >>> :set -XDataKinds -XTypeFamilies -XTypeOperators
--
-- >>> import Servant.API
--
-- >>> import Servant.Utils.Links
--
-- >>> import Data.Proxy
--
-- >>>
--
-- >>>
--
-- >>>
--
-- >>> type Hello = "hello" :> Get '[JSON] Int
--
-- >>> type Bye = "bye" :> QueryParam "name" String :> Delete '[JSON] ()
--
-- >>> type API = Hello :<|> Bye
--
-- >>> let api = Proxy :: Proxy API
--
--
-- It is possible to generate links that are guaranteed to be within
-- API with safeLink. The first argument to
-- safeLink is a type representing the API you would like to
-- restrict links to. The second argument is the destination endpoint you
-- would like the link to point to, this will need to end with a verb
-- like GET or POST. Further arguments may be required depending on the
-- type of the endpoint. If everything lines up you will get a URI
-- out the other end.
--
-- You may omit QueryParams and the like should you not want to
-- provide them, but types which form part of the URL path like
-- Capture must be included. The reason you may want to omit
-- QueryParams is that safeLink is a bit magical: if parameters
-- are included that could take input it will return a function that
-- accepts that input and generates a link. This is best shown with an
-- example. Here, a link is generated with no parameters:
--
--
-- >>> let hello = Proxy :: Proxy ("hello" :> Get '[JSON] Int)
--
-- >>> print (safeLink api hello :: URI)
-- hello
--
--
-- If the API has an endpoint with parameters then we can generate links
-- with or without those:
--
--
-- >>> let with = Proxy :: Proxy ("bye" :> QueryParam "name" String :> Delete '[JSON] ())
--
-- >>> print $ safeLink api with "Hubert"
-- bye?name=Hubert
--
--
--
-- >>> let without = Proxy :: Proxy ("bye" :> Delete '[JSON] ())
--
-- >>> print $ safeLink api without
-- bye
--
--
-- If you would like create a helper for generating links only within
-- that API, you can partially apply safeLink if you specify a correct
-- type signature like so:
--
--
-- >>> :set -XConstraintKinds
--
-- >>> :{
--
-- >>> let apiLink :: (IsElem endpoint API, HasLink endpoint)
--
-- >>> => Proxy endpoint -> MkLink endpoint
--
-- >>> apiLink = safeLink api
--
-- >>> :}
--
--
-- Attempting to construct a link to an endpoint that does not exist in
-- api will result in a type error like this:
--
--
-- >>> let bad_link = Proxy :: Proxy ("hello" :> Delete '[JSON] ())
--
-- >>> safeLink api bad_link
-- ...
-- Could not deduce (Or
-- (IsElem' (Delete '[JSON] ()) (Get '[JSON] Int))
-- (IsElem'
-- ("hello" :> Delete '[JSON] ())
-- ("bye" :> (QueryParam "name" String :> Delete '[JSON] ()))))
-- arising from a use of ‘safeLink’
-- In the expression: safeLink api bad_link
-- In an equation for ‘it’: it = safeLink api bad_link
--
--
-- This error is essentially saying that the type family couldn't find
-- bad_link under api after trying the open (but empty) type family
-- IsElem' as a last resort.
module Servant.Utils.Links
-- | Create a valid (by construction) relative URI with query params.
--
-- This function will only typecheck if endpoint is part of the
-- API api
safeLink :: (IsElem endpoint api, HasLink endpoint) => Proxy api -> Proxy endpoint -> MkLink endpoint
-- | Represents a general universal resource identifier using its component
-- parts.
--
-- For example, for the URI
--
--
-- foo://anonymous@www.haskell.org:42/ghc?query#frag
--
--
-- the components are:
data URI :: *
URI :: String -> Maybe URIAuth -> String -> String -> String -> URI
-- |
-- foo:
--
uriScheme :: URI -> String
-- |
-- //anonymous@www.haskell.org:42
--
uriAuthority :: URI -> Maybe URIAuth
-- |
-- /ghc
--
uriPath :: URI -> String
-- |
-- ?query
--
uriQuery :: URI -> String
-- |
-- #frag
--
uriFragment :: URI -> String
-- | Construct a toLink for an endpoint.
class HasLink endpoint where type family MkLink endpoint
toLink :: HasLink endpoint => Proxy endpoint -> Link -> MkLink endpoint
linkURI :: Link -> URI
-- | A safe link datatype. The only way of constructing a Link is
-- using safeLink, which means any Link is guaranteed to be
-- part of the mentioned API.
data Link
-- | You may use this type family to tell the type checker that your custom
-- type may be skipped as part of a link. This is useful for things like
-- QueryParam that are optional in a URI and do not affect them if
-- they are omitted.
--
--
-- >>> data CustomThing
--
-- >>> type instance IsElem' e (CustomThing :> s) = IsElem e s
--
--
-- Note that IsElem is called, which will mutually recurse back to
-- IsElem' if it exhausts all other options again.
--
-- Once you have written a HasLink instance for CustomThing you are ready
-- to go.
-- | Closed type family, check if endpoint is within api
-- | If either a or b produce an empty constraint, produce an empty
-- constraint.
instance Show (Param a)
instance Show Link
instance HasLink Raw
instance HasLink (Delete y r)
instance HasLink (Put y r)
instance HasLink (Post y r)
instance HasLink (Get y r)
instance (ToText v, HasLink sub) => HasLink (Capture sym v :> sub)
instance HasLink sub => HasLink (ReqBody ct a :> sub)
instance (KnownSymbol sym, HasLink sub) => HasLink (MatrixFlag sym :> sub)
instance (KnownSymbol sym, ToText v, HasLink sub) => HasLink (MatrixParams sym v :> sub)
instance (KnownSymbol sym, ToText v, HasLink sub) => HasLink (MatrixParam sym v :> sub)
instance (KnownSymbol sym, HasLink sub) => HasLink (QueryFlag sym :> sub)
instance (KnownSymbol sym, ToText v, HasLink sub) => HasLink (QueryParams sym v :> sub)
instance (KnownSymbol sym, ToText v, HasLink sub) => HasLink (QueryParam sym v :> sub)
instance (KnownSymbol sym, HasLink sub) => HasLink (sym :> sub)
module Servant.API