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.Note, this library is tested with pandoc 2.7.3 and may not be compatible with older versions.
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/) git clone https://github.com/gdevanla/pandoc-markdown-ghci-filter.git cd pandoc-markdown-ghci-filter stack build stack build pandoc-markdown-ghci-filter # executable only available to local stack environment or stack install pandoc-markdown-ghci-filter # if you want to across all stack environments pandoc -s -t json test.md | pandoc-markdown-ghci-filter-exe | pandoc -f json -t markdown - All interactive statements (prefixed with
>>) need to be preceded by\nto let the filter respect original new line spacing. If this is not followed,\nmay be truncated. - 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. - If you want the filter to ignore a certain
codeblock, you can turn-off the filter by setting thecodeblock attribute as follows
{.haskell code_filter="Off"} -- do not run this code through GHCi >> putStrLn "This line will not be expanded by the filter" Note, the default value is "On"
- Attaching different formattting properties to
output. - As explained in
Usage Notes, allinteractivestatements should be preceded by an empty line, for the filter to maintain the\ncharacters 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 Expand type definitions
testDefinition :: Integer -> Integer -> Integer testDefinition x y = x + y >>:t testDefinition >>:t testDefinition 10 >>:t testDefinition 10 20 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 Expand type definitions
testDefinition :: Integer -> Integer -> Integer testDefinition x y = x + y >>:t testDefinition testDefinition :: Integer -> Integer -> Integer >>:t testDefinition 10 testDefinition 10 :: Integer -> Integer >>:t testDefinition 10 20 testDefinition 10 20 :: Integer 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