TAP::Parser::Source(3p) Perl Programmers Reference Guide

TAP::Parser::Source(3p) Perl Programmers Reference Guide #

TAP::Parser::Source(3p) Perl Programmers Reference Guide

NNAAMMEE #

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

VVEERRSSIIOONN #

 Version 3.44

SSYYNNOOPPSSIISS #

   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

DDEESSCCRRIIPPTTIIOONN #

 A TAP _s_o_u_r_c_e is something that produces a stream of TAP for the parser to
 consume, such as an executable file, a text file, an archive, an IO
 handle, a database, etc.  "TAP::Parser::Source"s encapsulate these _r_a_w
 sources, and provide some useful meta data about them.  They are used by
 TAP::Parser::SourceHandlers, which do whatever is required to produce &
 capture a stream of TAP from the _r_a_w source, and package it up in a
 TAP::Parser::Iterator for the parser to consume.

 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.

MMEETTHHOODDSS #

CCllaassss MMeetthhooddss _"_n_e_w_"

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

 Returns a new "TAP::Parser::Source" object.

IInnssttaannccee MMeetthhooddss _"_r_a_w_"

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

 Chaining getter/setter for the raw TAP source.  This is a reference, as
 it may contain large amounts of data (eg: raw TAP).

 _"_m_e_t_a_"

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

 Chaining getter/setter for meta data about the source.  This defaults to
 an empty hashref.  See "assemble_meta" for more info.

 _"_h_a_s___m_e_t_a_"

 True if the source has meta data.

 _"_c_o_n_f_i_g_"

   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.  This defaults to an
 empty hashref.  See "config_for" for more info.

 _"_m_e_r_g_e_"

   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.

 _"_s_w_i_t_c_h_e_s_"

   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.

 _"_t_e_s_t___a_r_g_s_"

   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.

 _"_a_s_s_e_m_b_l_e___m_e_t_a_"

   my $meta = $source->assemble_meta;

 Gathers meta data about the "raw" source, stashes it in "meta" and
 returns it as a hashref.  This is done so that the
 TAP::Parser::SourceHandlers don't have to repeat common checks.
 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,

 _"_s_h_e_b_a_n_g_"

 Get the shebang line for a script file.

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

 May be called as a class method

 _"_c_o_n_f_i_g___f_o_r_"

   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.

AAUUTTHHOORRSS #

 Steve Purkis.

SSEEEE AALLSSOO #

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

perl v5.36.3 2023-02-15 TAP::Parser::Source(3p)