NAME

Datafile::Hash - Pure-Perl utilities for datafiles and INI-style config files with multi-level sections

LICENSE

This module is free software.

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

SYNOPSIS

use Datafile::Hash qw(readhash writehash);

my %config;

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

# $config{section}{subsection}{key} = 'value'

# Flat key-value file example
readhash('settings.txt', \%config, {
    delimiter => '=',      # still INI mode
    group     => 0,        # flat hash, ignore sections
});

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

DESCRIPTION

Lightweight pure-Perl module for reading and writing key-value data files, including full INI-style files with multi-level sections. Supports flat files, dotted-key notation, or true nested hashes. Safe atomic writes and consistent error handling.

FUNCTIONS

readhash($filename, $hash_ref, \%options)

Loads key-value data into a hash reference.

Returns: ($entry_count, \@messages)

$entry_count - number of key-value pairs read \@messages - informational/warning messages

writehash($filename, $hash_ref, \%options)

Writes hash data back to file.

Returns: ($entry_count, \@messages)

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

OPTIONS

delimiter => '=' (default)

Key-value separator. If '=' or ':' → full INI mode with sections and quoting. Any other delimiter → flat key-value mode (no sections).

group => 2 (default)

How to handle sections: 0 - ignore sections, flat hash 1 - dotted keys (section.sub.key) 2 - nested hashes (recommended for INI)

key_fields => 1 (default)

Number of leading fields to use as key (only used in flat mode).

Ignored in INI mode (forced to 1).

skip_empty => 1 (default)

Skip blank lines.

skip_headers => 0 (default)

Number of leading lines to skip (e.g., BOM or banner).

comment_char => '#' (default)

Character marking comment lines.

search => undef (default)

String, regex, or arrayref — only matching lines are processed.

verbose => 0 (default)

Include detailed messages in return arrayref.

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

Rename existing file to .bak.

comment => undef (writehash only)

String or arrayref of comment lines to write at top.

prot => 0660 (default) (writehash only)

File permissions (octal) for new file.

INI mode automatically handles: - Section headers [section.subsection] - Quoted values with escaped quotes (\") - Proper value quoting on write when needed (contains special chars, newlines, leading/trailing space, or empty)