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

EXAMPLES

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

AUTHOR

160       Michael G Schwern <schwern@pobox.com>
161
162       Adam Kennedy <adamk@cpan.org>
163

COPYRIGHT

175       Copyright 2005 - 2008 Adam Kennedy.
176
177       Copyright 2001 - 2003 Michael G Schwern.
178
179       This program is free software; you can redistribute it and/or modify it
180       under the same terms as Perl itself.
181
182       The full text of the license can be found in the LICENSE file included
183       with this module.
184
185
186
187perl v5.12.0                      2008-07-13                     Pod::Tests(3)

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

AUTHOR

SEE ALSO

COPYRIGHT