blib/lib/App/Test/Generator/PodExampleExtractor.pm

filter: Statementstmt 100% 98 / 98 Branchbran 90.4% 38 / 42 Conditioncond 66.6% 8 / 12 MC/DCmcdc 42.8% 3 / 7 Subroutinesub 100% 12 / 12 Podpod 100% 2 / 2 totaltotal 93.0% 161 / 173 CC 31 SCAR 18.4
CC
31
Cov
95%
_verbatim_paragraphs
11.2
_looks_like_perl
8.1
_extract_annotated_lines
6.0
CRAP 6.3
« lib/App/Test/Generator/Mutation/ReturnUndef.pm ↑ Summary lib/App/Test/Generator/Model/Method.pm »
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
BranchTrueFalseTotal
unless defined $args{"file"} 5 70 75
148 70 ▶ croak "File not found: $args{file}" unless -f $args{file};
Branch: 1 branch
BranchTrueFalseTotal
unless -f $args{"file"} 6 64 70
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
BranchTrueFalseTotal
if ($text =~ /=head[12]\s+SYNOPSIS\s*\n(.*?)(?=\n=head|\n=cut|\z)/gsu) 31 61 92
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
BranchTrueFalseTotal
if ($text =~ /=for\s+example\s+begin\s*\n(.*?)=for\s+example\s+end/gsu) 4 61 65
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
BranchTrueFalseTotal
if ($line =~ /^=head\d+\s+(.+)/u) 1165 33277 34442
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
BranchTrueFalseTotal
unless $line =~ /$VERBATIM_RE/u 16476 16801 33277
315 16801 ▶ next unless $line =~ $ANNOTATION_RE;
Branch: 1 branch
BranchTrueFalseTotal
unless $line =~ /$ANNOTATION_RE/u 16760 41 16801
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
BranchTrueFalseTotal
unless length $code_only 16 25 41
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
BranchTrueFalseTotal
if ($line =~ /$VERBATIM_RE/u or $line =~ /\S/u and @current) { } 1230 130 1360
Condition66%4/6
$line =~ /$VERBATIM_RE/u or $line =~ /\S/u and @current
l!l&&r!l&&!r
12300130
$line =~ /\S/u and @current
!ll&&!rl&&r
81490
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
ABCresult
1XX1
0111
00X0
0100
363 1230 push @current, $line;
364 } else {
365 130 ▶ if(@current) {
Branch: 1 branch
BranchTrueFalseTotal
if (@current) 51 79 130
366 51 my $code = _dedent(join("\n", @current));
367 51 ▶ push @examples, {
Branch: 1 branch
BranchTrueFalseTotal
if length $code and _looks_like_perl($code) 42 9 51
Condition66%2/3
length $code and _looks_like_perl($code)
!ll&&!rl&&r
0942
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)
ABresult
0X0
100
111
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
BranchTrueFalseTotal
if (@current) 33 2 35
379 33 my $code = _dedent(join("\n", @current));
380 33 ▶ push @examples, {
Branch: 1 branch
BranchTrueFalseTotal
if length $code and _looks_like_perl($code) 31 2 33
Condition66%2/3
length $code and _looks_like_perl($code)
!ll&&!rl&&r
0231
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)
ABresult
0X0
100
111
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
BranchTrueFalseTotal
unless @non_empty 0 84 84
407 1283 my ($min) = sort { $a <=> $b }
408 84 ▶ map { /^([ \t]*)/ ? length($1) : 0 } @non_empty;
Branch: 1 branch
BranchTrueFalseTotal
/^([ \t]*)/u ? : 1230 0 1230
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
BranchTrueFalseTotal
unless $line =~ /\S/u 0 100 100
431 100 ▶ next if $line =~ /^\s*#/; # skip comment-only lines
Branch: 1 branch
BranchTrueFalseTotal
if $line =~ /^\s*#/u 15 85 100
432 # Perl sigils
433 85 ▶ return 1 if $line =~ /[\$\@\%]/;
Branch: 1 branch
BranchTrueFalseTotal
if $line =~ /[\$\@\%]/u 53 32 85
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
BranchTrueFalseTotal
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/u 17 15 32
436 # Method call or package separator
437 15 ▶ return 1 if $line =~ /(?:->|::)/;
Branch: 1 branch
BranchTrueFalseTotal
if $line =~ /(?:->|::)/u 3 12 15
438 # Fat comma — a hash or argument list
439 12 ▶ return 1 if $line =~ /=>/;
Branch: 1 branch
BranchTrueFalseTotal
if $line =~ /=>/u 0 12 12
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;
« lib/App/Test/Generator/Mutation/ReturnUndef.pm ↑ Summary lib/App/Test/Generator/Model/Method.pm »