NAME
App::Test::Generator::PodExampleExtractor - Extract runnable code examples from a Perl module's POD
VERSION
Version 0.49
SYNOPSIS
Pattern 1: list every example found in a module.
use App::Test::Generator::PodExampleExtractor;
my $ex = App::Test::Generator::PodExampleExtractor->new(
file => 'lib/My/Module.pm',
);
my $examples = $ex->extract();
for my $e (@$examples) {
printf "%-30s %s\n", $e->{label}, $e->{code};
}
Pattern 2: keep only the examples that say what they return. These are the ones that can be checked automatically.
my @checkable = grep { defined $_->{expected} } @{ $ex->extract() };
for my $e (@checkable) {
print "Run: $e->{annotated_line}\n";
print "Expect: $e->{expected}\n";
}
Pattern 3: count the examples in each documentation section.
my %count;
$count{ $_->{section} }++ for @{ $ex->extract() };
printf "%-20s %d\n", $_, $count{$_} for sort keys %count;
Pattern 4: handle a missing file without stopping the program.
my $ex2 = eval {
App::Test::Generator::PodExampleExtractor->new(file => $path);
};
warn "Skipping $path: $@" unless $ex2;
DESCRIPTION
Parses the POD of a Perl module and returns a structured list of runnable code examples. Three sources are collected:
Verbatim blocks inside
=head1 SYNOPSISand=head2 SYNOPSIS=for example begin...=for example endblocksAnnotated single-line call examples inside per-method docstrings (lines matching
$obj->method(...) # returns valueormethod(...) # =value>)
Return-value annotations of the form # returns value or # => value are parsed and exposed as expected in the result hashref, enabling downstream test generators to emit is() assertions.
new
Construct a new extractor for the given source file.
my $ex = App::Test::Generator::PodExampleExtractor->new(
file => 'lib/My/Module.pm',
);
Arguments
filePath to the Perl module to extract examples from. Required. The file must exist on disk.
Returns
A blessed App::Test::Generator::PodExampleExtractor object. Croaks if file is missing or does not exist.
The file is not opened by new. It is read each time you call extract.
EXAMPLE
use App::Test::Generator::PodExampleExtractor;
my $ex = App::Test::Generator::PodExampleExtractor->new(
file => 'lib/Acme/Widget.pm',
);
printf "Extracting examples from %s\n", 'lib/Acme/Widget.pm';
MESSAGES
file is required-
filewas not supplied. File not found: $path-
filewas supplied but the path does not exist on disk.
API SPECIFICATION
input
{ file => { type => SCALAR } }
output
{ type => OBJECT, isa => 'App::Test::Generator::PodExampleExtractor' }
The mathematical description is in "FORMAL SPECIFICATION".
extract
Extract all runnable examples from the module's POD.
my $examples = $ex->extract();
Arguments
None beyond $self.
Returns
An arrayref of example hashrefs, deduplicated by code text. Each hashref has the following keys:
label- human-readable name for use as a test label (e.g."SYNOPSIS example 1")section- the POD section heading (=head1/=head2text) where the example was foundcode- the raw code text, dedented. May be multi-line for verbatim blocks.expected- the expected return value string from a# returns valueor# => valueannotation;undefif not annotated.annotated_line- for annotated single-line examples, the bare expression with the annotation stripped;undeffor verbatim blocks.
EXAMPLE
my $examples = $ex->extract();
for my $e (@{$examples}) {
printf "[%s] %s\n", $e->{label}, $e->{code};
if(defined $e->{expected}) {
printf " expects: %s\n", $e->{expected};
}
}
# Count examples without a declared return value
my @unannotated = grep { !defined $_->{expected} } @{$examples};
printf "%d unannotated examples\n", scalar @unannotated;
MESSAGES
read_file 'PATH' - ...(raised byFile::Slurp::read_file)-
The source file was removed, or became unreadable, between the call to
newand the call toextract. The rest of the message is the reason given by the operating system.
API SPECIFICATION
input
{ self => { type => OBJECT, isa => 'App::Test::Generator::PodExampleExtractor' } }
output
{ type => ARRAYREF }
The mathematical description is in "FORMAL SPECIFICATION".
COMMON PITFALLS
- Shell-command blocks are silently dropped
-
Verbatim paragraphs that contain only shell commands (e.g.
prove -l t/orextract-schemas lib/My/Module.pm) are filtered out by_looks_like_perl. They would cause compile errors underuse strictin a generated test file. If you want a shell command to appear as an example, put it in a POD comment block, not a verbatim paragraph. - Annotations must be on the same line as the call expression
-
The
# returns/# =>annotation is parsed as a line-level suffix. Multi-line calls spread across multiple lines will not pick up an annotation on the last line. Only the last line is examined, and the call expression on earlier lines is lost. expectedis always a raw string-
The
expectedfield is the literal text captured after# returnsor# =>. It is not evaluated or type-converted. Downstream code that emitsis($result, $expected)must handle quoting appropriately. - SYNOPSIS blocks from
=head3and deeper are not collected -
Only
=head1 SYNOPSISand=head2 SYNOPSISsections are scanned for verbatim blocks. Deeper heading levels are ignored. newtakes a list of pairs, not a hashref-
Write
new(file => $path). If you writenew({ file => $path })the file name is not seen, andnewcroaks withfile is required. Any argument other thanfileis ignored without a warning. - How
undefis handled -
file => undefmakesnewcroak withfile is required.expectedandannotated_lineareundeffor every example that came from a whole block. Always test them withdefinedbefore you use them.label,sectionandcodeare neverundef.A file with no examples gives an empty arrayref (
[]), neverundef.
- Annotated lines are searched for in the whole file, not only in POD
-
Every indented line of the file is checked for a
# returns ...or# => ...comment. This includes indented lines of ordinary Perl code. A code line such asreturn $total; # returns the sumis reported as an example with
expectedset tothe sum. Thesectionof such an example is the last POD heading seen above it, orUNKNOWNif there was none. Use a different wording in code comments if you do not want this. - An annotated line inside a block is reported twice
-
A line with an annotation that sits inside a SYNOPSIS block appears once as part of the whole block and once more by itself. The two entries have different
codetext, so the duplicate check does not join them. - Each call to
extractreads the file again -
The result is not stored in the object. Two calls give two separate arrayrefs. Changing one result does not change the other. If the file changed on disk between the calls, the results can be different.
ENCODING
The file is read as raw bytes. Nothing is decoded.
The
fileargumentThe path is passed to the operating system unchanged. ASCII paths always work. For a path with non-ASCII characters, pass it as bytes in the encoding your file system uses (normally UTF-8).
File contents
Any byte values are accepted. UTF-8 text, other non-ASCII text and emojis do not cause errors and are not damaged. All the markers this module looks for (
=head1,=for example,#,=>,returns) are ASCII, so they are found correctly in a UTF-8 file.Returned strings
section,label,code,expectedandannotated_lineare byte strings. If the file is UTF-8, each non-ASCII character or emoji is still several separate bytes in the result. CallEncode::decode('UTF-8', $string)if you need Perl character strings, for example before you measure a length or print through a UTF-8 handle.The
=encodinglineIt is ignored. The module does not use it to convert anything.
Line endings
Only
\nends a line. A file with Windows line endings keeps a\rinside multi-linecodevalues.
LIMITATIONS
- No evaluation of verbatim blocks
-
Verbatim blocks are returned as raw code strings. The module does not evaluate them or check that they are syntactically valid Perl. Blocks that are syntactically broken will cause the downstream test file to fail to compile.
- Deduplication is by exact
codetext -
Two examples with identical
codestrings are deduplicated even if they come from different sections. If the same one-liner appears in both SYNOPSIS and a method docstring, only the first occurrence is kept.
SEE ALSO
bin/pod-example-tester- App::Test::Generator
- Pod::Simple
AUTHOR
Nigel Horne, <njh at nigelhorne.com>
FORMAL SPECIFICATION
This section describes each method in Z notation. It is for readers who want an exact, mathematical statement. You do not need it to use the module.
How to read it: a name ending in ? is an input, a name ending in ! is an output, and a name ending in ' is the value after the call. The symbol Ξ before the state name means "this call does not change the object".
The state of an object is one value, the path given to new:
┌─ PodExampleExtractor ─────────────────────────────
│ file : PATH
├───────────────────────────────────────────────────
│ file ≠ undef
└───────────────────────────────────────────────────
┌─ Example ─────────────────────────────────────────
│ section, label, code : STRING
│ expected, annotated_line : STRING ∪ { undef }
├───────────────────────────────────────────────────
│ code ≠ ''
│ expected = undef ⇔ annotated_line = undef
│ annotated_line ≠ undef ⇒ annotated_line = code
└───────────────────────────────────────────────────
new
┌─ New ─────────────────────────────────────────────
│ PodExampleExtractor′
│ file? : VALUE
│ result! : PodExampleExtractor
├───────────────────────────────────────────────────
│ pre file? ≠ undef ∧ file? names an existing plain file
│ post file′ = file?
│ result! = θ PodExampleExtractor′
└───────────────────────────────────────────────────
file? = undef ⇒ croak 'file is required'
file? is not an existing file ⇒ croak 'File not found: ' ⁀ file?
extract
┌─ Extract ─────────────────────────────────────────
│ Ξ PodExampleExtractor
│ result! : seq Example
├───────────────────────────────────────────────────
│ pre file can be read
│ post result! = synopsis blocks ⁀ 'for example' blocks
│ ⁀ annotated lines, with later copies of
│ the same code removed
│ ∀ i, j : dom result! •
│ i ≠ j ⇒ result!(i).code ≠ result!(j).code
│ ∀ e : ran result! • ∃ n : ℕ₁ •
│ e.label = e.section ⁀ ' example ' ⁀ n
│ ∀ i, j : dom result! •
│ i ≠ j ⇒ result!(i).label ≠ result!(j).label
└───────────────────────────────────────────────────
file cannot be read ⇒ croak (message from File::Slurp)
STATE DIAGRAM
An object of this class has only one working state. It is created ready to use and it never changes afterwards.
new(file => undef)
new(file => path that does not exist)
+------------------------------+
| action: croak, no object |
v |
+-------------+ |
| NO OBJECT |-----------------------+
+-------------+
|
| new(file => existing file)
| action: remember the path (file is not read)
v
+-------------+ extract() [file can be read]
| |---------------------------------+
| READY | action: read the file, |
| | return a new list of examples |
| |<--------------------------------+
| |
| | extract() [file removed or
| | not readable]
| |---------------------------------+
| | action: croak, nothing changes|
| |<--------------------------------+
+-------------+
|
| last reference goes away
| action: Perl frees the object
v
+-------------+
| GONE |
+-------------+
Side effects: extract opens the file for reading and closes it again before it returns. No method writes to disk or prints anything.
LICENCE AND COPYRIGHT
Copyright 2026 Nigel Horne.
Usage is subject to the terms of GPL2. If you use it, please let me know.