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 SYNOPSIS and =head2 SYNOPSIS

  • =for example begin ... =for example end blocks

  • Annotated single-line call examples inside per-method docstrings (lines matching $obj->method(...) # returns value or method(...) # = 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

  • file

    Path 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

file was not supplied.

File not found: $path

file was 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/=head2 text) where the example was found

  • code - the raw code text, dedented. May be multi-line for verbatim blocks.

  • expected - the expected return value string from a # returns value or # => value annotation; undef if not annotated.

  • annotated_line - for annotated single-line examples, the bare expression with the annotation stripped; undef for 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 by File::Slurp::read_file)

The source file was removed, or became unreadable, between the call to new and the call to extract. 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/ or extract-schemas lib/My/Module.pm) are filtered out by _looks_like_perl. They would cause compile errors under use strict in 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.

expected is always a raw string

The expected field is the literal text captured after # returns or # =>. It is not evaluated or type-converted. Downstream code that emits is($result, $expected) must handle quoting appropriately.

SYNOPSIS blocks from =head3 and deeper are not collected

Only =head1 SYNOPSIS and =head2 SYNOPSIS sections are scanned for verbatim blocks. Deeper heading levels are ignored.

new takes a list of pairs, not a hashref

Write new(file => $path). If you write new({ file => $path }) the file name is not seen, and new croaks with file is required. Any argument other than file is ignored without a warning.

How undef is handled
  • file => undef makes new croak with file is required.

  • expected and annotated_line are undef for every example that came from a whole block. Always test them with defined before you use them.

  • label, section and code are never undef.

  • A file with no examples gives an empty arrayref ([]), never undef.

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 as

return $total;    # returns the sum

is reported as an example with expected set to the sum. The section of such an example is the last POD heading seen above it, or UNKNOWN if 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 code text, so the duplicate check does not join them.

Each call to extract reads 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 file argument

    The 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, expected and annotated_line are byte strings. If the file is UTF-8, each non-ASCII character or emoji is still several separate bytes in the result. Call Encode::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 =encoding line

    It is ignored. The module does not use it to convert anything.

  • Line endings

    Only \n ends a line. A file with Windows line endings keeps a \r inside multi-line code values.

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 code text

Two examples with identical code strings 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.