readme-lhs

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

ghc options

{-# OPTIONS_GHC -Wall #-}

pragmas

{-# 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]
  void $ 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

Output that doesn’t exist is simply cleared.

Technicals

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 lhs method is latex. Pandoc can read this, but defaults to bird tracks when rendering markdown+lhs.

• markdown. All non bird-tracked lines are considered to be markdown. It’s probably incompatible with haddock. This might be easily fixable.

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

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

As it currently stands, ghc cannot read a file with fenced code-blocks that look like:

\```haskell
\```

Given this, a file cannot be both a valid haskell file, and a markdown file that is rendered nicely by github. This would resolve with adoption of the literate markdown ghc proposal.

template

A bare bones stack template is located in other/readme-lhs.hsfiles. It contains what you need to quickly get started with literate programming.

workflow

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