snap package:snap

Top-level package for the Snap Web Framework This is the top-level package for the official Snap Framework libraries. It includes:

• The Snaplets API
• Snaplets for sessions, authentication, and templates

To get started, issue the following sequence of commands:

$ cabal install snap snap-templates
$ mkdir myproject
$ cd myproject
$ snap init

If you have trouble or any questions, see our FAQ page (http://snapframework.com/faq) or the documentation (http://snapframework.com/docs). Note: since version 1.0, the "snap" executable program for generating starter projects is provided by the snap-templates package.

This module provides convenience exports of the modules most commonly used when developing with the Snap Framework. For documentation about Snaplets, see Snap.Snaplet. For the core web server API, see Snap.Core.

Constructs a url relative to the current snaplet.

Snaplets allow you to build web applications out of composable parts. This allows you to build self-contained units and glue them together to make your overall application. A snaplet has a few moving parts, some user-defined and some provided by the snaplet API:

• each snaplet has its own configuration given to it at startup.
• each snaplet is given its own directory on the filesystem, from which it reads its configuration and in which it can store files.
• each snaplet comes with an Initializer which defines how to create an instance of the Snaplet at startup. The initializer decides how to interpret the snaplet configuration, which URLs to handle (and how), sets up the initial snaplet state, tells the snaplet runtime system how to clean the snaplet up, etc.
• each snaplet contains some user-defined in-memory state; for instance, a snaplet that talks to a database might contain a reference to a connection pool. The snaplet state is an ordinary Haskell record, with a datatype defined by the snaplet author. The initial state record is created during initialization and is available to snaplet Handlers when serving HTTP requests.

NOTE: This documentation is written as a prose tutorial of the snaplets API. Don't be scared by the fact that it's auto-generated and is filled with type signatures. Just keep reading.

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.

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

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.

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.

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

Gets a human readable description of the snaplet.

Gets the snaplet's path on the filesystem.

Gets the current snaple's name.

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

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

Gets the config data structure for the current snaplet.

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

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.

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