Updated documentation, ERADME, scanning, sorting and filter virtual file handles...

[idzebra-moved-to-github.git] / perl / lib / IDZebra / ScanList.pm

diff --git a/perl/lib/IDZebra/ScanList.pm b/perl/lib/IDZebra/ScanList.pm
index 155b1ba..9383f00 100644 (file)
--- a/perl/lib/IDZebra/ScanList.pm
+++ b/perl/lib/IDZebra/ScanList.pm
@@ -1,4 +1,4 @@
-# $Id: ScanList.pm,v 1.1 2003-03-04 19:33:52 pop Exp $
+# $Id: ScanList.pm,v 1.2 2003-03-05 13:55:22 pop Exp $
 # 
 # Zebra perl API header
 # =============================================================================
@@ -13,7 +13,7 @@ BEGIN {
     use IDZebra::ScanEntry;
     use Scalar::Util qw(weaken);
     use Carp;
-    our $VERSION = do { my @r = (q$Revision: 1.1 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; 
+    our $VERSION = do { my @r = (q$Revision: 1.2 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; 
     our @ISA = qw(IDZebra::Logger);
 }
 
@@ -141,10 +141,60 @@ IDZebra::ScanList - Scan results
 
 =head1 SYNOPSIS
 
+  $sl = $sess->scan(expression => "\@attr 1=4 \@attr 6=2 a",
+                   databases => [qw(demo1 demo2)]);
+
+  @entries = $sl->entries(position    => 5,
+                         num_entries => 10);
+
+  print STDERR 
+    $sl->num_entries,','
+    $sl->is_partail,',',
+    $sl->position;
+
+
 =head1 DESCRIPTION
 
+The scan list object is the result of a scan call, and can be used to retrieve entries from the list. To do this, use the B<entries> method,
+
+  @entries = $sl->entries(position    => 5,
+                         num_entries => 10);
+
+returning an array of I<IDZebra::ScanEntry> objects. 
+The possible arguments are:
+
+=over 4
+
+=item B<position>
+
+The requested position of the scanned term in the returned list. For example, if position 5 is given, and the scan term is "a", then the entry corresponding to term "a" will be on the position 5 of the list (4th. elment of the array). It may happen, that due to the position of term in the whole index, it's not possible to put the entry on the requested position (for example, the term is on the 2nd position of the index), this case I<$sl-E<gt>position> will contain a different value, presenting the actual position. The default value is 1.
+
+=item B<num_entries>
+
+The requested number of entries in the list. See I<$sl-E<gt>num_entries> for the actual number of fetched entries. The dafault value is 20.
+
+=back
+
 =head1 PROPERTIES
 
+You can reach the following properties as function calls on the IDZebra::ScanList object:
+
+=over 4
+
+=item B<position>
+
+After calling I<entries>, the actual position of the requested term.
+
+=item B<num_entries>
+
+After calling I<entries>, the actual number of entries returned.
+
+=item B<is_partial>
+
+Only partial list is returned by I<entries>.
+
+=back
+
 =head1 COPYRIGHT
 
 Fill in
@@ -155,6 +205,6 @@ Peter Popovics, pop@technomat.hu
 
 =head1 SEE ALSO
 
-IDZebra, IDZebra::Session, Zebra documentation
+Zebra documentation, IDZebra::Session manpage.
 
 =cut