This is a short guide to writing Literate Haskell programs using Markdown.
The source code of this very Web page is a Markdown file with a frontmatter. At the same time, the source code is a Literate Haskell program, i.e. you can compile and run it.
Let's write a small program.
First, we define a Haskell module:
module Main where
... and then, define a main function:
main :: IO ()
main = putStrLn "Hello World!"
By now, we have implemented a valid Haskell program that is embedded in our Markdown document (the source code). We will define two more functions to demonstrate doctest.
-- | Adds 7 to the given 'Int'.
--
-- >>> add7 35
-- 42
add7 :: Int -> Int
add7 = (+) 7
-- | Divides 42 by the given 'Int'.
--
-- >>> div42 1
-- 42
-- >>> div42 2
-- 21
-- >>> div42 3
-- 14
-- >>> div42 6
-- 7
-- >>> div42 7
-- 6
-- >>> div42 0
-- 0
-- >>> div42 42
-- 1
div42 :: Int -> Int
div42 = div 42
We need to install markdown-unlit, a custom unlit program to extract Haskell code from Markdown files. Once installed, we can compile our program:
$ ghc -pgmLmarkdown-unlit Main.lhs
[1 of 1] Compiling Main ( Main.lhs, Main.o )
Linking Main ...
This will produce your executable (Main) along with Main.o and Main.hi
files. You can run your program:
$ ./Main
Hello World!
We could have run the program directly using runhaskell, too:
$ runhaskell -pgmLmarkdown-unlit Main.lhs
Hello World!
Also, we can produce the Haskell code of interest:
$ markdown-unlit -h label Main.lhs Main.hs
We can study Main.hs or run doctest on it (do not forget to re-generate
Main.hs after changing the source code):
$ doctest Main.hs
label:51: failure in expression `div42 0'
expected: 0
but got: *** Exception: divide by zero
^
Examples: 8 Tried: 7 Errors: 0 Failures: 1