$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:
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.
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*.
