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 code

SEE 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.

See http://www.perl.com/perl/misc/Artistic.html