Personal tools

Literate programming

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(Added a literate case to the listings configuration, so the set difference operation (\\) doesn't get replaced by two lambdas.)
(Updated "hiding code from haskell" to reflect modern lhs2TeX)
(9 intermediate revisions by 7 users not shown)

Revision as of 17:36, 13 October 2010

Literate programming was invented / coined / started by Dr. Donald Knuth. In fact, if you asked Dr. Knuth what his favourite programming language was, (5th question of you would be told CWEB - which is a literate programming tool combining C and tex.

What is literate programming? To quote Dr. Knuth:


The tool used to generate hyperlinked documentation from literate code is Haddock


1 Haskell and literate programming




2 Bird Style

According to the Haskell Report, this style of comment was developed by Richard Bird (hence the name) and Philip Wadler. All lines starting with > are interpreted as code, everything else is considered a comment. One additional requirement is that you always leave a blank line before and after the code block:

In Bird-style you have to leave a blank before the code.
> fact :: Integer -> Integer
> fact 0 = 1
> fact n = n * fact (n-1)
And you have to leave a blank line after the code as well.

The idea behind this restriction is capturing the mistake of not inserting the > mark at the beginning of the line. In general this is not only good practice, but also a formatting that makes the code more readable.

However, there are cases in which you might like to get around this restriction. Perhaps you're writing Haskell code within a markup language that's not Latex, and you may have to surround your code with something equivalent to \begin{code} and \end{code}. In this case, GHC provides a flag that can be used to lift the blank lines requirement:

$ ghc -optL -q

3 Latex suggestions for literate programming


tsort []     = []
tsort (x:xs) = tsort [y | y<-xs, y>x] ++ [x] ++ tsort [y | y<-xs, y<=x]

and the code will be formatted as you requested.


3.1 Verbatim package


Use verbatim:


3.2 Listings package




      \csname lst@SetFirstLabel\endcsname}
    {\csname lst@SaveFirstLabel\endcsname}


For arrow notation add the line (requires MnSymbol package, or stmaryrd if you use Yleft instead):

               {<<<}{{$\lll$}}2 {>>>}{{$\ggg$}}2 {-<}{{$\leftY$}}1

3.3 Hiding code from Latex



Auxiliary functions can be hidden as follows:



Ciao, Steffen Mazanek

3.4 Hiding code from Haskell


And the definition of the following function
would totally screw up my program, so I'm not
definining it:

\begin{code}% this is not really code
main :: IO ()
main = print "just an example"


While this works well for vanilla LaTeX, if you're using lhs2TeX, then you'll get the "% this is not really code" printed in your output. Instead of doing the above, either use \begin{spec} ... \end{spec}, or if you're writing Bird-style code, flip your ">" characters around:

Neither of the following definitions are really code:

main :: IO ()
main = print "another example"

< main :: IO ()
< main = print "...and another"

4 Transformation of .lhs-files


5 Editors

5.1 Multi-mode support in Emacs




    :submode text-mode
    :front "^[^>]"
    :include-front true
    :back "^>\\|$"
    :submode literate-haskell-mode
    :front-offset (end-of-line 1)
    :include-back nil

(defun my-mmm-mode ()
  ;; go into mmm minor mode when class is given
  (setq mmm-global-mode 'true))

(setq mmm-submode-decoration-level 0)



% Local Variables: ***
% mode: latex ***
% End: ***


5.2 Vim

See Literate programming/Vim.

6 lhs2TeX




Since it can typeset Haskell formulas in mathematical notation with LaTeX's math mode, you can also use it to create testable papers. That is, readers can play with the formulas presented in the paper if they obtain the literate Haskell source code for the paper.

7 Shuffle

Shuffle is a tool which extends the capabilities of lhs2TeX. It was used in documenting the Essential Haskell Compiler project. It is available as part of this project, but it is usable also independently.

8 See also