Pod::Tests(3pm)

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

NAME

6       Pod::Tests - (DEPRECATED) Extracts embedded tests and code examples
7       from POD
8

SYNOPSIS

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

DESCRIPTION

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

EXAMPLES

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

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

AUTHOR

SEE ALSO

COPYRIGHT