/ 
IO-YAML-0.04
River stage zero No dependents
/ IO::YAML

NAME

IO::YAML - read and write YAML streams incrementally

SYNOPSIS

use IO::YAML;

$io = IO::YAML->new($path_or_filehandle);
$io = IO::YAML->new(
    'path'      => '/path/to/a/file',
    'auto_load' => $bool,
);
$io = IO::YAML->new(
    'handle' => $fh,
    'mode'   => '>',  # or 'w'; '<' or 'r'; '>>' or 'a'
);

$io = IO::YAML->new;
$io->open($path, '>')  or die $!;  # Open a stream for writing
$io->open($path, '>>') or die $!;  # Open a stream for appending

print $io $mystring;
print $io @myvalues;
print $io \@myarray;
print $io \%myhash;
print $io $myobj;

$io = IO::YAML->new;
$io->open($path, '<')  or die $!;  # Open a stream for reading
while (<$io>) {
    $data = YAML::Load($_);
}

$io = IO::YAML->new;
$io->open($path) or die $!;  # Default mode is reading
$io->auto_load(1);
while (not $io->eof) {
    $data = <$io>;
}

$io = IO::YAML->new($path_or_handle);
$io->auto_load(1);
my @values = <$io>;  # Roughly equivalent to YAML::LoadFile(...)

DESCRIPTION

IO::YAML may be used to read and write YAML streams one document (i.e., one value) at a time.

A YAML stream is a file consisting of a sequence of YAML documents; the stream may optionally be followed by the end-of-stream marker (a line consisting solely of the three-byte sequence "..."), after which any sequence of bytes may occur (and will be ignored).

The first line of each document must begin with the three-byte sequence ---.

Here's a simple example consisting of three documents; their values are the string 'foo', an empty array, and a hash with three elements:

--- #YAML:1.0 foo
--- #YAML:1.0 []
--- #YAML:1.0
title: Testing 1, 2, 3
author: nkuitse
date: 2004-03-05
...
Blah blah blah,
These lines aren't part
of the YAML stream
and will be ignored.
^D

(Here, ^D indicates the end of the file.)

Unlike the current version of YAML, IO::YAML properly recognizes the stream terminator (...) and ignores the following lines.

In this next example, the stream consists of a single YAML document whose value is undef:

--- ~
^D

As this example shows, the first line in each document need not contain the full YAML 1.0 header; nor must the stream contain the end-of-stream marker.

Reading from a YAML stream

To read from a YAML stream, you may use the angle-brackets operator (e.g., <$fh>) or the equivalent methods getline or read. Rather than reading a single line, this will read an entire YAML document.

while(defined(my $yaml = <$io>)) {
    my $value = YAML::Load($yaml);
    ...
}

The YAML::Load step may be omitted by setting the IO::YAML object's auto_load property to a true value:

$io->auto_load(1);
while(defined(my $value = <$io>)) {
    ...
}

However, this example is complicated by the fact that the value of a YAML document may be undef; the loop as written will terminate when the end of the stream is reached or when an undef value is read.

To avoid this problem while still taking advantage of the auto_load property, use $io->eof to test for the end of the stream:

$io->auto_load(1);
while(not $io->eof) {
    my $value = <$io>;
    ...
}

Writing to a YAML stream

To print to a YAML stream, call print just as you would with a regular file handle; the value(s) you're printing will be converted to YAML format before being written:

$io = IO::YAML->new;
$io->open('>file') or die "Couldn't open 'file'";
print $io $anything;

