/ 
File-ValueFile-v0.03
River stage zero No dependents
/ File::ValueFile::Simple::Reader

NAME

File::ValueFile::Simple::Reader - module for reading and writing ValueFile files

VERSION

version v0.03

SYNOPSIS

use File::ValueFile::Simple::Reader;

This module provides a simple way to read ValueFile files.

METHODS

new

my $reader = File::ValueFile::Simple::Reader->new($in [, %opts ]);

Opens a reader for the given input file. $in can be an open file handle that must support seeking or a filename.

This method dies on any problem.

In addition the following options (all optional) are supported:

supported_formats

The list of supported formats. This can be a single format, a arrayref of formats, or 'all'. Formats can be given by ISE or as Data::Identifier.

supported_features

The list of supported features. This can be a single format, a arrayref of formats, or 'all'. Formats can be given by ISE or as Data::Identifier.

utf8

The UTF-8 flag for the decoded data. If set to true, values are decoded as UTF-8. If set to (non-undef) false values are decoded as 8-bit strings (binary). If set to auto the UTF-8 flag is automatically detected using the format and features. This is the default.

read_to_cb

$reader->read_to_cb(sub {
    my ($reader, @line) = @_;
    # ...
});

Reads the file calling a callback for every data line (record). The callback is passed the reader as first argument and the line as the rest of the arguments.

read_as_hash

my $hashref = $reader->read_as_hash;

Reads the file as a hash. This is only possible if the file contains only key-value pairs. If there are more than one value for any given key this method fails. If that is needed "read_as_hash_of_arrays" can be used.

If there is any error, this method dies.

read_as_hash_of_arrays

my $hashref = $reader->read_as_hash_of_arrays;

Reads the file into a hash of arrays. Each hash element is a reference to an array of all values for the given key. If only one value is valid per key consider using "read_as_hash".

If there is any error, this method dies.

read_as_simple_tree

my $tree = $reader->read_as_simple_tree;

Reads the file into a simple tree. This is similar to "read_as_hash_of_arrays" however allowing for multiple levels of keys. Each element on any of the levels of the tree can be a reference to a hash if there are more levels, a reference to an array if there are multiple values, or a scalar holding the actual value.

For every branch values must be on the same level. Values and subkeys on the same level are not permitted.

If there is any error, this method dies.

read_as_taglist

my $list = $reader->read_as_taglist;

Reads the file as a tag list. Returns the list of found tags as an arrayref of Data::Identifier elements.

This method supports a number of standard formats. If the format is not known the code falls back to a generic handler.

If there is any error, this method dies.

See also: "write_taglist" in File::ValueFile::Simple::Writer.

format

my Data::Identifier $format = $reader->format;
# or:
my Data::Identifier $format = $reader->format(default => $def);

Returns the format of the file. This requires the file to be read first. If no format is set yet the default is returned. If no default is given this method dies.

features

my @features = $reader->features;
# or:
my @features = $reader->features(default => [...]);

Returns the list of features requested by the file. This requires the file to be read first. If no features are requested the default is returned. If no default is given this method dies.

Elements of the list returned are instances Data::Identifier.

AUTHOR

Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2024 by Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)