/ 
Datafile-Array-1.05
/ Datafile::Array

NAME

Datafile::Array - Pure-Perl utilities for reading and writing delimited data files

LICENSE

This module is free software.

You can redistribute it and/or modify it under the same terms as Perl itself.

SYNOPSIS

use Datafile::Array qw(readarray writearray parse_csv_line);

my @records;
my @fields;

my ($count, $msgs) = readarray('data.txt', \@records, \@fields, {
    delimiter    => ';',
    csvquotes    => 1,        # enable proper CSV quoted fields and multi-line
    has_headers  => 1,
    prefix       => 1,        # expect 'H' header and 'R' data lines
    trim_values  => 1,
    verbose      => 1,
});

# @records now contains array of hashes
# @fields contains the detected or provided field names

writearray('data.txt', \@records, \@fields, {
    header  => 1,
    prefix  => 1,
    backup  => 1,
    comment => 'Exported on ' . scalar localtime,
});

DESCRIPTION

Lightweight pure-Perl module for reading and writing simple delimited data files. Supports optional CSV-style quoted fields (including multi-line records), automatic or explicit headers, prefix lines (H/R convention), search filtering, trimming, and safe atomic writes.

FUNCTIONS

readarray($filename, $data_ref, $fields_ref, \%options)

Loads delimited data into an array of hashes (or hash of hashes if using keys).

Returns two values: ($record_count, \@messages)

$record_count - number of data records read \@messages - arrayref of informational/warning messages (especially when verbose => 1)

writearray($filename, $data_ref, $fields_ref, \%options)

Writes data back to file safely (using temporary file + rename).

Returns two values: ($record_count, \@messages)

On I/O error, returns (0, \@error_messages) instead of dying.

parse_csv_line($line, [$delimiter = ','])

Standalone lightweight CSV line parser.

Parses a single line according to CSV rules: - Handles quoted fields - Escaped quotes via "" - Fields containing delimiter, newlines, or quotes - Lenient on unclosed quotes (treats rest as literal)

Returns array of fields.

Example: my @fields = parse_csv_line(q{hello,"world","say ""hi"""}, ','); # @fields = ('hello', 'world', 'say "hi"')

OPTIONS

delimiter => ';' (default)

Field separator character.

csvquotes => 0 (default) | 1

Enable full CSV quoted-field parsing, including escaped quotes (""), fields containing delimiter/newlines, and multi-line records.

has_headers => 1 (default)

Number of header lines to expect (or skip if prefix used). Set to 0 if no header.

prefix => 0 (default) | 1

Enable H/R prefix mode: first field of header line must be 'H', data lines 'R'.

key_fields => 1 (default)

Number of leading fields to use as composite key when loading into a hash.

trim_values => 1 (default)

Trim whitespace from all field values.

comment_char => '#' (default)

Character that marks comment lines (skipped).

skip_empty => 1 (default)

Skip blank lines.

search => undef (default)

String, regex, or arrayref of patterns. Only lines matching ALL patterns are processed.

verbose => 0 (default)

Include detailed progress messages in returned arrayref.

header => 0 (default) | 1 (writearray only)

Write header line (field names).

backup => 0 (default) | 1 (writearray only)

Rename existing file to .bak before overwriting.

prot => 0660 (default) (writearray only)

File permissions for new file (octal).

comment => undef (writearray only)

String or arrayref of comment lines to write at top.