-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Snap: A Haskell Web Framework: project starter executable and glue code library
--
-- Snap Framework project starter executable and glue code library
@package snap
@version 0.5.3
-- | Snap.Extension.Heist exports the MonadHeist interface
-- which allows you to integrate Heist templates into your Snap
-- application. The interface's operations are heistServe,
-- heistServeSingle, heistLocal and render. As a
-- convenience, we also provide renderWithSplices that combines
-- heistLocal and render into a single function call.
--
-- Snap.Extension.Heist.Impl contains the only implementation of
-- this interface and can be used to turn your application's monad into a
-- MonadHeist.
--
-- MonadHeist is unusual among Snap extensions in that it's a
-- multi-parameter typeclass. The last parameter is your application's
-- monad, and the first is the monad you want the TemplateState to
-- use. This is usually, but not always, also your application's monad.
--
-- This module should not be used directly. Instead, import
-- Snap.Extension.Heist.Impl in your application.
module Snap.Extension.Heist
-- | The MonadHeist type class. Minimal complete definition:
-- render, heistLocal.
class (Monad n, MonadSnap m) => MonadHeist n m | m -> n
render :: MonadHeist n m => ByteString -> m ()
renderAs :: MonadHeist n m => ByteString -> ByteString -> m ()
heistLocal :: MonadHeist n m => (TemplateState n -> TemplateState n) -> m a -> m a
heistServe :: MonadHeist n m => m ()
heistServeSingle :: MonadHeist n m => ByteString -> m ()
-- | Helper function for common use case: Render a template with a given
-- set of splices.
renderWithSplices :: MonadHeist n m => ByteString -> [(Text, Splice n)] -> m ()
module Snap.Extension
-- | A SnapExtend is a MonadReader and a MonadSnap
-- whose environment is the application state for a given progam. You
-- would usually type alias SnapExtend AppState to something
-- like App to form the monad in which you write your
-- application.
data SnapExtend s a
-- | The Initializer monad. The code that initialises your
-- application's state is written in the Initializer monad. It's
-- used for constructing values which have cleanup/destroy and reload
-- actions associated with them.
data Initializer s
-- | Values of types which are instances of InitializerState have
-- cleanup/destroy and reload actions associated with them.
class InitializerState s
extensionId :: InitializerState s => s -> ByteString
mkCleanup :: InitializerState s => s -> IO ()
mkReload :: InitializerState s => s -> IO ()
-- | Given the Initializer for your application's state, and a value in the
-- monad formed by SnapExtend wrapped it, this returns a
-- Snap action, a cleanup action and a reload action.
runInitializer :: Bool -> Initializer s -> SnapExtend s () -> IO (Snap (), IO (), IO [(ByteString, Maybe ByteString)])
-- | Serves the same purpose as runInitializer, but combines the
-- application's web handler with a user-supplied action to be run to
-- reload the application's state.
runInitializerWithReloadAction :: Bool -> Initializer s -> SnapExtend s () -> (IO [(ByteString, Maybe ByteString)] -> SnapExtend s ()) -> IO (Snap (), IO ())
-- | A cut-down version of runInitializer, for use by the hint
-- loading code
runInitializerWithoutReloadAction :: Initializer s -> SnapExtend s () -> IO (Snap (), IO ())
-- | Although it has the same type signature, this is not the same as
-- return in the Initializer monad. Return simply lifts a
-- value into the Initializer monad, but this lifts the value and
-- its destroy/reload actions. Use this when making your own
-- Initializer actions.
mkInitializer :: InitializerState s => s -> Initializer s
-- | This takes the last value of the tuple returned by
-- runInitializer, which is a list representing the results of an
-- attempt to reload the application's Snap Extensions, and turns it into
-- a Snap action which displays the these results.
defaultReloadHandler :: MonadSnap m => IO [(ByteString, Maybe ByteString)] -> m ()
-- | Use this reload handler to disable the ability to have a web handler
-- which reloads Snap extensions.
nullReloadHandler :: MonadSnap m => IO [(ByteString, Maybe ByteString)] -> m ()
instance Functor (SnapExtend s)
instance Applicative (SnapExtend s)
instance Alternative (SnapExtend s)
instance Monad (SnapExtend s)
instance MonadPlus (SnapExtend s)
instance MonadIO (SnapExtend s)
instance MonadCatchIO (SnapExtend s)
instance MonadSnap (SnapExtend s)
instance MonadReader s (SnapExtend s)
instance MonadIO Initializer
instance Monad Initializer
instance Applicative Initializer
instance Functor Initializer
-- | Snap.Extension.Heist.Impl is an implementation of the
-- MonadHeist interface defined in Snap.Extension.Heist.
--
-- As always, to use, add HeistState to your application's state,
-- along with an instance of HasHeistState for your application's
-- state, making sure to use a heistInitializer in your
-- application's Initializer, and then you're ready to go.
--
-- Snap.Extension.Heist.Impl is a little different to other Snap
-- Extensions, which is unfortunate as it is probably the most widely
-- useful one. As explained below, HeistState takes your
-- application's monad as a type argument, and HasHeistState is a
-- multi-parameter type class, the additional first parameter also being
-- your application's monad.
--
-- Two instances of MonadHeist are provided with this module. One
-- is designed for users wanting to use Heist templates with their
-- application, the other is designed for users writing Snap Extensions
-- which use their own Heist templates internally.
--
-- The first one of these instances is HasHeistState (SnapExtend s) s
-- => MonadHeist (SnapExtend s) (SnapExtend s). This means that
-- any type s which has a HeistState, whose
-- 'TemplateState'\'s monad is SnapExtend s forms a
-- MonadHeist whose 'TemplateState'\'s monad is SnapExtend
-- s and whose monad itself is SnapExtend s. The s
-- here is your application's state, and SnapExtend s is your
-- application's monad.
--
-- The second one of these instances is HasHeistState m s =>
-- MonadHeist m (ReaderT s m). This means that any type s
-- which has, for any m, a HeistState m, forms a
-- MonadHeist, whose 'TemplateState'\'s monad is m, when
-- made the environment of a ReaderT wrapped around m.
-- The s here would be the Snap Extension's internal state, and
-- the m would be SnapExtend wrapped around any
-- s' which was an instance of the Snap Extension's
-- HasState class.
--
-- This implementation does not require that your application's monad
-- implement interfaces from any other Snap Extension.
module Snap.Extension.Heist.Impl
-- | Your application's state must include a HeistState in order for
-- your application to be a MonadHeist.
--
-- Unlike other -State types, this is of kind (* -> *)
-- -> *. Unless you're developing your own Snap Extension which
-- has its own internal HeistState, the type argument you want to
-- pass to HeistState is your application's monad, which should be
-- SnapExtend wrapped around your application's state.
data MonadSnap m => HeistState m
-- | For your application's monad to be a MonadHeist, your
-- application's state needs to be an instance of HasHeistState.
-- Minimal complete definition: getHeistState,
-- setHeistState.
--
-- Unlike other HasState type classes, this is a type class has
-- two parameters. Among other things, this means that you will need to
-- enable the FlexibleInstances and
-- MultiParameterTypeClasses language extensions to be able to
-- create an instance of HasHeistState. In most cases, the last
-- parameter will as usual be your application's state, and the
-- additional first one will be the monad formed by wrapping
-- SnapExtend around your application's state.
--
-- However, if you are developing your own Snap Extension which uses its
-- own internal HeistState, the last parameter will be your Snap
-- Extension's internal state, and the additional first parameter will be
-- any monad formed by wrapping SnapExtend around a type which
-- has an instance of the HasState class for your monad. These
-- two use cases are subtly different, which is why HasHeistState
-- needs two type parameters.
class MonadSnap m => HasHeistState m s | s -> m
getHeistState :: HasHeistState m s => s -> HeistState m
setHeistState :: HasHeistState m s => HeistState m -> s -> s
modifyHeistState :: HasHeistState m s => (HeistState m -> HeistState m) -> s -> s
-- | The Initializer for HeistState.
heistInitializer :: MonadSnap m => FilePath -> (TemplateState m -> TemplateState m) -> Initializer (HeistState m)
-- | The MonadHeist type class. Minimal complete definition:
-- render, heistLocal.
class (Monad n, MonadSnap m) => MonadHeist n m | m -> n
render :: MonadHeist n m => ByteString -> m ()
renderAs :: MonadHeist n m => ByteString -> ByteString -> m ()
heistLocal :: MonadHeist n m => (TemplateState n -> TemplateState n) -> m a -> m a
heistServe :: MonadHeist n m => m ()
heistServeSingle :: MonadHeist n m => ByteString -> m ()
-- | Take your application's state and register these splices in it so that
-- you don't have to re-list them in every handler. Should be called from
-- inside your application's Initializer. The splices registered
-- by this function do not persist through template reloads. Those
-- splices must be passed as a parameter to heistInitializer.
--
-- (NOTE: In the future we may decide to deprecate registerSplices in
-- favor of the heistInitializer argument.)
--
-- Typical use cases are dynamically generated components that are
-- present in many of your views.
--
-- Example Usage:
--
--
-- appInit :: Initializer AppState
-- appInit = do
-- hs <- heistInitializer "templates"
-- registerSplices hs $
-- [ ("tabs", tabsSplice)
-- , ("loginLogout", loginLogoutSplice) ]
--
registerSplices :: (MonadSnap m, MonadIO n) => HeistState m -> [(Text, Splice m)] -> n ()
instance HasHeistState m s => MonadHeist m (ReaderT s m)
instance HasHeistState (SnapExtend s) s => MonadHeist (SnapExtend s) (SnapExtend s)
instance MonadSnap m => InitializerState (HeistState m)
-- | This module provides replacements for the httpServe and
-- quickHttpServe functions exported by Snap.Http.Server.
-- By taking a Initializer as an argument, these functions
-- simplify the glue code that is needed to use Snap Extensions.
module Snap.Extension.Server
-- | ConfigExtend is similar to the Config exported by
-- Snap.Http.Server, but is augmented with a
-- reloadHandler field which can be accessed using
-- getReloadHandler and setReloadHandler.
type ConfigExtend s = Config (SnapExtend s) (IO [(ByteString, Maybe ByteString)] -> SnapExtend s ())
-- | Starts serving HTTP requests using the given handler, with settings
-- from the ConfigExtend passed in. This function never returns;
-- to shut down the HTTP server, kill the controlling thread.
httpServe :: ConfigExtend s -> Initializer s -> SnapExtend s () -> IO ()
-- | Starts serving HTTP using the given handler. The configuration is read
-- from the options given on the command-line, as returned by
-- commandLineConfig.
quickHttpServe :: Initializer s -> SnapExtend s () -> IO ()
-- | These are the default values for all the fields in
-- ConfigExtend.
--
--
-- hostname = "localhost"
-- address = "0.0.0.0"
-- port = 8000
-- accessLog = "log/access.log"
-- errorLog = "log/error.log"
-- locale = "en_US"
-- compression = True
-- verbose = True
-- errorHandler = prints the error message
-- reloadHandler = prints the result of each reload handler (error/success)
--
defaultConfig :: ConfigExtend s
getReloadHandler :: ConfigExtend s -> Maybe (IO [(ByteString, Maybe ByteString)] -> SnapExtend s ())
setReloadHandler :: (IO [(ByteString, Maybe ByteString)] -> SnapExtend s ()) -> ConfigExtend s -> ConfigExtend s
-- | This module includes the machinery necessary to use hint to load
-- action code dynamically. It includes a Template Haskell function to
-- gather the necessary compile-time information about code location,
-- compiler arguments, etc, and bind that information into the calls to
-- the dynamic loader.
module Snap.Extension.Loader.Devel
-- | This function derives all the information necessary to use the
-- interpreter from the compile-time environment, and compiles it in to
-- the generated code.
--
-- This could be considered a TH wrapper around a function
--
--
-- loadSnap :: Initializer s -> SnapExtend s () -> [String] -> IO (Snap ())
--
--
-- with a magical implementation.
--
-- The upshot is that you shouldn't need to recompile your server during
-- development unless your .cabal file changes, or the code that uses
-- this splice changes.
loadSnapTH :: Name -> Name -> [String] -> Q Exp
-- | This is the backing implementation for loadSnapTH. This
-- interface can be used when the types involved don't include a
-- SnapExtend and an Initializer.
loadSnapTH' :: [String] -> [String] -> [String] -> String -> Q Exp