vcs.maemo.org Git - dh-make-perl/blob - dev/i386/libtest-harness-perl/libtest-harness-perl-3.12/lib/TAP/Parser/Iterator.pm

   1 package TAP::Parser::Iterator;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA);
   5
   6 use TAP::Object ();
   7
   8 @ISA = qw(TAP::Object);
   9
  10 =head1 NAME
  11
  12 TAP::Parser::Iterator - Internal base class for TAP::Parser Iterators
  13
  14 =head1 VERSION
  15
  16 Version 3.12
  17
  18 =cut
  19
  20 $VERSION = '3.12';
  21
  22 =head1 SYNOPSIS
  23
  24   # see TAP::Parser::IteratorFactory for general usage
  25
  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   }
  33
  34 =head1 DESCRIPTION
  35
  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.
  39
  40 =head1 METHODS
  41
  42 =head2 Class Methods
  43
  44 =head3 C<new>
  45
  46 Create an iterator.  Provided by L<TAP::Object>.
  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
  58 B<Note:> this method is abstract and should be overridden.
  59
  60  while ( my $item = $iter->next_raw ) { ... }
  61
  62 Iterate raw input without applying any fixes for quirky input syntax.
  63
  64 =cut
  65
  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
  81 sub next_raw {
  82     require Carp;
  83     my $msg = Carp::longmess('abstract method called directly!');
  84     $_[0]->_croak($msg);
  85 }
  86
  87
  88 =head3 C<handle_unicode>
  89
  90 If necessary switch the input stream to handle unicode. This only has
  91 any effect for I/O handle based streams.
  92
  93 The default implementation does nothing.
  94
  95 =cut
  96
  97 sub handle_unicode { }
  98
  99
 100 =head3 C<get_select_handles>
 101
 102 Return a list of filehandles that may be used upstream in a select()
 103 call to signal that this Iterator is ready. Iterators that are not
 104 handle-based should return an empty list.
 105
 106 The default implementation does nothing.
 107
 108 =cut
 109
 110 sub get_select_handles {
 111     return;
 112 }
 113
 114
 115 =head3 C<wait>
 116
 117 B<Note:> this method is abstract and should be overridden.
 118
 119  my $wait_status = $iter->wait;
 120
 121 Return the C<wait> status for this iterator.
 122
 123 =head3 C<exit>
 124
 125 B<Note:> this method is abstract and should be overridden.
 126
 127  my $wait_status = $iter->exit;
 128
 129 Return the C<exit> status for this iterator.
 130
 131 =cut
 132
 133 sub wait {
 134     require Carp;
 135     my $msg = Carp::longmess('abstract method called directly!');
 136     $_[0]->_croak($msg);
 137 }
 138
 139 sub exit {
 140     require Carp;
 141     my $msg = Carp::longmess('abstract method called directly!');
 142     $_[0]->_croak($msg);
 143 }
 144
 145
 146 1;
 147
 148 =head1 SUBCLASSING
 149
 150 Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview.
 151
 152 You must override the abstract methods as noted above.
 153
 154 =head2 Example
 155
 156 L<TAP::Parser::Iterator::Array> is probably the easiest example to follow.
 157 There's not much point repeating it here.
 158
 159 =head1 SEE ALSO
 160
 161 L<TAP::Object>,
 162 L<TAP::Parser>,
 163 L<TAP::Parser::IteratorFactory>,
 164 L<TAP::Parser::Iterator::Array>,
 165 L<TAP::Parser::Iterator::Stream>,
 166 L<TAP::Parser::Iterator::Process>,
 167
 168 =cut
 169