Literate modules +l,-l,+e,-e

Literate modules +l,-l,+e,-e

Like most programming languages, Hugs usually treats source file input as a sequence of lines in which program text is the norm, and comments play a secondary role. In Hugs, as in Haskell, comments are introduced by the character sequences -- and {- ... -}.

An alternative approach, using an idea described by Knuth as "literate programming,'' gives more emphasis to comments and documentation, with additional characters needed to distinguish program text from comments. Hugs supports a form of literate programming based on an idea due to Richard Bird and originally implemented as part of the functional programming language Orwell.

In a Hugs literate module, program lines are marked by a > character in the first column; any other line is treated as a program comment. This makes it particularly easy to write a document which is both an executable Hugs module and, at the same time, without need for any preprocessing, suitable for use with document preparation software such as LaTeX.

Hugs will treat any input file with a name ending in .hs as a normal module and any input file with a name ending in .lhs as a literate module. If the -l option is selected, then any other file loaded into Hugs will be treated as a normal module. Conversely, if +l is selected, then these files will be treated as literate modules. The effect of using literate modules can be thought of as applying a preprocessor to each input file that is loaded into Hugs. This has a particularly simple definition in Hugs:

 illiterate   :: String -> String
 illiterate cs = unlines [ " " ++ xs | ('>':xs) <- lines cs ]

The system of literate modules that was used in Orwell is a little more complicated than this and requires the programmer to adopt two further conventions in an attempt to catch simple errors in literate modules:

Every input file must contain at least one line whose first character is >. This prevents modules with no definitions (because the programmer has forgotten to use the > character to mark definitions) from being accepted.
Lines containing definitions must be separated from comment lines by one or more blank lines (i.e., lines containing only space and tab characters). This is useful for catching programs where the leading > character has been omitted from one or more lines in the definition of a function. For example:
```
> map f []     = []
  map f (x:xs) = f x : map f xs
```
would be treated as an error.

Hugs will report on errors of this kind whenever the -e option is enabled (the default setting).

The Haskell Report defines a second style of literate programming in which code is surrounded by \begin{code} and \end{code}. See Appendix C of the Haskell Report for more information about literate programming in Haskell.