You can `print' anything that YAML is capable of serializing; an exception will be raised if you attempt to print something that can't be serialized (e.g., a reference to a subroutine).

The complication with undef values that affects the reading of a YAML stream is not an issue when writing to a YAML stream.

Reading and writing beyond the end of the YAML stream

If a YAML stream is terminated by a line consisting solely of three periods (...), you can read beyond the terminator by doing this:

$io->auto_load(1);
while(not $io->eof) {
    my $value = <$io>;
    ...
}
$fh = $io->handle;
while (<$fh>) {
    ...
}

The ... line will be skipped. Thus, to echo a YAML stream and any following lines, do this:

$io = IO::YAML->new(...);
$io->auto_load(1);
while (not $io->eof) {
    $data = <$io>;
    print YAML::Dump($data);
}
$fh = $io->handle;
unless ($fh->eof) {
    print "...\n";
    while (<$fh>) {
        print;
    }
}

You can also use the terminate method to add an explicit end-of-stream marker ("..." on a line by itself) to a YAML stream that you have open for writing (or appending), and (if you wish) use the underlying file handle to write beyond the end of stream marker:

$io = IO::YAML->new($file_or_handle, '>');
print $io @data_values;
$io->terminate;
$fh = $io->handle;
print $fh @extra_stuff;

METHODS

new
$io = IO::YAML->new;

# Concise forms
$io = IO::YAML->new("$file");     # Default is read-only
$io = IO::YAML->new("<$file");    # Read-only made explicit
$io = IO::YAML->new(">$file");    # Read-write (empty header & body)
$io = IO::YAML->new($file, '<');  # Or '>', '+<', 'r', etc.
$io = IO::YAML->new(\*STDIN);
$io = IO::YAML->new(\*STDOUT, '>');
$io = IO::YAML->new($anything_that_isa_GLOB);

# Full-fledged forms
$io = IO::YAML->new(
    'path' => $file,        # File will be opened read-only
    'auto_load' => 1,       # Default is 0
);
$io = IO::YAML->new(
    'path' => $file,        # File will be opened or created
    'mode' => '>',          # Default is '<'; '>>' is also allowed
);

Instantiate an IO::YAML object. An exception is thrown if anything goes wrong.

If a path is specified, the file at that path will be opened. Otherwise, you'll have to open it yourself using the open() method.

If a path has been specified and the file doesn't already exist, it will be created -- but only if you've specified a mode that permits writing; if you haven't, an exception will be thrown.

The following arguments may be specified in the constructor:

path

Path to a file to create (if it doesn't already exist) and open.

mode

Read/write/append mode for the new file. This must be specified in one of the following forms:

<
>
>>
r
w
a

Modes that allow for both reading and writing are not allowed, since YAML documents are variable in size.

NOTE: Numeric modes are not yet implemented.

open
$io = IO::YAML->new;
$io->open("<$file") or die $!;
$io->open($file, $mode) or die $!;

Open a file with the specified name and mode. You must use this method if the instance was created without a path element (and one has not been assigned using the path() method).

Upon failure, sets $! to a meaningful message and returns a false value.

The possible modes are as described for new.

The open() method may be called repeatedly on the same instance, without having to close it.

close
$io->close or die $!;

Close the filehandle.

print
$io->print($data) or die $!;
getline
getlines
seek
$io->seek($pos, $whence);

Set the IO::YAML file handle's position in bytes within the YAML stream. This will fail unless it moves the position to the beginning of a YAML document or the end of the whole file handle.

tell
$pos = $io->tell;

Return the the IO::YAML file handle's position in bytes.

truncate
$io->truncate(0);
$io->truncate($io->tell);

Truncates the IO::YAML file to the specified length. As illustrated here, this must be either 0 or equal to the filehandle's current position.

eof
if ($io->eof) { ... }

Return 1 if the IO::YAML filehandle is at the end of the YAML stream. This may or may not be the actual end of the filehandle, since a YAML stream may be followed by a terminator (... on a line by itself) and any number of additional bytes.

BUGS

Autoflush might not be working.

Seeking to the first position beyond the end of the YAML stream should be possible but doesn't currently work.

TO DO

Normalize modes passed in the constructor.

Implement numeric modes.

Add tests for seek and tell methods.

Enable seeking to the first byte beyond the end of the YAML stream.

Figure out how to allow read-write access and truncate().

SEE ALSO

YAML

AUTHOR

Paul Hoffman (nkuitse AT cpan DOT org)

COPYRIGHT

Copyright 2004-2006 Paul M. Hoffman.

This is free software, and is made available under the same terms as Perl itself.