view release on metacpan or  search on metacpan

lib/Datafile/Hash.pm  view on Meta::CPAN

      comment => ['Auto-generated - do not edit manually', scalar localtime],
  });

=head1 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.

=head1 FUNCTIONS

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

Loads key-value data into a hash reference.

Returns:
  ($entry_count, \@messages, \%groups_seen)

C<$entry_count>    - number of key-value pairs read
C<\@messages>      - informational/warning messages
C<\%groups_seen>   - hashref of section names encountered (only in INI mode)

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

Writes hash data back to file.

Returns:
  ($entry_count, \@messages)

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

=head1 OPTIONS

=over 4

=item delimiter => '=' (default)

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

=item group => 2 (default)

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

=item key_fields => 1 (default)

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

Ignored in INI mode (forced to 1).

=item skip_empty => 1 (default)

Skip blank lines.

=item skip_headers => 0 (default)

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

=item comment_char => '#' (default)

Character marking comment lines.

=item search => undef (default)

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

=item verbose => 0 (default)

Include detailed messages in return arrayref.

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

Rename existing file to .bak.

=item comment => undef (writehash only)

String or arrayref of comment lines to write at top.

=item prot => 0660 (default) (writehash only)

File permissions (octal) for new file.

=back

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)