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


-- | A family of combinators for defining webservices APIs and serving them
--   
--   A family of combinators for defining webservices APIs and serving them
--   
--   You can learn about the basics in <a>the getting started</a> guide.
--   
--   <a>Here</a>'s a runnable example, with comments, that defines a dummy
--   API and implements a webserver that serves this API, using this
--   package.
@package servant-server
@version 0.2.4

module Servant.Server.Internal
data ReqBodyState
Uncalled :: ReqBodyState
Called :: !ByteString -> ReqBodyState
Done :: !ByteString -> ReqBodyState
toApplication :: RoutingApplication -> Application
data RouteMismatch

-- | the usual "not found" error
NotFound :: RouteMismatch

-- | a more informative "you just got the HTTP method wrong" error
WrongMethod :: RouteMismatch

-- | an even more informative "your json request body wasn't valid" error
InvalidBody :: String -> RouteMismatch

-- | <pre>
--   &gt; mempty = NotFound
--   &gt;
--   &gt; NotFound      <a>mappend</a>             x = x
--   &gt; WrongMethod   <a>mappend</a> InvalidBody s = InvalidBody s
--   &gt; WrongMethod   <a>mappend</a>             _ = WrongMethod
--   &gt; InvalidBody s <a>mappend</a>             _ = InvalidBody s
--   </pre>

-- | A wrapper around <tt><a>Either</a> <a>RouteMismatch</a> a</tt>.
newtype RouteResult a
RR :: Either RouteMismatch a -> RouteResult a
[routeResult] :: RouteResult a -> Either RouteMismatch a
failWith :: RouteMismatch -> RouteResult a
succeedWith :: a -> RouteResult a
isMismatch :: RouteResult a -> Bool

-- | Like `null . pathInfo`, but works with redundant trailing slashes.
pathIsEmpty :: Request -> Bool

-- | If we get a <a>Right</a>, it has precedence over everything else.
--   
--   This in particular means that if we could get several <a>Right</a>s,
--   only the first we encounter would be taken into account.
type RoutingApplication = Request  the request, the field 'pathInfo' may be modified by url routing -> (RouteResult Response -> IO ResponseReceived) -> IO ResponseReceived
splitMatrixParameters :: Text -> (Text, Text)
parsePathInfo :: Request -> [Text]

-- | Returns a processed pathInfo from the request.
--   
--   In order to handle matrix parameters in the request correctly, the raw
--   pathInfo needs to be processed, so routing works as intended. Therefor
--   this function should be used to access the pathInfo for routing
--   purposes.
processedPathInfo :: Request -> [Text]
class HasServer layout where type Server layout :: * where {
    type family Server layout :: *;
}
route :: HasServer layout => Proxy layout -> Server layout -> RoutingApplication

-- | A server for <tt>a <a>:&lt;|&gt;</a> b</tt> first tries to match the
--   request against the route represented by <tt>a</tt> and if it fails
--   tries <tt>b</tt>. You must provide a request handler for each route.
--   
--   <pre>
--   type MyApi = "books" :&gt; Get [Book] -- GET /books
--           :&lt;|&gt; "books" :&gt; ReqBody Book :&gt; Post Book -- POST /books
--   
--   server :: Server MyApi
--   server = listAllBooks :&lt;|&gt; postBook
--     where listAllBooks = ...
--           postBook book = ...
--   </pre>
captured :: FromText a => proxy (Capture sym a) -> Text -> Maybe a

-- | If you use <a>Capture</a> in one of the endpoints for your API, this
--   automatically requires your server-side handler to be a function that
--   takes an argument of the type specified by the <a>Capture</a>. This
--   lets servant worry about getting it from the URL and turning it into a
--   value of the type you specify.
--   
--   You can control how it'll be converted from <a>Text</a> to your type
--   by simply providing an instance of <a>FromText</a> for your type.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; Capture "isbn" Text :&gt; Get Book
--   
--   server :: Server MyApi
--   server = getBook
--     where getBook :: Text -&gt; EitherT (Int, String) IO Book
--           getBook isbn = ...
--   </pre>

-- | If you have a <a>Delete</a> endpoint in your API, the handler for this
--   endpoint is meant to delete a resource.
--   
--   The code of the handler will, just like for <a>Get</a>, <a>Post</a>
--   and <a>Put</a>, run in <tt>EitherT (Int, String) IO ()</tt>. The
--   <a>Int</a> represents the status code and the <a>String</a> a message
--   to be returned. You can use <a>left</a> to painlessly error out if the
--   conditions for a successful deletion are not met.

