File Coverage

blib/lib/TAP/Parser/Iterator.pm
Criterion Covered Total %
statement 15 24 62.5
branch 2 2 100.0
condition 5 5 100.0
subroutine 6 9 66.6
pod 6 6 100.0
total 34 46 73.9


line stmt bran cond sub pod time code
1             package TAP::Parser::Iterator;
2              
3 39     39   2061 use strict;
  39         42  
  39         938  
4 39     39   123 use warnings;
  39         38  
  39         857  
5              
6 39     39   126 use base 'TAP::Object';
  39         754  
  39         10457  
7              
8             =head1 NAME
9              
10             TAP::Parser::Iterator - Base class for TAP source iterators
11              
12             =head1 VERSION
13              
14             Version 3.38
15              
16             =cut
17              
18             our $VERSION = '3.38';
19              
20             =head1 SYNOPSIS
21              
22             # to subclass:
23             use TAP::Parser::Iterator ();
24             use base 'TAP::Parser::Iterator';
25             sub _initialize {
26             # see TAP::Object...
27             }
28              
29             sub next_raw { ... }
30             sub wait { ... }
31             sub exit { ... }
32              
33             =head1 DESCRIPTION
34              
35             This is a simple iterator base class that defines L's iterator
36             API. Iterators are typically created from Ls.
37              
38             =head1 METHODS
39              
40             =head2 Class Methods
41              
42             =head3 C
43              
44             Create an iterator. Provided by L.
45              
46             =head2 Instance Methods
47              
48             =head3 C
49              
50             while ( my $item = $iter->next ) { ... }
51              
52             Iterate through it, of course.
53              
54             =head3 C
55              
56             B this method is abstract and should be overridden.
57              
58             while ( my $item = $iter->next_raw ) { ... }
59              
60             Iterate raw input without applying any fixes for quirky input syntax.
61              
62             =cut
63              
64             sub next {
65 1675     1675 1 6792 my $self = shift;
66 1675         5746 my $line = $self->next_raw;
67              
68             # vms nit: When encountering 'not ok', vms often has the 'not' on a line
69             # by itself:
70             # not
71             # ok 1 - 'I hate VMS'
72 1673 100 100     15467 if ( defined($line) and $line =~ /^\s*not\s*$/ ) {
73 4   100     18 $line .= ( $self->next_raw || '' );
74             }
75              
76 1673         4486 return $line;
77             }
78              
79             sub next_raw {
80 0     0 1 0 require Carp;
81 0         0 my $msg = Carp::longmess('abstract method called directly!');
82 0         0 $_[0]->_croak($msg);
83             }
84              
85             =head3 C
86              
87             If necessary switch the input stream to handle unicode. This only has
88             any effect for I/O handle based streams.
89              
90             The default implementation does nothing.
91              
92             =cut
93              
94       10 1   sub handle_unicode { }
95              
96             =head3 C
97              
98             Return a list of filehandles that may be used upstream in a select()
99             call to signal that this Iterator is ready. Iterators that are not
100             handle-based should return an empty list.
101              
102             The default implementation does nothing.
103              
104             =cut
105              
106             sub get_select_handles {
107 10     10 1 28 return;
108             }
109              
110             =head3 C
111              
112             B this method is abstract and should be overridden.
113              
114             my $wait_status = $iter->wait;
115              
116             Return the C status for this iterator.
117              
118             =head3 C
119              
120             B this method is abstract and should be overridden.
121              
122             my $wait_status = $iter->exit;
123              
124             Return the C status for this iterator.
125              
126             =cut
127              
128             sub wait {
129 0     0 1   require Carp;
130 0           my $msg = Carp::longmess('abstract method called directly!');
131 0           $_[0]->_croak($msg);
132             }
133              
134             sub exit {
135 0     0 1   require Carp;
136 0           my $msg = Carp::longmess('abstract method called directly!');
137 0           $_[0]->_croak($msg);
138             }
139              
140             1;
141              
142             =head1 SUBCLASSING
143              
144             Please see L for a subclassing overview.
145              
146             You must override the abstract methods as noted above.
147              
148             =head2 Example
149              
150             L is probably the easiest example to follow.
151             There's not much point repeating it here.
152              
153             =head1 SEE ALSO
154              
155             L,
156             L,
157             L,
158             L,
159             L,
160              
161             =cut
162