lib/perl5/5.8.8/TAP/Parser/SourceHandler/Handle.pm

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