IteratorFactory.pm revision 1.1 
1package TAP::Parser::IteratorFactory;
2
3use strict;
4use vars qw($VERSION @ISA);
5
6use TAP::Object                    ();
7use TAP::Parser::Iterator::Array   ();
8use TAP::Parser::Iterator::Stream  ();
9use TAP::Parser::Iterator::Process ();
10
11@ISA = qw(TAP::Object);
12
13=head1 NAME
14
15TAP::Parser::IteratorFactory - Internal TAP::Parser Iterator
16
17=head1 VERSION
18
19Version 3.17
20
21=cut
22
23$VERSION = '3.17';
24
25=head1 SYNOPSIS
26
27  use TAP::Parser::IteratorFactory;
28  my $factory = TAP::Parser::IteratorFactory->new;
29  my $iter = $factory->make_iterator(\*TEST);
30  my $iter = $factory->make_iterator(\@array);
31  my $iter = $factory->make_iterator(\%hash);
32
33  my $line = $iter->next;
34
35=head1 DESCRIPTION
36
37This is a factory class for simple iterator wrappers for arrays, filehandles,
38and hashes.  Unless you're subclassing, you probably won't need to use this
39module directly.
40
41=head1 METHODS
42
43=head2 Class Methods
44
45=head3 C<new>
46
47Creates a new factory class.
48I<Note:> You currently don't need to instantiate a factory in order to use it.
49
50=head3 C<make_iterator>
51
52Create an iterator.  The type of iterator created depends on the arguments to
53the constructor:
54
55  my $iter = TAP::Parser::Iterator->make_iterator( $filehandle );
56
57Creates a I<stream> iterator (see L</make_stream_iterator>).
58
59  my $iter = TAP::Parser::Iterator->make_iterator( $array_reference );
60
61Creates an I<array> iterator (see L</make_array_iterator>).
62
63  my $iter = TAP::Parser::Iterator->make_iterator( $hash_reference );
64
65Creates a I<process> iterator (see L</make_process_iterator>).
66
67=cut
68
69sub make_iterator {
70    my ( $proto, $thing ) = @_;
71
72    my $ref = ref $thing;
73    if ( $ref eq 'GLOB' || $ref eq 'IO::Handle' ) {
74        return $proto->make_stream_iterator($thing);
75    }
76    elsif ( $ref eq 'ARRAY' ) {
77        return $proto->make_array_iterator($thing);
78    }
79    elsif ( $ref eq 'HASH' ) {
80        return $proto->make_process_iterator($thing);
81    }
82    else {
83        die "Can't iterate with a $ref";
84    }
85}
86
87=head3 C<make_stream_iterator>
88
89Make a new stream iterator and return it.  Passes through any arguments given.
90Defaults to a L<TAP::Parser::Iterator::Stream>.
91
92=head3 C<make_array_iterator>
93
94Make a new array iterator and return it.  Passes through any arguments given.
95Defaults to a L<TAP::Parser::Iterator::Array>.
96
97=head3 C<make_process_iterator>
98
99Make a new process iterator and return it.  Passes through any arguments given.
100Defaults to a L<TAP::Parser::Iterator::Process>.
101
102=cut
103
104sub make_stream_iterator {
105    my $proto = shift;
106    TAP::Parser::Iterator::Stream->new(@_);
107}
108
109sub make_array_iterator {
110    my $proto = shift;
111    TAP::Parser::Iterator::Array->new(@_);
112}
113
114sub make_process_iterator {
115    my $proto = shift;
116    TAP::Parser::Iterator::Process->new(@_);
117}
118
1191;
120
121=head1 SUBCLASSING
122
123Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview.
124
125There are a few things to bear in mind when creating your own
126C<ResultFactory>:
127
128=over 4
129
130=item 1
131
132The factory itself is never instantiated (this I<may> change in the future).
133This means that C<_initialize> is never called.
134
135=back
136
137=head2 Example
138
139  package MyIteratorFactory;
140
141  use strict;
142  use vars '@ISA';
143
144  use MyStreamIterator;
145  use TAP::Parser::IteratorFactory;
146
147  @ISA = qw( TAP::Parser::IteratorFactory );
148
149  # override stream iterator
150  sub make_stream_iterator {
151    my $proto = shift;
152    MyStreamIterator->new(@_);
153  }
154
155  1;
156
157=head1 ATTRIBUTION
158
159Originally ripped off from L<Test::Harness>.
160
161=head1 SEE ALSO
162
163L<TAP::Object>,
164L<TAP::Parser>,
165L<TAP::Parser::Iterator>,
166L<TAP::Parser::Iterator::Array>,
167L<TAP::Parser::Iterator::Stream>,
168L<TAP::Parser::Iterator::Process>,
169
170=cut
171
172