NAME

IO::WithHeader::YAML - read/write YAML header and body in one file

SYNOPSIS

    use IO::WithHeader::YAML;
    
    $io = IO::WithHeader::YAML->new($path_or_filehandle);
    $io = IO::WithHeader::YAML->new(\%header);
    $io = IO::WithHeader::YAML->new(
        'path'   => '/path/to/a/file/which/might/not/exist/yet',
        'handle' => $fh,
        'header' => { 'title' => $title, 'author' => $author, ... },
        'body'   => $scalar_or_filehandle_to_copy_from,
    );
    
    $io->open($path, '>') or die;  # Open the body
    print $io "Something to put in the file's body\n";
    
    $path = $io->path;
    $io->path('/path/to/a/file');
    $io->open or die;
    while (<$io>) { ... }
    
    %header = %{ $io->header };
    $io->header(\%header);
    
    $body = $io->body;  # Read the entire body
    $io->body($body);   # Write the entire body

DESCRIPTION

IO::WithHeader::YAML reads and writes files containing a header in YAML form. The header may be changed without changing the body, and the body may be read from or writen to without disturbing the header.

The file (or filehandle) must begin with the YAML representation of a hash, followed by the YAML end-of-stream marker `...'. The rest of the file or stream can be anything at all. Here's a simple example:

    --- #YAML:1.0
    title: Testing 1, 2, 3
    author: nkuitse
    date: 2004-03-05
    ...
    This is a test.  This is only a test.
    That's all I have to say at this time.
    ^D

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

In this next example, the file's body is empty, as is its header: