Datafile::Simple - README

Datafile::Simple is a lightweight pure-Perl distribution containing two complementary modules for handling common data files:

• Datafile::Array – For tabular/delimited data (like CSV or fixed-format files)
• Datafile::Hash – For key-value and INI-style configuration files with sections

Both modules share the same design philosophy:

• No external dependencies
• Safe atomic writes (temp file + rename)
• Consistent return values and error handling
• Verbose messaging support
• UTF-8 encoding

Installation

perl Makefile.PL
make
make test
make install

Modules

Datafile::Array

Handles reading and writing delimited data files with optional CSV quoting, headers, and prefix lines.

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,        # full CSV support with multi-line
    has_headers  => 1,
    prefix       => 1,        # H/R prefix mode
    trim_values  => 1,
    verbose      => 1,
});

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

# Standalone CSV parsing
my @parts = parse_csv_line('a,"b,c","d""e"', ',');

FUNCTIONS

• readarray($file, $data_ref, $fields_ref, %opts)
  Returns ($record_count, \@messages)

• writearray($file, $data_ref, $fields_ref, %opts)
  Returns ($record_count, \@messages)

• parse_csv_line($line, [$delimiter = ','])
  Lightweight standalone CSV line parser.
  Handles quoted fields, escaped quotes (""), fields containing delimiter/newlines.
  Lenient on unclosed quotes. Returns array of fields.

KEY OPTIONS

• delimiter => ';' (default)
• csvquotes => 0 | 1 (enable full CSV parsing)
• has_headers => 1 (expect header line(s))
• prefix => 0 | 1 (H/R line prefix mode)
• key_fields => 1 (composite keys for hash mode)
• trim_values => 1
• comment_char => '#'
• skip_empty => 1
• search => undef (filter lines)
• verbose => 0
• header => 0 | 1 (writearray: write header)
• backup => 0 | 1 (writearray: keep .bak)
• prot => 0660 (writearray: file permissions)
• comment => undef (writearray: top comments)

Datafile::Hash

Handles flat key-value files and full INI-style files with multi-level sections.

SYNOPSIS

use Datafile::Hash qw(readhash writehash);

my %config;

# INI with nested sections
readhash('config.ini', \%config, {
    delimiter => '=',      # triggers INI mode
    group     => 2,        # nested hashes (default)
});

# $config{database}{host} = 'localhost'

# Flat file
readhash('settings.txt', \%config, {
    delimiter => '=',
    group     => 0,        # ignore sections, flat hash
});

writehash('config.ini', \%config, {
    backup  => 1,
    comment => ['Auto-generated', scalar localtime],
});

FUNCTIONS

• readhash($file, $hash_ref, %opts)
  Returns ($entry_count, \@messages)

• writehash($file, $hash_ref, %opts)
  Returns ($entry_count, \@messages)

KEY OPTIONS

• delimiter => '=' (default)
  '=' or ':' → INI mode with sections and quoting
  Anything else → flat key-value mode
• group => 2 (default)
  0 = flat hash (ignore sections)
  1 = dotted keys (section.sub.key)
  2 = nested hashes (recommended)
• key_fields => 1 (flat mode only)
• skip_empty => 1
• skip_headers => 0 (skip leading banner lines)
• comment_char => '#'
• search => undef
• verbose => 0
• backup => 0 | 1 (writehash)
• comment => undef (writehash: top comments)
• prot => 0660 (writehash)

INI mode features:

• [section.subsection] headers
• Quoted values with escaped quotes (")
• Automatic quoting on write when needed

Common Features

Both modules:

• Use UTF-8 encoding
• Skip comment lines (default #)
• Support search filtering
• Return verbose messages when requested
• Perform safe atomic writes
• Gracefully handle I/O errors (return errors instead of die)

License

This module is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

See the official Perl licensing terms: https://dev.perl.org/licenses/