inliterate: Dynamic reporting for Haskell

The aim of inliterate is generate dynamic markdown reports from literate Haskell code in which code blocks can be evaluated to present the results of analyses in textual or graphical form.

inliterate is a GHC preprocessor which transforms a markdown document into a Haskell program, which, when run, prints to stdout the input document in HTML format. Certain code blocks with special annotations can be treated in particular ways: as Haskell code that must be included in the generating program (at the top level or in a do block) and as code that must be evaluated with the results inserted into the HTML document.

For an example document, see https://github.com/diffusionkinetics/open/blob/master/plotlyhs/gendoc/GenDocInlit.hs which ccompiles into https://glutamate.github.io/plotlyhs/.

The inliterate document

The inliterate ddocument should contain the following pragma on the first line or after the LANGUAGE pragmas:

{-# OPTIONS_GHC -F -pgmF inlitpp #-}

this tells GHC to invoke the preprocessor.

Code blocks

inliterate gives special meaning to the following code block language annotations (see the plotlyhs documentation generator to see how these are invoked)

html_header

this HTML should go in the header. Use this to load JavaScript or CSS, for instance for graphing libraries.

haskell top

Haskell code that is added to the top level

haskell do

Haskell code that is added to the main do block. use this for loading data or otherwise performing input and output.

haskell eval

Haskell code that is evaluated. The resultant type must be an instance of the AskInliterate class ddefined in Inliterate.Import.

hide

add this to top or do code to prevent it from being printed in the output document (but it is still run)

How to run

As an excutable

if you only have a few documents, you can put them in your cabal file as an executable, with inliterate as a build dependency.

here's the example from the plotlyhs documentation generator:

executable plotly-gendoc
  main-is: GenDocInlit.hs
  build-depends:       base >=4.6 && <5
                     , plotlyhs
                     , lucid
                     , aeson
                     , text
                     , microlens
                     , plotlyhs
                     , inliterate
                     , datasets
                     , neat-interpolation

Using stack runghc

if you have a larger number, or dynamically changing, set of documents, you can run them individually using stack runghc. inliterate should be listed in your cabal file as a build dependency to make sure the package is visible.

stack runghc InliterateFile.hs

if you want only the body HTML and not the headers, you can pass the argument --no-inlit-wrap to the executable

stack runghc InliterateFile.hs -- --no-inlit-wrap