NAME

Test::Pod::Content - Test a Pod's content

SYNOPSIS

use Test::Pod::Content tests => 3;
pod_section_is 'Test::Pod::Content' , 'NAME', "Test::Pod::Content - Test a Pod's content", 'NAME section';
pod_section_like 'Test/Pod/Content.pm', 'SYNOPSIS', qr{ use \s Test::Pod::Content; }xm, 'SYNOPSIS section';
pod_section_like 'Test/Pod/Content.pm', 'DESCRIPTION', qr{ Test::Pod::Content \s provides \s the }xm, 'DESCRIPTION section';

DESCRIPTION

This is a very simple module for testing a Pod's content. It is mainly intended for testing the content of generated Pod - that s, the Pod included in perl modules generated by some mechanism.

Another usage example is to test whether all files contain the same copyright notice:

plan tests => scalar @filelist;

for my $file (sort @filelist) {
   pod_section_like( $file, 'LICENSE AND COPYRIGHT', qr{ 
       This \s library \s is \s free \s software\. \s
       You \s may \s distribute/modify \s it \s under \s
       the \s same \s terms \s as \s perl \s itself
   }xms, "$file License notice");
}

See the files in the t/ directory for live examples.

Test::Pod::Content has a very simple concept of Pods: To Test::Pod::Content, a Pod is separated into section. Each section starts with a =head(1|2|3|4) directive, and ends with the next =head, or with the end of the document (=cut).

This is a very drastic simplification of Pod's document object model, and only allows for coarse-grained tests.

Test::Pod::Content provides the following subroutines for testing a Pod's content:

Subroutines

pod_section_is

pod_section_is $file, $section, $content, $comment;

Tests whether a Pod section contains exactly the text given. Most useful for testing the NAME section. You probably want to use pod_section_like for all other sections.

$file may either be a filename (including path) or a module name. Test::Pod::Content will search in @INC for the file/module given.

pod_section_like

pod_section_like $file, $section, qr{ use \s Test::Pod::Content\s }xm, $comment;

Tests whether the text in a Pod section matches the given regex. Be sure to include the m / s regex qualifier if you expect your Pod section to span multiple lines.

$file may either be a filename (including path) or a module name. Test::Pod::Content will search in @INC for the file/module given.

BUGS AND LIMITATIONS

• Performance

  Every call to a pod_section_* method searches for the file in question in @INC and parses it from its start. This means that every test requires a Pod parser run, which is quite inefficient if you conduct a big number of tests.

LICENSE AND COPYRIGHT

Copyright 2007 Martin Kutter.

This library is free software. You may distribute/modify it under the same terms as perl itself

AUTHOR

Martin Kutter <martin.kutter fen-net.de>