/ 
App-Test-Generator-0.42
/ App::Test::Generator::PodExampleExtractor

NAME

App::Test::Generator::PodExampleExtractor - Extract runnable code examples from a Perl module's POD

SYNOPSIS

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};
}

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

Constructor.

my $ex = App::Test::Generator::PodExampleExtractor->new(file => 'lib/My/Module.pm');

API specification

input

{ file => { type => SCALAR } }

output

{ type => OBJECT, isa => 'App::Test::Generator::PodExampleExtractor' }

extract

Extract all runnable examples from the module's POD.

my $examples = $ex->extract();

API specification

input

{}

output

{ type => ARRAYREF }

Each element is a hashref with keys:

  • label - human-readable name for use as a test label

  • section - POD section/method from which it was extracted

  • code - the raw code text (may be multi-line)

  • expected - expected return value string (undef if not annotated)

  • annotated_line - the single line carrying a # returns / # => annotation, or undef

AUTHOR

Nigel Horne

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.