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


-- | A collection of useful helpers and utilities for Snap web applications.
--   
--   This package contains a collection of helper functions that come in
--   handy in most practical, real-world applications. Check individual
--   modules to understand what's here. You can simply import Snap.Extras
--   and use the initializer in there to get them all at once.
@package snap-extras
@version 0.7

module Snap.Extras.NavTrails
data NavTrail b
NavTrail :: SnapletLens b SessionManager -> NavTrail b

-- | A session manager for the base
ntSes :: NavTrail b -> SnapletLens b SessionManager
initNavTrail :: SnapletLens b SessionManager -> Maybe (Snaplet (Heist b)) -> SnapletInit b (NavTrail b)
setFocus :: Handler b (NavTrail b) ()
setFocus' :: ByteString -> Handler b (NavTrail b) ()
setFocusToRef :: Handler b (NavTrail b) ()
getFocus :: Handler b (NavTrail b) (Maybe Text)
getFocusDef :: Text -> Handler b (NavTrail b) Text
redirBack :: MonadSnap m => m a
redirFocus :: ByteString -> Handler b (NavTrail b) a
backSplice :: MonadSnap m => HeistT m m Template
backCSplice :: Splice (Handler b v)
focusSplice :: SnapletLens (Snaplet v) (NavTrail b) -> Splice (Handler b v)
focusCSplice :: SnapletLens (Snaplet v) (NavTrail b) -> Splice (Handler b v)
addNavTrailSplices :: Snaplet (Heist b) -> Initializer b (NavTrail b) ()

module Snap.Extras.CSRF

-- | A splice that makes the CSRF token available to templates. Typically
--   we use it by binding a splice and using the CSRF token provided by the
--   session snaplet as follows:
--   
--   <pre>
--   ("csrfToken", csrfTokenSplice $ with session <a>csrfToken</a>)
--   </pre>
--   
--   Where <tt>session</tt> is a lens to the session snaplet. Then you can
--   make it available to javascript code by putting a meta tag at the top
--   of every page like this:
--   
--   <pre>
--   &lt;meta name="csrf-token" content="${csrfToken}"&gt;
--   </pre>
csrfTokenSplice :: Monad m => m Text -> Splice m

-- | Adds a hidden _csrf input field as the first child of the bound tag.
--   For full site protection against CSRF, you should bind this splice to
--   the form tag, and then make sure your app checks all POST requests for
--   the presence of this CSRF token and that the token is randomly
--   generated and secure on a per session basis.
secureForm :: MonadIO m => m Text -> Splice m

-- | Use this function to wrap your whole site with CSRF protection. Due to
--   security considerations, the way Snap parses file uploads means that
--   the CSRF token cannot be checked before the file uploads have been
--   handled. This function protects your whole site except for handlers of
--   multipart/form-data forms (forms with file uploads). To protect those
--   handlers, you have to call handleCSRF explicitly after the file has
--   been processed.
blanketCSRF :: SnapletLens v SessionManager -> Handler b v () -> Handler b v ()

-- | If a request is a POST, check the CSRF token and fail with the
--   specified handler if the check fails. If if the token is correct or if
--   it's not a POST request, then control passes through as a no-op.
handleCSRF :: SnapletLens v SessionManager -> Handler b v () -> Handler b v ()

module Snap.Extras.SpliceUtils.Interpreted

-- | Gets the value of a request parameter. Example use:
--   
--   <a>name="username"/</a>
paramSplice :: MonadSnap m => Splice m

-- | A list of splices offered in this module
utilSplices :: Splices (SnapletISplice b)

-- | Splice helper for when you're rendering a select element
selectSplice :: Monad m => Text -> Text -> [(Text, Text)] -> Maybe Text -> Splice m

-- | Assume text area contains the name of a splice as Text.
--   
--   This is helpful when you pass a default value to digestive-functors by
--   putting the name of a splice as the value of a textarea tag.
--   
--   <pre>
--   heistLocal runTextAreas $ render "joo/index"
--   </pre>
runTextAreas :: Monad m => HeistState m -> HeistState m

-- | Searches a directory on disk and all its subdirectories for all files
--   with names that don't begin with an underscore and end with a .js
--   extension. It then returns script tags for each of these files.
--   
--   You can use this function to create a splice:
--   
--   <pre>
--   ("staticscripts", scriptsSplice "static/js" "/")
--   </pre>
--   
--   Then when you use the <tt>&lt;staticscripts/&gt;</tt> tag in your
--   templates, it will automatically include all the javascript code in
--   the <tt>static/js</tt> directory.
scriptsSplice :: MonadIO m => FilePath -> String -> m [Node]

