Pod::Tests(3pm)

1Pod::Tests(3)         User Contributed Perl Documentation        Pod::Tests(3)
2
3
4

NAME

6       Pod::Tests - Extracts embedded tests and code examples from POD
7

SYNOPSIS

9         use Pod::Tests;
10         $p = Pod::Tests->new;
11
12         $p->parse_file($file);
13         $p->parse_fh($fh);
14         $p->parse(@code);
15
16         my @examples = $p->examples;
17         my @tests    = $p->tests;
18
19         foreach my $example (@examples) {
20             print "The example:  '$example->{code}' was on line ".
21                   "$example->{line}\n";
22         }
23
24         my @test_code         = $p->build_tests(@tests);
25         my @example_test_code = $p->build_examples(@examples);
26

DESCRIPTION

28       This is a specialized POD viewer to extract embedded tests and code
29       examples from POD.  It doesn't do much more than that.  pod2test does
30       the useful work.
31
32       Parsing
33
34       After creating a Pod::Tests object, you parse the POD by calling one of
35       the available parsing methods documented below.  You can call parse as
36       many times as you'd like, all examples and tests found will stack up
37       inside the object.
38
39       Testing
40
41       Once extracted, the tests can be built into stand-alone testing code
42       using the build_tests() and build_examples() methods.  However, it is
43       recommended that you first look at the pod2test program before embark‐
44       ing on this.
45
46       Methods
47
48       new
49
50         $parser = Pod::Tests->new;
51
52       Returns a new Pod::Tests object which lets you read tests and examples
53       out of a POD document.
54
55       parse
56
57         $parser->parse(@code);
58
59       Finds the examples and tests in a bunch of lines of Perl @code.  Once
60       run they're available via examples() and testing().
61
62       parse_file $file
63
64         $parser->parse_file($filename);
65
66       Just like parse() except it works on a file.
67
68       parse_fh $fh
69
70         $parser->parse_fh($fh);
71
72       Just like parse() except it works on a filehandle.
73
74       tests
75
76         @testing  = $parser->tests;
77
78       Returns the tests found in the parsed POD documents.  Each element of
79       @testing is a hash representing an individual testing block and con‐
80       tains information about that block.
81
82         $test->{code}         actual testing code
83         $test->{line}         line from where the test was taken
84
85       examples
86
87         @examples = $parser->examples;
88
89       Returns the examples found in the parsed POD documents.  Each element
90       of @examples is a hash representing an individual testing block and
91       contains information about that block.
92
93         $test->{code}         actual testing code
94         $test->{line}         line from where the test was taken
95
96       build_tests
97
98         my @code = $p->build_tests(@tests);
99
100       Returns a code fragment based on the given embedded @tests.  This frag‐
101       ment is expected to print the usual "ok/not ok" (or something
102       Test::Harness can read) or nothing at all.
103
104       Typical usage might be:
105
106           my @code = $p->build_tests($p->tests);
107
108       This fragment is suitable for placing into a larger test script.
109
110       NOTE Look at pod2test before embarking on your own test building.
111
112       build_examples
113
114         my @code = $p->build_examples(@examples);
115
116       Similar to build_tests(), it creates a code fragment which tests the
117       basic validity of your example code.  Essentially, it just makes sure
118       it compiles.
119
120       If your example has an "example testing" block associated with it it
121       will run the the example code and the example testing block.
122

EXAMPLES

124       Here's the simplest example, just finding the tests and examples in a
125       single module.
126
127         my $p = Pod::Tests->new;
128         $p->parse_file("path/to/Some.pm");
129
130       And one to find all the tests and examples in a directory of files.
131       This illustrates building a set of examples and tests through multiple
132       calls to parse_file().
133
134         my $p = Pod::Tests->new;
135         opendir(PODS, "path/to/some/lib/") ⎪⎪ die $!;
136         while( my $file = readdir PODS ) {
137             $p->parse_file($file);
138         }
139         printf "Found %d examples and %d tests in path/to/some/lib\n",
140                scalar $p->examples, scalar $p->tests;
141
142       Finally, an example of parsing your own POD using the DATA filehandle.
143
144         use Fcntl qw(:seek);
145         my $p = Pod::Tests->new;
146
147         # Seek to the beginning of the current code.
148         seek(DATA, 0, SEEK_SET) ⎪⎪ die $!;
149         $p->parse_fh(\*DATA);
150
151       SUPPORT
152
153       This module has been replaced by the newer Test::Inline 2. Most testing
154       code that currently works with "pod2test" should continue to work with
155       the new version. The most notable exceptions are "=for begin" and "=for
156       end", which are deprecated.
157
158       After upgrading, Pod::Tests and "pod2test" were split out to provide a
159       compatibility package for legacy code.
160
161       "pod2test" will stay in CPAN, but should remain unchanged indefinately,
162       with the exception of any minor bugs that will require squishing.
163
164       Bugs in this dist should be reported via the following URL. Feature
165       requests should not be submitted, as further development is now occur‐
166       ing in Test::Inline.
167
168       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pod-Tests>
169

AUTHOR

171       Michael G Schwern <schwern@pobox.com>
172
173       Repackaged by Adam Kennedy <cpan@ali.as>
174

COPYRIGHT

186       Copyright 2001 - 2003 Michael G Schwern. All rights reserved.
187
188       Some parts copyright 2005 Adam Kennedy. All rights reserved.
189
190       This program is free software; you can redistribute it and/or modify it
191       under the same terms as Perl itself.
192
193       The full text of the license can be found in the LICENSE file included
194       with this module.
195
196
197
198perl v5.8.8                       2005-09-21                     Pod::Tests(3)

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

AUTHOR

SEE ALSO

COPYRIGHT