Text.BlogLiterately.Transform

Tools for putting together a pipeline transforming the source for a post into a completely formatted HTML document.

Standard transforms

These transforms are enabled by default in the standard BlogLiterately executable.

standardTransforms :: [Transform]

The standard set of transforms that are run by default (in order from top to bottom):

• optionsXF: extract options specified in [BLOpts] blocks in the file
• profileXF: load the requested profile (if any)
• passwordXF: prompt the user for a password if needed
• titleXF: extract the title from a special title block
• wptexifyXF: turn LaTeX into WordPress format if requested
• ghciXF: run and typeset ghci sessions if requested
• uploadImagesXF: upload images if requested
• centerImagesXF: center images occurring in their own paragraph
• highlightOptsXF: load the requested highlighting style file
• highlightXF: perform syntax highlighting
• citationsXF: process citations

optionsXF :: Transform

Extract blocks tagged with [BLOpts] and use their contents as options.

profileXF :: Transform

Load options from a profile if one is specified.

highlightOptsXF :: Transform

Read a user-supplied style file and add its contents to the highlighting options.

passwordXF :: Transform

Prompt the user for a password if the blog field is set but no password has been provided.

titleXF :: Transform

Potentially extract a title from the metadata block, and set it in the options record.

wptexifyXF :: Transform

Format embedded LaTeX for WordPress (if the wplatex flag is set).

ghciXF :: Transform

Format embedded ghci sessions (if the ghci flag is set).

uploadImagesXF :: Transform

Upload embedded local images to the server (if the uploadImages flag is set).

highlightXF :: Transform

Perform syntax highlighting on code blocks.

centerImagesXF :: Transform

Center any images which occur in a paragraph by themselves. Inline images are not affected.

citationsXF :: Transform

Format citations.

Transforms

data Transform

A document transformation consists of two parts: an actual transformation, expressed as a function over Pandoc documents, and a condition specifying whether the transformation should actually be applied.

The transformation itself takes a BlogLiterately configuration as an argument. You may of course ignore it if you do not need to know anything about the configuration. The --xtra (or -x) flag is also provided especially as a method of getting information from the command-line to custom extensions. Arguments passed via -x on the command line are available from the xtra field of the BlogLiterately configuration.

The transformation is then specified as a stateful computation over both a BlogLiterately options record, and a Pandoc document. It may also have effects in the IO monad.

• If you have a pure function of type @BlogLiterately -> Pandoc
• > Pandoc@, you can use the pureTransform function to create a Transform.
• If you have a function of type BlogLiterately -> Pandoc -> IO Pandoc, you can use ioTransform.
• Otherwise you can directly create something of type StateT (BlogLiterately, Pandoc) IO ().

For examples, see the implementations of the standard transforms below.

Constructors

Transform

Fields

getTransform :: StateT (BlogLiterately, Pandoc) IO ()

A document transformation, which can transform both the document and the options and have effects in the IO monad. The options record can be transformed because the document itself may contain information which affects the options.

xfCond :: BlogLiterately -> Bool

A condition under which to run the transformation.

pureTransform :: (BlogLiterately -> Pandoc -> Pandoc) -> (BlogLiterately -> Bool) -> Transform

Construct a transformation from a pure function.

ioTransform :: (BlogLiterately -> Pandoc -> IO Pandoc) -> (BlogLiterately -> Bool) -> Transform

Construct a transformation from a function in the IO monad.

runTransform :: Transform -> StateT (BlogLiterately, Pandoc) IO ()

Run a Transform (if its condition is met).

runTransforms :: [Transform] -> BlogLiterately -> Pandoc -> IO (BlogLiterately, Pandoc)

Run a pipeline of Transforms.

Transforming documents

xformDoc :: BlogLiterately -> [Transform] -> String -> IO (Either PandocError (BlogLiterately, String))

Transform a complete input document string to an HTML output string, given a list of transformation passes.

Utilities

fixLineEndings :: String -> String

Turn CRLF pairs into a single LF. This is necessary since readMarkdown is picky about line endings.