-- | When implementing the handler for a <a>Get</a> endpoint, just like for
--   <a>Delete</a>, <a>Post</a> and <a>Put</a>, the handler code runs in
--   the <tt>EitherT (Int, String) IO</tt> monad, where the <a>Int</a>
--   represents the status code and the <a>String</a> a message, returned
--   in case of failure. You can quite handily use <a>left</a> to quickly
--   fail if some conditions are not met.
--   
--   If successfully returning a value, we just require that its type has a
--   <a>ToJSON</a> instance and servant takes care of encoding it for you,
--   yielding status code 200 along the way.

-- | If you use <a>Header</a> in one of the endpoints for your API, this
--   automatically requires your server-side handler to be a function that
--   takes an argument of the type specified by <a>Header</a>. This lets
--   servant worry about extracting it from the request and turning it into
--   a value of the type you specify.
--   
--   All it asks is for a <a>FromText</a> instance.
--   
--   Example:
--   
--   <pre>
--   newtype Referer = Referer Text
--     deriving (Eq, Show, FromText, ToText)
--   
--              -- GET /view-my-referer
--   type MyApi = "view-my-referer" :&gt; Header "Referer" Referer :&gt; Get Referer
--   
--   server :: Server MyApi
--   server = viewReferer
--     where viewReferer :: Referer -&gt; EitherT (Int, String) IO referer
--           viewReferer referer = return referer
--   </pre>

-- | When implementing the handler for a <a>Post</a> endpoint, just like
--   for <a>Delete</a>, <a>Get</a> and <a>Put</a>, the handler code runs in
--   the <tt>EitherT (Int, String) IO</tt> monad, where the <a>Int</a>
--   represents the status code and the <a>String</a> a message, returned
--   in case of failure. You can quite handily use <a>left</a> to quickly
--   fail if some conditions are not met.
--   
--   If successfully returning a value, we just require that its type has a
--   <a>ToJSON</a> instance and servant takes care of encoding it for you,
--   yielding status code 201 along the way.

-- | When implementing the handler for a <a>Put</a> endpoint, just like for
--   <a>Delete</a>, <a>Get</a> and <a>Post</a>, the handler code runs in
--   the <tt>EitherT (Int, String) IO</tt> monad, where the <a>Int</a>
--   represents the status code and the <a>String</a> a message, returned
--   in case of failure. You can quite handily use <a>left</a> to quickly
--   fail if some conditions are not met.
--   
--   If successfully returning a value, we just require that its type has a
--   <a>ToJSON</a> instance and servant takes care of encoding it for you,
--   yielding status code 200 along the way.

-- | If you use <tt><a>QueryParam</a> "author" Text</tt> in one of the
--   endpoints for your API, this automatically requires your server-side
--   handler to be a function that takes an argument of type
--   <tt><a>Maybe</a> <a>Text</a></tt>.
--   
--   This lets servant worry about looking it up in the query string and
--   turning it into a value of the type you specify, enclosed in
--   <a>Maybe</a>, because it may not be there and servant would then hand
--   you <a>Nothing</a>.
--   
--   You can control how it'll be converted from <a>Text</a> to your type
--   by simply providing an instance of <a>FromText</a> for your type.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; QueryParam "author" Text :&gt; Get [Book]
--   
--   server :: Server MyApi
--   server = getBooksBy
--     where getBooksBy :: Maybe Text -&gt; EitherT (Int, String) IO [Book]
--           getBooksBy Nothing       = ...return all books...
--           getBooksBy (Just author) = ...return books by the given author...
--   </pre>

-- | If you use <tt><a>QueryParams</a> "authors" Text</tt> in one of the
--   endpoints for your API, this automatically requires your server-side
--   handler to be a function that takes an argument of type
--   <tt>[<a>Text</a>]</tt>.
--   
--   This lets servant worry about looking up 0 or more values in the query
--   string associated to <tt>authors</tt> and turning each of them into a
--   value of the type you specify.
--   
--   You can control how the individual values are converted from
--   <a>Text</a> to your type by simply providing an instance of
--   <a>FromText</a> for your type.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; QueryParams "authors" Text :&gt; Get [Book]
--   
--   server :: Server MyApi
--   server = getBooksBy
--     where getBooksBy :: [Text] -&gt; EitherT (Int, String) IO [Book]
--           getBooksBy authors = ...return all books by these authors...
--   </pre>

