/*
 * Copyright (c) 2009 Zmanda, Inc.  All Rights Reserved.
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 as published
 * by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
 *
 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
 */

%perlcode %{

=head1 NAME

Amanda::Tapelist - manipulate the Amanda tapelist

=head1 SYNOPSIS

    use Amanda::Tapelist;

    # to get a read only copy of the tapelist file:
    my $tl = Amanda::Tapelist->new("/path/to/tapefile");

    # to read/update/write the tapelist file
    # read and take lock
    my $tl = Amanda::Tapelist->new("/path/to/tapefile", 1);
    # modify the memory copy
    $tl->add_tapelabel($datestamp, $label);
    $tl->add_tapelabel($datestamp2, $label2, $comment, 1);
    # write it and unlock
    $tl->write();

    # If you already have a read only copy and want to modify it
    # take a read only copy
    my $tl = Amanda::Tapelist->new("/path/to/tapefile");
    # reload and take lock
    $tl->reload(1);
    # modify the memory copy
    tl->add_tapelabel($datestamp, $label);
    $tl->add_tapelabel($datestamp2, $label2, $comment, 1);
    # write it and unlock
    $tl->write();

=head1 OBJECT-ORIENTED INTERFACE

C<new> returns a hash with no C<tles> set if the tapelist does
not exist. C<tles> is an empty array if the tapelist is empty.
Invalid entries are silently ignored.

=head2 tapelist object

A tapelist object is a hash with the following keys:

=over

=item C<filename>

  The filename of the tapelist file.

=item C<filename_lock>

  The filename of the lock file.

=item C<fl>

  A Amanda::Util::file_lock is the file is locked.

=item C<tles>

A sequence of tapelist elements (referred to as TLEs in this document),
sorted by datestamp from newest to oldest.

=back

=head2 tapelist element

A tapelist elementas a hash with the following keys:

=over

=item C<position>

the one-based position of the TLE in the tapelist

=item C<datestamp>

the datestamp on which this was written, or "0" for an unused tape

=item C<reuse>

true if this tape can be reused when it is no longer active

=item C<label>

tape label

=item C<comment>

the comment for this tape, or undef if no comment was given

=back

=head1 Method

The following methods are available on a tapelist object C<$tl>:

=over

=item C<relod($lock)>

reload the tapelist file, lock it if $lock is set

=item C<lookup_tapelabel($lbl)>

look up and return a reference to the TLE with the given label

=item C<lookup_tapepos($pos)>

look up and return a reference to the TLE in the given position

=item C<lookup_tapedate($date)>

look up and return a reference to the TLE with the given datestamp

=item C<remove_tapelabel($lbl)>

remove the tape with the given label

=item C<add_tapelabel($date, $lbl, $comment, $reuse)>

add a tape with the given date, label, comment and reuse to the end of the
tapelist. reuse can be 1 or undef for a reusable volume, it must be 0 for
a no-reusable volume.

=item C<write()> or C<write($filename)>

write the tapelist out to the same file as when read or to C<$filename> if it
is set, remove the lock if a lock was taken

=item C<unlock()>

remove the lock if a lock was taken

=item C<clear_tapelist()>

remove all tle from the tles.

=back

=head1 INTERACTION WITH C CODE

The C portions of Amanda treat the tapelist as a global variable,
while this package treats it as an object (and can thus handle more
than one tapelist simultaneously).  Every call to C<reload>
fills this global variable with a copy of the tapelist, and likewise
C<clear_tapelist> clears the global.  However, any changes made from
Perl are not reflected in the C copy, nor are changes made by C
modules reflected in the Perl copy.

=cut


%}