=head1 NAME

Attean::API::PushParser - Role for parsers that natively call a callback function for each parsed item

=head1 VERSION

This document describes Attean::API::PushParser version 0.030

=head1 DESCRIPTION

The Attean::API::PushParser role defines parsers that can efficiently call a
callback function for each object constructed from the parsed data. This role
adds methods that builds on this functionality to allow parsing data using
different approaches.

=head1 ROLES

This role consumes the L<Attean::API::Parser> role.

=head1 REQUIRED METHODS

Classes consuming this role must provide the following methods:

=over 4

=item C<< parse_cb_from_io( $fh ) >>

Calls the C<< $parser->handler >> function once for each object that result
from parsing the data read from the L<IO::Handle> object C<< $fh >>.

=item C<< parse_cb_from_bytes( $data ) >>

Calls the C<< $parser->handler >> function once for each object that result
from parsing the data read from the UTF-8 encoded byte string C<< $data >>.

=back

=head1 METHODS

This role provides default implementations of the following methods:

=over 4

=item C<< parse_iter_from_io( $fh ) >>

Returns an L<Attean::API::Iterator> that result from parsing the data read from
the L<IO::Handle> object C<< $fh >>.

=item C<< parse_iter_from_bytes( $data ) >>

Returns an L<Attean::API::Iterator> that result from parsing the data read from
the UTF-8 encoded byte string C<< $data >>.

=item C<< parse_list_from_io( $fh ) >>

Returns a list of all objects that result from parsing the data read from the
L<IO::Handle> object C<< $fh >>.

=item C<< parse_list_from_bytes( $data ) >>

Returns a list of all objects that result from parsing the data read from the
UTF-8 encoded byte string C<< $data >>.

=back

=head1 BUGS

Please report any bugs or feature requests to through the GitHub web interface
at L<https://github.com/kasei/attean/issues>.

=head1 SEE ALSO



=head1 AUTHOR

Gregory Todd Williams  C<< <gwilliams@cpan.org> >>

=head1 COPYRIGHT

Copyright (c) 2014--2020 Gregory Todd Williams.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

=cut
