Update Test-Harness to CPAN version 3.39
[perl.git] / cpan / Test-Harness / lib / TAP / Parser / SourceHandler / RawTAP.pm
1 package TAP::Parser::SourceHandler::RawTAP;
2
3 use strict;
4 use warnings;
5
6 use TAP::Parser::IteratorFactory ();
7 use TAP::Parser::Iterator::Array ();
8
9 use base 'TAP::Parser::SourceHandler';
10
11 TAP::Parser::IteratorFactory->register_handler(__PACKAGE__);
12
13 =head1 NAME
14
15 TAP::Parser::SourceHandler::RawTAP - Stream output from raw TAP in a scalar/array ref.
16
17 =head1 VERSION
18
19 Version 3.39
20
21 =cut
22
23 our $VERSION = '3.39';
24
25 =head1 SYNOPSIS
26
27   use TAP::Parser::Source;
28   use TAP::Parser::SourceHandler::RawTAP;
29
30   my $source = TAP::Parser::Source->new->raw( \"1..1\nok 1\n" );
31   $source->assemble_meta;
32
33   my $class = 'TAP::Parser::SourceHandler::RawTAP';
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 output> L<TAP::Parser::SourceHandler> - it has 2 jobs:
40
41 1. Figure out if the L<TAP::Parser::Source> it's given is raw TAP output
42 (L</can_handle>).
43
44 2. Creates an iterator for raw TAP output (L</make_iterator>).
45
46 Unless you're writing a plugin or subclassing L<TAP::Parser>, you probably
47 won't need to use this module directly.
48
49 =head1 METHODS
50
51 =head2 Class Methods
52
53 =head3 C<can_handle>
54
55   my $vote = $class->can_handle( $source );
56
57 Only votes if $source is an array, or a scalar with newlines.  Casts the
58 following votes:
59
60   0.9  if it's a scalar with '..' in it
61   0.7  if it's a scalar with 'ok' in it
62   0.3  if it's just a scalar with newlines
63   0.5  if it's an array
64
65 =cut
66
67 sub can_handle {
68     my ( $class, $src ) = @_;
69     my $meta = $src->meta;
70
71     return 0 if $meta->{file};
72     if ( $meta->{is_scalar} ) {
73         return 0 unless $meta->{has_newlines};
74         return 0.9 if ${ $src->raw } =~ /\d\.\.\d/;
75         return 0.7 if ${ $src->raw } =~ /ok/;
76         return 0.3;
77     }
78     elsif ( $meta->{is_array} ) {
79         return 0.5;
80     }
81     return 0;
82 }
83
84 =head3 C<make_iterator>
85
86   my $iterator = $class->make_iterator( $source );
87
88 Returns a new L<TAP::Parser::Iterator::Array> for the source.
89 C<$source-E<gt>raw> must be an array ref, or a scalar ref.
90
91 C<croak>s on error.
92
93 =cut
94
95 sub make_iterator {
96     my ( $class, $src ) = @_;
97     my $meta = $src->meta;
98
99     my $tap_array;
100     if ( $meta->{is_scalar} ) {
101         $tap_array = [ split "\n" => ${ $src->raw } ];
102     }
103     elsif ( $meta->{is_array} ) {
104         $tap_array = $src->raw;
105     }
106
107     $class->_croak('No raw TAP found in $source->raw')
108       unless scalar $tap_array;
109
110     return TAP::Parser::Iterator::Array->new($tap_array);
111 }
112
113 1;
114
115 =head1 SUBCLASSING
116
117 Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview.
118
119 =head1 SEE ALSO
120
121 L<TAP::Object>,
122 L<TAP::Parser>,
123 L<TAP::Parser::IteratorFactory>,
124 L<TAP::Parser::SourceHandler>,
125 L<TAP::Parser::SourceHandler::Executable>,
126 L<TAP::Parser::SourceHandler::Perl>,
127 L<TAP::Parser::SourceHandler::File>,
128 L<TAP::Parser::SourceHandler::Handle>
129
130 =cut