<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">package TAP::Parser::Iterator;

use strict;
use warnings;

use base 'TAP::Object';

=head1 NAME

TAP::Parser::Iterator - Base class for TAP source iterators

=head1 VERSION

Version 3.50

=cut

our $VERSION = '3.50';

=head1 SYNOPSIS

  # to subclass:
  use TAP::Parser::Iterator ();
  use base 'TAP::Parser::Iterator';
  sub _initialize {
    # see TAP::Object...
  }

  sub next_raw { ... }
  sub wait     { ... }
  sub exit     { ... }

=head1 DESCRIPTION

This is a simple iterator base class that defines L&lt;TAP::Parser&gt;'s iterator
API.  Iterators are typically created from L&lt;TAP::Parser::SourceHandler&gt;s.

=head1 METHODS

=head2 Class Methods

=head3 C&lt;new&gt;

Create an iterator.  Provided by L&lt;TAP::Object&gt;.

=head2 Instance Methods

=head3 C&lt;next&gt;

 while ( my $item = $iter-&gt;next ) { ... }

Iterate through it, of course.

=head3 C&lt;next_raw&gt;

B&lt;Note:&gt; this method is abstract and should be overridden.

 while ( my $item = $iter-&gt;next_raw ) { ... }

Iterate raw input without applying any fixes for quirky input syntax.

=cut

sub next {
    my $self = shift;
    my $line = $self-&gt;next_raw;

    # vms nit:  When encountering 'not ok', vms often has the 'not' on a line
    # by itself:
    #   not
    #   ok 1 - 'I hate VMS'
    if ( defined($line) and $line =~ /^\s*not\s*$/ ) {
        $line .= ( $self-&gt;next_raw || '' );
    }

    return $line;
}

sub next_raw {
    require Carp;
    my $msg = Carp::longmess('abstract method called directly!');
    $_[0]-&gt;_croak($msg);
}

=head3 C&lt;handle_unicode&gt;

If necessary switch the input stream to handle unicode. This only has
any effect for I/O handle based streams.

The default implementation does nothing.

=cut

sub handle_unicode { }

=head3 C&lt;get_select_handles&gt;

Return a list of filehandles that may be used upstream in a select()
call to signal that this Iterator is ready. Iterators that are not
handle-based should return an empty list.

The default implementation does nothing.

=cut

sub get_select_handles {
    return;
}

=head3 C&lt;wait&gt;

B&lt;Note:&gt; this method is abstract and should be overridden.

 my $wait_status = $iter-&gt;wait;

Return the C&lt;wait&gt; status for this iterator.

=head3 C&lt;exit&gt;

B&lt;Note:&gt; this method is abstract and should be overridden.

 my $wait_status = $iter-&gt;exit;

Return the C&lt;exit&gt; status for this iterator.

=cut

sub wait {
    require Carp;
    my $msg = Carp::longmess('abstract method called directly!');
    $_[0]-&gt;_croak($msg);
}

sub exit {
    require Carp;
    my $msg = Carp::longmess('abstract method called directly!');
    $_[0]-&gt;_croak($msg);
}

1;

=head1 SUBCLASSING

Please see L&lt;TAP::Parser/SUBCLASSING&gt; for a subclassing overview.

You must override the abstract methods as noted above.

=head2 Example

L&lt;TAP::Parser::Iterator::Array&gt; is probably the easiest example to follow.
There's not much point repeating it here.

=head1 SEE ALSO

L&lt;TAP::Object&gt;,
L&lt;TAP::Parser&gt;,
L&lt;TAP::Parser::Iterator::Array&gt;,
L&lt;TAP::Parser::Iterator::Stream&gt;,
L&lt;TAP::Parser::Iterator::Process&gt;,

=cut

</pre></body></html>