NAME

File::Kvpar - read and write files containing key-value paragraphs

SYNOPSIS

    $kv = File::Kvpar->new($file);
    $kv = File::Kvpar->new($mode, $file);  # $mode = '<' || '>' || ...
    $kv = File::Kvpar->new($fh);
    $iter = $kv->iter;
    while ($elem = &$iter) {
        ...
    }
    @a = $kv->elements;
    $a = $kv->head;
    @a = $kv->tail;
    foreach ($kv->elements) {
        ...
    }

DESCRIPTION

A kvpar file consists of zero or more paragraphs (delimited by blank lines). Each line in a paragraph has the form KEY VAL; the key and value are separated by a single space (ASCII character 32).

A single element may have the form @STR VAL -- if it does, the element's hash will be augmented with the key/value pairs ( @ => STR, # => VAL ). No further interpretation is made, but one use of this might be to treat STR as the object's type and VAL as the object's primary key.

METHODS

new

    $kv = File::Kvpar->new($file);
    $kv = File::Kvpar->new($mode, $file);
    $kv = File::Kvpar->new($fh);

Open or create a kvpar-formatted file.

$mode defaults to < if a file path is the only argument.

For greater control, pass a filehandle as the only argument. Passing both a mode and filehandle will cause an exception to be thrown.

iter

    $iter = $kv->iter;
    while ($hash = &$iter) { ... }
    while ($hash = $iter->()) { ... }

Return a CODE reference that may be invoked to obtain the next element in the file. It returns the undefined value if all elements have been read.

elements

Return a list (not an array reference) of all elements in the file. Any unread elements will be read.

head

Return the first element in the file. It will be read if it hasn't already been.

tail

    @elems = $kv->tail;

Return a list of all elements after the first. Any unread elements will be read.

write

    $kv->write(@hashes);

Write @hashes to the current position in the file. The file will be truncated afterwards, since the alternative would totally mess up files in most cases. The file must have been opened for write access, of course.

append

    $kv->append(@hashes);

Write @hashes to the end of the file. The file must have been opened for write access, of course.

truncate

    $kv = File::Kvpar->new('<+', $file);
    $kv->head;  # Read and discard the first element
    $kv->truncate;
    $kv->write({...});

Truncate the file at the current position and discard any elements that may have been read at or after the current position. If nothing has been read from the file, the file will become empty.

reset

    $kv->reset;

Set the file position to 0 -- i.e., seek to the beginning of the file -- and discard any elements that have already been read. If the file has been opened for write access, the next write will truncate it. If it has been opened for append access, the next append will wreak havoc unless you call truncate first.

This will throw an exception if the underlying filehandle is not seekable.