Filter::LiterateComments - Haskell-style literate comments
This document describes version 0.01 of Filter::LiterateComments, released November 4, 2004.
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; > }
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.
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.
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.
=begin code
=end code
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
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.
Autrijus Tang <autrijus@autrijus.org>
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
To install Filter::LiterateComments, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Filter::LiterateComments
CPAN shell
perl -MCPAN -e shell install Filter::LiterateComments
For more information on module installation, please visit the detailed CPAN module installation guide.