Pod::Tests(3pm)

📦
version 1.20 · 3 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Pod::Tests 💖

okay bestie, listen up — this is the manual page for Pod::Tests, from the User Contributed Perl Documentation section of the perl man pages. It's the thing that goes and digs your embedded tests and code examples out of your POD. 🎀

✨ NAME ✨

Pod::Tests — (DEPRECATED) Extracts embedded tests and code examples from POD 🦋

fr fr, it's deprecated, I'm not being dramatic — the module itself is labeled (DEPRECATED) right there in the NAME. 💀

🌸 SYNOPSIS 🌸

use Pod::Tests;
$p = Pod::Tests->new;

$p->parse_file($file);
$p->parse_fh($fh);
$p->parse(@code);

my @examples = $p->examples;
my @tests    = $p->tests;

foreach my $example (@examples) {
    print "The example:  '$example->{code}' was on line ".
          "$example->{line}\n";
}

my @test_code         = $p->build_tests(@tests);
my @example_test_code = $p->build_examples(@examples);

literally that's the whole vibe in one code block, no cap. ✨

👑 DESCRIPTION 👑

So this is a specialized POD viewer — and when I say specialized I mean it does one job. It extracts embedded tests and code examples from POD. That's it. It doesn't do much more than that, bestie. 🫶

And here's the tea: pod2test does the useful work. Pod::Tests is the little helper behind the curtain. 🧚

🔍 Parsing

After you make a Pod::Tests object, you parse the POD by calling one of the available parsing methods documented below. And you can call parse as many times as you'd like — all examples and tests found will stack up inside the object. It just keeps collecting. Obsessed. 💅

🧪 Testing

Once they're extracted, the tests can be built into stand-alone testing code using the build_tests() and build_examples() methods.

But — it is recommended that you first look at the pod2test program before embarking on this. Do not just raw-dog your own test builder, bestie, please. 😭

🛠️ Methods

⭐ new

$parser = Pod::Tests->new;

Returns a new Pod::Tests object which lets you read tests and examples out of a POD document. ✨

⭐ parse

$parser->parse(@code);

Finds the examples and tests in a bunch of lines of Perl @code. Once run they're available via examples() and testing(). 🦋

⭐ parse_file $file

$parser->parse_file($filename);

Just like parse() except it works on a file. 📁

⭐ parse_fh $fh

$parser->parse_fh($fh);

Just like parse() except it works on a filehandle. 🫧

⭐ tests

@testing  = $parser->tests;

Returns the tests found in the parsed POD documents. Each element of @testing is a hash representing an individual testing block and contains information about that block. 💜

$test->{code}         actual testing code
$test->{line}         line from where the test was taken

⭐ examples

@examples = $parser->examples;

Returns the examples found in the parsed POD documents. Each element of @examples is a hash representing an individual testing block and contains information about that block. 🎀

$test->{code}         actual testing code
$test->{line}         line from where the test was taken

⭐ build_tests

my @code = $p->build_tests(@tests);

Returns a code fragment based on the given embedded @tests. This fragment is expected to print the usual "ok/not ok" (or something Test::Harness can read) or nothing at all. 🌈

Typical usage might be:

my @code = $p->build_tests($p->tests);

This fragment is suitable for placing into a larger test script. 🔥

NOTE Look at pod2test before embarking on your own test building. Like, actually look at it. 🙈

⭐ build_examples

my @code = $p->build_examples(@examples);

Similar to build_tests(), it creates a code fragment which tests the basic validity of your example code. Essentially, it just makes sure it compiles. ✅

If your example has an "example testing" block associated with it, it will run the the example code and the example testing block. (yes, "the the" — that's the original, and I am not touching it, iykyk 🫶)

🌟 EXAMPLES 🌟

Here's the simplest example, just finding the tests and examples in a single module. 🍓

my $p = Pod::Tests->new;
$p->parse_file("path/to/Some.pm");

And one to find all the tests and examples in a directory of files. This illustrates building a set of examples and tests through multiple calls to parse_file(). 📂

my $p = Pod::Tests->new;
opendir(PODS, "path/to/some/lib/") || die $!;
while( my $file = readdir PODS ) {
    $p->parse_file($file);
}
printf "Found %d examples and %d tests in path/to/some/lib\n",
       scalar $p->examples, scalar $p->tests;

Finally, an example of parsing your own POD using the DATA filehandle. 💫

use Fcntl qw(:seek);
my $p = Pod::Tests->new;

# Seek to the beginning of the current code.
seek(DATA, 0, SEEK_SET) || die $!;
$p->parse_fh(\*DATA);

💌 SUPPORT

Okay so this module has been replaced by the newer Test::Inline 2. Most testing code that currently works with "pod2test" should continue to work with the new version. ✨

The most notable exceptions are "=for begin" and "=for end", which are deprecated. 💀

After upgrading, Pod::Tests and "pod2test" were split out to provide a compatibility package for legacy code.

"pod2test" will stay in CPAN, but should remain unchanged indefinately, with the exception of any minor bugs that will require squishing. 🐛

Bugs in this dist should be reported via the following URL. Feature requests should not be submitted, as further development is now occuring in Test::Inline.

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pod-Tests>

🫶 AUTHOR 🫶

Michael G Schwern <schwern@pobox.com>

Adam Kennedy <adamk@cpan.org>

🔗 SEE ALSO 🔗

Copyright 2005 - 2008 Adam Kennedy.

Copyright 2001 - 2003 Michael G Schwern.

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

The full text of the license can be found in the LICENSE file included with this module.

and that's the whole page, bestie — you ate that 💅

this one's from perl v5.38.2, dated 2024-02-21 — mwah, sending you off with a kiss, go write some tests 🎀✨💖

📦 where this page comes from