-- | If you use <tt><a>QueryFlag</a> "published"</tt> in one of the
--   endpoints for your API, this automatically requires your server-side
--   handler to be a function that takes an argument of type <a>Bool</a>.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; QueryFlag "published" :&gt; Get [Book]
--   
--   server :: Server MyApi
--   server = getBooks
--     where getBooks :: Bool -&gt; EitherT (Int, String) IO [Book]
--           getBooks onlyPublished = ...return all books, or only the ones that are already published, depending on the argument...
--   </pre>
parseMatrixText :: ByteString -> QueryText

-- | If you use <tt><a>MatrixParam</a> "author" Text</tt> in one of the
--   endpoints for your API, this automatically requires your server-side
--   handler to be a function that takes an argument of type
--   <tt><a>Maybe</a> <a>Text</a></tt>.
--   
--   This lets servant worry about looking it up in the query string and
--   turning it into a value of the type you specify, enclosed in
--   <a>Maybe</a>, because it may not be there and servant would then hand
--   you <a>Nothing</a>.
--   
--   You can control how it'll be converted from <a>Text</a> to your type
--   by simply providing an instance of <a>FromText</a> for your type.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; MatrixParam "author" Text :&gt; Get [Book]
--   
--   server :: Server MyApi
--   server = getBooksBy
--     where getBooksBy :: Maybe Text -&gt; EitherT (Int, String) IO [Book]
--           getBooksBy Nothing       = ...return all books...
--           getBooksBy (Just author) = ...return books by the given author...
--   </pre>

-- | If you use <tt><a>MatrixParams</a> "authors" Text</tt> in one of the
--   endpoints for your API, this automatically requires your server-side
--   handler to be a function that takes an argument of type
--   <tt>[<a>Text</a>]</tt>.
--   
--   This lets servant worry about looking up 0 or more values in the query
--   string associated to <tt>authors</tt> and turning each of them into a
--   value of the type you specify.
--   
--   You can control how the individual values are converted from
--   <a>Text</a> to your type by simply providing an instance of
--   <a>FromText</a> for your type.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; MatrixParams "authors" Text :&gt; Get [Book]
--   
--   server :: Server MyApi
--   server = getBooksBy
--     where getBooksBy :: [Text] -&gt; EitherT (Int, String) IO [Book]
--           getBooksBy authors = ...return all books by these authors...
--   </pre>

-- | If you use <tt><a>MatrixFlag</a> "published"</tt> in one of the
--   endpoints for your API, this automatically requires your server-side
--   handler to be a function that takes an argument of type <a>Bool</a>.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; MatrixFlag "published" :&gt; Get [Book]
--   
--   server :: Server MyApi
--   server = getBooks
--     where getBooks :: Bool -&gt; EitherT (Int, String) IO [Book]
--           getBooks onlyPublished = ...return all books, or only the ones that are already published, depending on the argument...
--   </pre>

-- | Just pass the request to the underlying application and serve its
--   response.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "images" :&gt; Raw
--   
--   server :: Server MyApi
--   server = serveDirectory "/var/www/images"
--   </pre>

-- | If you use <a>ReqBody</a> in one of the endpoints for your API, this
--   automatically requires your server-side handler to be a function that
--   takes an argument of the type specified by <a>ReqBody</a>. This lets
--   servant worry about extracting it from the request and turning it into
--   a value of the type you specify.
--   
--   All it asks is for a <a>FromJSON</a> instance.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; ReqBody Book :&gt; Post Book
--   
--   server :: Server MyApi
--   server = postBook
--     where postBook :: Book -&gt; EitherT (Int, String) IO Book
--           postBook book = ...insert into your db...
--   </pre>

