cpan/Test-Harness/lib/TAP/Parser/Iterator.pm

   1 package TAP::Parser::Iterator;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base 'TAP::Object';
   7
   8 =head1 NAME
   9
  10 TAP::Parser::Iterator - Base class for TAP source iterators
  11
  12 =head1 VERSION
  13
  14 Version 3.42
  15
  16 =cut
  17
  18 our $VERSION = '3.42';
  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<TAP::Parser>'s iterator
  36 API.  Iterators are typically created from L<TAP::Parser::SourceHandler>s.
  37
  38 =head1 METHODS
  39
  40 =head2 Class Methods
  41
  42 =head3 C<new>
  43
  44 Create an iterator.  Provided by L<TAP::Object>.
  45
  46 =head2 Instance Methods
  47
  48 =head3 C<next>
  49
  50  while ( my $item = $iter->next ) { ... }
  51
  52 Iterate through it, of course.
  53
  54 =head3 C<next_raw>
  55
  56 B<Note:> 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     my $self = shift;
  66     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     if ( defined($line) and $line =~ /^\s*not\s*$/ ) {
  73         $line .= ( $self->next_raw || '' );
  74     }
  75
  76     return $line;
  77 }
  78
  79 sub next_raw {
  80     require Carp;
  81     my $msg = Carp::longmess('abstract method called directly!');
  82     $_[0]->_croak($msg);
  83 }
  84
  85 =head3 C<handle_unicode>
  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 sub handle_unicode { }
  95
  96 =head3 C<get_select_handles>
  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     return;
 108 }
 109
 110 =head3 C<wait>
 111
 112 B<Note:> this method is abstract and should be overridden.
 113
 114  my $wait_status = $iter->wait;
 115
 116 Return the C<wait> status for this iterator.
 117
 118 =head3 C<exit>
 119
 120 B<Note:> this method is abstract and should be overridden.
 121
 122  my $wait_status = $iter->exit;
 123
 124 Return the C<exit> status for this iterator.
 125
 126 =cut
 127
 128 sub wait {
 129     require Carp;
 130     my $msg = Carp::longmess('abstract method called directly!');
 131     $_[0]->_croak($msg);
 132 }
 133
 134 sub exit {
 135     require Carp;
 136     my $msg = Carp::longmess('abstract method called directly!');
 137     $_[0]->_croak($msg);
 138 }
 139
 140 1;
 141
 142 =head1 SUBCLASSING
 143
 144 Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview.
 145
 146 You must override the abstract methods as noted above.
 147
 148 =head2 Example
 149
 150 L<TAP::Parser::Iterator::Array> is probably the easiest example to follow.
 151 There's not much point repeating it here.
 152
 153 =head1 SEE ALSO
 154
 155 L<TAP::Object>,
 156 L<TAP::Parser>,
 157 L<TAP::Parser::Iterator::Array>,
 158 L<TAP::Parser::Iterator::Stream>,
 159 L<TAP::Parser::Iterator::Process>,
 160
 161 =cut
 162