view release on metacpan or  search on metacpan

lib/File/ValueFile/Simple/Reader.pm  view on Meta::CPAN

# ---- Private helpers ----

sub _unescape_utf8 {
    my ($text) = @_;
    state $utf8 = Encode::find_encoding('UTF-8');
    return $utf8->decode(uri_unescape($text));
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version v0.10

=head1 SYNOPSIS

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

This module provides a simple way to read ValueFile files.

This module inherits from L<Data::Identifier::Interface::Userdata> (since v0.06), and L<Data::Identifier::Interface::Subobjects> (since v0.10).

=head1 METHODS

=head2 new

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

Opens a reader for the given input file.
C<$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:

=over

=item C<supported_formats>

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

=item C<supported_features>

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

=item C<utf8>

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

=back

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

=head2 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 L</read_as_hash_of_arrays> can be used.

If there is any error, this method dies.

=head2 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 L</read_as_hash>.

If there is any error, this method dies.

=head2 read_as_simple_tree

    my $tree = $reader->read_as_simple_tree;

Reads the file into a simple tree. This is similar to L</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.

=head2 read_as_taglist

    my $list = $reader->read_as_taglist( [ %opts ] );

Reads the file as a tag list. Returns the list of found tags as an arrayref of L<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.

The following, all optional, options are supported:

=over