-- | Check to see if the boolean flag named by the <a>ref</a> attribute is
--   present and set to true in snaplet user config file. If so, run what's
--   inside this splice, if not, simply omit that part.
--   
--   Example:
--   
--   <pre>
--   &lt;flag ref="beta-functions-enabled"&gt;
--   stuff...
--   &lt;/flag&gt;
--   </pre>
--   
--   This will look for an entry inside your .cfg file:
--   
--   <pre>
--   beta-functions-enabled = true
--   </pre>
ifFlagSplice :: SnapletISplice b
refererSplice :: MonadSnap m => Splice m

module Snap.Extras.SpliceUtils.Compiled
utilSplices :: MonadSnap m => Splices (Splice m)
refererCSplice :: MonadSnap m => Splice m

-- | Gets the value of a request parameter. Example use:
--   
--   <a>name="username"/</a>
paramSplice :: MonadSnap m => Splice m

-- | Searches a directory on disk and all its subdirectories for all files
--   with names that don't begin with an underscore and end with a .js
--   extension. It then returns script tags for each of these files.
--   
--   You can use this function to create a splice:
--   
--   <pre>
--   ("staticscripts", scriptsSplice "static/js" "/")
--   </pre>
--   
--   Then when you use the <tt>&lt;staticscripts/&gt;</tt> tag in your
--   templates, it will automatically include all the javascript code in
--   the <tt>static/js</tt> directory.
scriptsSplice :: MonadIO m => FilePath -> String -> Splice m


-- | Purpose of this module is to provide a simple, functional way to
--   define tabs in Snap applications.
module Snap.Extras.Tabs
initTabs :: HasHeist b => Snaplet (Heist b) -> Initializer b v ()
tabsSplice :: MonadSnap m => Splice m

-- | Compiled splice for tabs.
tabsCSplice :: MonadSnap m => Splice m

-- | How do we decide <a>active</a> for tab state?
data TabActiveMode

-- | Current url has to match exactly
TAMExactMatch :: TabActiveMode

-- | Only the prefix needs to match current url
TAMPrefixMatch :: TabActiveMode

-- | A sub-set of the current url has to match
TAMInfixMatch :: TabActiveMode
TAMDontMatch :: TabActiveMode

-- | A tab is a <a>Node</a> generator upon receiving a current URL context.
type Tab = Text -> Node

-- | Make tabs from tab definitions. Use the <a>tab</a> combinator to
--   define individual options.
mkTabs :: MonadSnap m => Text -> [Tab] -> Splice m

-- | Tab item constructor to be used with <a>mkTabs</a>. Just supply the
--   given arguments here and it will create a <a>Tab</a> ready to be used
--   in <a>mkTabs</a>.
--   
--   If the tab is currently active, the li tag will get a class of
--   'active'.
--   
--   Make sure to provide a trailing / when indicating URLs as snap context
--   paths contain it and active tab checks will be confused without it.
tab :: Text -> Text -> [(Text, Text)] -> TabActiveMode -> Tab

module Snap.Extras.FormUtils

-- | Transform to Nothing if field is empty string
maybeTrans :: (Eq a, IsString a) => a -> Result v (Maybe a)

-- | Maybe read into target value
readMayTrans :: Read a => Text -> Result v (Maybe a)

-- | Read into target value
readTrans :: (Read a, IsString v) => Text -> Result v a

-- | Constructs a generalized edit form splice that looks up an ID param
--   specified by the <tt>by</tt> attribute. You might use this splice as
--   follows:
--   
--   <pre>
--   &lt;editFormSplice by="id"&gt;
--   </pre>
--   
--   If you don't specify the <tt>by</tt> attribute, the default is
--   <tt>by="id"</tt>.
editFormSplice :: (Monad m, MonadSnap n) => (n (Maybe a) -> HeistT n m b) -> (ByteString -> n (Maybe a)) -> HeistT n m b

module Snap.Extras.FlashNotice

-- | Initialize the flash notice system. All you have to do now is to add
--   some flash tags in your application template. See <a>flashSplice</a>
--   for examples.
initFlashNotice :: HasHeist b => Snaplet (Heist b) -> SnapletLens b SessionManager -> Initializer b v ()

-- | Display an info message on next load of a page
flashInfo :: SnapletLens b SessionManager -> Text -> Handler b b ()

-- | Display an warning message on next load of a page
flashWarning :: SnapletLens b SessionManager -> Text -> Handler b b ()

-- | Display a success message on next load of a page
flashSuccess :: SnapletLens b SessionManager -> Text -> Handler b b ()

-- | Display an error message on next load of a page
flashError :: SnapletLens b SessionManager -> Text -> Handler b b ()

