# ***********************************************
# 
# !!!! 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::Segment - Warehouse for information about one segment of an inverted index.

=head1 SYNOPSIS

    # Index-time.
    package MyDataWriter;
    use base qw( Lucy::Index::DataWriter );

    sub finish {
        my $self     = shift;
        my $segment  = $self->get_segment;
        my $metadata = $self->SUPER::metadata();
        $metadata->{foo} = $self->get_foo;
        $segment->store_metadata(
            key       => 'my_component',
            metadata  => $metadata
        );
    }

    # Search-time.
    package MyDataReader;
    use base qw( Lucy::Index::DataReader );

    sub new {
        my $self     = shift->SUPER::new(@_);
        my $segment  = $self->get_segment;
        my $metadata = $segment->fetch_metadata('my_component');
        if ($metadata) {
            $self->set_foo( $metadata->{foo} );
            ...
        }
        return $self;
    }

=head1 DESCRIPTION

Lucy’s indexes are made up of individual “segments”, each of which is
is an independent inverted index.  On the file system, each segment is a
directory within the main index directory whose name starts with “seg_”:
“seg_2”, “seg_5a”, etc.

Each Segment object keeps track of information about an index segment: its
fields, document count, and so on.  The Segment object itself writes one
file, C<segmeta.json>; besides storing info needed by Segment
itself, the “segmeta” file serves as a central repository for metadata
generated by other index components – relieving them of the burden of
storing metadata themselves.

=head1 METHODS

=head2 add_field

    my $int = $segment->add_field($field);

Register a new field and assign it a field number.  If the field was
already known, nothing happens.

=over

=item *

B<field> - Field name.

=back

Returns: the field’s field number, which is a positive integer.

=head2 store_metadata

    $segment->store_metadata(
        key      => $key,       # required
        metadata => $metadata,  # required
    );

Store arbitrary information in the segment’s metadata hash, to be
serialized later.  Throws an error if C<key> is used twice.

=over

=item *

B<key> - String identifying an index component.

=item *

B<metadata> - JSON-izable data structure.

=back

=head2 fetch_metadata

    my $obj = $segment->fetch_metadata($key);

Fetch a value from the Segment’s metadata hash.

=head2 field_num

    my $int = $segment->field_num($field);

Given a field name, return its field number for this segment (which
may differ from its number in other segments).  Return 0 (an invalid
field number) if the field name can’t be found.

=over

=item *

B<field> - Field name.

=back

=head2 field_name

    my $string = $segment->field_name($field_num);

Given a field number, return the name of its field, or undef
if the field name can’t be found.

=head2 get_name

    my $string = $segment->get_name();

Getter for the object’s seg name.

=head2 get_number

    my $int = $segment->get_number();

Getter for the segment number.

=head2 set_count

    $segment->set_count($count);

Setter for the object’s document count.

=head2 get_count

    my $int = $segment->get_count();

Getter for the object’s document count.

=head2 compare_to

    my $int = $segment->compare_to($other);

Compare by segment number.

=head1 INHERITANCE

Lucy::Index::Segment isa Clownfish::Obj.

=cut

