# ***********************************************
# 
# !!!! DO NOT EDIT !!!!
# 
# This file was auto-generated by Build.PL.
# 
# ***********************************************
# 
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

=encoding utf8

=head1 NAME

Lucy::Index::Snapshot - Point-in-time index file list.

=head1 SYNOPSIS

    my $snapshot = Lucy::Index::Snapshot->new;
    $snapshot->read_file( folder => $folder );    # load most recent snapshot
    my $files = $snapshot->list;
    print "$_\n" for @$files;

=head1 DESCRIPTION

A Snapshot is list of index files and folders.  Because index files, once
written, are never modified, a Snapshot defines a point-in-time view of the
data in an index.

L<IndexReader|Lucy::Index::IndexReader> objects interpret the data
associated with a single Snapshot.

=head1 CONSTRUCTORS

=head2 new

    my $snapshot = Lucy::Index::Snapshot->new;

Constructor.  Takes no arguments.

=head1 METHODS

=head2 list

    my $arrayref = $snapshot->list();

Return an array of all entries.

=head2 num_entries

    my $int = $snapshot->num_entries();

Return the number of entries (including directories).

=head2 add_entry

    $snapshot->add_entry($entry);

Add a filepath to the snapshot.

=head2 delete_entry

    my $bool = $snapshot->delete_entry($entry);

Delete a filepath from the snapshot.

Returns: true if the entry existed and was successfully deleted, false
otherwise.

=head2 read_file

    my $result = $snapshot->read_file(
        folder => $folder  # required
        path   => $path    # default: undef
    );

Decode a snapshot file and initialize the object to reflect its
contents.

=over

=item *

B<folder> - A Folder.

=item *

B<path> - The location of the snapshot file.  If not supplied, the
most recent snapshot file in the base directory will be chosen.

=back

Returns: the Snapshot object itself

=head2 write_file

    $snapshot->write_file(
        folder => $folder  # required
        path   => $path    # default: undef
    );

Write a snapshot file.  The caller must lock the index while this
operation takes place, and the operation will fail if the snapshot file
already exists.

=over

=item *

B<folder> - A Folder.

=item *

B<path> - The path of the file to write.  If undef, a file
name will be chosen which supersedes the latest snapshot file in the
index folder.

=back

=head2 set_path

    $snapshot->set_path($path);

Set the path to the file that the Snapshot object serves as a proxy
for.

=head2 get_path

    my $string = $snapshot->get_path();

Get the path to the snapshot file.  Initially undef; updated
by L<read_file()|/read_file>, L<write_file()|/write_file>, and L<set_path()|/set_path>.

=head1 INHERITANCE

Lucy::Index::Snapshot isa Clownfish::Obj.

=cut