.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Lucy::Index::IndexReader 3pm"
.TH Lucy::Index::IndexReader 3pm "2015-03-06" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lucy::Index::IndexReader \- Read from an inverted index.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    my $reader = Lucy::Index::IndexReader\->open(
\&        index => \*(Aq/path/to/index\*(Aq,
\&    );
\&    my $seg_readers = $reader\->seg_readers;
\&    for my $seg_reader (@$seg_readers) {
\&        my $seg_name = $seg_reader\->get_segment\->get_name;
\&        my $num_docs = $seg_reader\->doc_max;
\&        print "Segment $seg_name ($num_docs documents):\en";
\&        my $doc_reader = $seg_reader\->obtain("Lucy::Index::DocReader");
\&        for my $doc_id ( 1 .. $num_docs ) {
\&            my $doc = $doc_reader\->fetch_doc($doc_id);
\&            print "  $doc_id: $doc\->{title}\en";
\&        }
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
IndexReader is the interface through which
IndexSearcher objects access the
content of an index.
.PP
IndexReader objects always represent a point-in-time view of an index as it
existed at the moment the reader was created.  If you want search results
to reflect modifications to an index, you must create a new IndexReader
after the update process completes.
.PP
IndexReaders are composites; most of the work is done by individual
DataReader sub-components, which may be
accessed via \fIfetch()\fR and \fIobtain()\fR.  The most efficient and powerful access
to index data happens at the segment level via
SegReader's sub-components.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "open( \fI[labeled params]\fP )"
.IX Subsection "open( [labeled params] )"
.Vb 5
\&    my $reader = Lucy::Index::IndexReader\->open(
\&        index    => \*(Aq/path/to/index\*(Aq, # required
\&        snapshot => $snapshot,
\&        manager  => $index_manager,
\&    );
.Ve
.PP
IndexReader is an abstract base class; \fIopen()\fR returns the IndexReader
subclass PolyReader, which channels the output of 0 or more SegReaders.
.IP "\(bu" 4
\&\fBindex\fR \- Either a string filepath or a Folder.
.IP "\(bu" 4
\&\fBsnapshot\fR \- A Snapshot.  If not supplied, the most recent snapshot
file will be used.
.IP "\(bu" 4
\&\fBmanager\fR \- An IndexManager.
Read-locking is off by default; supplying this argument turns it on.
.SH "ABSTRACT METHODS"
.IX Header "ABSTRACT METHODS"
.SS "\fIdoc_max()\fP"
.IX Subsection "doc_max()"
Return the maximum number of documents available to the reader, which
is also the highest possible internal document id.  Documents which
have been marked as deleted but not yet purged from the index are
included in this count.
.SS "\fIdoc_count()\fP"
.IX Subsection "doc_count()"
Return the number of documents available to the reader, subtracting
any that are marked as deleted.
.SS "\fIdel_count()\fP"
.IX Subsection "del_count()"
Return the number of documents which have been marked as deleted but
not yet purged from the index.
.SS "\fIseg_readers()\fP"
.IX Subsection "seg_readers()"
Return an array of all the SegReaders represented within the
IndexReader.
.SS "\fIoffsets()\fP"
.IX Subsection "offsets()"
Return an array with one entry for each segment, corresponding to
segment doc_id start offset.
.SH "METHODS"
.IX Header "METHODS"
.SS "fetch(api)"
.IX Subsection "fetch(api)"
Fetch a component, or return undef if the component can't be found.
.IP "\(bu" 4
\&\fBapi\fR \- The name of the DataReader subclass that the desired
component must implement.
.SS "obtain(api)"
.IX Subsection "obtain(api)"
Fetch a component, or throw an error if the component can't be found.
.IP "\(bu" 4
\&\fBapi\fR \- The name of the DataReader subclass that the desired
component must implement.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
Lucy::Index::IndexReader isa Lucy::Index::DataReader isa Lucy::Object::Obj.