herringbone-0.0.7: A library for compiling and serving static web assets.

Safe HaskellNone




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.


 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


Creating a Herringbone

data Herringbone Source

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




hbSourceDirs :: [FilePath]

A list of source directories; this is where assets should be placed.

hbDestDir :: FilePath

Where to copy assets to after they've been compiled.

hbPPs :: PPs


herringbone :: ConfigBuilder -> HerringboneSource

Preferred way of creating Herringbone instances.

addSourceDir :: FilePath -> ConfigBuilderSource

Adds a directory to the list of source directories.

setDestDir :: FilePath -> ConfigBuilderSource

Sets the destination directory. Note that this will overwrite the destination directory if one is already set.

addPreprocessors :: [PP] -> ConfigBuilderSource

Add the preprocessors in the list to the preprocessor collection.


data LogicalPath Source

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

makeLogicalPath :: [Text] -> Maybe LogicalPathSource

Create a LogicalPath from a list of Text values. This returns Nothing if the path would be unsafe (that is, if it contains ".."), to prevent directory traversal attacks.

unsafeMakeLogicalPath :: [Text] -> LogicalPathSource

Create a LogicalPath without checking any of the values.

data Asset Source

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




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.

assetLogicalPath :: LogicalPath

The logical path referencing this asset.

assetModifiedTime :: UTCTime

Modification time of the asset's source file.



data PP Source

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

You can add more preprocessors by adding more file extensions; "application.js.coffee.erb" will be preprocessed first by "erb", then by "coffee" (assuming you have registered preprocessors for those files).




ppExtension :: Text

The file extension this preprocessor acts upon, eg "sass" or "hamlet"

ppAction :: ByteString -> PPM (Either CompileError ByteString)

Perform the preprocessing.



Beware: This instance only looks at the extensions to decide whether two PPs are equal.

Ord PP 
Show PP 

data PPs Source

A collection of preprocessors.


type CompileError = ByteStringSource

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)




ppReaderHb :: Herringbone

The Herringbone which was used to build the asset

ppReaderLogicalPath :: LogicalPath

The Logical path of the requested asset.

ppReaderSourcePath :: FilePath

The file path to the source file

ppReaderPPs :: [PP]

Preprocessors being invoked.

data PPM a Source

A monad in which preprocessor actions happen.