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


-- | dynamic plugin system for web applications
--   
--   dynamic plugin system for web applications
@package web-plugins
@version 0.2.2

module Web.Plugins.Core

-- | <a>When</a> indicates when a clean up action should be run
data When

-- | always run this action when <a>destroyPlugins</a> is called
Always :: When

-- | only run this action if <a>destroyPlugins</a> is called with a failure
--   present
OnFailure :: When

-- | only run this action when <a>destroyPlugins</a> is called with a
--   normal shutdown
OnNormal :: When

-- | A <a>Cleanup</a> is an <a>IO</a> action to run when the server shuts
--   down. The server can either shutdown normally or due to a failure. The
--   <a>When</a> parameter indicates when an action should run.
data Cleanup
Cleanup :: When -> (IO ()) -> Cleanup

-- | The <a>PluginName</a> should uniquely identify a plugin -- though we
--   currently have no way to enforce that.
type PluginName = Text

-- | The <a>PluginsState</a> record holds all the record keeping
--   information needed for loading, unloading, and invoking plugins. In
--   theory you should not be modifying or inspecting this structure
--   directly -- only calling the helper functions that modify or read it.
data PluginsState theme n hook config st
PluginsState :: Map PluginName (Plugins theme n hook config st -> [Text] -> n) -> [Cleanup] -> Map PluginName Dynamic -> Map PluginName (TVar Dynamic) -> Maybe theme -> [hook] -> config -> st -> PluginsState theme n hook config st
pluginsHandler :: PluginsState theme n hook config st -> Map PluginName (Plugins theme n hook config st -> [Text] -> n)
pluginsOnShutdown :: PluginsState theme n hook config st -> [Cleanup]
pluginsRouteFn :: PluginsState theme n hook config st -> Map PluginName Dynamic

-- | per-plugin state
pluginsPluginState :: PluginsState theme n hook config st -> Map PluginName (TVar Dynamic)
pluginsTheme :: PluginsState theme n hook config st -> Maybe theme
pluginsPostHooks :: PluginsState theme n hook config st -> [hook]
pluginsConfig :: PluginsState theme n hook config st -> config
pluginsState :: PluginsState theme n hook config st -> st

-- | The <a>Plugins</a> type is the handle to the plugins system. Generally
--   you will have exactly one <a>Plugins</a> value in your app.
--   
--   see also <a>withPlugins</a>
newtype Plugins theme m hook config st
Plugins :: TVar (PluginsState theme m hook config st) -> Plugins theme m hook config st
ptv :: Plugins theme m hook config st -> TVar (PluginsState theme m hook config st)

-- | initialize the plugins system
--   
--   see also <a>withPlugins</a>
initPlugins :: config -> st -> IO (Plugins theme n hook config st)

-- | shutdown the plugins system
--   
--   see also <a>withPlugins</a>
destroyPlugins :: When -> Plugins theme m hook config st -> IO ()

-- | a bracketed combination of <a>initPlugins</a> and
--   <a>destroyPlugins</a>. Takes care of passing the correct termination
--   condition.
withPlugins :: config -> st -> (Plugins theme m hook config st -> IO a) -> IO a

-- | get the current <tt>st</tt> value from <a>Plugins</a>
getPluginsSt :: MonadIO m => Plugins theme n hook config st -> m st

-- | put the current st value from <a>Plugins</a>
putPluginsSt :: MonadIO m => Plugins theme n hook config st -> st -> m ()

-- | add a new plugin-local state
addPluginState :: (MonadIO m, Typeable state) => Plugins theme n hook config st -> Text -> state -> m ()

-- | Get the state for a particular plugin
--   
--   per-plugin state is optional. This will return <a>Nothing</a> if the
--   plugin did not register any local state.
getPluginState :: (MonadIO m, Typeable state) => Plugins theme n hook config st -> Text -> m (Maybe state)

-- | modify the current st value from <a>Plugins</a>
modifyPluginsSt :: MonadIO m => Plugins theme n hook config st -> (st -> st) -> m ()

-- | add a new route handler
addHandler :: MonadIO m => Plugins theme n hook config st -> Text -> (Plugins theme n hook config st -> [Text] -> n) -> m ()

-- | add a new cleanup action to the top of the stack
addCleanup :: MonadIO m => Plugins theme n hook config st -> When -> IO () -> m ()

-- | add a new post initialization hook
addPostHook :: MonadIO m => Plugins theme n hook config st -> hook -> m ()

-- | get all the post initialization hooks
getPostHooks :: MonadIO m => Plugins theme n hook config st -> m [hook]

-- | add the routing function for a plugin
--   
--   see also: <a>getPluginRouteFn</a>
addPluginRouteFn :: (MonadIO m, Typeable url) => Plugins theme n hook config st -> PluginName -> (url -> [(Text, Maybe Text)] -> Text) -> m ()

-- | get the plugin routing function for the named plugin
--   
--   see also: <a>addPluginRouteFn</a>
getPluginRouteFn :: (MonadIO m, Typeable url) => Plugins theme n hook config st -> PluginName -> m (Maybe (url -> [(Text, Maybe Text)] -> Text))

-- | set the current <tt>theme</tt>
setTheme :: MonadIO m => Plugins theme n hook config st -> Maybe theme -> m ()

-- | get the current <tt>theme</tt>
getTheme :: MonadIO m => Plugins theme n hook config st -> m (Maybe theme)

-- | get the <tt>config</tt> value from the <a>Plugins</a> type
getConfig :: MonadIO m => Plugins theme n hook config st -> m config

-- | NOTE: it is possible to set the URL type incorrectly here and not get
--   a type error. How can we fix that ?
data Plugin url theme n hook config st
Plugin :: PluginName -> (Plugins theme n hook config st -> IO (Maybe Text)) -> [PluginName] -> (url -> Text) -> hook -> Plugin url theme n hook config st
pluginName :: Plugin url theme n hook config st -> PluginName
pluginInit :: Plugin url theme n hook config st -> Plugins theme n hook config st -> IO (Maybe Text)

-- | plugins which much be initialized before this one can be
pluginDepends :: Plugin url theme n hook config st -> [PluginName]
pluginToPathInfo :: Plugin url theme n hook config st -> url -> Text
pluginPostHook :: Plugin url theme n hook config st -> hook

-- | initialize a plugin
initPlugin :: Typeable url => Plugins theme n hook config st -> PluginName -> Plugin url theme n hook config st -> IO (Maybe Text)

-- | serve requests using the <a>Plugins</a> handle
serve :: Plugins theme n hook config st -> PluginName -> [Text] -> IO (Either String n)
instance Eq When
instance Ord When
instance Show When