-- 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.3


-- | Purpose of this module is to provide a simple, functional way to
--   define tabs in Snap applications.
module Snap.Extras.Tabs
initTabs :: HasHeist b => Initializer b v ()
tabsSplice :: 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

module Snap.Extras.SpliceUtils

-- | Run the splice contents if given condition is True, make splice
--   disappear if not.
ifSplice :: Monad m => Bool -> Splice m

-- | 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 :: [(Text, SnapletISplice b)]

-- | Bind splices offered in this module in your <a>Initializer</a>
addUtilSplices :: HasHeist b => Initializer b v ()

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

-- | Assume text are 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

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 => 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

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

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 ()

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 ()