Safe Haskell	Safe-Infered

Anansi

Contents

Basic operations
Documents
Document parsing
Looms
- Built-in looms

Synopsis

Basic operations

defaultMain :: Map Text Loom -> IO ()Source

Run Anansi with the provided looms. Loom names are namespaced by their package name, such as "anansi.noweb" or "anansi-hscolour.html". If your looms aren't available on Hackage, a Java-style name such as "com.mycompany.myformat" is a good alternative.

parse Source

Arguments

:: Monad m
=> (FilePath -> m ByteString)	File loader
-> FilePath	Path to the root file
-> m (Either ParseError Document)

Parse a set of files into a Document. If a parse failure occurs, a ParseError will be returned instead.

tangle Source

Arguments

:: Monad m
=> (FilePath -> ByteString -> m ())	File writer
-> Bool	Enable writing #line declarations
-> Document
-> m ()

Write a Document to files. Paths passed to the file writer are pulled directly from the document, so if you need to process them further, that logic must be placed in the writer computation.

In most cases, users will want to write #line pragmas to tangled source, so error messages will refer back to the original input files. Haddock does not handle these pragmas properly, so disable them when the tangled sources will be processed into API documentation.

weave :: Loom -> Document -> ByteString Source

Write a document to some sort of document markup. This will typically be rendered into documentation by external tools, such as LaTeX or a web browser.

This writes a ByteString rather than Text so that looms have full control over character encoding.

Documents

data Document Source

Instances

Eq Document
Show Document

documentBlocks :: Document -> [Block]Source

documentOptions :: Document -> Map Text Text Source

A map of :option commands found in the document. If the same option is specified multiple times, the most recent will be used.

documentLoomName :: Document -> Maybe Text Source

The last :loom command given, if any. A document does not require a loom name if it's just going to be tangled, or will be woven by the user calling weave. Documents woven by defaultMain do require a loom name.

data Block Source

Constructors

BlockText Text
BlockFile Text [Content]
BlockDefine Text [Content]

Instances

Eq Block
Ord Block
Show Block

data Content Source

Constructors

ContentText Position Text
ContentMacro Position Text Text	A macro reference within a content block. The first `Text` is any indentation found before the first `'\|'`, and the second is the name of the macro.

Instances

Eq Content
Ord Content
Show Content

data Position Source

Instances

Eq Position
Ord Position
Show Position

positionFile :: Position -> FilePath Source

positionLine :: Position -> Integer Source

Document parsing

data ParseError Source

Instances

Eq ParseError
Show ParseError
Error ParseError	ignore me

parseErrorPosition :: ParseError -> Position Source

parseErrorMessage :: ParseError -> Text Source

Looms

type Loom = Document -> LoomM ()Source

A loom contains all the logic required to convert a Document into markup suitable for processing with an external documentation tool.

Within a loom, use ask to retrieve the LoomOptions, and tell to append data to the output.

data LoomM a Source

Instances

Monad LoomM
Functor LoomM
MonadWriter LoomM
MonadReader LoomM

data LoomOptions Source

A set of processed :option commands related to looms. Looms are always free to check options manually, but this simplifies common cases.

Instances

Eq LoomOptions
Show LoomOptions

loomOptionTabSize :: LoomOptions -> Integer Source

Built-in looms

looms :: Map Text Loom Source

looms = Data.Map.fromList
    [ ("anansi.debug", loomDebug)
    , ("anansi.html", loomHTML)
    , ("anansi.latex", loomLaTeX)
    , ("anansi.markdown", loomMarkdown)
    , ("anansi.noweb", loomNoWeb)
    ]

loomDebug :: Loom Source

Just show each block. This is useful for seeing exactly what your document is being parsed to.

loomHTML :: Loom Source

Generate simple, <pre>-based HTML. Users who would like to weave specialized HTML to fit with their existing templates are encouraged to copy this loom and modify it as needed.

loomLaTeX :: Loom Source

Generate simple, alltt-based LaTeX. Users who would like to weave specialized LaTeX to fit with their existing templates are encouraged to copy this loom and modify it as needed.

loomMarkdown :: Loom Source

Generate Markdown. Modified from LaTeX.hs.

loomNoWeb :: Loom Source

Generate LaTeX markup, emulating the behavior of NoWeb. This is useful for porting existing NoWeb-based projects to Anansi without having to rewrite the styling.