moose-class/exercises/t/lib/TAP/Parser/IteratorFactory.pm

   1 package TAP::Parser::IteratorFactory;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA);
   5
   6 use TAP::Object                    ();
   7 use TAP::Parser::Iterator::Array   ();
   8 use TAP::Parser::Iterator::Stream  ();
   9 use TAP::Parser::Iterator::Process ();
  10
  11 @ISA = qw(TAP::Object);
  12
  13 =head1 NAME
  14
  15 TAP::Parser::IteratorFactory - Internal TAP::Parser Iterator
  16
  17 =head1 VERSION
  18
  19 Version 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
  37 This is a factory class for simple iterator wrappers for arrays, filehandles,
  38 and hashes.  Unless you're subclassing, you probably won't need to use this
  39 module directly.
  40
  41 =head1 METHODS
  42
  43 =head2 Class Methods
  44
  45 =head3 C<new>
  46
  47 Creates a new factory class.
  48 I<Note:> You currently don't need to instantiate a factory in order to use it.
  49
  50 =head3 C<make_iterator>
  51
  52 Create an iterator.  The type of iterator created depends on the arguments to
  53 the constructor:
  54
  55   my $iter = TAP::Parser::Iterator->make_iterator( $filehandle );
  56
  57 Creates a I<stream> iterator (see L</make_stream_iterator>).
  58
  59   my $iter = TAP::Parser::Iterator->make_iterator( $array_reference );
  60
  61 Creates an I<array> iterator (see L</make_array_iterator>).
  62
  63   my $iter = TAP::Parser::Iterator->make_iterator( $hash_reference );
  64
  65 Creates a I<process> iterator (see L</make_process_iterator>).
  66
  67 =cut
  68
  69 sub 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
  89 Make a new stream iterator and return it.  Passes through any arguments given.
  90 Defaults to a L<TAP::Parser::Iterator::Stream>.
  91
  92 =head3 C<make_array_iterator>
  93
  94 Make a new array iterator and return it.  Passes through any arguments given.
  95 Defaults to a L<TAP::Parser::Iterator::Array>.
  96
  97 =head3 C<make_process_iterator>
  98
  99 Make a new process iterator and return it.  Passes through any arguments given.
 100 Defaults to a L<TAP::Parser::Iterator::Process>.
 101
 102 =cut
 103
 104 sub make_stream_iterator {
 105     my $proto = shift;
 106     TAP::Parser::Iterator::Stream->new(@_);
 107 }
 108
 109 sub make_array_iterator {
 110     my $proto = shift;
 111     TAP::Parser::Iterator::Array->new(@_);
 112 }
 113
 114 sub make_process_iterator {
 115     my $proto = shift;
 116     TAP::Parser::Iterator::Process->new(@_);
 117 }
 118
 119 1;
 120
 121 =head1 SUBCLASSING
 122
 123 Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview.
 124
 125 There are a few things to bear in mind when creating your own
 126 C<ResultFactory>:
 127
 128 =over 4
 129
 130 =item 1
 131
 132 The factory itself is never instantiated (this I<may> change in the future).
 133 This 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
 159 Originally ripped off from L<Test::Harness>.
 160
 161 =head1 SEE ALSO
 162
 163 L<TAP::Object>,
 164 L<TAP::Parser>,
 165 L<TAP::Parser::Iterator>,
 166 L<TAP::Parser::Iterator::Array>,
 167 L<TAP::Parser::Iterator::Stream>,
 168 L<TAP::Parser::Iterator::Process>,
 169
 170 =cut
 171