Safe Haskell	None
Language	Haskell2010

Web.Herringbone

Contents

Creating a Herringbone
Assets
Preprocessors

Description

herringbone is a Haskell library for compiling and serving web assets. It aims to make it dead simple to create a Middleware or Application which deals with all of your static assets, including preprocessing for languages like Fay, CoffeeScript, Sass, and LESS.

It takes most of its inspiration from the Ruby library, Sprockets, hence the name.

Example:

import Web.Herringbone

fay, sass :: PP

hb = Herringbone
hb = herringbone
    ( addSourceDir "assets"
    . setDestDir   "compiled_assets"
    . addPreprocessors [fay, sass]
    )

-- You can now access assets programmatically
asset <- findAsset hb (fromJust . makeLogicalPath $ ["application.js"])

-- Or serve them with a Wai application
app = toApplication hb

Synopsis

Creating a Herringbone

data Herringbone Source

The 'main' datatype in this library. All of the important functions will take a Herringbone as their first argument.

hbSourceDir :: Herringbone -> FilePath Source

The directory where Herringbone will look when searching for assets.

hbDestDir :: Herringbone -> FilePath Source

The directory to place assets in after compilation.

hbPPs :: Herringbone -> PPs Source

The collection of preprocessors that will be used when preprocessing assets.

hbVerbose :: Herringbone -> Bool Source

True iff the Herringbone has the verbose setting enabled.

data HerringboneSettings Source

Contains configuration.

Constructors

HerringboneSettings
Fields settingsSourceDir :: FilePath The directory to take asset sources from. settingsDestDir :: FilePath Where to copy assets to after they've been compiled. settingsPPs :: PPs Preprocessors settingsVerbose :: Bool Dump debugging data to stdout on every request.

Instances

Show HerringboneSettings

module Web.Herringbone.Internal.Configuration

Assets

data LogicalPath Source

All assets in Herringbone are referenced by their logical path. This is the path to an asset, relative to the source directory.

Instances

Eq LogicalPath
Show LogicalPath

makeLogicalPath :: [Text] -> Maybe LogicalPath Source

Create a LogicalPath from a list of path segments. For example, ["data", "dogs.txt"] would map to data/dogs.txt (relative to the source directory). This returns Nothing if the path would be unsafe (that is, if it contains ".."), to prevent directory traversal attacks.

unsafeMakeLogicalPath :: [Text] -> LogicalPath Source

Create a LogicalPath without checking any of the values.

fromLogicalPath :: LogicalPath -> [Text] Source

toFilePath :: LogicalPath -> FilePath Source

data Asset Source

A preprocessed asset. Any function that returns this will already have done the preprocessing (if necessary).

Constructors

Asset
Fields assetSize :: Integer Size of the asset in bytes. assetSourcePath :: FilePath Path to the asset's source file on disk. assetFilePath :: FilePath Path to the preprocessed asset on disk. Note that assets which do not require preprocessing will still be copied to the destination directory. assetModifiedTime :: UTCTime Modification time of the asset's source file.

Instances

Show Asset

assetContent :: Asset -> IO ByteString Source

findAsset :: Herringbone -> LogicalPath -> IO (Either AssetError Asset) Source

The most important function in this library. Attempts to find the asset referenced by the given LogicalPath, compiles it if necessary (based on file modification time), and returns it to you as an Asset (or an AssetError, if something went wrong).

precompile :: Herringbone -> IO [(LogicalPath, AssetError)] Source

Precompiles all assets, returning a list of the logical paths of assets that failed to compile (if any) together with AssetError values describing what went wrong.

Preprocessors

data PP Source

A preprocessor something which is run on the asset before it is served. Preprocessors are run when a file matches its rule. For example, if you have a preprocessor which takes "coffee" files and emits "js" files, there is a file named "application.coffee", and you request "application.js", Herringbone will run the coffee preprocessor on "application.coffee" and serve you the result.

Constructors

PP
Fields ppName :: Text Identifies a preprocessor. Mainly useful for debugging compile errors. ppConsumes :: Text Extension for files this preprocessor consumes. ppProduces :: Text Extension for files this preprocessor produces. ppAction :: PPAction Performs the compilation.

Instances

Show PP

data PPs Source

A collection of preprocessors. This can store many preprocessors which produce files with the same extension, but may not store more than one preprocessor which consumes files of a particular extension.

Instances

Show PPs

data AssetError Source

A value describing an error that occurred while trying to produce an Asset.

Constructors

AssetNotFound
AssetCompileError CompileError
AmbiguousSources [FilePath]

Instances

Eq AssetError
Show AssetError

type CompileError = ByteString Source

A string which should contain information about why an asset failed to compile.

data PPReader Source

Data which is given to preprocessors on the off-chance that they need it (eg, Fay)

Constructors

PPReader
Fields ppReaderHb :: Herringbone The Herringbone which was used to build the asset ppReaderSourcePath :: FilePath The file path to the source file ppReaderPPs :: [PP] Preprocessors being invoked. Currently this will only ever have zero or one elements; in the future, Herringbone may be able to run multiple preprocessors on a single file.

Instances

MonadReader PPReader PPM

data PPM a Source

A monad in which preprocessor actions happen.

Instances

Monad PPM
Functor PPM
Applicative PPM
MonadIO PPM
MonadReader PPReader PPM