| 1 | package Filter::LiterateComments; | ||||||||||||||||||
| 2 | 2 | $Filter::LiterateComments::VERSION = '0.01'; | |||||||||||||||||
| 3 | |||||||||||||||||||
| 4 | 2 | ▶ | use strict; | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 5 | 2 | ▶ | use Filter::Simple \&lperl_to_perl; | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 6 | |||||||||||||||||||
| 7 | =head1 NAME | ||||||||||||||||||
| 8 | |||||||||||||||||||
| 9 | Filter::LiterateComments - Haskell-style literate comments | ||||||||||||||||||
| 10 | |||||||||||||||||||
| 11 | =head1 VERSION | ||||||||||||||||||
| 12 | |||||||||||||||||||
| 13 | This document describes version 0.01 of Filter::LiterateComments, | ||||||||||||||||||
| 14 | released November 4, 2004. | ||||||||||||||||||
| 15 | |||||||||||||||||||
| 16 | =head1 SYNOPSIS | ||||||||||||||||||
| 17 | |||||||||||||||||||
| 18 | use Filter::LiterateComments; | ||||||||||||||||||
| 19 | |||||||||||||||||||
| 20 | This literate program prompts the user for a number and prints | ||||||||||||||||||
| 21 | the factorial of that number: | ||||||||||||||||||
| 22 | |||||||||||||||||||
| 23 | > print "Enter a number: "; | ||||||||||||||||||
| 24 | > chomp( my $l = <STDIN> ); | ||||||||||||||||||
| 25 | > print "n! = ", fact( $l ), $/; | ||||||||||||||||||
| 26 | |||||||||||||||||||
| 27 | This is the factorial function, using a recursive definition: | ||||||||||||||||||
| 28 | |||||||||||||||||||
| 29 | > sub fact ($) { | ||||||||||||||||||
| 30 | > $_[0] ? ( $_[0] * fact( $_[0]-1 ) ) : 1; | ||||||||||||||||||
| 31 | > } | ||||||||||||||||||
| 32 | |||||||||||||||||||
| 33 | =head1 DESCRIPTION | ||||||||||||||||||
| 34 | |||||||||||||||||||
| 35 | This module supports two modes of literate comments, both taken from | ||||||||||||||||||
| 36 | the literate Haskell (F<.lhs>) format, with the I<TeX Mode> replaced with | ||||||||||||||||||
| 37 | a similar I<POD Mode>. | ||||||||||||||||||
| 38 | |||||||||||||||||||
| 39 | The relevant documentation from the Haskell 98 Report is reproduced below. | ||||||||||||||||||
| 40 | |||||||||||||||||||
| 41 | =head2 Quoted Mode | ||||||||||||||||||
| 42 | |||||||||||||||||||
| 43 | The I<literate comment> convention, first developed by Richard Bird and Philip | ||||||||||||||||||
| 44 | Wadler for Orwell, and inspired in turn by Donald Knuth's I<literate | ||||||||||||||||||
| 45 | programming>, is an alternative style for encoding Haskell source code. | ||||||||||||||||||
| 46 | |||||||||||||||||||
| 47 | The literate style encourages comments by making them the default. A line in | ||||||||||||||||||
| 48 | which C<< > >> is the first character is treated as part of the program; all | ||||||||||||||||||
| 49 | other lines are comment. | ||||||||||||||||||
| 50 | |||||||||||||||||||
| 51 | The program text is recovered by taking only those lines beginning with | ||||||||||||||||||
| 52 | C<< > >>, and replacing the leading C<< > >> with a space. | ||||||||||||||||||
| 53 | |||||||||||||||||||
| 54 | =head2 POD Mode | ||||||||||||||||||
| 55 | |||||||||||||||||||
| 56 | An alternative style of literate programming is particularly suitable for use | ||||||||||||||||||
| 57 | with POD (Plain Old Documentation) tools. In this convention, only those parts | ||||||||||||||||||
| 58 | of the literate program that are entirely enclosed between C<=begin code> ... | ||||||||||||||||||
| 59 | C<=end code> delimiters are treated as program text; all other lines are | ||||||||||||||||||
| 60 | comment. | ||||||||||||||||||
| 61 | |||||||||||||||||||
| 62 | More precisely: | ||||||||||||||||||
| 63 | |||||||||||||||||||
| 64 | =over 4 | ||||||||||||||||||
| 65 | |||||||||||||||||||
| 66 | =item * | ||||||||||||||||||
| 67 | |||||||||||||||||||
| 68 | Program code begins on the first line following a line that starts | ||||||||||||||||||
| 69 | with C<=begin code>. | ||||||||||||||||||
| 70 | |||||||||||||||||||
| 71 | =item * | ||||||||||||||||||
| 72 | |||||||||||||||||||
| 73 | Program code ends just before a subsequent line that starts with | ||||||||||||||||||
| 74 | C<=end code>. | ||||||||||||||||||
| 75 | |||||||||||||||||||
| 76 | =back | ||||||||||||||||||
| 77 | |||||||||||||||||||
| 78 | It is not necessary to insert additional blank lines before or after these | ||||||||||||||||||
| 79 | delimiters, though it may be stylistically desirable. | ||||||||||||||||||
| 80 | |||||||||||||||||||
| 81 | With POD mode, the program in the L</SYNOPSIS> will look like this: | ||||||||||||||||||
| 82 | |||||||||||||||||||
| 83 | use Filter::LiterateComments; | ||||||||||||||||||
| 84 | |||||||||||||||||||
| 85 | This literate program prompts the user for a number and prints | ||||||||||||||||||
| 86 | the factorial of that number: | ||||||||||||||||||
| 87 | |||||||||||||||||||
| 88 | =begin code | ||||||||||||||||||
| 89 | |||||||||||||||||||
| 90 | print "Enter a number: "; | ||||||||||||||||||
| 91 | chomp( my $l = <STDIN> ); | ||||||||||||||||||
| 92 | print "n! = ", fact( $l ), $/; | ||||||||||||||||||
| 93 | |||||||||||||||||||
| 94 | =end code | ||||||||||||||||||
| 95 | |||||||||||||||||||
| 96 | This is the factorial function, using a recursive definition: | ||||||||||||||||||
| 97 | |||||||||||||||||||
| 98 | =begin code | ||||||||||||||||||
| 99 | |||||||||||||||||||
| 100 | sub fact ($) { | ||||||||||||||||||
| 101 | $_[0] ? ( $_[0] * fact( $_[0]-1 ) ) : 1; | ||||||||||||||||||
| 102 | } | ||||||||||||||||||
| 103 | |||||||||||||||||||
| 104 | =end code | ||||||||||||||||||
| 105 | |||||||||||||||||||
| 106 | =cut | ||||||||||||||||||
| 107 | |||||||||||||||||||
| 108 | 2 | ▶ | sub lperl_to_perl { | ||||||||||||||||
|
Subroutine
lperl_to_perl: called CC=3 SCAR=11.0
Pod
undocumented
| |||||||||||||||||||
| 109 | 2 | ▶ | if ( s{^=begin\s+code\s*$}{=cut\n}mg ) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 110 | # POD mode | ||||||||||||||||||
| 111 | 1 | s{^=end\s+code\s*$}{=pod\n}mg; | |||||||||||||||||
| 112 | } | ||||||||||||||||||
| 113 | else { | ||||||||||||||||||
| 114 | # Quoted mode | ||||||||||||||||||
| 115 | 1 | ▶ | s{^(> )?}{$1 ? '' : '# '}meg; | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 116 | } | ||||||||||||||||||
| 117 | } | ||||||||||||||||||
| 118 | |||||||||||||||||||
| 119 | 0 | ▶ | sub lperl_to_pod { | ||||||||||||||||
|
Subroutine
lperl_to_pod: not called CC=4 SCAR=30.0
Pod
undocumented
| |||||||||||||||||||
| 120 | 0 | my $in_code = 1; | |||||||||||||||||
| 121 | |||||||||||||||||||
| 122 | 0 | s[^(> )?][ scalar ( | |||||||||||||||||
| 123 | 0 | ▶ | ($1) ? $in_code ? '' | ||||||||||||||||
|
Branch: 3 branches
| |||||||||||||||||||
| 124 | : (($in_code = 1), "=cut\n\n") | ||||||||||||||||||
| 125 | : $in_code ? (($in_code = 0), "\n=pod\n") | ||||||||||||||||||
| 126 | : '' | ||||||||||||||||||
| 127 | ) ]meg; | ||||||||||||||||||
| 128 | } | ||||||||||||||||||
| 129 | |||||||||||||||||||
| 130 | 0 | ▶ | sub perl_to_lperl { | ||||||||||||||||
|
Subroutine
perl_to_lperl: not called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||
| 131 | # XXX TODO | ||||||||||||||||||
| 132 | } | ||||||||||||||||||
| 133 | |||||||||||||||||||
| 134 | 0 | ▶ | sub pod_to_lperl { | ||||||||||||||||
|
Subroutine
pod_to_lperl: not called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||
| 135 | # XXX TODO | ||||||||||||||||||
| 136 | } | ||||||||||||||||||
| 137 | |||||||||||||||||||
| 138 | 2 | 1; | |||||||||||||||||
| 139 | |||||||||||||||||||
| 140 | =head1 SEE ALSO | ||||||||||||||||||
| 141 | |||||||||||||||||||
| 142 | The Vim syntax file F<eg/lperl.vim> in this module's source distribution. | ||||||||||||||||||
| 143 | |||||||||||||||||||
| 144 | The Haskell 98 Report: L<http://haskell.org/definition> -- see section | ||||||||||||||||||
| 145 | 9.6, I<literate comments>. | ||||||||||||||||||
| 146 | |||||||||||||||||||
| 147 | =head1 AUTHORS | ||||||||||||||||||
| 148 | |||||||||||||||||||
| 149 | Autrijus Tang E<lt>autrijus@autrijus.orgE<gt> | ||||||||||||||||||
| 150 | |||||||||||||||||||
| 151 | =head1 COPYRIGHT | ||||||||||||||||||
| 152 | |||||||||||||||||||
| 153 | Copyright 2004 by Autrijus Tang E<lt>autrijus@autrijus.orgE<gt>. | ||||||||||||||||||
| 154 | |||||||||||||||||||
| 155 | This program is free software; you can redistribute it and/or modify it | ||||||||||||||||||
| 156 | under the same terms as Perl itself. | ||||||||||||||||||
| 157 | |||||||||||||||||||
| 158 | See L<http://www.perl.com/perl/misc/Artistic.html> | ||||||||||||||||||
| 159 | |||||||||||||||||||
| 160 | =cut | ||||||||||||||||||