NAME
Filter::LiterateComments - Haskell-style literate comments
VERSION
This document describes version 0.01 of Filter::LiterateComments, released November 4, 2004.
SYNOPSIS
use Filter::LiterateComments;
This literate program prompts the user for a number and prints
the factorial of that number:
> print "Enter a number: ";
> chomp( my $l = <STDIN> );
> print "n! = ", fact( $l ), $/;
This is the factorial function, using a recursive definition:
> sub fact ($) {
> $_[0] ? ( $_[0] * fact( $_[0]-1 ) ) : 1;
> }DESCRIPTION
This module supports two modes of literate comments, both taken from the literate Haskell (.lhs) format, with the TeX Mode replaced with a similar POD Mode.
The relevant documentation from the Haskell 98 Report is reproduced below.
Quoted Mode
The literate comment convention, first developed by Richard Bird and Philip Wadler for Orwell, and inspired in turn by Donald Knuth's literate programming, is an alternative style for encoding Haskell source code.
The literate style encourages comments by making them the default. A line in which > is the first character is treated as part of the program; all other lines are comment.
The program text is recovered by taking only those lines beginning with >, and replacing the leading > with a space.
POD Mode
An alternative style of literate programming is particularly suitable for use with POD (Plain Old Documentation) tools. In this convention, only those parts of the literate program that are entirely enclosed between =begin code ... =end code delimiters are treated as program text; all other lines are comment.
More precisely:
Program code begins on the first line following a line that starts with
=begin code.Program code ends just before a subsequent line that starts with
=end code.
It is not necessary to insert additional blank lines before or after these delimiters, though it may be stylistically desirable.
With POD mode, the program in the "SYNOPSIS" will look like this:
use Filter::LiterateComments;
This literate program prompts the user for a number and prints
the factorial of that number:
=begin code
print "Enter a number: ";
chomp( my $l = <STDIN> );
print "n! = ", fact( $l ), $/;
=end code
This is the factorial function, using a recursive definition:
=begin code
sub fact ($) {
$_[0] ? ( $_[0] * fact( $_[0]-1 ) ) : 1;
}
=end codeSEE ALSO
The Vim syntax file eg/lperl.vim in this module's source distribution.
The Haskell 98 Report: http://haskell.org/definition -- see section 9.6, literate comments.
AUTHORS
Autrijus Tang <autrijus@autrijus.org>
COPYRIGHT
Copyright 2004 by Autrijus Tang <autrijus@autrijus.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.