-- | A splice for rendering a given flash notice dirctive.
--   
--   Ex: <a>type='warning'/</a> Ex: <a>type='success'/</a>
flashSplice :: SnapletLens b SessionManager -> SnapletISplice b

-- | A compiled splice for rendering a given flash notice dirctive.
--   
--   Ex: <a>type='warning'/</a> Ex: <a>type='success'/</a>
flashCSplice :: SnapletLens b SessionManager -> SnapletCSplice b

module Snap.Extras.TextUtils
readT :: Read a => Text -> a
showT :: Show a => a -> Text
readBS :: Read a => ByteString -> a
showBS :: Show a => a -> ByteString
titleCase :: Text -> Text

module Snap.Extras.CoreUtils

-- | Discard anything after this and return given status code to HTTP
--   client immediately.
finishEarly :: MonadSnap m => Int -> ByteString -> m b

-- | Finish early with error code 400
badReq :: MonadSnap m => ByteString -> m b

-- | Finish early with error code 404
notFound :: MonadSnap m => ByteString -> m b

-- | Finish early with error code 500
serverError :: MonadSnap m => ByteString -> m b

-- | Mark response as 'text/plain'
plainResponse :: MonadSnap m => m ()

-- | Mark response as 'application/json'
jsonResponse :: MonadSnap m => m ()

-- | Mark response as 'application/javascript'
jsResponse :: MonadSnap m => m ()

-- | Easier debug logging into error log. First argument is a
--   category/namespace and the second argument is anything that has a
--   <a>Show</a> instance.
easyLog :: (Show t, MonadSnap m) => String -> t -> m ()

-- | Alternate version of getParam that considers empty string Nothing
getParam' :: MonadSnap m => ByteString -> m (Maybe ByteString)

-- | Require that a parameter is present or terminate early.
reqParam :: MonadSnap m => ByteString -> m ByteString

-- | Read a parameter from request. Be sure it is readable if it's there,
--   or else this will raise an error.
readParam :: (MonadSnap m, Read a) => ByteString -> m (Maybe a)

-- | Try to read a parameter from request. Computation may fail because the
--   param is not there, or because it can't be read.
readMayParam :: (MonadSnap m, Read a) => ByteString -> m (Maybe a)

-- | Redirects back to the refering page. If there is no Referer header,
--   then redirect to /.
redirectReferer :: MonadSnap m => m b

-- | Redirects back to the refering page. If there is no Referer header,
--   then redirect to /.
redirectRefererFunc :: MonadSnap m => (Maybe ByteString -> ByteString) -> m b

-- | If the current rqURI does not have a trailing slash, then redirect to
--   the same page with a slash added.
dirify :: MonadSnap m => m ()

-- | If the current rqURI has a trailing slash, then redirect to the same
--   page with no trailing slash.
undirify :: MonadSnap m => m ()
maybeBadReq :: MonadSnap m => ByteString -> m (Maybe a) -> m a

-- | Evaluates an action that returns a Maybe and
fromMaybeM :: Monad m => m a -> m (Maybe a) -> m a

-- | Concatenates two URL segments with a <a>/</a> between them. To prevent
--   double slashes, all trailing slashes are removed from the first path
--   and all leading slashes are removed from the second path.
(-/-) :: ByteString -> ByteString -> ByteString

module Snap.Extras.JSON

-- | Parse request body into JSON or return an error string.
getBoundedJSON :: (MonadSnap m, FromJSON a) => Int64 -> m (Either String a)

-- | Try to parse request body as JSON with a default max size of 50000.
getJSON :: (MonadSnap m, FromJSON a) => m (Either String a)

-- | Demand the presence of JSON in the body with a size up to N bytes. If
--   parsing fails for any reson, request is terminated early and a server
--   error is returned.
reqBoundedJSON :: (MonadSnap m, FromJSON a) => Int64 -> m a

-- | Demand the presence of JSON in the body assuming it is not larger than
--   50000 bytes.
reqJSON :: (MonadSnap m, FromJSON b) => m b

-- | Get JSON data from the given Param field
getJSONField :: (MonadSnap m, FromJSON a) => ByteString -> m (Either String a)

-- | Force the JSON value from field. Similar to <a>getJSONField</a>
reqJSONField :: (MonadSnap m, FromJSON a) => ByteString -> m a

-- | Set MIME to 'application/json' and write given object into
--   <a>Response</a> body.
writeJSON :: (MonadSnap m, ToJSON a) => a -> m ()

module Snap.Extras

-- | Initialize all the <a>Extras</a> functionality in your Snap app.
--   Currently, we don't need to keep any state and simply return ().
initExtras :: HasHeist b => Snaplet (Heist b) -> SnapletLens b SessionManager -> SnapletInit b ()