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

NAME

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

VERSION

version v0.03

SYNOPSIS

use File::ValueFile::Simple::Writer;

This module provides a simple way to write ValueFile files.

METHODS

new

my $writer = File::ValueFile::Simple::Writer->new($out [, %opts]);

Opens a writer for the given output file. $out 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:

format

The format to use. Must be an ISE or an instances of Data::Identifier.

required_feature, copy_feature, optional_feature

Features that are used in the file. Required features need to be supported by the reading entity. Copy features are safe to be copied, even if not understood. Optional features do not need to be understood by the reader.

May be a single feature or a list (as array ref). Each feature is given by the ISE or an instances of Data::Identifier.

utf8

The UTF-8 flag for encoding strings. If set true all data with code points outside the ASCII range is encoded as UTF-8. If set (non-undef) false all data is encoded as binary (code points outside the 8 bit range are invalid). If set to auto UTF-8 is enabled based on the set format and features. This is the default.

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 format to be given via "new". If no format is set the default is returned. If no default is given this method dies.

features

my @features = $reader->features;

Returns the list of features of the file. This requires the features to be given via "new".

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

write

$writer->write(@line);

Writes a single line (record). Correctly escapes the output.

Values in @line may be strings, numbers, or instances of Data::Identifier.

write_with_comment

$writer->write_with_comment(@line, $comment);

Write a line alike "write" but finishes the line with a comment. The comment must be a single line comment or undef.

If the comment is undef no comment is written.

For writing comments individually see "write_comment".

write_blank

$writer->write_blank;

Write a blank line. Such lines have no technical meaning, however are sometimes used to make the result more readable.

write_comment

$writer->write_comment($comment [, ...]);

Writes one or more comments. Each comment begins a new line. If a comment contains line breaks it is split into a individual comments. If any comment is undef it is skipped without any warnings.

write_hash

$writer->write_hash($hashref);

Writes a hash as returned by "read_as_hash" in File::ValueFile::Simple::Reader or "read_as_hash_of_arrays" in File::ValueFile::Simple::Reader.

Values in $hashref may be strings, numbers, or instances of Data::Identifier.

write_taglist

$writer->write_taglist($tag [, ...]);
# or:
$writer->write_taglist($arrayref_of_tags);

Writes a taglist using the selected format. The exact output depends on the selected format and features.

This method takes the tags to be written as arguments. If any argument is an arrayref then the tags contained in that arrayref are also written.

A tag here is anything that can be used as input to "new" in Data::Identifier's from. If a given tag uses an identifier that is not supported by the selected format (and features) this method might try to convert or die.

Note: UUIDs are the only identifier type supported by all formats.

If there is any error, this method dies.

See also: "read_as_taglist" in File::ValueFile::Simple::Reader.

write_tag_ise

$writer->write_tag_ise(@ids);

Writes a tag-ise line for the given identifiers. @ids can include raw ISEs or instances of Data::Identifier.

The method will write a most compatible line with a comment if the provided data allows.

write_tag_relation

$writer->write_tag_relation($tag, $relation, $related);
# or:
$writer->write_tag_relation($tag, $relation, $related, $context, $filter);
# or:
$writer->write_tag_relation(tag => $tag, relation => $relation, related => $related [, context => $context ] [, filter => ]);
# or:
$writer->write_tag_relation({tag => $tag, relation => $relation, related => $related [, context => $context ] [, filter => ]});
# or:
$writer->write_tag_relation($link);

Writes a tag-relation line for the given relation. This function is smart and will write the most compatible line possible, including a comment.

Each of $tag, $relation, $related, $context, and $filter must be a raw ISE or an instances of Data::Identifier. $context, and $filter may also be undef.

$link must be any object that implements the methods tag, relation, related, context, and filter. Each method must return the corresponding value in a format as defined above. Each method must also tolerable the options default, no_defaults, and as to be passed (with any value).

write_tag_metadata

$writer->write_tag_metadata($tag, $relation, $data_raw);
# or:
$writer->write_tag_metadata($tag, $relation, $type, $encoding, $data_raw);
# or:
$writer->write_tag_metadata(tag => $tag, relation => $relation, data_raw => $data_raw [, type => $type ] [, encoding => $encoding ] [, context => $context ]);
# or:
$writer->write_tag_metadata({tag => $tag, relation => $relation, data_raw => $data_raw [, type => $type ] [, encoding => $encoding ] [, context => $context ]});
# or:
$writer->write_tag_metadata($link);

Writes a tag-metadata line for the given relation. This function is smart and will write the most compatible line possible, including a comment.

Each of $tag, $relation, $context, $type, and $encoding must be a raw ISE or an instances of Data::Identifier. $context, $type, and $encoding may also be undef.

$raw_data must be a value allowed by "write".

$link must be any object that implements the methods tag, relation, context, type, and encoding. Each method must return the corresponding value in a format as defined above. Each method must also tolerable the options default, no_defaults, and as to be passed (with any value).

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)