blib/lib/Filter/LiterateComments.pm

filter: Statementstmt 80.0% 12 / 15 Branchbran 40.0% 4 / 10 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 50.0% 3 / 6 Podpod 0.0% 0 / 4 totaltotal 54.2% 19 / 35 CC 6 SCAR 21.3
CC
6
Cov
64%
lperl_to_pod
20.0
lperl_to_perl
3.0
BEGIN
1.0
CRAP 8.5
↑ Summary
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
BranchTrueFalseTotal
if (s/^=begin\s+code\s*$/=cut\n/gm) { } 1 1 2
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
BranchTrueFalseTotal
$1 ? : 4 12 16
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
BranchTrueFalseTotal
$1 ? : 0 0 0
$in_code ? : 0 0 0
$in_code ? : 0 0 0
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
↑ Summary