cpan/Test-Harness/lib/TAP/Parser/SourceHandler/Handle.pm

   1 package TAP::Parser::SourceHandler::Handle;
   2
   3 use strict;
   4 use warnings;
   5
   6 use TAP::Parser::IteratorFactory  ();
   7 use TAP::Parser::Iterator::Stream ();
   8
   9 use base 'TAP::Parser::SourceHandler';
  10
  11 TAP::Parser::IteratorFactory->register_handler(__PACKAGE__);
  12
  13 =head1 NAME
  14
  15 TAP::Parser::SourceHandler::Handle - Stream TAP from an IO::Handle or a GLOB.
  16
  17 =head1 VERSION
  18
  19 Version 3.31
  20
  21 =cut
  22
  23 our $VERSION = '3.31';
  24
  25 =head1 SYNOPSIS
  26
  27   use TAP::Parser::Source;
  28   use TAP::Parser::SourceHandler::Executable;
  29
  30   my $source = TAP::Parser::Source->new->raw( \*TAP_FILE );
  31   $source->assemble_meta;
  32
  33   my $class = 'TAP::Parser::SourceHandler::Handle';
  34   my $vote  = $class->can_handle( $source );
  35   my $iter  = $class->make_iterator( $source );
  36
  37 =head1 DESCRIPTION
  38
  39 This is a I<raw TAP stored in an IO Handle> L<TAP::Parser::SourceHandler> class.  It
  40 has 2 jobs:
  41
  42 1. Figure out if the L<TAP::Parser::Source> it's given is an L<IO::Handle> or
  43 GLOB containing raw TAP output (L</can_handle>).
  44
  45 2. Creates an iterator for IO::Handle's & globs (L</make_iterator>).
  46
  47 Unless you're writing a plugin or subclassing L<TAP::Parser>, you probably
  48 won't need to use this module directly.
  49
  50 =head1 METHODS
  51
  52 =head2 Class Methods
  53
  54 =head3 C<can_handle>
  55
  56   my $vote = $class->can_handle( $source );
  57
  58 Casts the following votes:
  59
  60   0.9 if $source is an IO::Handle
  61   0.8 if $source is a glob
  62
  63 =cut
  64
  65 sub can_handle {
  66     my ( $class, $src ) = @_;
  67     my $meta = $src->meta;
  68
  69     return 0.9
  70       if $meta->{is_object}
  71           && UNIVERSAL::isa( $src->raw, 'IO::Handle' );
  72
  73     return 0.8 if $meta->{is_glob};
  74
  75     return 0;
  76 }
  77
  78 =head3 C<make_iterator>
  79
  80   my $iterator = $class->make_iterator( $source );
  81
  82 Returns a new L<TAP::Parser::Iterator::Stream> for the source.
  83
  84 =cut
  85
  86 sub make_iterator {
  87     my ( $class, $source ) = @_;
  88
  89     $class->_croak('$source->raw must be a glob ref or an IO::Handle')
  90       unless $source->meta->{is_glob}
  91           || UNIVERSAL::isa( $source->raw, 'IO::Handle' );
  92
  93     return $class->iterator_class->new( $source->raw );
  94 }
  95
  96 =head3 C<iterator_class>
  97
  98 The class of iterator to use, override if you're sub-classing.  Defaults
  99 to L<TAP::Parser::Iterator::Stream>.
 100
 101 =cut
 102
 103 use constant iterator_class => 'TAP::Parser::Iterator::Stream';
 104
 105 1;
 106
 107 =head1 SUBCLASSING
 108
 109 Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview.
 110
 111 =head1 SEE ALSO
 112
 113 L<TAP::Object>,
 114 L<TAP::Parser>,
 115 L<TAP::Parser::Iterator>,
 116 L<TAP::Parser::Iterator::Stream>,
 117 L<TAP::Parser::IteratorFactory>,
 118 L<TAP::Parser::SourceHandler>,
 119 L<TAP::Parser::SourceHandler::Executable>,
 120 L<TAP::Parser::SourceHandler::Perl>,
 121 L<TAP::Parser::SourceHandler::File>,
 122 L<TAP::Parser::SourceHandler::RawTAP>
 123
 124 =cut