TAP::PARSER::SOURCE(3perl)

💖 TAP::Parser::Source — a TAP source & meta data about it 💖

okay bestie, come sit with me, we're reading a Perl manual page together and honestly? it's cute. this one lives in the Perl Programmers Reference Guide and it's version 3.52 🎀

---

✨ NAME ✨

TAP::Parser::Source — a TAP source & meta data about it

no cap, that's literally the whole vibe: it's a source, and it's the receipts about the source 📝

---

🌸 VERSION 🌸

Version 3.52

---

🦋 SYNOPSIS 🦋

here's the ✨ moment ✨ where it all comes together:

use TAP::Parser::Source;
my $source = TAP::Parser::Source->new;
$source->raw( \'reference to raw TAP source' )
       ->config( \%config )
       ->merge( $boolean )
       ->switches( \@switches )
       ->test_args( \@args )
       ->assemble_meta;

do { ... } if $source->meta->{is_file};
# see assemble_meta for a full list of data available

look at that chaining, she's method-chaining like it's a relay race and every method passes the baton 🏃♀️💨 and yes, the comment at the end is doing the heavy lifting — go read assemble_meta when you want the full menu.

---

🌈 DESCRIPTION 🌈

so a TAP source is literally anything that produces a stream of TAP for the parser to consume. like: an executable file, a text file, an archive, an IO handle, a database, etc. (the "etc." is carrying so much weight there and honestly, iconic).

TAP::Parser::Sources wrap up these raw sources and hand you some genuinely useful meta data about them. who uses them? TAP::Parser::SourceHandlers, that's who — they do whatever is required to produce & capture a stream of TAP from the raw source, and package it up all nice in a TAP::Parser::Iterator for the parser to consume 🫶

real talk though — unless you're writing a new TAP::Parser::SourceHandler, a plugin, or subclassing TAP::Parser, you probably won't need to use this module directly. it's giving backstage pass, not front door. 💅

---

👑 METHODS 👑

🌟 Class Methods

• new

my $source = TAP::Parser::Source->new;

Returns a new TAP::Parser::Source object. fresh out the box, brand new, main character energy ✨

💅 Instance Methods

• raw

my $raw = $source->raw;
$source->raw( $some_value );

Chaining getter/setter for the raw TAP source. heads up: this is a reference, because it may contain large amounts of data (eg: raw TAP). big data, big feels 😭

• meta

my $meta = $source->meta;
$source->meta({ %some_value });

Chaining getter/setter for meta data about the source. defaults to an empty hashref. see "assemble_meta" for more info — she's the one with the details 📋

• has_meta

True if the source has meta data. simple as that, bestie 💜

• config

my $config = $source->config;
$source->config({ %some_value });

Chaining getter/setter for the source's configuration, if any has been provided by the user. how it's used is up to you (no rules, just vibes). defaults to an empty hashref. see "config_for" for more info.

• merge

my $merge = $source->merge;
$source->config( $bool );

Chaining getter/setter for the flag that dictates whether STDOUT and STDERR should be merged (where appropriate). defaults to undef.

• switches

my $switches = $source->switches;
$source->config([ @switches ]);

Chaining getter/setter for the list of command-line switches that should be passed to the source (where appropriate). defaults to undef.

• test_args

my $test_args = $source->test_args;
$source->config([ @test_args ]);

Chaining getter/setter for the list of command-line arguments that should be passed to the source (where appropriate). defaults to undef.

• assemble_meta

my $meta = $source->assemble_meta;

Gathers meta data about the "raw" source, stashes it in "meta" and returns it as a hashref. the whole point? so that the TAP::Parser::SourceHandlers don't have to repeat common checks over and over (we love a shared workload, teamwork makes the dream work 🫶).

Currently this includes:

is_scalar => $bool,
is_hash   => $bool,
is_array  => $bool,

# for scalars:
length => $n
has_newlines => $bool

# only done if the scalar looks like a filename
is_file => $bool,
is_dir  => $bool,
is_symlink => $bool,
file => {
    # only done if the scalar looks like a filename
    basename => $string, # including ext
    dir      => $string,
    ext      => $string,
    lc_ext   => $string,
    # system checks
    exists  => $bool,
    stat    => [ ... ], # perldoc -f stat
    empty   => $bool,
    size    => $n,
    text    => $bool,
    binary  => $bool,
    read    => $bool,
    write   => $bool,
    execute => $bool,
    setuid  => $bool,
    setgid  => $bool,
    sticky  => $bool,
    is_file => $bool,
    is_dir  => $bool,
    is_symlink => $bool,
    # only done if the file's a symlink
    lstat      => [ ... ], # perldoc -f lstat
    # only done if the file's a readable text file
    shebang => $first_line,
}

# for arrays:
size => $n,

like hello?? that's a whole information buffet and you didn't even have to cook 🍓

• shebang

Get the shebang line for a script file.

my $shebang = TAP::Parser::Source->shebang( $some_script );

May be called as a class method 👑

• config_for

my $config = $source->config_for( $class );

Returns "config" for the $class given. class names may be fully qualified or abbreviated, eg:

# these are equivalent
$source->config_for( 'Perl' );
$source->config_for( 'TAP::Parser::SourceHandler::Perl' );

If a fully qualified $class is given, its abbreviated version is checked first. (she checks the short one before the long one — efficient queen 💅)

---

🎀 AUTHORS 🎀

Steve Purkis. thank you for your service, legend 🫡

---

⭐ SEE ALSO ⭐

TAP::Object, TAP::Parser, TAP::Parser::IteratorFactory, TAP::Parser::SourceHandler

go read them, they're all in the same friend group 💖

---

and that's the whole page bestie!! come back any time 🌸 this one shipped as perl v5.44.0, dated 2026-10-17, and fr fr it ate 💅✨🦋