view release on metacpan or  search on metacpan

lib/File/Raw/Separated.pm  view on Meta::CPAN

=item Individual names

Any of the nine bare names listed above can be requested directly;
each lands as C<file_E<lt>nameE<gt>>.

=back

=head1 ROW-AV ALIASING (callback variants)

C<file_parse_buf_each>, C<file_parse_stream> (and their dialect-pinned
counterparts) hand the callback the SAME arrayref every row, with its
contents replaced. Stash a copy if you need to retain the row across
calls:

    file_parse_buf_each($buf, sub {
        my $row = [@{$_[0]}];   # explicit copy
        push @keep, $row;
    });

Header mode uses a fresh hashref per row, so the aliasing only affects
the array-form callback path.

=head1 STREAMING

C<file_parse_stream> opens the file at the C level (PerlLIO_open) and
reads in 64 KiB chunks, feeding each to the parser's incremental API.
RSS is bounded by the read buffer + C<max_field_len> regardless of
total file size.

To abort mid-stream, C<die> from the callback. The exception
propagates; the file descriptor and parser state are cleaned up on
every exit path.

=head1 PLUGIN INTEGRATION WITH FILE::RAW

Loading C<File::Raw::Separated> registers two plugins with File::Raw
via C<file_register_plugin> (declared in C<include/file_plugin.h>):

=over 4

=item *

C<csv> plugin - CSV defaults (sep C<,>, quote C<">). READ phase fires
from C<File::Raw::slurp($p, plugin =E<gt> 'csv', ...)>, returning AoA
(or AoH under C<header =E<gt> 1>).

=item *

C<tsv> plugin - TSV defaults (sep C<\t>, no quoting).

=back

The plugins register at module load and stay registered for the life
of the process. Per-call options arrive through File::Raw's variadic
XSUB plumbing; there is no global state to mutate. To opt out for a
particular call, just don't pass C<plugin =E<gt>>.

The WRITE / RECORD / STREAM phases are not yet wired - they will land
once the parser core grows a serialiser and File::Raw teaches
C<each_line>, C<grep_lines>, etc. the plugin pipeline. In the meantime
use C<parse_stream> for streaming directly.

=head1 SEE ALSO

L<File::Raw> - the underlying fast file IO layer.

=head1 AUTHOR

LNATION <email@lnation.org>

=head1 LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

=cut