Snaplet's type parameter s here is user-defined and can be any Haskell type. A value of type Snaplet s countains a couple of things:

• a value of type s, called the "user state".
• some bookkeeping data the framework uses to plug things together, like the snaplet's configuration, the snaplet's root directory on the filesystem, the snaplet's root URL, and so on.

An opaque data type holding internal snaplet configuration data. It is exported publicly because the getOpaqueConfig function in MonadSnaplet makes implementing new instances of MonadSnaplet more convenient.

Transforms a lens of the type you get from makeLenses to an similar lens that is more suitable for internal use.

The m type parameter used in the MonadSnaplet type signatures will usually be either Initializer or Handler, but other monads may sometimes be useful.

Minimal complete definition:

• withTop', with', getLens, and getOpaqueConfig.

Gets a list of the names of snaplets that are direct ancestors of the current snaplet.

Gets the snaplet's path on the filesystem.

Gets the current snaple's name.

Gets a human readable description of the snaplet.

Gets the config data structure for the current snaplet.

Gets the base URL for the current snaplet. Directories get added to the current snaplet path by calls to nestSnaplet.

Constructs a url relative to the current snaplet.

Gets the route pattern that matched for the handler. This lets you find out exactly which of the strings you used in addRoutes matched.

Sets the route pattern that matched for the handler. Use this when to override the default pattern which is the key to the alist passed to addRoutes.

Gets the Snaplet v from the current snaplet's state.

Puts a new Snaplet v in the current snaplet's state.

Modifies the Snaplet v in the current snaplet's state.

Gets the Snaplet v from the current snaplet's state and applies a function to it.

Monad used for initializing snaplets.

Opaque newtype which gives us compile-time guarantees that the user is using makeSnaplet and either nestSnaplet or embedSnaplet correctly.

All snaplet initializers must be wrapped in a call to makeSnaplet, which handles standardized housekeeping common to all snaplets. Common usage will look something like this:

fooInit :: SnapletInit b Foo
fooInit = makeSnaplet "foo" "An example snaplet" Nothing $ do
    -- Your initializer code here
    return $ Foo 42

Note that you're writing your initializer code in the Initializer monad, and makeSnaplet converts it into an opaque SnapletInit type. This allows us to use the type system to ensure that the API is used correctly.

Runs another snaplet's initializer and returns the initialized Snaplet value. Calling an initializer with nestSnaplet gives the nested snaplet access to the same base state that the current snaplet has. This makes it possible for the child snaplet to make use of functionality provided by sibling snaplets.

Runs another snaplet's initializer and returns the initialized Snaplet value. The difference between this and nestSnaplet is the first type parameter in the third argument. The "v1 v1" makes the child snaplet think that it is the top-level state, which means that it will not be able to use functionality provided by snaplets included above it in the snaplet tree. This strongly isolates the child snaplet, and allows you to eliminate the b type variable. The embedded snaplet can still get functionality from other snaplets, but only if it nests or embeds the snaplet itself.

Note that this function does not change where this snaplet is located in the filesystem. The snaplet directory structure convention stays the same. Also, embedSnaplet limits the ways that snaplets can interact, so we usually recommend using nestSnaplet instead. However, we provide this function because sometimes reduced flexibility is useful. In short, if you don't understand what this function does for you from looking at its type, you probably don't want to use it.

Sets a snaplet's name. All snaplets have a default name set by the snaplet author. This function allows you to override that name. You will have to do this if you have more than one instance of the same kind of snaplet because snaplet names must be unique. This function must immediately surround the snaplet's initializer. For example:

fooState <- nestSnaplet "fooA" $ nameSnaplet "myFoo" $ fooInit

Attaches an unload handler to the snaplet. The unload handler will be called when the server shuts down, or is reloaded.

Adds an IO action that modifies the current snaplet state to be run at the end of initialization on the state that was created. This makes it easier to allow one snaplet's state to be modified by another snaplet's initializer. A good example of this is when a snaplet has templates that define its views. The Heist snaplet provides the addTemplates function which allows other snaplets to set up their own templates. addTemplates is implemented using this function.

Variant of addPostInitHook for when you have things wrapped in a Snaplet.

Initializers should use this function for all informational or error messages to be displayed to the user. On application startup they will be sent to the console. When executed from the reloader, they will be sent back to the user in the HTTP response.

Lets you retrieve the list of routes currently set up by an Initializer. This can be useful in debugging.

Return the current environment string. This will be the environment given to runSnaplet or from the command line when using serveSnaplet. Usefully for changing behavior during development and testing.

Adds routing to the current Handler. The new routes are merged with the main routing section and take precedence over existing routing that was previously defined.

Wraps the base snaplet's routing in another handler, allowing you to run code before and after all routes in an application.

Here are some examples of things you might do:

wrapSite (\site -> logHandlerStart >> site >> logHandlerFinished)
wrapSite (\site -> ensureAdminUser >> site)

Snaplet infrastructure is available during runtime request processing through the Handler monad. There aren't very many standalone functions to read about here, but this is deceptive. The key is in the type class instances. Handler is an instance of MonadSnap, which means it is the monad you will use to write all your application routes. It also has a MonadSnaplet instance, which gives you all the functionality described above.

Pass if the request is not coming from localhost.

Handler that reloads the site.

Lets you change a snaplet's initial state. It's alomst like a reload, except that it doesn't run the initializer. It just modifies the result of the initializer. This can be used to let you define actions for reloading individual snaplets.

This function brackets a Handler action in resource acquisition and release. Like bracketSnap, this is provided because MonadCatchIO's bracket function doesn't work properly in the case of a short-circuit return from the action being bracketed.

In order to prevent confusion regarding the effects of the aquisition and release actions on the Handler state, this function doesn't accept Handler actions for the acquire or release actions.

This function will run the release action in all cases where the acquire action succeeded. This includes the following behaviors from the bracketed Snap action.

1. Normal completion
2. Short-circuit completion, either from calling fail or finishWith
3. An exception being thrown.

Given an environment and a Snaplet initializer, produce a concatenated log of all messages generated during initialization, a snap handler, and a cleanup action. The environment is an arbitrary string such as "devel" or "production". This string is used to determine the name of the configuration files used by each snaplet. If an environment of Nothing is used, then runSnaplet defaults to "devel".

Given a configuration and a snap handler, complete it and produce the completed configuration as well as a new toplevel handler with things like compression and a 500 handler set up.

Initialize and run a Snaplet. This function parses command-line arguments, runs the given Snaplet initializer, and starts an HTTP server running the Snaplet's toplevel Handler.

Like serveSnaplet, but don't try to parse command-line arguments.

Allows you to get all of your app's config data in the IO monad without the web server infrastructure.