readme-lhs

The language in which we express our ideas has a strong influence on our thought processes. \~ Knuth

This is an example of mixing literate haskell with markdown, and in using Readme.Lhs. The file is composed of several elements:

• literate haskell. Bird-tracks are used, as the alternative method is latex rather than markdown, which doesn’t survive a pandoc round trip.

• markdown. All non bird-tracked lines are considered to be markdown. It’s probably incompatible with haddock, but this may well resolve with adoption of the literate markdown ghc proposal.

• fenced code blocks with an output class, which are used to insert computation results. The fenced code blocks look like:

  ```{.output .example} ```

ghc options

{-# OPTIONS_GHC -Wall #-}

pragmas

-- doctest doesn't look at the cabal file, so you need pragmas here
{-# LANGUAGE NoImplicitPrelude #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE ScopedTypeVariables #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE FlexibleInstances #-}

libraries

• protolude
• readme-lhs

import Protolude
import Readme.Lhs

code

• hoogle

main :: IO ()
main = do
  let n = 10
  let answer = product [1..n::Integer]
  _ <- runOutput ("example.lhs", LHS) ("readme.md", GitHubMarkdown) $ do
    output "example1" "Simple example of an output"

Simple example of an output

    output "example2" (show answer)

10! is equal to:

3628800

  pure ()

Output that doesn’t exist is simply cleared.

hsfiles writeup

A literate-programming friendly; tight work-flow stack template.

other/readme-lhs.hsfiles

other/batteries.hsfiles

This is my latest working template, overly influenced by lexi-lambda’s opinionated guide. The template includes:

• some minor tweaks to protolude
• lens, foldl, formatting & text as must have libraries
• generic-lens-labels

workflow

stack build --exec "$(stack path --local-install-root)/bin/readme-lhs-example" --file-watch