view release on metacpan or  search on metacpan

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

    my $rows = file_slurp("data.csv", plugin => 'csv');
    my $rows = file_slurp("data.csv", plugin => 'csv', sep => ';', strict => 1);
    my $rows = file_slurp("data.tsv", plugin => 'tsv');
    my $text = file_slurp("readme.txt"); # no plugin => raw bytes

=head1 OPTIONS

Every parse function and every C<plugin =E<gt> 'csv'|'tsv'> dispatch
accepts the same set of trailing keys.

=over 4

=item C<dialect>

C<csv> (default for the unified C<parse_*> functions) or C<tsv>.
Selects the seeded defaults for C<sep> and C<quote>; any explicit keys
you also set override the dialect's defaults. The C<plugin =E<gt> ...>
form picks the dialect by plugin name; C<dialect> in that case is
ignored.

=item C<sep>

Single-byte field separator. Default C<,> for CSV, C<\t> for TSV.

=item C<quote>

Single-byte quote character. Default C<"> for CSV, disabled for TSV.
Pass C<undef> to disable quoting (every quote becomes literal data).

=item C<escape>

Single-byte backslash-style escape character. When set, inside a
quoted field the escape char consumes the next byte literally. Default
C<undef> (RFC 4180 doubled-quote escape only).

=item C<strict>

If true, croaks on malformed input (stray quote mid-field, unbalanced
quotes, EOL mismatch under pinned C<eol>). Error message includes byte
offset (and file path for C<parse_stream>). Default false (lenient
recovery).

=item C<eol>

One of C<auto>, C<lf>, C<crlf>, C<cr>. Default C<auto>: locks to the
first detected terminator and stays in that mode for the rest of the
parse. Pinning a non-matching EOL under C<strict> croaks.

=item C<trim>

Strip leading/trailing ASCII space and tab from B<unquoted> fields
only. Quoted fields preserve all bytes. Default false.

=item C<empty_is_undef>

Empty unquoted field becomes C<undef>. Quoted empty (C<"">) stays the
empty string. Default false (always returns C<"">).

=item C<binary>

Skip UTF-8 BOM stripping and skip C<sv_utf8_decode> on each field.
Default false.

=item C<header>

Controls whether rows are emitted as arrayrefs (default) or hashrefs.
Two forms:

=over 4

=item C<< header => 1 >>

The first emitted row is consumed as field names; subsequent rows are
emitted as hashrefs keyed by those names. Use when the file has its
own header line.

=item C<< header => [qw(name age city)] >>

Caller supplies the names. The parser does B<not> consume any row as
a header - row 0 is treated as data and emitted as a hashref against
the supplied names. Use when the file has no header line of its own.
The arrayref must be non-empty, contain no C<undef> entries, and have
no duplicates (each is checked at call time and croaks otherwise).

=back

In either form: a row with more fields than the header croaks; a
shorter row pads missing keys with C<undef>. Default false (arrayref
rows).

=item C<max_field_len>

Cap on a single field's byte length. Exceeding the cap croaks with
C<field exceeds max length>. Default 16 MiB.

=back

=head1 IMPORT

C<import> is an XSUB (installed at BOOT). Each requested name is
stamped into the caller's package as C<file_E<lt>nameE<gt>> via
C<newXS> - the same mechanism L<File::Raw> uses, so the two modules
compose without colliding (C<file_slurp> from File::Raw,
C<file_parse_buf> from here, etc.).

The C<file_> prefix is added by the importer; you request names
B<without> it. Unknown names produce a warning, not a die.

=over 4

=item C<import>

Bareword shorthand for C<:all> - matches the L<File::Raw> idiom
C<use File::Raw qw(import)>.

=item C<:all>

All nine names. Equivalent to C<:unified :csv :tsv>.

=item C<:unified>