readme-lhs Build Status

a literate haskell workflow.

stack build --copy-bins --exec "readme" --exec "pandoc -f markdown+lhs -i readme.lhs -t html -o index.html --filter pandoc-include --mathjax" --exec "pandoc -f markdown+lhs -i readme.lhs -t markdown -o --filter pandoc-include --mathjax" --exec "echo Yah, it succeeded" --file-watch

The command above is a major milestone in my personal workflow. I switch between osx at home and windows at work and I'm getting consistent and fast startups for new projects. I type stack new project-name readme-lhs && cd project-name, fire up this command and start cutting code and docs in readme.lhs. On save, I get:

A poor haskellers imitation of jupyter, sure, but until we climb the curve of tool maturity this will do me as a quick project start.



The template produces a shell project that builds out-of-the-box.

stack new project-name readme-lhs
cd project-name
stack install

and it should chirp back a cheery "ok".

If you dont want to pollute the global ~/.local/bin, you can drop back to

stack new project-name readme-lhs
cd project-name
stack build
$(stack path --local-install-root)/bin/readme

The template file can always be edited, renamed etc and dropped into a directory, and stack will find it.

design wonkery

Stripping away optional extras, readme-lhs tries for a minimalist design:

Here's what I threw out:

I then keep this repo around for phase 2, where a project takes a successful shape and and needs test and app boiler-plate.

lhs executable

I use both .lhs and .hs styles, and often need to flip between the two. In particular, hlint didn't always play nice with .lhs, and for a while I needed to flip from .lhs to .hs, run hlint, and then flip back to .lhs.

lhs makes no attempt to account for haddock and will thus not be suitable for most people.

To install and use lhs:

git clone
cd readme-lhs
stack install
lhs --file-in readme.lhs --file-out readme.hs




{-# OPTIONS_GHC -Wall #-}
{-# OPTIONS_GHC -fno-warn-type-defaults #-}
import Protolude

main :: IO ()
main = do
  print "readme-lhs library"
  let fac n = foldr (\x g n' -> g (x*n')) identity [1..n] 1
  writeFile "other/" $
      "$\\prod_{x=1}^{20} x = " <> show (fac 20) <> "$\n"

Output from the code above appears in this readme.lhs when rendered with pandoc-include (except if you're reading this as the repo, sorry):

\(\prod_{x=1}^{20} x = 2432902008176640000\)


Haskell code is managed using stack and written with spacemacs using the intero engine. Protolude is our prelude of choice. Documentation is written using markdown and rendered with pandoc and pandoc-include. Repos and all blog material is hosted via github and tested with travis ci.