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
# Automatically add "...\n" at end of each document written
$io->auto_terminate(1);
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, each
of which may (optionally) be terminated by a line consisting solely of
three periods ("...").
The first line of each document must begin with the three-byte sequence
"---".
Here's a simple YAML file 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
^D
(Here, "^D" indicates the end of the file.)
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.
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>;
...
}
IO::YAML properly recognizes the document terminator ("..."). Some
versions of YAML do not recognize it, however; in order to prevent
problems when reading YAML streams with auto-loading off, IO::YAML
strips the document terminator line if it is present.
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.
Terminating YAML documents
Documents in a YAML stream may be terminated by a line consisting solely
of the string "...". You can use the "terminate" method to add an
explicit document terminator to a YAML stream that you have open for
writing (or appending):
$io = IO::YAML->new($file_or_handle, '>');
foreach my $value (@data_values) {
print $io $value;
$io->terminate;
}
It's generally safer to have YAML documents terminated automatically:
# 1. Set auto_terminate to a true value
# a) When creating the object
$io = IO::YAML->new(
'handle' => $fh,
'mode' => '>>',
'auto_terminate' => 1,
);
# or b) At any point thereafter
$io = IO::YAML->new(...);
$io->auto_terminate(1);
# 2. Documents are now auto-terminated
foreach my $value (@data_values) {
print $io $value;
# $io->terminate called implicitly
}
Note that it's not the YAML *stream* that's terminated; it's the YAML
document that was previously written.
Low-level access
Sometimes it is helpful to be able to access a YAML stream at a lower
level. For example, you may wish to read and write a file consisting of
a YAML document (here, serving as a header of sorts) followed by
arbitrary text. The "handle" method may be used to obtain the underlying
file handle so that it can be used for this low-level access:
# Read header + body
$io->auto_load(1);
$header = <$io>;
$fh = $io->handle;
while (<$fh>) {
# Process each line after the YAML document
}
# Write header + body
$io->auto_terminate(1);
print $io $header;
$fh = $io->handle;
for (@other_stuff_to_write) {
print $fh $_;
}
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.
*auto_load*
Indicates whether YAML document values should be auto-loaded
after being read (see above). The default is not to auto-load
values.
*auto_terminate*
Indicates whether YAML documents should be auto-terminated when
they are written (see above). The default is not to
auto-terminate documents.
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.
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-2007, 2009 Paul M. Hoffman.
This is free software, and is made available under the same terms as
Perl itself.