/ 
File-ValueFile-v0.07
River stage one • 1 direct dependent • 1 total dependent
/ File::ValueFile::Simple::Writer

NAME

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

VERSION

version v0.07

SYNOPSIS

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

This module provides a simple way to write ValueFile files.

This module inherit from Data::Identifier::Interface::Userdata.

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.

style

(since v0.07)

A hashref with values as can be passed to "style".

format

my Data::Identifier $format = $writer->format;
# or:
my Data::Identifier $format = $writer->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 = $writer->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.

style

$writer->style($style0 => $value0 [, $style1 = $value1 [, ...] ] );
# or:
my $value = $writer->style($style);

(since v0.07)

Gets or sets styles for the current writer. This method dies if it detects any error.

The following styles are supported:

degenerate_generator_hint

Whether or not degenerate to "write_tag_ise" if a call to "write_tag_generator_hint" is incomplete (no generator or hint provided). One of undef (default) or 'auto'.

generator_hint

The style to use for generator hints (see "write_tag_generator_hint"). One of 'auto' (default) or 'tag-generator-hint'.

tag_ise_no_ise_retry

The list of retry values to use if "write_tag_ise" cannot find a valid ISE for any of the given identifiers. One of undef (default) to disable retries, uuid, oid, or uri to use the UUID, OID, or URI, or all to try them all. May also be a arrayref of the values listed above.

tag_ise_no_ise_one

Whether or not use only the first usable value if tag_ise_no_ise_retry is active. Boolean, default true (only use the first).

tag_ise_no_ise_no_uriid

Whether or not https://uriid.org/ backup values should be skipped if tag_ise_no_ise_retry is active. Boolean, default true.

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);
# or:
$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).

write_tag_generator_hint

$writer->write_tag_generator_hint($tag, $generator, $hint);
# or:
$writer->write_tag_generator_hint($tag); # requires Data::Identifier v0.13

Write a generator hint for the given $generator and $hint values. $tag and $generator may be an ISE or an instances of Data::Identifier. $hint is the raw hint.

If only $tag is given the other values will be extracted if $tag is a Data::Identifier and includes them.

This method automatically selects the best command to write depending on the format and features.

write_tagname

$writer->write_tagname($tag, $tagname);

Writes the given tagname for the given tag. If $tagname is undef or an empty string this method will silently return without error.

This method automatically selects the best command to write depending on the format and features.

Note: The tagname to be written is subject to normal character set rules. Therefore it should be a perl unicode string (not UTF-8 encoded).

AUTHOR

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

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)