GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  IO::YAML (3)

.ds Aq ’

NAME

IO::YAML - read and write YAML streams incrementally

CONTENTS

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

<B>IO::YAMLB> 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 <B>notB> 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 "Couldnt 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

<B>newB>


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

<B>NOTE:B> 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 <B>notB> to auto-load values.
auto_terminate Indicates whether YAML documents should be auto-terminated when they are written (see above). The default is <B>notB> to auto-terminate documents.

<B>openB>


    $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 <B>newB>.

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

<B>closeB>


    $io->close or die $!;



Close the filehandle.

<B>printB>


    $io->print($data) or die $!;



<B>getlineB>
<B>getlinesB>
<B>seekB>


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

<B>tellB>


    $pos = $io->tell;



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

<B>truncateB>


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

<B>eofB>


    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 <B>seekB> and <B>tellB> 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 IO::YAML (3) 2016-03-17

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.