Update Test-Harness to CPAN version 3.39
[perl.git] / cpan / Test-Harness / lib / TAP / Parser / SourceHandler / File.pm
1 package TAP::Parser::SourceHandler::File;
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::File - Stream TAP from a text file.
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::File;
29
30   my $source = TAP::Parser::Source->new->raw( \'file.tap' );
31   $source->assemble_meta;
32
33   my $class = 'TAP::Parser::SourceHandler::File';
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 a file> L<TAP::Parser::SourceHandler> - it has 2 jobs:
40
41 1. Figure out if the I<raw> source it's given is a file containing raw TAP
42 output.  See L<TAP::Parser::IteratorFactory> for more details.
43
44 2. Takes raw TAP from the text file given, and converts into an 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 looks like a regular file.  Casts the following votes:
58
59   0.9 if it's a .tap file
60   0.9 if it has an extension matching any given in user config.
61
62 =cut
63
64 sub can_handle {
65     my ( $class, $src ) = @_;
66     my $meta   = $src->meta;
67     my $config = $src->config_for($class);
68
69     return 0 unless $meta->{is_file};
70     my $file = $meta->{file};
71     return 0.9 if $file->{lc_ext} eq '.tap';
72
73     if ( my $exts = $config->{extensions} ) {
74         return 0.9 if grep { lc($_) eq $file->{lc_ext} } @$exts;
75     }
76
77     return 0;
78 }
79
80 =head3 C<make_iterator>
81
82   my $iterator = $class->make_iterator( $source );
83
84 Returns a new L<TAP::Parser::Iterator::Stream> for the source.  C<croak>s
85 on error.
86
87 =cut
88
89 sub make_iterator {
90     my ( $class, $source ) = @_;
91
92     $class->_croak('$source->raw must be a scalar ref')
93       unless $source->meta->{is_scalar};
94
95     my $file = ${ $source->raw };
96     my $fh;
97     open( $fh, '<', $file )
98       or $class->_croak("error opening TAP source file '$file': $!");
99     return $class->iterator_class->new($fh);
100 }
101
102 =head3 C<iterator_class>
103
104 The class of iterator to use, override if you're sub-classing.  Defaults
105 to L<TAP::Parser::Iterator::Stream>.
106
107 =cut
108
109 use constant iterator_class => 'TAP::Parser::Iterator::Stream';
110
111 1;
112
113 __END__
114
115 =head1 CONFIGURATION
116
117   {
118    extensions => [ @case_insensitive_exts_to_match ]
119   }
120
121 =head1 SUBCLASSING
122
123 Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview.
124
125 =head1 SEE ALSO
126
127 L<TAP::Object>,
128 L<TAP::Parser>,
129 L<TAP::Parser::SourceHandler>,
130 L<TAP::Parser::SourceHandler::Executable>,
131 L<TAP::Parser::SourceHandler::Perl>,
132 L<TAP::Parser::SourceHandler::Handle>,
133 L<TAP::Parser::SourceHandler::RawTAP>
134
135 =cut