A Pandoc filter that identifies code blocks(Haskell) in Pandoc supported formats, executes the code in GHCI and embeds the results in the returned output by updating the AST provided by Pandoc.

Often a markdown(or any pandoc supported document) for any Haskell related documentation or a technical blog post involves code blocks. The code block could include definitions and also a demonstration of output with an interactive prompt. For, example, take this code block:

-- README.md -- definition increment:: Integer -> Integer increment x = x + 1 -- interactive prompt to demonstrate the working of definitions so far >> increment 41 

It would be nice if this code block was automatically evaluated and output of increment 41 is automatically recorded below >> increment 41, as follows:

-- README.md -- definition increment:: Integer -> Integer increment x = x + 1 -- interactive prompt to demonstrate the working of definitions so far >> increment 41 42 

Notice, that the 42 is automatically populated by this filter while transforming the original document.

To transform the document, we need to run the document through the pandoc filter, as follows:

 -- set up pandoc_filter to the executable of this program (see Installation) pandoc -s -t json README.md | pandoc_filter | pandoc -f json -t markdown 

To read more about how filter work, visit the this page.

- [Stack](https://docs.haskellstack.org/en/stable/README/) 

Currently, this filter can be installed from the source (it will be available on Hackage once the tool is stable).

 git clone https://github.com/gdevanla/pandoc-markdown-ghci-filter.git cd pandoc-markdown-ghci-filter stack build stack setup # Note, this command copies this tool to ~/.local/bin. # test it on a test_markdown file pandoc -s -t json README.md | pandoc-markdown-ghci-filter-exe | pandoc -f json -t markdown 

1. All interactive statements (prefixed with >>) need to be preceded by \n to let the filter respect original new line spacing. If this is not followed, \n may be truncated.
2. The program internally wraps all commands inside the GHCi multi-line construct :{..:}. Therefore, the code segments should not have multi-line constructs as part of code blocks.
3. If you want the filter to ignore a certain code block, you can turn-off the filter by setting the code block attribute as follows

 {.haskell code_filter="Off"} -- do not run this code through GHCi >> putStrLn "This line will not be expanded by the filter" This line will not be expanded by the filter 

Note, the default value is "On"

1. Attaching different formattting properties to output.
2. As explained in Usage Notes, all interactive statements should be preceded by an empty line, for the filter to maintain the \n characters as given by the input.

Sample markdown as fed into filter through pandoc.

import Data.Text >> putStrLn "This string should show up in the output" 

addOne:: Integer -> Integer addOne x = x + 1 >> addOne 13 multBy2:: Integer -> Integer multBy2 x = x * 2 >> (addOne 10) + (multBy2 20) 

Any errors that occur while executing statements in the code block are also rendered.

 wrongFuncDefinition:: Integer -> Integer wrongFuncDefintion = x + 1 >> functionNotInScope 10 

import Data.Text >> putStrLn "This string should show up in the output" This string should show up in the output 

addOne:: Integer -> Integer addOne x = x + 1 >> addOne 13 14 multBy2:: Integer -> Integer multBy2 x = x * 2 >> (addOne 10) + (multBy2 20) 51 

Any errors that occur while executing statements in the code block are also rendered.

 wrongFuncDefinition:: Integer -> Integer wrongFuncDefintion = x + 1 <interactive>:16:1: error: The type signature for ‘wrongFuncDefinition’ lacks an accompanying binding >> functionNotInScope 10 <interactive>:29:2: error: Variable not in scope: functionNotInScope :: Integer -> t 

Fun Fact: This document was generated using this same tool it describes. This README-pre-process.md was used to generate this document. Here is the command that was used:

pandoc -s -t json README-pre-process.md | stack runhaskell app/Main.hs | pandoc -f json -t markdown > README.md