-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A minimalist web framework for the WAI server interface -- -- Simple is "framework-less" web framework for Haskell web applications -- based on the WAI server interface (e.g. for use with the warp server). -- Simple does not enforce a particular structure or paradigm for web -- applications. Rather, Simple contains tools to help you create your -- own patterns (or re-create existing ones). Simple is minimalist, -- providing a lightweight base - the most basic Simple app is little -- more than a WAI Application with some routing logic. Everything -- else (e.g. authentication, controllers, persistence, caching etc') is -- provided in composable units, so you can include only the ones you -- need in your app, and easily replace with your own components. -- -- To get started, create an app skeleton with the smpl utility: -- -- 
--   $ cabal install simple
--   $ smpl create my_app_name
--   $ cd my_app_name
--   $ smpl
--
-- -- See Web.Simple for a more detailed introduction. @package simple @version 0.11.1 -- | This module defines some convenience functions for creating responses. module Web.Simple.Responses -- | Creates a 200 (OK) Response with the given content-type and -- resposne body ok :: ContentType -> ByteString -> Response -- | Creates a 200 (OK) Response with content-type "text/html" and -- the given resposne body okHtml :: ByteString -> Response -- | Creates a 200 (OK) Response with content-type -- "application/json" and the given resposne body okJson :: ByteString -> Response -- | Creates a 200 (OK) Response with content-type "application/xml" -- and the given resposne body okXml :: ByteString -> Response -- | Given a URL returns a 301 (Moved Permanently) Response -- redirecting to that URL. movedTo :: String -> Response -- | Given a URL returns a 303 (See Other) Response redirecting to -- that URL. redirectTo :: ByteString -> Response -- | Returns a 400 (Bad Request) Response. badRequest :: Response -- | Returns a 401 (Authorization Required) Response requiring basic -- authentication in the given realm. requireBasicAuth :: String -> Response -- | Returns a 403 (Forbidden) Response. forbidden :: Response -- | Returns a 404 (Not Found) Response. notFound :: Response -- | Returns a 500 (Server Error) Response. serverError :: ByteString -> Response -- | ControllerT provides a convenient syntax for writting -- Application code as a Monadic action with access to an HTTP -- request as well as app specific data (e.g. a database connection pool, -- app configuration etc.) This module also defines some helper functions -- that leverage this feature. For example, redirectBack reads the -- underlying request to extract the referer and returns a redirect -- response: -- -- 
--   myControllerT = do
--     ...
--     if badLogin then
--       redirectBack
--       else
--         ...
--   
--
module Web.Simple.Controller.Trans -- | The ControllerT Monad is both a State-like monad which, when run, -- computes either a Response or a result. Within the ControllerT -- Monad, the remainder of the computation can be short-circuited by -- responding with a Response. newtype ControllerT s m a ControllerT :: (s -> Request -> m (Either Response a, s)) -> ControllerT s m a [runController] :: ControllerT s m a -> s -> Request -> m (Either Response a, s) hoistEither :: Monad m => Either Response a -> ControllerT s m a -- | Extract the request request :: Monad m => ControllerT s m Request -- | Modify the request for the given computation localRequest :: Monad m => (Request -> Request) -> ControllerT s m a -> ControllerT s m a -- | Extract the application-specific state controllerState :: Monad m => ControllerT s m s putState :: Monad m => s -> ControllerT s m () -- | Convert the controller into an Application controllerApp :: Monad m => s -> ControllerT s m a -> SimpleApplication m -- | Provide a response -- -- 
--   respond r >>= f === respond r
--
respond :: Monad m => Response -> ControllerT s m a -- | Lift an application to a controller fromApp :: Monad m => (Request -> m Response) -> ControllerT s m () -- | Matches on the hostname from the Request. The route only -- succeeds on exact matches. routeHost :: Monad m => ByteString -> ControllerT s m a -> ControllerT s m () -- | Matches if the path is empty. -- -- Note that this route checks that pathInfo is empty, so it works -- as expected in nested contexts that have popped components from the -- pathInfo list. routeTop :: Monad m => ControllerT s m a -> ControllerT s m () -- | Matches on the HTTP request method (e.g. GET, POST, -- PUT) routeMethod :: Monad m => StdMethod -> ControllerT s m a -> ControllerT s m () -- | Matches if the request's Content-Type exactly matches the given string routeAccept :: Monad m => ByteString -> ControllerT s m a -> ControllerT s m () -- | Routes the given URL pattern. Patterns can include directories as well -- as variable patterns (prefixed with :) to be added to -- queryString (see routeVar) -- -- routePattern :: Monad m => Text -> ControllerT s m a -> ControllerT s m () -- | Matches if the first directory in the path matches the given -- ByteString routeName :: Monad m => Text -> ControllerT s m a -> ControllerT s m () -- | Always matches if there is at least one directory in pathInfo -- but and adds a parameter to queryString where the key is the -- first parameter and the value is the directory consumed from the path. routeVar :: Monad m => Text -> ControllerT s m a -> ControllerT s m () -- | Looks up the parameter name in the request's query string and returns -- the Parseable value or Nothing. -- -- For example, for a request with query string: "?foo=bar&baz=7", -- queryParam "foo" would return Just "bar", but -- queryParam "zap" would return Nothing. queryParam :: (Monad m, Parseable a) => ByteString -> ControllerT s m (Maybe a) -- | Like queryParam, but throws an exception if the parameter is -- not present. queryParam' :: (Monad m, Parseable a) => ByteString -> ControllerT s m a -- | Selects all values with the given parameter name queryParams :: (Monad m, Parseable a) => ByteString -> ControllerT s m [a] -- | The class of types into which query parameters may be converted class Parseable a parse :: Parseable a => ByteString -> a -- | Like queryParam, but further processes the parameter value with -- read. If that conversion fails, an exception is thrown. readQueryParam :: (Monad m, Read a) => ByteString -> ControllerT s m (Maybe a) -- | Like readQueryParam, but throws an exception if the parameter -- is not present. readQueryParam' :: (Monad m, Read a) => ByteString -> ControllerT s m a -- | Like queryParams, but further processes the parameter values -- with read. If any read-conversion fails, an exception is -- thrown. readQueryParams :: (Monad m, Read a) => ByteString -> ControllerT s m [a] readParamValue :: (Monad m, Read a) => ByteString -> Text -> ControllerT s m a -- | Returns the value of the given request header or Nothing if it -- is not present in the HTTP request. requestHeader :: Monad m => HeaderName -> ControllerT s m (Maybe ByteString) -- | Redirect back to the referer. If the referer header is not present -- redirect to root (i.e., /). redirectBack :: Monad m => ControllerT s m () -- | Redirect back to the referer. If the referer header is not present -- fallback on the given Response. redirectBackOr :: Monad m => Response -> ControllerT s m () -- | Like Application, but with m as the underlying monad type SimpleApplication m = Request -> m Response -- | Like Application, but with m as the underlying monad type SimpleMiddleware m = SimpleApplication m -> SimpleApplication m guard :: Monad m => Bool -> ControllerT s m a -> ControllerT s m () guardM :: Monad m => ControllerT s m Bool -> ControllerT s m a -> ControllerT s m () guardReq :: Monad m => (Request -> Bool) -> ControllerT s m a -> ControllerT s m () data ControllerException ControllerException :: String -> ControllerException err :: String -> ControllerT s m a instance GHC.Base.Functor m => GHC.Base.Functor (Web.Simple.Controller.Trans.ControllerT s m) instance (GHC.Base.Monad m, GHC.Base.Functor m) => GHC.Base.Applicative (Web.Simple.Controller.Trans.ControllerT s m) instance GHC.Base.Monad m => GHC.Base.Monad (Web.Simple.Controller.Trans.ControllerT s m) instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Alternative (Web.Simple.Controller.Trans.ControllerT s m) instance GHC.Base.Monad m => GHC.Base.MonadPlus (Web.Simple.Controller.Trans.ControllerT s m) instance Control.Monad.Trans.Class.MonadTrans (Web.Simple.Controller.Trans.ControllerT s) instance GHC.Base.Monad m => Control.Monad.State.Class.MonadState s (Web.Simple.Controller.Trans.ControllerT s m) instance GHC.Base.Monad m => Control.Monad.Reader.Class.MonadReader Network.Wai.Internal.Request (Web.Simple.Controller.Trans.ControllerT s m) instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Web.Simple.Controller.Trans.ControllerT s m) instance (GHC.Base.Applicative m, GHC.Base.Monad m, Control.Monad.Base.MonadBase m m) => Control.Monad.Base.MonadBase m (Web.Simple.Controller.Trans.ControllerT s m) instance Control.Monad.Trans.Control.MonadBaseControl m m => Control.Monad.Trans.Control.MonadBaseControl m (Web.Simple.Controller.Trans.ControllerT s m) instance Web.Simple.Controller.Trans.Parseable Data.ByteString.Internal.ByteString instance Web.Simple.Controller.Trans.Parseable GHC.Base.String instance Web.Simple.Controller.Trans.Parseable Data.Text.Internal.Text instance GHC.Show.Show Web.Simple.Controller.Trans.ControllerException instance GHC.Exception.Exception Web.Simple.Controller.Trans.ControllerException -- | Controller provides a convenient syntax for writting -- Application code as a Monadic action with access to an HTTP -- request as well as app specific data (e.g. a database connection pool, -- app configuration etc.) This module also defines some helper functions -- that leverage this feature. For example, redirectBack reads the -- underlying request to extract the referer and returns a redirect -- response: -- -- 
--   myController = do
--     ...
--     if badLogin then
--       redirectBack
--       else
--         ...
--   
--
module Web.Simple.Controller -- | The Controller Monad is both a State-like monad which, when run, -- computes either a Response or a result. Within the Controller -- Monad, the remainder of the computation can be short-circuited by -- responding with a Response. type Controller s = ControllerT s IO -- | The ControllerT Monad is both a State-like monad which, when run, -- computes either a Response or a result. Within the ControllerT -- Monad, the remainder of the computation can be short-circuited by -- responding with a Response. newtype ControllerT s m a ControllerT :: (s -> Request -> m (Either Response a, s)) -> ControllerT s m a [runController] :: ControllerT s m a -> s -> Request -> m (Either Response a, s) -- | Convert the controller into an Application controllerApp :: s -> Controller s a -> Application -- | Extract the application-specific state controllerState :: Controller s s putState :: s -> Controller s () -- | Extract the request request :: Controller s Request -- | Modify the request for the given computation localRequest :: (Request -> Request) -> Controller s a -> Controller s a -- | Provide a response -- -- 
--   respond r >>= f === respond r
--
respond :: Response -> Controller s a -- | Returns the value of the given request header or Nothing if it -- is not present in the HTTP request. requestHeader :: HeaderName -> Controller s (Maybe ByteString) -- | Matches on the hostname from the Request. The route only -- succeeds on exact matches. routeHost :: ByteString -> Controller s a -> Controller s () -- | Matches if the path is empty. -- -- Note that this route checks that pathInfo is empty, so it works -- as expected in nested contexts that have popped components from the -- pathInfo list. routeTop :: Controller s a -> Controller s () -- | Matches on the HTTP request method (e.g. GET, POST, -- PUT) routeMethod :: StdMethod -> Controller s a -> Controller s () -- | Matches if the request's Content-Type exactly matches the given string routeAccept :: ByteString -> Controller s a -> Controller s () -- | Routes the given URL pattern. Patterns can include directories as well -- as variable patterns (prefixed with :) to be added to -- queryString (see routeVar) -- -- routePattern :: Text -> Controller s a -> Controller s () -- | Matches if the first directory in the path matches the given -- ByteString routeName :: Text -> Controller s a -> Controller s () -- | Always matches if there is at least one directory in pathInfo -- but and adds a parameter to queryString where the key is the -- first parameter and the value is the directory consumed from the path. routeVar :: Text -> Controller s a -> Controller s () -- | The class of types into which query parameters may be converted class Parseable a -- | Looks up the parameter name in the request's query string and returns -- the Parseable value or Nothing. -- -- For example, for a request with query string: "?foo=bar&baz=7", -- queryParam "foo" would return Just "bar", but -- queryParam "zap" would return Nothing. queryParam :: Parseable a => ByteString -> Controller s (Maybe a) -- | Like queryParam, but throws an exception if the parameter is -- not present. queryParam' :: Parseable a => ByteString -> Controller s a -- | Selects all values with the given parameter name queryParams :: Parseable a => ByteString -> Controller s [a] -- | Like queryParam, but further processes the parameter value with -- read. If that conversion fails, an exception is thrown. readQueryParam :: Read a => ByteString -> Controller s (Maybe a) -- | Like readQueryParam, but throws an exception if the parameter -- is not present. readQueryParam' :: Read a => ByteString -> Controller s a -- | Like queryParams, but further processes the parameter values -- with read. If any read-conversion fails, an exception is -- thrown. readQueryParams :: Read a => ByteString -> Controller s [a] -- | Parses a HTML form from the request body. It returns a list of -- Params as well as a list of Files, which are pairs -- mapping the name of a file form field to a FileInfo -- pointing to a temporary file with the contents of the upload. -- -- 
--   myControllerT = do
--     (prms, files) <- parseForm
--     let mPicFile = lookup "profile_pic" files
--     case mPicFile of
--       Just (picFile) -> do
--         sourceFile (fileContent picFile) $$
--           sinkFile ("images/" ++ (fileName picFile))
--         respond $ redirectTo "/"
--       Nothing -> redirectBack
--
parseForm :: Controller s ([Param], [(ByteString, FileInfo ByteString)]) -- | Redirect back to the referer. If the referer header is not present -- redirect to root (i.e., /). redirectBack :: Controller s a -- | Redirect back to the referer. If the referer header is not present -- fallback on the given Response. redirectBackOr :: Response -> Controller s a data ControllerException -- | Reads and returns the body of the HTTP request. body :: Controller s ByteString hoistEither :: Either Response a -> Controller s a module Web.Simple.Controller.Exception onException :: Controller s a -> Controller s b -> Controller s a finally :: Controller s a -> Controller s b -> Controller s a bracket :: Controller s a -> (a -> Controller s b) -> (a -> Controller s c) -> Controller s c handle :: Exception e => (e -> Controller s a) -> Controller s a -> Controller s a module Web.Simple.Static serveStatic :: FilePath -> Controller a () -- | Provides HTTP Basic Authentication. module Web.Simple.Auth -- | An AuthRouter authenticates a Request and, if -- successful, forwards the Request to the Routeable. type AuthRouter r a = (Request -> ByteString -> ByteString -> Controller r (Maybe Request)) -> Controller r a -> Controller r a -- | An AuthRouter that uses HTTP basic authentication to -- authenticate a request in a particular realm. basicAuthRoute :: String -> AuthRouter r a -- | A Route that uses HTTP basic authentication to authenticate a -- request for a realm with the given username ans password. The request -- is rewritten with an 'X-User' header containing the authenticated -- username before being passed to the next Route. basicAuth :: String -> ByteString -> ByteString -> Controller r a -> Controller r a -- | Wraps an AuthRouter to take a simpler authentication function -- (that just just takes a username and password, and returns True -- or False). It also adds an "X-User" header to the -- Request with the authenticated user's name (the first argument -- to the authentication function). authRewriteReq :: AuthRouter r a -> (ByteString -> ByteString -> Controller r Bool) -> Controller r a -> Controller r a -- | Frank is a Sinatra-inspired DSL (see http://www.sinatrarb.com) -- for creating routes. It is composable with all ToApplication -- types, but is designed to be used with Controllers. Each verb -- (get, post, put, etc') takes a URL pattern of the -- form "/dir/:paramname/dir" (see routePattern for details) and a -- ToApplication: -- -- 
--   main :: IO ()
--   main = run 3000 $ controllerApp () $ do
--     get "/" $ do
--       req <- request
--       respond $ okHtml $ fromString $
--         "Welcome Home " ++ (show $ serverName req)
--     get "/user/:id" $ do
--       userId <- queryParam "id" >>= fromMaybe ""
--       respond $ ok "text/json" $ fromString $
--         "{\"myid\": " ++ (show userId) ++ "}"
--     put "/user/:id" $ do
--       ...
--
module Web.Frank -- | Matches the GET method on the given URL pattern get :: Monad m => Text -> ControllerT s m a -> ControllerT s m () -- | Matches the POST method on the given URL pattern post :: Monad m => Text -> ControllerT s m a -> ControllerT s m () -- | Matches the PUT method on the given URL pattern put :: Monad m => Text -> ControllerT s m a -> ControllerT s m () -- | Matches the DELETE method on the given URL pattern delete :: Monad m => Text -> ControllerT s m a -> ControllerT s m () -- | Matches the OPTIONS method on the given URL pattern options :: Monad m => Text -> ControllerT s m a -> ControllerT s m () module Web.Simple.Templates class Monad m => HasTemplates m hs where defaultLayout = return Nothing viewDirectory = return "views" functionMap = return defaultFunctionMap getTemplate = defaultGetTemplate layoutObject = defaultLayoutObject -- | The layout to use by default. Layouts are just templates that embed -- views. They are rendered with the a global object containing the -- rendered view in the "yield" field, and the object the view was -- rendered with in the "page" field. By default, no template is used. defaultLayout :: HasTemplates m hs => ControllerT hs m (Maybe Template) -- | The directory to look for views passed to render. This defaults -- to "views", so -- -- 
--   render "index.html.tmpl" ...
--
-- -- will look for a view template in "views/index.html.tmpl". viewDirectory :: HasTemplates m hs => ControllerT hs m FilePath -- | A map of pure functions that can be called from within a template. See -- FunctionMap and Function for details. functionMap :: HasTemplates m hs => ControllerT hs m FunctionMap -- | Function to use to get a template. By default, it looks in the -- viewDirectory for the given file name and compiles the file -- into a template. This can be overriden to, for example, cache compiled -- templates in memory. getTemplate :: HasTemplates m hs => FilePath -> ControllerT hs m Template -- | The Value passed to a layout given the rendered view template -- and the value originally passed to the view template. By default, -- produces an Object with "yield", containing the rendered view, -- and "page", containing the value originally passed to the view. layoutObject :: (HasTemplates m hs, ToJSON pageContent, ToJSON pageVal) => pageContent -> pageVal -> ControllerT hs m Value -- | Renders a view template with the default layout and a global used to -- evaluate variables in the template. render :: (HasTemplates m hs, Monad m, ToJSON a) => FilePath -> a -> ControllerT hs m () -- | Same as render but without a template. renderPlain :: (HasTemplates m hs, ToJSON a) => FilePath -> a -> ControllerT hs m () -- | Render a view using the layout named by the first argument. renderLayout :: (HasTemplates m hs, ToJSON a) => FilePath -> FilePath -> a -> ControllerT hs m () -- | Same as renderLayout but uses already compiled layouts. renderLayoutTmpl :: (HasTemplates m hs, ToJSON a) => Template -> Template -> a -> ByteString -> ControllerT hs m () defaultGetTemplate :: (HasTemplates m hs, MonadIO m) => FilePath -> ControllerT hs m Template defaultFunctionMap :: FunctionMap defaultLayoutObject :: (HasTemplates m hs, ToJSON pageContent, ToJSON pageVal) => pageContent -> pageVal -> ControllerT hs m Value -- | O(n*log n) Construct a map with the supplied mappings. If the -- list contains duplicate mappings, the later mappings take precedence. fromList :: (Eq k, Hashable k) => [(k, v)] -> HashMap k v -- | A funcation that's callable from inside a template newtype Function :: * Function :: ([Value] -> Value) -> Function [call] :: Function -> [Value] -> Value class ToFunction a toFunction :: ToFunction a => a -> Function type FunctionMap = HashMap Identifier Function -- | REST is a DSL for creating routes using RESTful HTTP verbs. See -- http://en.wikipedia.org/wiki/Representational_state_transfer module Web.REST -- | Type used to encode a REST controller. data REST m s REST :: ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> REST m s [restIndex] :: REST m s -> ControllerT s m () [restShow] :: REST m s -> ControllerT s m () [restCreate] :: REST m s -> ControllerT s m () [restUpdate] :: REST m s -> ControllerT s m () [restDelete] :: REST m s -> ControllerT s m () [restEdit] :: REST m s -> ControllerT s m () [restNew] :: REST m s -> ControllerT s m () type RESTController m r = RESTControllerM m r () rest :: Monad m => RESTControllerM m r a -> REST m r routeREST :: Monad m => REST m s -> ControllerT s m () -- | GET / index :: ControllerT s m () -> RESTController m s -- | GET /:id show :: ControllerT s m () -> RESTController m s -- | POST / create :: ControllerT s m () -> RESTController m s -- | PUT /:id update :: ControllerT s m () -> RESTController m s -- | DELETE /:id delete :: ControllerT s m () -> RESTController m s -- | GET /:id/edit edit :: ControllerT s m () -> RESTController m s -- | GET /new new :: ControllerT s m () -> RESTController m s -- | Simple is based on WAI - an standard interface for -- communicating between web servers (like warp) and web applications. -- You can use Simple completely independently (and of course, use -- any WAI server to run it). Alternatively, you can embed existing -- existing WAI applications inside an app built with Simple, and -- embed an app built with simple in another WAI app. -- -- All the components in Simple are designed to be small and -- simple enough to understand, replaceable, and work as well -- independantly as they do together. module Web.Simple