-- | Make sure the incoming request starts with <tt>"/path"</tt>, strip it
--   and pass the rest of the request path to <tt>sublayout</tt>.
instance GHC.Show.Show a => GHC.Show.Show (Servant.Server.Internal.RouteResult a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Servant.Server.Internal.RouteResult a)
instance GHC.Show.Show Servant.Server.Internal.RouteMismatch
instance GHC.Classes.Eq Servant.Server.Internal.RouteMismatch
instance GHC.Base.Monoid Servant.Server.Internal.RouteMismatch
instance GHC.Base.Monoid (Servant.Server.Internal.RouteResult a)
instance (Servant.Server.Internal.HasServer a, Servant.Server.Internal.HasServer b) => Servant.Server.Internal.HasServer (a Servant.API.Alternative.:<|> b)
instance (GHC.TypeLits.KnownSymbol capture, Servant.Common.Text.FromText a, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.Capture.Capture capture a Servant.API.Sub.:> sublayout)
instance Servant.Server.Internal.HasServer Servant.API.Delete.Delete
instance Data.Aeson.Types.Class.ToJSON result => Servant.Server.Internal.HasServer (Servant.API.Get.Get result)
instance (GHC.TypeLits.KnownSymbol sym, Servant.Common.Text.FromText a, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.Header.Header sym a Servant.API.Sub.:> sublayout)
instance Data.Aeson.Types.Class.ToJSON a => Servant.Server.Internal.HasServer (Servant.API.Post.Post a)
instance Data.Aeson.Types.Class.ToJSON a => Servant.Server.Internal.HasServer (Servant.API.Put.Put a)
instance (GHC.TypeLits.KnownSymbol sym, Servant.Common.Text.FromText a, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.QueryParam.QueryParam sym a Servant.API.Sub.:> sublayout)
instance (GHC.TypeLits.KnownSymbol sym, Servant.Common.Text.FromText a, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.QueryParam.QueryParams sym a Servant.API.Sub.:> sublayout)
instance (GHC.TypeLits.KnownSymbol sym, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.QueryParam.QueryFlag sym Servant.API.Sub.:> sublayout)
instance (GHC.TypeLits.KnownSymbol sym, Servant.Common.Text.FromText a, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.MatrixParam.MatrixParam sym a Servant.API.Sub.:> sublayout)
instance (GHC.TypeLits.KnownSymbol sym, Servant.Common.Text.FromText a, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.MatrixParam.MatrixParams sym a Servant.API.Sub.:> sublayout)
instance (GHC.TypeLits.KnownSymbol sym, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.MatrixParam.MatrixFlag sym Servant.API.Sub.:> sublayout)
instance Servant.Server.Internal.HasServer Servant.API.Raw.Raw
instance (Data.Aeson.Types.Class.FromJSON a, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (Servant.API.ReqBody.ReqBody a Servant.API.Sub.:> sublayout)
instance (GHC.TypeLits.KnownSymbol path, Servant.Server.Internal.HasServer sublayout) => Servant.Server.Internal.HasServer (path Servant.API.Sub.:> sublayout)


-- | This module lets you implement <a>Server</a>s for defined APIs. You'll
--   most likely just need <a>serve</a>.
module Servant.Server

-- | <a>serve</a> allows you to implement an API and produce a wai
--   <a>Application</a>.
--   
--   Example:
--   
--   <pre>
--   type MyApi = "books" :&gt; Get [Book] -- GET /books
--           :&lt;|&gt; "books" :&gt; ReqBody Book :&gt; Post Book -- POST /books
--   
--   server :: Server MyApi
--   server = listAllBooks :&lt;|&gt; postBook
--     where listAllBooks = ...
--           postBook book = ...
--   
--   myApi :: Proxy MyApi
--   myApi = Proxy
--   
--   app :: Application
--   app = serve myApi server
--   
--   main :: IO ()
--   main = Network.Wai.Handler.Warp.run 8080 app
--   </pre>
serve :: HasServer layout => Proxy layout -> Server layout -> Application
class HasServer layout where type Server layout :: * where {
    type family Server layout :: *;
}
route :: HasServer layout => Proxy layout -> Server layout -> RoutingApplication


-- | This module defines a sever-side handler that lets you serve static
--   files.
--   
--   <ul>
--   <li><a>serveDirectory</a> lets you serve anything that lives under a
--   particular directory on your filesystem.</li>
--   </ul>
module Servant.Utils.StaticFiles

-- | Serve anything under the specified directory as a <a>Raw</a> endpoint.
--   
--   <pre>
--   type MyApi = "static" :&gt; Raw
--   
--   server :: Server MyApi
--   server = serveDirectory "/var/www"
--   </pre>
--   
--   would capture any request to <tt>/static/&lt;something&gt;</tt> and
--   look for <tt>&lt;something&gt;</tt> under <tt>/var/www</tt>.
--   
--   It will do its best to guess the MIME type for that file, based on the
--   extension, and send an appropriate <i>Content-Type</i> header if
--   possible.
--   
--   If your goal is to serve HTML, CSS and Javascript files that use the
--   rest of the API as a webapp backend, you will most likely not want the
--   static files to be hidden behind a <i>/static/</i> prefix. In that
--   case, remember to put the <a>serveDirectory</a> handler in the last
--   position, because <i>servant</i> will try to match the handlers in
--   order.
serveDirectory :: FilePath -> Server Raw

module Servant

-- | A concrete, poly-kinded proxy type
data Proxy k (t :: k) :: forall k. k -> *
Proxy :: Proxy k