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