| 1 | package App::Test::Generator::PodExampleExtractor; | ||||||||||||||||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||||||||||||||||
| 3 | 9 | ▶ | use 5.036; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 4 | 9 | ▶ | use Carp qw(croak); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 5 | 9 | ▶ | use File::Slurp qw(read_file); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 6 | 9 | ▶ | use Readonly; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||||||||||||||||
| 8 | 9 | our $VERSION = '0.49'; | |||||||||||||||||||||||||||||||||||||||||
| 9 | |||||||||||||||||||||||||||||||||||||||||||
| 10 | 9 | Readonly my $ANNOTATION_RE => qr/\#\s*(?:=>|returns?)\s*(.+?)\s*$/; | |||||||||||||||||||||||||||||||||||||||||
| 11 | 9 | Readonly my $VERBATIM_RE => qr/^[ \t]/; | |||||||||||||||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||||||||||||||||
| 13 | =encoding utf8 | ||||||||||||||||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||||||||||||||||
| 15 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||||||||||||||||
| 17 | App::Test::Generator::PodExampleExtractor - Extract runnable code examples from a Perl module's POD | ||||||||||||||||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||||||||||||||||
| 19 | =head1 VERSION | ||||||||||||||||||||||||||||||||||||||||||
| 20 | |||||||||||||||||||||||||||||||||||||||||||
| 21 | Version 0.49 | ||||||||||||||||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||||||||||||||||
| 23 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||||||||||||||||
| 25 | Pattern 1: list every example found in a module. | ||||||||||||||||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||||||||||||||||
| 27 | use App::Test::Generator::PodExampleExtractor; | ||||||||||||||||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||||||||||||||||
| 29 | my $ex = App::Test::Generator::PodExampleExtractor->new( | ||||||||||||||||||||||||||||||||||||||||||
| 30 | file => 'lib/My/Module.pm', | ||||||||||||||||||||||||||||||||||||||||||
| 31 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 32 | my $examples = $ex->extract(); | ||||||||||||||||||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||||||||||||||||
| 34 | for my $e (@$examples) { | ||||||||||||||||||||||||||||||||||||||||||
| 35 | printf "%-30s %s\n", $e->{label}, $e->{code}; | ||||||||||||||||||||||||||||||||||||||||||
| 36 | } | ||||||||||||||||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||||||||||||||||
| 38 | Pattern 2: keep only the examples that say what they return. | ||||||||||||||||||||||||||||||||||||||||||
| 39 | These are the ones that can be checked automatically. | ||||||||||||||||||||||||||||||||||||||||||
| 40 | |||||||||||||||||||||||||||||||||||||||||||
| 41 | my @checkable = grep { defined $_->{expected} } @{ $ex->extract() }; | ||||||||||||||||||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||||||||||||||||
| 43 | for my $e (@checkable) { | ||||||||||||||||||||||||||||||||||||||||||
| 44 | print "Run: $e->{annotated_line}\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 45 | print "Expect: $e->{expected}\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 46 | } | ||||||||||||||||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||||||||||||||||
| 48 | Pattern 3: count the examples in each documentation section. | ||||||||||||||||||||||||||||||||||||||||||
| 49 | |||||||||||||||||||||||||||||||||||||||||||
| 50 | my %count; | ||||||||||||||||||||||||||||||||||||||||||
| 51 | $count{ $_->{section} }++ for @{ $ex->extract() }; | ||||||||||||||||||||||||||||||||||||||||||
| 52 | printf "%-20s %d\n", $_, $count{$_} for sort keys %count; | ||||||||||||||||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||||||||||||||||
| 54 | Pattern 4: handle a missing file without stopping the program. | ||||||||||||||||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||||||||||||||||
| 56 | my $ex2 = eval { | ||||||||||||||||||||||||||||||||||||||||||
| 57 | App::Test::Generator::PodExampleExtractor->new(file => $path); | ||||||||||||||||||||||||||||||||||||||||||
| 58 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 59 | warn "Skipping $path: $@" unless $ex2; | ||||||||||||||||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||||||||||||||||
| 61 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||||||||||||||||
| 63 | Parses the POD of a Perl module and returns a structured list of | ||||||||||||||||||||||||||||||||||||||||||
| 64 | runnable code examples. Three sources are collected: | ||||||||||||||||||||||||||||||||||||||||||
| 65 | |||||||||||||||||||||||||||||||||||||||||||
| 66 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||||||||||||||||
| 68 | =item * Verbatim blocks inside C<=head1 SYNOPSIS> and C<=head2 SYNOPSIS> | ||||||||||||||||||||||||||||||||||||||||||
| 69 | |||||||||||||||||||||||||||||||||||||||||||
| 70 | =item * C<=for example begin> ... C<=for example end> blocks | ||||||||||||||||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||||||||||||||||
| 72 | =item * Annotated single-line call examples inside per-method docstrings | ||||||||||||||||||||||||||||||||||||||||||
| 73 | (lines matching C<$obj-E<gt>method(...) # returns value> or | ||||||||||||||||||||||||||||||||||||||||||
| 74 | C<method(...) # => value>) | ||||||||||||||||||||||||||||||||||||||||||
| 75 | |||||||||||||||||||||||||||||||||||||||||||
| 76 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||||||||||||||||
| 78 | Return-value annotations of the form C<# returns value> or C<< # => value >> | ||||||||||||||||||||||||||||||||||||||||||
| 79 | are parsed and exposed as C<expected> in the result hashref, enabling | ||||||||||||||||||||||||||||||||||||||||||
| 80 | downstream test generators to emit C<is()> assertions. | ||||||||||||||||||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||||||||||||||||
| 82 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||||||||||||||||
| 84 | Construct a new extractor for the given source file. | ||||||||||||||||||||||||||||||||||||||||||
| 85 | |||||||||||||||||||||||||||||||||||||||||||
| 86 | my $ex = App::Test::Generator::PodExampleExtractor->new( | ||||||||||||||||||||||||||||||||||||||||||
| 87 | file => 'lib/My/Module.pm', | ||||||||||||||||||||||||||||||||||||||||||
| 88 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 89 | |||||||||||||||||||||||||||||||||||||||||||
| 90 | =head3 Arguments | ||||||||||||||||||||||||||||||||||||||||||
| 91 | |||||||||||||||||||||||||||||||||||||||||||
| 92 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||||||||||||||||||
| 94 | =item * C<file> | ||||||||||||||||||||||||||||||||||||||||||
| 95 | |||||||||||||||||||||||||||||||||||||||||||
| 96 | Path to the Perl module to extract examples from. Required. | ||||||||||||||||||||||||||||||||||||||||||
| 97 | The file must exist on disk. | ||||||||||||||||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||||||||||||||||
| 99 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||||||||||||||||
| 101 | =head3 Returns | ||||||||||||||||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||||||||||||||||
| 103 | A blessed C<App::Test::Generator::PodExampleExtractor> object. | ||||||||||||||||||||||||||||||||||||||||||
| 104 | Croaks if C<file> is missing or does not exist. | ||||||||||||||||||||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||||||||||||||||||
| 106 | The file is not opened by C<new>. It is read each time you call C<extract>. | ||||||||||||||||||||||||||||||||||||||||||
| 107 | |||||||||||||||||||||||||||||||||||||||||||
| 108 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||||||||||||||||||||
| 110 | use App::Test::Generator::PodExampleExtractor; | ||||||||||||||||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||||||||||||||||
| 112 | my $ex = App::Test::Generator::PodExampleExtractor->new( | ||||||||||||||||||||||||||||||||||||||||||
| 113 | file => 'lib/Acme/Widget.pm', | ||||||||||||||||||||||||||||||||||||||||||
| 114 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 115 | printf "Extracting examples from %s\n", 'lib/Acme/Widget.pm'; | ||||||||||||||||||||||||||||||||||||||||||
| 116 | |||||||||||||||||||||||||||||||||||||||||||
| 117 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||
| 118 | |||||||||||||||||||||||||||||||||||||||||||
| 119 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||||||||||||||||
| 121 | =item C<file is required> | ||||||||||||||||||||||||||||||||||||||||||
| 122 | |||||||||||||||||||||||||||||||||||||||||||
| 123 | C<file> was not supplied. | ||||||||||||||||||||||||||||||||||||||||||
| 124 | |||||||||||||||||||||||||||||||||||||||||||
| 125 | =item C<File not found: $path> | ||||||||||||||||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||||||||||||||||
| 127 | C<file> was supplied but the path does not exist on disk. | ||||||||||||||||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||||||||||||||||
| 129 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||||||||||||||||
| 131 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||
| 132 | |||||||||||||||||||||||||||||||||||||||||||
| 133 | =head4 input | ||||||||||||||||||||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||||||||||||||||||||
| 135 | { file => { type => SCALAR } } | ||||||||||||||||||||||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||||||||||||||||||||
| 137 | =head4 output | ||||||||||||||||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||||||||||||||||
| 139 | { type => OBJECT, isa => 'App::Test::Generator::PodExampleExtractor' } | ||||||||||||||||||||||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||||||||||||||||||||
| 141 | The mathematical description is in L</FORMAL SPECIFICATION>. | ||||||||||||||||||||||||||||||||||||||||||
| 142 | |||||||||||||||||||||||||||||||||||||||||||
| 143 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 144 | |||||||||||||||||||||||||||||||||||||||||||
| 145 | 75 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 146 | 75 | my ($class, %args) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 147 | 75 | ▶ | croak 'file is required' unless defined $args{file}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 148 | 70 | ▶ | croak "File not found: $args{file}" unless -f $args{file}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 149 | 64 | return bless { file => $args{file} }, $class; | |||||||||||||||||||||||||||||||||||||||||
| 150 | } | ||||||||||||||||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||||||||||||||||
| 152 | =head2 extract | ||||||||||||||||||||||||||||||||||||||||||
| 153 | |||||||||||||||||||||||||||||||||||||||||||
| 154 | Extract all runnable examples from the module's POD. | ||||||||||||||||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||||||||||||||||
| 156 | my $examples = $ex->extract(); | ||||||||||||||||||||||||||||||||||||||||||
| 157 | |||||||||||||||||||||||||||||||||||||||||||
| 158 | =head3 Arguments | ||||||||||||||||||||||||||||||||||||||||||
| 159 | |||||||||||||||||||||||||||||||||||||||||||
| 160 | None beyond C<$self>. | ||||||||||||||||||||||||||||||||||||||||||
| 161 | |||||||||||||||||||||||||||||||||||||||||||
| 162 | =head3 Returns | ||||||||||||||||||||||||||||||||||||||||||
| 163 | |||||||||||||||||||||||||||||||||||||||||||
| 164 | An arrayref of example hashrefs, deduplicated by C<code> text. Each hashref | ||||||||||||||||||||||||||||||||||||||||||
| 165 | has the following keys: | ||||||||||||||||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||||||||||||||||
| 167 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||||||||||||||||
| 169 | =item * C<label> - human-readable name for use as a test label (e.g. C<"SYNOPSIS example 1">) | ||||||||||||||||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||||||||||||||||
| 171 | =item * C<section> - the POD section heading (C<=head1>/C<=head2> text) where the example was found | ||||||||||||||||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||||||||||||||||
| 173 | =item * C<code> - the raw code text, dedented. May be multi-line for verbatim blocks. | ||||||||||||||||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||||||||||||||||
| 175 | =item * C<expected> - the expected return value string from a C<# returns value> or C<< # => value >> annotation; C<undef> if not annotated. | ||||||||||||||||||||||||||||||||||||||||||
| 176 | |||||||||||||||||||||||||||||||||||||||||||
| 177 | =item * C<annotated_line> - for annotated single-line examples, the bare expression with the annotation stripped; C<undef> for verbatim blocks. | ||||||||||||||||||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||||||||||||||||||
| 179 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 180 | |||||||||||||||||||||||||||||||||||||||||||
| 181 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||
| 182 | |||||||||||||||||||||||||||||||||||||||||||
| 183 | my $examples = $ex->extract(); | ||||||||||||||||||||||||||||||||||||||||||
| 184 | for my $e (@{$examples}) { | ||||||||||||||||||||||||||||||||||||||||||
| 185 | printf "[%s] %s\n", $e->{label}, $e->{code}; | ||||||||||||||||||||||||||||||||||||||||||
| 186 | if(defined $e->{expected}) { | ||||||||||||||||||||||||||||||||||||||||||
| 187 | printf " expects: %s\n", $e->{expected}; | ||||||||||||||||||||||||||||||||||||||||||
| 188 | } | ||||||||||||||||||||||||||||||||||||||||||
| 189 | } | ||||||||||||||||||||||||||||||||||||||||||
| 190 | |||||||||||||||||||||||||||||||||||||||||||
| 191 | # Count examples without a declared return value | ||||||||||||||||||||||||||||||||||||||||||
| 192 | my @unannotated = grep { !defined $_->{expected} } @{$examples}; | ||||||||||||||||||||||||||||||||||||||||||
| 193 | printf "%d unannotated examples\n", scalar @unannotated; | ||||||||||||||||||||||||||||||||||||||||||
| 194 | |||||||||||||||||||||||||||||||||||||||||||
| 195 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||||||||||||||||
| 197 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||||||||||||||||
| 199 | =item C<read_file 'PATH' - ...> (raised by C<File::Slurp::read_file>) | ||||||||||||||||||||||||||||||||||||||||||
| 200 | |||||||||||||||||||||||||||||||||||||||||||
| 201 | The source file was removed, or became unreadable, between the call to | ||||||||||||||||||||||||||||||||||||||||||
| 202 | C<new> and the call to C<extract>. The rest of the message is the reason | ||||||||||||||||||||||||||||||||||||||||||
| 203 | given by the operating system. | ||||||||||||||||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||||||||||||||||
| 205 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||||||||||||||||||
| 207 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||||||||||||||||
| 209 | =head4 input | ||||||||||||||||||||||||||||||||||||||||||
| 210 | |||||||||||||||||||||||||||||||||||||||||||
| 211 | { self => { type => OBJECT, isa => 'App::Test::Generator::PodExampleExtractor' } } | ||||||||||||||||||||||||||||||||||||||||||
| 212 | |||||||||||||||||||||||||||||||||||||||||||
| 213 | =head4 output | ||||||||||||||||||||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||||||||||||||||||||
| 215 | { type => ARRAYREF } | ||||||||||||||||||||||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||||||||||||||||||||
| 217 | The mathematical description is in L</FORMAL SPECIFICATION>. | ||||||||||||||||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||||||||||||||||
| 219 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||||||||||||||||
| 221 | 61 | ▶ | sub extract { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
extract: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 222 | 61 | my $self = $_[0]; | |||||||||||||||||||||||||||||||||||||||||
| 223 | |||||||||||||||||||||||||||||||||||||||||||
| 224 | 61 | my $text = read_file($self->{file}, err_mode => 'croak'); | |||||||||||||||||||||||||||||||||||||||||
| 225 | |||||||||||||||||||||||||||||||||||||||||||
| 226 | 61 | my @raw; | |||||||||||||||||||||||||||||||||||||||||
| 227 | 61 | push @raw, _extract_synopsis_blocks($text); | |||||||||||||||||||||||||||||||||||||||||
| 228 | 61 | push @raw, _extract_for_example_blocks($text); | |||||||||||||||||||||||||||||||||||||||||
| 229 | 61 | push @raw, _extract_annotated_lines($text); | |||||||||||||||||||||||||||||||||||||||||
| 230 | |||||||||||||||||||||||||||||||||||||||||||
| 231 | # deduplicate by code text | ||||||||||||||||||||||||||||||||||||||||||
| 232 | 61 | my %seen; | |||||||||||||||||||||||||||||||||||||||||
| 233 | 61 | my @unique = grep { !$seen{ $_->{code} }++ } @raw; | |||||||||||||||||||||||||||||||||||||||||
| 234 | |||||||||||||||||||||||||||||||||||||||||||
| 235 | # assign numbered labels within each section | ||||||||||||||||||||||||||||||||||||||||||
| 236 | 61 | my %section_count; | |||||||||||||||||||||||||||||||||||||||||
| 237 | 61 | for my $e (@unique) { | |||||||||||||||||||||||||||||||||||||||||
| 238 | 96 | my $n = ++$section_count{ $e->{section} }; | |||||||||||||||||||||||||||||||||||||||||
| 239 | 96 | $e->{label} = "$e->{section} example $n"; | |||||||||||||||||||||||||||||||||||||||||
| 240 | } | ||||||||||||||||||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||||||||||||||||||
| 242 | 61 | return \@unique; | |||||||||||||||||||||||||||||||||||||||||
| 243 | } | ||||||||||||||||||||||||||||||||||||||||||
| 244 | |||||||||||||||||||||||||||||||||||||||||||
| 245 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 246 | # _extract_synopsis_blocks | ||||||||||||||||||||||||||||||||||||||||||
| 247 | # | ||||||||||||||||||||||||||||||||||||||||||
| 248 | # Purpose: Extract verbatim (indented) paragraphs from | ||||||||||||||||||||||||||||||||||||||||||
| 249 | # =head1 SYNOPSIS and =head2 SYNOPSIS sections. | ||||||||||||||||||||||||||||||||||||||||||
| 250 | # | ||||||||||||||||||||||||||||||||||||||||||
| 251 | # Entry: $text - full module source including POD | ||||||||||||||||||||||||||||||||||||||||||
| 252 | # | ||||||||||||||||||||||||||||||||||||||||||
| 253 | # Exit: Returns a list of example hashrefs. | ||||||||||||||||||||||||||||||||||||||||||
| 254 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 255 | 61 | ▶ | sub _extract_synopsis_blocks { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_extract_synopsis_blocks: called CC=2 SCAR=6.9
| |||||||||||||||||||||||||||||||||||||||||||
| 256 | 61 | my $text = $_[0]; | |||||||||||||||||||||||||||||||||||||||||
| 257 | |||||||||||||||||||||||||||||||||||||||||||
| 258 | 61 | my @examples; | |||||||||||||||||||||||||||||||||||||||||
| 259 | 61 | ▶ | while($text =~ /=head[12]\s+SYNOPSIS\s*\n(.*?)(?=\n=head|\n=cut|\z)/sg) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 260 | 31 | my $block = $1; | |||||||||||||||||||||||||||||||||||||||||
| 261 | 31 | push @examples, _verbatim_paragraphs($block, 'SYNOPSIS'); | |||||||||||||||||||||||||||||||||||||||||
| 262 | } | ||||||||||||||||||||||||||||||||||||||||||
| 263 | 61 | return @examples; | |||||||||||||||||||||||||||||||||||||||||
| 264 | } | ||||||||||||||||||||||||||||||||||||||||||
| 265 | |||||||||||||||||||||||||||||||||||||||||||
| 266 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 267 | # _extract_for_example_blocks | ||||||||||||||||||||||||||||||||||||||||||
| 268 | # | ||||||||||||||||||||||||||||||||||||||||||
| 269 | # Purpose: Extract code inside =for example begin / =for example end pairs. | ||||||||||||||||||||||||||||||||||||||||||
| 270 | # | ||||||||||||||||||||||||||||||||||||||||||
| 271 | # Entry: $text - full module source including POD | ||||||||||||||||||||||||||||||||||||||||||
| 272 | # | ||||||||||||||||||||||||||||||||||||||||||
| 273 | # Exit: Returns a list of example hashrefs. | ||||||||||||||||||||||||||||||||||||||||||
| 274 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 275 | 61 | ▶ | sub _extract_for_example_blocks { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_extract_for_example_blocks: called CC=2 SCAR=6.9
| |||||||||||||||||||||||||||||||||||||||||||
| 276 | 61 | my $text = $_[0]; | |||||||||||||||||||||||||||||||||||||||||
| 277 | |||||||||||||||||||||||||||||||||||||||||||
| 278 | 61 | my @examples; | |||||||||||||||||||||||||||||||||||||||||
| 279 | 61 | my $n = 0; | |||||||||||||||||||||||||||||||||||||||||
| 280 | 61 | ▶ | while($text =~ /=for\s+example\s+begin\s*\n(.*?)=for\s+example\s+end/sg) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 281 | 4 | my $block = $1; | |||||||||||||||||||||||||||||||||||||||||
| 282 | 4 | push @examples, _verbatim_paragraphs($block, '=for example ' . ++$n); | |||||||||||||||||||||||||||||||||||||||||
| 283 | } | ||||||||||||||||||||||||||||||||||||||||||
| 284 | 61 | return @examples; | |||||||||||||||||||||||||||||||||||||||||
| 285 | } | ||||||||||||||||||||||||||||||||||||||||||
| 286 | |||||||||||||||||||||||||||||||||||||||||||
| 287 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 288 | # _extract_annotated_lines | ||||||||||||||||||||||||||||||||||||||||||
| 289 | # | ||||||||||||||||||||||||||||||||||||||||||
| 290 | # Purpose: Find individual lines inside per-method docstrings that | ||||||||||||||||||||||||||||||||||||||||||
| 291 | # carry a # returns / # => annotation. These are single- | ||||||||||||||||||||||||||||||||||||||||||
| 292 | # call examples where the expected value is documented inline. | ||||||||||||||||||||||||||||||||||||||||||
| 293 | # | ||||||||||||||||||||||||||||||||||||||||||
| 294 | # Entry: $text - full module source including POD | ||||||||||||||||||||||||||||||||||||||||||
| 295 | # | ||||||||||||||||||||||||||||||||||||||||||
| 296 | # Exit: Returns a list of example hashrefs (each wrapping the | ||||||||||||||||||||||||||||||||||||||||||
| 297 | # annotated line plus the leading context, if any). | ||||||||||||||||||||||||||||||||||||||||||
| 298 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 299 | 61 | ▶ | sub _extract_annotated_lines { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_extract_annotated_lines: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||||||||||||||||
| 300 | 61 | my $text = $_[0]; | |||||||||||||||||||||||||||||||||||||||||
| 301 | |||||||||||||||||||||||||||||||||||||||||||
| 302 | 61 | my @examples; | |||||||||||||||||||||||||||||||||||||||||
| 303 | 61 | my $section = 'UNKNOWN'; | |||||||||||||||||||||||||||||||||||||||||
| 304 | |||||||||||||||||||||||||||||||||||||||||||
| 305 | 61 | for my $line (split /\n/, $text) { | |||||||||||||||||||||||||||||||||||||||||
| 306 | # Track current POD section heading | ||||||||||||||||||||||||||||||||||||||||||
| 307 | 34442 | ▶ | if($line =~ /^=head\d+\s+(.+)/) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 308 | 1165 | $section = $1; | |||||||||||||||||||||||||||||||||||||||||
| 309 | 1165 | $section =~ s/\s+$//; | |||||||||||||||||||||||||||||||||||||||||
| 310 | 1165 | next; | |||||||||||||||||||||||||||||||||||||||||
| 311 | } | ||||||||||||||||||||||||||||||||||||||||||
| 312 | |||||||||||||||||||||||||||||||||||||||||||
| 313 | # Annotated verbatim line inside POD | ||||||||||||||||||||||||||||||||||||||||||
| 314 | 33277 | ▶ | next unless $line =~ $VERBATIM_RE; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 315 | 16801 | ▶ | next unless $line =~ $ANNOTATION_RE; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 316 | |||||||||||||||||||||||||||||||||||||||||||
| 317 | 41 | my $expected = $1; | |||||||||||||||||||||||||||||||||||||||||
| 318 | 41 | $expected =~ s/\s+$//; | |||||||||||||||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||||||||||||||||
| 320 | # Strip leading whitespace from code text | ||||||||||||||||||||||||||||||||||||||||||
| 321 | 41 | (my $code = $line) =~ s/^[ \t]+//; | |||||||||||||||||||||||||||||||||||||||||
| 322 | |||||||||||||||||||||||||||||||||||||||||||
| 323 | # Strip the annotation comment from the code | ||||||||||||||||||||||||||||||||||||||||||
| 324 | 41 | (my $code_only = $code) =~ s/\s*\#\s*(?:=>|returns?)\s*.+$//; | |||||||||||||||||||||||||||||||||||||||||
| 325 | 41 | $code_only =~ s/\s+$//; | |||||||||||||||||||||||||||||||||||||||||
| 326 | |||||||||||||||||||||||||||||||||||||||||||
| 327 | 41 | ▶ | next unless length $code_only; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 328 | |||||||||||||||||||||||||||||||||||||||||||
| 329 | 25 | push @examples, { | |||||||||||||||||||||||||||||||||||||||||
| 330 | section => $section, | ||||||||||||||||||||||||||||||||||||||||||
| 331 | code => $code_only, | ||||||||||||||||||||||||||||||||||||||||||
| 332 | expected => $expected, | ||||||||||||||||||||||||||||||||||||||||||
| 333 | annotated_line => $code_only, | ||||||||||||||||||||||||||||||||||||||||||
| 334 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 335 | } | ||||||||||||||||||||||||||||||||||||||||||
| 336 | |||||||||||||||||||||||||||||||||||||||||||
| 337 | 61 | return @examples; | |||||||||||||||||||||||||||||||||||||||||
| 338 | } | ||||||||||||||||||||||||||||||||||||||||||
| 339 | |||||||||||||||||||||||||||||||||||||||||||
| 340 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 341 | # _verbatim_paragraphs | ||||||||||||||||||||||||||||||||||||||||||
| 342 | # | ||||||||||||||||||||||||||||||||||||||||||
| 343 | # Purpose: Split a POD text block into its indented | ||||||||||||||||||||||||||||||||||||||||||
| 344 | # (verbatim) paragraphs and return example hashrefs. | ||||||||||||||||||||||||||||||||||||||||||
| 345 | # Paragraphs that contain no Perl-looking syntax | ||||||||||||||||||||||||||||||||||||||||||
| 346 | # (e.g. shell commands like "prove -l t/foo.t") are | ||||||||||||||||||||||||||||||||||||||||||
| 347 | # silently dropped — they would cause compile errors | ||||||||||||||||||||||||||||||||||||||||||
| 348 | # under "use strict" in the generated test file. | ||||||||||||||||||||||||||||||||||||||||||
| 349 | # | ||||||||||||||||||||||||||||||||||||||||||
| 350 | # Entry: $block - text block to scan | ||||||||||||||||||||||||||||||||||||||||||
| 351 | # $section - label string for the containing section | ||||||||||||||||||||||||||||||||||||||||||
| 352 | # | ||||||||||||||||||||||||||||||||||||||||||
| 353 | # Exit: Returns a list of example hashrefs with no expected value. | ||||||||||||||||||||||||||||||||||||||||||
| 354 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 355 | 35 | ▶ | sub _verbatim_paragraphs { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_verbatim_paragraphs: called CC=11 SCAR=24.1
| |||||||||||||||||||||||||||||||||||||||||||
| 356 | 35 | my ($block, $section) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 357 | |||||||||||||||||||||||||||||||||||||||||||
| 358 | 35 | my @examples; | |||||||||||||||||||||||||||||||||||||||||
| 359 | my @current; | ||||||||||||||||||||||||||||||||||||||||||
| 360 | |||||||||||||||||||||||||||||||||||||||||||
| 361 | 35 | for my $line (split /\n/, $block) { | |||||||||||||||||||||||||||||||||||||||||
| 362 | 1360 | ▶ | if($line =~ $VERBATIM_RE || ($line =~ /\S/ && @current)) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%4/6
$line =~ /$VERBATIM_RE/u or $line =~ /\S/u and @current
$line =~ /\S/u and @current
MC/DC33%1/3
$line =~ /$VERBATIM_RE/u or $line =~ /\S/u and @current
$line =~ /$VERBATIM_RE/u
$line =~ /\S/u
@current
Truth table75%3/4
A or B and C
A= $line =~ /$VERBATIM_RE/uB= $line =~ /\S/uC= @current
| |||||||||||||||||||||||||||||||||||||||||||
| 363 | 1230 | push @current, $line; | |||||||||||||||||||||||||||||||||||||||||
| 364 | } else { | ||||||||||||||||||||||||||||||||||||||||||
| 365 | 130 | ▶ | if(@current) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 366 | 51 | my $code = _dedent(join("\n", @current)); | |||||||||||||||||||||||||||||||||||||||||
| 367 | 51 | ▶ | push @examples, { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
length $code and _looks_like_perl($code)
MC/DC50%1/2
length $code and _looks_like_perl($code)
length $code
_looks_like_perl($code)
Truth table66%2/3
A and B
A= length $codeB= _looks_like_perl($code)
| |||||||||||||||||||||||||||||||||||||||||||
| 368 | section => $section, | ||||||||||||||||||||||||||||||||||||||||||
| 369 | code => $code, | ||||||||||||||||||||||||||||||||||||||||||
| 370 | expected => undef, | ||||||||||||||||||||||||||||||||||||||||||
| 371 | annotated_line => undef, | ||||||||||||||||||||||||||||||||||||||||||
| 372 | } if length($code) && _looks_like_perl($code); | ||||||||||||||||||||||||||||||||||||||||||
| 373 | 51 | @current = (); | |||||||||||||||||||||||||||||||||||||||||
| 374 | } | ||||||||||||||||||||||||||||||||||||||||||
| 375 | } | ||||||||||||||||||||||||||||||||||||||||||
| 376 | } | ||||||||||||||||||||||||||||||||||||||||||
| 377 | |||||||||||||||||||||||||||||||||||||||||||
| 378 | 35 | ▶ | if(@current) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 379 | 33 | my $code = _dedent(join("\n", @current)); | |||||||||||||||||||||||||||||||||||||||||
| 380 | 33 | ▶ | push @examples, { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
length $code and _looks_like_perl($code)
MC/DC50%1/2
length $code and _looks_like_perl($code)
length $code
_looks_like_perl($code)
Truth table66%2/3
A and B
A= length $codeB= _looks_like_perl($code)
| |||||||||||||||||||||||||||||||||||||||||||
| 381 | section => $section, | ||||||||||||||||||||||||||||||||||||||||||
| 382 | code => $code, | ||||||||||||||||||||||||||||||||||||||||||
| 383 | expected => undef, | ||||||||||||||||||||||||||||||||||||||||||
| 384 | annotated_line => undef, | ||||||||||||||||||||||||||||||||||||||||||
| 385 | } if length($code) && _looks_like_perl($code); | ||||||||||||||||||||||||||||||||||||||||||
| 386 | } | ||||||||||||||||||||||||||||||||||||||||||
| 387 | |||||||||||||||||||||||||||||||||||||||||||
| 388 | 35 | return @examples; | |||||||||||||||||||||||||||||||||||||||||
| 389 | } | ||||||||||||||||||||||||||||||||||||||||||
| 390 | |||||||||||||||||||||||||||||||||||||||||||
| 391 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 392 | # _dedent | ||||||||||||||||||||||||||||||||||||||||||
| 393 | # | ||||||||||||||||||||||||||||||||||||||||||
| 394 | # Purpose: Remove the common leading whitespace from every line | ||||||||||||||||||||||||||||||||||||||||||
| 395 | # of a verbatim block so relative indentation is kept | ||||||||||||||||||||||||||||||||||||||||||
| 396 | # (like Python's textwrap.dedent). | ||||||||||||||||||||||||||||||||||||||||||
| 397 | # | ||||||||||||||||||||||||||||||||||||||||||
| 398 | # Entry: $text - multi-line string | ||||||||||||||||||||||||||||||||||||||||||
| 399 | # | ||||||||||||||||||||||||||||||||||||||||||
| 400 | # Exit: Returns the dedented string with trailing whitespace removed. | ||||||||||||||||||||||||||||||||||||||||||
| 401 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 402 | 84 | ▶ | sub _dedent { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_dedent: called CC=4 SCAR=13.9
| |||||||||||||||||||||||||||||||||||||||||||
| 403 | 84 | my $text = $_[0]; | |||||||||||||||||||||||||||||||||||||||||
| 404 | 84 | my @lines = split /\n/, $text; | |||||||||||||||||||||||||||||||||||||||||
| 405 | 84 | my @non_empty = grep { /\S/ } @lines; | |||||||||||||||||||||||||||||||||||||||||
| 406 | 84 | ▶ | return '' unless @non_empty; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 407 | 1283 | my ($min) = sort { $a <=> $b } | |||||||||||||||||||||||||||||||||||||||||
| 408 | 84 | ▶ | map { /^([ \t]*)/ ? length($1) : 0 } @non_empty; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 409 | 84 | s/^[ \t]{0,$min}// for @lines; | |||||||||||||||||||||||||||||||||||||||||
| 410 | 84 | my $out = join("\n", @lines); | |||||||||||||||||||||||||||||||||||||||||
| 411 | 84 | $out =~ s/\s+$//; | |||||||||||||||||||||||||||||||||||||||||
| 412 | 84 | return $out; | |||||||||||||||||||||||||||||||||||||||||
| 413 | } | ||||||||||||||||||||||||||||||||||||||||||
| 414 | |||||||||||||||||||||||||||||||||||||||||||
| 415 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 416 | # _looks_like_perl | ||||||||||||||||||||||||||||||||||||||||||
| 417 | # | ||||||||||||||||||||||||||||||||||||||||||
| 418 | # Purpose: Return true when a verbatim block contains at least one | ||||||||||||||||||||||||||||||||||||||||||
| 419 | # line that is recognisably Perl syntax. Used to skip | ||||||||||||||||||||||||||||||||||||||||||
| 420 | # blocks of shell commands (e.g. "prove -l t/foo.t") that | ||||||||||||||||||||||||||||||||||||||||||
| 421 | # would cause compile errors under "use strict". | ||||||||||||||||||||||||||||||||||||||||||
| 422 | # | ||||||||||||||||||||||||||||||||||||||||||
| 423 | # Entry: $code - dedented block text | ||||||||||||||||||||||||||||||||||||||||||
| 424 | # | ||||||||||||||||||||||||||||||||||||||||||
| 425 | # Exit: Returns 1 (Perl) or '' (not Perl). | ||||||||||||||||||||||||||||||||||||||||||
| 426 | # -------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 427 | 84 | ▶ | sub _looks_like_perl { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_looks_like_perl: called CC=8 SCAR=20.9
| |||||||||||||||||||||||||||||||||||||||||||
| 428 | 84 | my $code = $_[0]; | |||||||||||||||||||||||||||||||||||||||||
| 429 | 84 | for my $line (split /\n/, $code) { | |||||||||||||||||||||||||||||||||||||||||
| 430 | 100 | ▶ | next unless $line =~ /\S/; # skip blank lines | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 431 | 100 | ▶ | next if $line =~ /^\s*#/; # skip comment-only lines | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 432 | # Perl sigils | ||||||||||||||||||||||||||||||||||||||||||
| 433 | 85 | ▶ | return 1 if $line =~ /[\$\@\%]/; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 434 | # Perl keywords at start of statement | ||||||||||||||||||||||||||||||||||||||||||
| 435 | 32 | ▶ | return 1 if $line =~ /^\s*(?:my|our|local|use|require|no|package|sub|for(?:each)?|if|unless|while|until|return|die|croak|warn|print|say|eval|BEGIN|END|push|pop|shift|unshift|keys|values|grep|map|sort)\b/; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 436 | # Method call or package separator | ||||||||||||||||||||||||||||||||||||||||||
| 437 | 15 | ▶ | return 1 if $line =~ /(?:->|::)/; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 438 | # Fat comma — a hash or argument list | ||||||||||||||||||||||||||||||||||||||||||
| 439 | 12 | ▶ | return 1 if $line =~ /=>/; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 440 | } | ||||||||||||||||||||||||||||||||||||||||||
| 441 | 11 | return ''; | |||||||||||||||||||||||||||||||||||||||||
| 442 | } | ||||||||||||||||||||||||||||||||||||||||||
| 443 | |||||||||||||||||||||||||||||||||||||||||||
| 444 | =head1 COMMON PITFALLS | ||||||||||||||||||||||||||||||||||||||||||
| 445 | |||||||||||||||||||||||||||||||||||||||||||
| 446 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 447 | |||||||||||||||||||||||||||||||||||||||||||
| 448 | =item Shell-command blocks are silently dropped | ||||||||||||||||||||||||||||||||||||||||||
| 449 | |||||||||||||||||||||||||||||||||||||||||||
| 450 | Verbatim paragraphs that contain only shell commands (e.g. C<prove -l t/> or | ||||||||||||||||||||||||||||||||||||||||||
| 451 | C<extract-schemas lib/My/Module.pm>) are filtered out by C<_looks_like_perl>. | ||||||||||||||||||||||||||||||||||||||||||
| 452 | They would cause compile errors under C<use strict> in a generated test file. | ||||||||||||||||||||||||||||||||||||||||||
| 453 | If you want a shell command to appear as an example, put it in a POD comment | ||||||||||||||||||||||||||||||||||||||||||
| 454 | block, not a verbatim paragraph. | ||||||||||||||||||||||||||||||||||||||||||
| 455 | |||||||||||||||||||||||||||||||||||||||||||
| 456 | =item Annotations must be on the B<same line> as the call expression | ||||||||||||||||||||||||||||||||||||||||||
| 457 | |||||||||||||||||||||||||||||||||||||||||||
| 458 | The C<# returns> / C<< # => >> annotation is parsed as a line-level suffix. | ||||||||||||||||||||||||||||||||||||||||||
| 459 | Multi-line calls spread across multiple lines will not pick up an annotation on | ||||||||||||||||||||||||||||||||||||||||||
| 460 | the last line. Only the last line is examined, and the call expression on | ||||||||||||||||||||||||||||||||||||||||||
| 461 | earlier lines is lost. | ||||||||||||||||||||||||||||||||||||||||||
| 462 | |||||||||||||||||||||||||||||||||||||||||||
| 463 | =item C<expected> is always a raw string | ||||||||||||||||||||||||||||||||||||||||||
| 464 | |||||||||||||||||||||||||||||||||||||||||||
| 465 | The C<expected> field is the literal text captured after C<# returns> or | ||||||||||||||||||||||||||||||||||||||||||
| 466 | C<< # => >>. It is not evaluated or type-converted. Downstream code that | ||||||||||||||||||||||||||||||||||||||||||
| 467 | emits C<is($result, $expected)> must handle quoting appropriately. | ||||||||||||||||||||||||||||||||||||||||||
| 468 | |||||||||||||||||||||||||||||||||||||||||||
| 469 | =item SYNOPSIS blocks from C<=head3> and deeper are not collected | ||||||||||||||||||||||||||||||||||||||||||
| 470 | |||||||||||||||||||||||||||||||||||||||||||
| 471 | Only C<=head1 SYNOPSIS> and C<=head2 SYNOPSIS> sections are scanned for | ||||||||||||||||||||||||||||||||||||||||||
| 472 | verbatim blocks. Deeper heading levels are ignored. | ||||||||||||||||||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||||||||||||||||
| 474 | =item C<new> takes a list of pairs, not a hashref | ||||||||||||||||||||||||||||||||||||||||||
| 475 | |||||||||||||||||||||||||||||||||||||||||||
| 476 | Write C<< new(file => $path) >>. If you write C<< new({ file => $path }) >> | ||||||||||||||||||||||||||||||||||||||||||
| 477 | the file name is not seen, and C<new> croaks with C<file is required>. | ||||||||||||||||||||||||||||||||||||||||||
| 478 | Any argument other than C<file> is ignored without a warning. | ||||||||||||||||||||||||||||||||||||||||||
| 479 | |||||||||||||||||||||||||||||||||||||||||||
| 480 | =item How C<undef> is handled | ||||||||||||||||||||||||||||||||||||||||||
| 481 | |||||||||||||||||||||||||||||||||||||||||||
| 482 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 483 | |||||||||||||||||||||||||||||||||||||||||||
| 484 | =item * C<< file => undef >> makes C<new> croak with C<file is required>. | ||||||||||||||||||||||||||||||||||||||||||
| 485 | |||||||||||||||||||||||||||||||||||||||||||
| 486 | =item * C<expected> and C<annotated_line> are C<undef> for every example | ||||||||||||||||||||||||||||||||||||||||||
| 487 | that came from a whole block. Always test them with C<defined> before | ||||||||||||||||||||||||||||||||||||||||||
| 488 | you use them. | ||||||||||||||||||||||||||||||||||||||||||
| 489 | |||||||||||||||||||||||||||||||||||||||||||
| 490 | =item * C<label>, C<section> and C<code> are never C<undef>. | ||||||||||||||||||||||||||||||||||||||||||
| 491 | |||||||||||||||||||||||||||||||||||||||||||
| 492 | =item * A file with no examples gives an empty arrayref (C<[]>), never | ||||||||||||||||||||||||||||||||||||||||||
| 493 | C<undef>. | ||||||||||||||||||||||||||||||||||||||||||
| 494 | |||||||||||||||||||||||||||||||||||||||||||
| 495 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 496 | |||||||||||||||||||||||||||||||||||||||||||
| 497 | =item Annotated lines are searched for in the whole file, not only in POD | ||||||||||||||||||||||||||||||||||||||||||
| 498 | |||||||||||||||||||||||||||||||||||||||||||
| 499 | Every indented line of the file is checked for a C<# returns ...> or | ||||||||||||||||||||||||||||||||||||||||||
| 500 | C<< # => ... >> comment. This includes indented lines of ordinary Perl | ||||||||||||||||||||||||||||||||||||||||||
| 501 | code. A code line such as | ||||||||||||||||||||||||||||||||||||||||||
| 502 | |||||||||||||||||||||||||||||||||||||||||||
| 503 | return $total; # returns the sum | ||||||||||||||||||||||||||||||||||||||||||
| 504 | |||||||||||||||||||||||||||||||||||||||||||
| 505 | is reported as an example with C<expected> set to C<the sum>. The | ||||||||||||||||||||||||||||||||||||||||||
| 506 | C<section> of such an example is the last POD heading seen above it, or | ||||||||||||||||||||||||||||||||||||||||||
| 507 | C<UNKNOWN> if there was none. Use a different wording in code comments | ||||||||||||||||||||||||||||||||||||||||||
| 508 | if you do not want this. | ||||||||||||||||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||||||||||||||||
| 510 | =item An annotated line inside a block is reported twice | ||||||||||||||||||||||||||||||||||||||||||
| 511 | |||||||||||||||||||||||||||||||||||||||||||
| 512 | A line with an annotation that sits inside a SYNOPSIS block appears once | ||||||||||||||||||||||||||||||||||||||||||
| 513 | as part of the whole block and once more by itself. The two entries have | ||||||||||||||||||||||||||||||||||||||||||
| 514 | different C<code> text, so the duplicate check does not join them. | ||||||||||||||||||||||||||||||||||||||||||
| 515 | |||||||||||||||||||||||||||||||||||||||||||
| 516 | =item Each call to C<extract> reads the file again | ||||||||||||||||||||||||||||||||||||||||||
| 517 | |||||||||||||||||||||||||||||||||||||||||||
| 518 | The result is not stored in the object. Two calls give two separate | ||||||||||||||||||||||||||||||||||||||||||
| 519 | arrayrefs. Changing one result does not change the other. If the file | ||||||||||||||||||||||||||||||||||||||||||
| 520 | changed on disk between the calls, the results can be different. | ||||||||||||||||||||||||||||||||||||||||||
| 521 | |||||||||||||||||||||||||||||||||||||||||||
| 522 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 523 | |||||||||||||||||||||||||||||||||||||||||||
| 524 | =head1 ENCODING | ||||||||||||||||||||||||||||||||||||||||||
| 525 | |||||||||||||||||||||||||||||||||||||||||||
| 526 | The file is read as raw bytes. Nothing is decoded. | ||||||||||||||||||||||||||||||||||||||||||
| 527 | |||||||||||||||||||||||||||||||||||||||||||
| 528 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 529 | |||||||||||||||||||||||||||||||||||||||||||
| 530 | =item * The C<file> argument | ||||||||||||||||||||||||||||||||||||||||||
| 531 | |||||||||||||||||||||||||||||||||||||||||||
| 532 | The path is passed to the operating system unchanged. ASCII paths | ||||||||||||||||||||||||||||||||||||||||||
| 533 | always work. For a path with non-ASCII characters, pass it as bytes in | ||||||||||||||||||||||||||||||||||||||||||
| 534 | the encoding your file system uses (normally UTF-8). | ||||||||||||||||||||||||||||||||||||||||||
| 535 | |||||||||||||||||||||||||||||||||||||||||||
| 536 | =item * File contents | ||||||||||||||||||||||||||||||||||||||||||
| 537 | |||||||||||||||||||||||||||||||||||||||||||
| 538 | Any byte values are accepted. UTF-8 text, other non-ASCII text and | ||||||||||||||||||||||||||||||||||||||||||
| 539 | emojis do not cause errors and are not damaged. All the markers this | ||||||||||||||||||||||||||||||||||||||||||
| 540 | module looks for (C<=head1>, C<=for example>, C<#>, C<< => >>, | ||||||||||||||||||||||||||||||||||||||||||
| 541 | C<returns>) are ASCII, so they are found correctly in a UTF-8 file. | ||||||||||||||||||||||||||||||||||||||||||
| 542 | |||||||||||||||||||||||||||||||||||||||||||
| 543 | =item * Returned strings | ||||||||||||||||||||||||||||||||||||||||||
| 544 | |||||||||||||||||||||||||||||||||||||||||||
| 545 | C<section>, C<label>, C<code>, C<expected> and C<annotated_line> are | ||||||||||||||||||||||||||||||||||||||||||
| 546 | B<byte> strings. If the file is UTF-8, each non-ASCII character or emoji | ||||||||||||||||||||||||||||||||||||||||||
| 547 | is still several separate bytes in the result. Call | ||||||||||||||||||||||||||||||||||||||||||
| 548 | C<Encode::decode('UTF-8', $string)> if you need Perl character strings, | ||||||||||||||||||||||||||||||||||||||||||
| 549 | for example before you measure a length or print through a UTF-8 handle. | ||||||||||||||||||||||||||||||||||||||||||
| 550 | |||||||||||||||||||||||||||||||||||||||||||
| 551 | =item * The C<=encoding> line | ||||||||||||||||||||||||||||||||||||||||||
| 552 | |||||||||||||||||||||||||||||||||||||||||||
| 553 | It is ignored. The module does not use it to convert anything. | ||||||||||||||||||||||||||||||||||||||||||
| 554 | |||||||||||||||||||||||||||||||||||||||||||
| 555 | =item * Line endings | ||||||||||||||||||||||||||||||||||||||||||
| 556 | |||||||||||||||||||||||||||||||||||||||||||
| 557 | Only C<\n> ends a line. A file with Windows line endings keeps a C<\r> | ||||||||||||||||||||||||||||||||||||||||||
| 558 | inside multi-line C<code> values. | ||||||||||||||||||||||||||||||||||||||||||
| 559 | |||||||||||||||||||||||||||||||||||||||||||
| 560 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 561 | |||||||||||||||||||||||||||||||||||||||||||
| 562 | =head1 LIMITATIONS | ||||||||||||||||||||||||||||||||||||||||||
| 563 | |||||||||||||||||||||||||||||||||||||||||||
| 564 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 565 | |||||||||||||||||||||||||||||||||||||||||||
| 566 | =item No evaluation of verbatim blocks | ||||||||||||||||||||||||||||||||||||||||||
| 567 | |||||||||||||||||||||||||||||||||||||||||||
| 568 | Verbatim blocks are returned as raw code strings. The module does not evaluate | ||||||||||||||||||||||||||||||||||||||||||
| 569 | them or check that they are syntactically valid Perl. Blocks that are | ||||||||||||||||||||||||||||||||||||||||||
| 570 | syntactically broken will cause the downstream test file to fail to compile. | ||||||||||||||||||||||||||||||||||||||||||
| 571 | |||||||||||||||||||||||||||||||||||||||||||
| 572 | =item Deduplication is by exact C<code> text | ||||||||||||||||||||||||||||||||||||||||||
| 573 | |||||||||||||||||||||||||||||||||||||||||||
| 574 | Two examples with identical C<code> strings are deduplicated even if they come | ||||||||||||||||||||||||||||||||||||||||||
| 575 | from different sections. If the same one-liner appears in both SYNOPSIS and a | ||||||||||||||||||||||||||||||||||||||||||
| 576 | method docstring, only the first occurrence is kept. | ||||||||||||||||||||||||||||||||||||||||||
| 577 | |||||||||||||||||||||||||||||||||||||||||||
| 578 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 579 | |||||||||||||||||||||||||||||||||||||||||||
| 580 | =head1 SEE ALSO | ||||||||||||||||||||||||||||||||||||||||||
| 581 | |||||||||||||||||||||||||||||||||||||||||||
| 582 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 583 | |||||||||||||||||||||||||||||||||||||||||||
| 584 | =item C<bin/pod-example-tester> | ||||||||||||||||||||||||||||||||||||||||||
| 585 | |||||||||||||||||||||||||||||||||||||||||||
| 586 | =item L<App::Test::Generator> | ||||||||||||||||||||||||||||||||||||||||||
| 587 | |||||||||||||||||||||||||||||||||||||||||||
| 588 | =item L<Pod::Simple> | ||||||||||||||||||||||||||||||||||||||||||
| 589 | |||||||||||||||||||||||||||||||||||||||||||
| 590 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 591 | |||||||||||||||||||||||||||||||||||||||||||
| 592 | =head1 AUTHOR | ||||||||||||||||||||||||||||||||||||||||||
| 593 | |||||||||||||||||||||||||||||||||||||||||||
| 594 | Nigel Horne, C<< <njh at nigelhorne.com> >> | ||||||||||||||||||||||||||||||||||||||||||
| 595 | |||||||||||||||||||||||||||||||||||||||||||
| 596 | =head1 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||
| 597 | |||||||||||||||||||||||||||||||||||||||||||
| 598 | This section describes each method in Z notation. It is for readers who | ||||||||||||||||||||||||||||||||||||||||||
| 599 | want an exact, mathematical statement. You do not need it to use the module. | ||||||||||||||||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||||||||||||||||
| 601 | How to read it: a name ending in C<?> is an input, a name ending in C<!> is | ||||||||||||||||||||||||||||||||||||||||||
| 602 | an output, and a name ending in C<'> is the value after the call. | ||||||||||||||||||||||||||||||||||||||||||
| 603 | The symbol E<0x039E> before the state name means "this call does not change | ||||||||||||||||||||||||||||||||||||||||||
| 604 | the object". | ||||||||||||||||||||||||||||||||||||||||||
| 605 | |||||||||||||||||||||||||||||||||||||||||||
| 606 | The state of an object is one value, the path given to C<new>: | ||||||||||||||||||||||||||||||||||||||||||
| 607 | |||||||||||||||||||||||||||||||||||||||||||
| 608 | ┌─ PodExampleExtractor ───────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 609 | │ file : PATH | ||||||||||||||||||||||||||||||||||||||||||
| 610 | ├─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 611 | │ file ≠ undef | ||||||||||||||||||||||||||||||||||||||||||
| 612 | └─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 613 | |||||||||||||||||||||||||||||||||||||||||||
| 614 | ┌─ Example ───────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 615 | │ section, label, code : STRING | ||||||||||||||||||||||||||||||||||||||||||
| 616 | │ expected, annotated_line : STRING ∪ { undef } | ||||||||||||||||||||||||||||||||||||||||||
| 617 | ├─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 618 | │ code ≠ '' | ||||||||||||||||||||||||||||||||||||||||||
| 619 | │ expected = undef ⇔ annotated_line = undef | ||||||||||||||||||||||||||||||||||||||||||
| 620 | │ annotated_line ≠ undef ⇒ annotated_line = code | ||||||||||||||||||||||||||||||||||||||||||
| 621 | └─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 622 | |||||||||||||||||||||||||||||||||||||||||||
| 623 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||
| 624 | |||||||||||||||||||||||||||||||||||||||||||
| 625 | ┌─ New ───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 626 | │ PodExampleExtractor′ | ||||||||||||||||||||||||||||||||||||||||||
| 627 | │ file? : VALUE | ||||||||||||||||||||||||||||||||||||||||||
| 628 | │ result! : PodExampleExtractor | ||||||||||||||||||||||||||||||||||||||||||
| 629 | ├─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 630 | │ pre file? ≠ undef ∧ file? names an existing plain file | ||||||||||||||||||||||||||||||||||||||||||
| 631 | │ post file′ = file? | ||||||||||||||||||||||||||||||||||||||||||
| 632 | │ result! = θ PodExampleExtractor′ | ||||||||||||||||||||||||||||||||||||||||||
| 633 | └─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 634 | |||||||||||||||||||||||||||||||||||||||||||
| 635 | file? = undef ⇒ croak 'file is required' | ||||||||||||||||||||||||||||||||||||||||||
| 636 | file? is not an existing file ⇒ croak 'File not found: ' ⁀ file? | ||||||||||||||||||||||||||||||||||||||||||
| 637 | |||||||||||||||||||||||||||||||||||||||||||
| 638 | =head2 extract | ||||||||||||||||||||||||||||||||||||||||||
| 639 | |||||||||||||||||||||||||||||||||||||||||||
| 640 | ┌─ Extract ───────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 641 | │ Ξ PodExampleExtractor | ||||||||||||||||||||||||||||||||||||||||||
| 642 | │ result! : seq Example | ||||||||||||||||||||||||||||||||||||||||||
| 643 | ├─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 644 | │ pre file can be read | ||||||||||||||||||||||||||||||||||||||||||
| 645 | │ post result! = synopsis blocks ⁀ 'for example' blocks | ||||||||||||||||||||||||||||||||||||||||||
| 646 | │ ⁀ annotated lines, with later copies of | ||||||||||||||||||||||||||||||||||||||||||
| 647 | │ the same code removed | ||||||||||||||||||||||||||||||||||||||||||
| 648 | │ ∀ i, j : dom result! • | ||||||||||||||||||||||||||||||||||||||||||
| 649 | │ i ≠ j ⇒ result!(i).code ≠ result!(j).code | ||||||||||||||||||||||||||||||||||||||||||
| 650 | │ ∀ e : ran result! • ∃ n : ℕ₁ • | ||||||||||||||||||||||||||||||||||||||||||
| 651 | │ e.label = e.section ⁀ ' example ' ⁀ n | ||||||||||||||||||||||||||||||||||||||||||
| 652 | │ ∀ i, j : dom result! • | ||||||||||||||||||||||||||||||||||||||||||
| 653 | │ i ≠ j ⇒ result!(i).label ≠ result!(j).label | ||||||||||||||||||||||||||||||||||||||||||
| 654 | └─────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||
| 655 | |||||||||||||||||||||||||||||||||||||||||||
| 656 | file cannot be read ⇒ croak (message from File::Slurp) | ||||||||||||||||||||||||||||||||||||||||||
| 657 | |||||||||||||||||||||||||||||||||||||||||||
| 658 | =head1 STATE DIAGRAM | ||||||||||||||||||||||||||||||||||||||||||
| 659 | |||||||||||||||||||||||||||||||||||||||||||
| 660 | An object of this class has only one working state. It is created ready | ||||||||||||||||||||||||||||||||||||||||||
| 661 | to use and it never changes afterwards. | ||||||||||||||||||||||||||||||||||||||||||
| 662 | |||||||||||||||||||||||||||||||||||||||||||
| 663 | new(file => undef) | ||||||||||||||||||||||||||||||||||||||||||
| 664 | new(file => path that does not exist) | ||||||||||||||||||||||||||||||||||||||||||
| 665 | +------------------------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 666 | | action: croak, no object | | ||||||||||||||||||||||||||||||||||||||||||
| 667 | v | | ||||||||||||||||||||||||||||||||||||||||||
| 668 | +-------------+ | | ||||||||||||||||||||||||||||||||||||||||||
| 669 | | NO OBJECT |-----------------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 670 | +-------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 671 | | | ||||||||||||||||||||||||||||||||||||||||||
| 672 | | new(file => existing file) | ||||||||||||||||||||||||||||||||||||||||||
| 673 | | action: remember the path (file is not read) | ||||||||||||||||||||||||||||||||||||||||||
| 674 | v | ||||||||||||||||||||||||||||||||||||||||||
| 675 | +-------------+ extract() [file can be read] | ||||||||||||||||||||||||||||||||||||||||||
| 676 | | |---------------------------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 677 | | READY | action: read the file, | | ||||||||||||||||||||||||||||||||||||||||||
| 678 | | | return a new list of examples | | ||||||||||||||||||||||||||||||||||||||||||
| 679 | | |<--------------------------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 680 | | | | ||||||||||||||||||||||||||||||||||||||||||
| 681 | | | extract() [file removed or | ||||||||||||||||||||||||||||||||||||||||||
| 682 | | | not readable] | ||||||||||||||||||||||||||||||||||||||||||
| 683 | | |---------------------------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 684 | | | action: croak, nothing changes| | ||||||||||||||||||||||||||||||||||||||||||
| 685 | | |<--------------------------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 686 | +-------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 687 | | | ||||||||||||||||||||||||||||||||||||||||||
| 688 | | last reference goes away | ||||||||||||||||||||||||||||||||||||||||||
| 689 | | action: Perl frees the object | ||||||||||||||||||||||||||||||||||||||||||
| 690 | v | ||||||||||||||||||||||||||||||||||||||||||
| 691 | +-------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 692 | | GONE | | ||||||||||||||||||||||||||||||||||||||||||
| 693 | +-------------+ | ||||||||||||||||||||||||||||||||||||||||||
| 694 | |||||||||||||||||||||||||||||||||||||||||||
| 695 | Side effects: C<extract> opens the file for reading and closes it again | ||||||||||||||||||||||||||||||||||||||||||
| 696 | before it returns. No method writes to disk or prints anything. | ||||||||||||||||||||||||||||||||||||||||||
| 697 | |||||||||||||||||||||||||||||||||||||||||||
| 698 | =head1 LICENCE AND COPYRIGHT | ||||||||||||||||||||||||||||||||||||||||||
| 699 | |||||||||||||||||||||||||||||||||||||||||||
| 700 | Copyright 2026 Nigel Horne. | ||||||||||||||||||||||||||||||||||||||||||
| 701 | |||||||||||||||||||||||||||||||||||||||||||
| 702 | Usage is subject to the terms of GPL2. | ||||||||||||||||||||||||||||||||||||||||||
| 703 | If you use it, | ||||||||||||||||||||||||||||||||||||||||||
| 704 | please let me know. | ||||||||||||||||||||||||||||||||||||||||||
| 705 | |||||||||||||||||||||||||||||||||||||||||||
| 706 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 707 | |||||||||||||||||||||||||||||||||||||||||||
| 708 | 9 | 1; | |||||||||||||||||||||||||||||||||||||||||