perl/lib/IDZebra/ScanList.pm

   1 # $Id: ScanList.pm,v 1.2 2003-03-05 13:55:22 pop Exp $
   2 #
   3 # Zebra perl API header
   4 # =============================================================================
   5 package IDZebra::ScanList;
   6
   7 use strict;
   8 use warnings;
   9
  10 BEGIN {
  11     use IDZebra;
  12     use IDZebra::Logger qw(:flags :calls);
  13     use IDZebra::ScanEntry;
  14     use Scalar::Util qw(weaken);
  15     use Carp;
  16     our $VERSION = do { my @r = (q$Revision: 1.2 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
  17     our @ISA = qw(IDZebra::Logger);
  18 }
  19
  20 1;
  21 # -----------------------------------------------------------------------------
  22 # Class constructors, destructor
  23 # -----------------------------------------------------------------------------
  24 sub new {
  25     my ($proto,$session, %args) = @_;
  26     my $class = ref($proto) || $proto;
  27     my $self = {};
  28     bless ($self, $class);
  29
  30     $self->{session} = $session;
  31     weaken ($self->{session});
  32
  33     $self->{expression} = $args{expression};
  34     $self->{databases} = $args{databases};
  35
  36     $self->{so} = IDZebra::ScanObj->new();
  37
  38     $self->{odr_stream} = IDZebra::odr_createmem($IDZebra::ODR_DECODE);
  39
  40     $self->entries(num_entries => 0);
  41
  42     return ($self);
  43 }
  44
  45 sub DESTROY {
  46     my $self = shift;
  47
  48     if ($self->{odr_stream}) {
  49         IDZebra::odr_reset($self->{odr_stream});
  50         IDZebra::odr_destroy($self->{odr_stream});
  51         $self->{odr_stream} = undef;
  52     }
  53
  54     delete($self->{so});
  55     delete($self->{session});
  56 }
  57
  58 # =============================================================================
  59 sub is_partial {
  60     my ($self) = @_;
  61     return ($self->{so}{is_partial});
  62 }
  63
  64 sub position {
  65     my ($self) = @_;
  66     return ($self->{so}{position});
  67 }
  68
  69 sub num_entries {
  70     my ($self) = @_;
  71     return ($self->{so}{num_entries});
  72 }
  73
  74 sub errCode {
  75     my ($self) = @_;
  76     return ($self->{session}->errCode);
  77 }
  78
  79 sub errString {
  80     my ($self) = @_;
  81     return ($self->{session}->errString);
  82 }
  83
  84 # -----------------------------------------------------------------------------
  85 sub entries {
  86     my ($self, %args) = @_;
  87
  88     unless ($self->{session}{zh}) {
  89         croak ("Session is closed or out of scope");
  90     }
  91
  92     my $so=$self->{so};
  93
  94     $so->{position}    = defined($args{position})    ? $args{position}    : 1;
  95     $so->{num_entries} = defined($args{num_entries}) ? $args{num_entries} : 20;
  96
  97     my @origdbs;
  98     if ($self->{databases}) {
  99         @origdbs = $self->{session}->databases;
 100         $self->{session}->databases(@{$self->{databases}});
 101     }
 102
 103     $so->{is_partial} = 0;
 104
 105     my $r = IDZebra::scan_PQF($self->{session}{zh}, $so,
 106                               $self->{odr_stream},
 107                               $self->{expression});
 108
 109     if ($self->{session}->errCode) {
 110         croak ("Error in scan, code: ".$self->{session}->errCode .
 111                ", message: ".$self->{session}->errString);
 112     }
 113
 114     my @res;
 115     for (my $i=1; $i<=$so->{num_entries}; $i++) {
 116
 117         push (@res,
 118             IDZebra::ScanEntry->new(entry    => IDZebra::getScanEntry($so, $i),
 119                                     position => $i,
 120                                     list     => $self));
 121     }
 122
 123     if ($self->{databases}) {
 124         $self->{session}->databases(@origdbs);
 125     }
 126
 127     IDZebra::odr_reset($self->{odr_stream});
 128
 129     $self->{so} = $so;
 130
 131     return (@res);
 132 }
 133
 134
 135 # ============================================================================
 136 __END__
 137
 138 =head1 NAME
 139
 140 IDZebra::ScanList - Scan results
 141
 142 =head1 SYNOPSIS
 143
 144   $sl = $sess->scan(expression => "\@attr 1=4 \@attr 6=2 a",
 145                     databases => [qw(demo1 demo2)]);
 146
 147   @entries = $sl->entries(position    => 5,
 148                           num_entries => 10);
 149
 150   print STDERR
 151     $sl->num_entries,','
 152     $sl->is_partail,',',
 153     $sl->position;
 154
 155
 156 =head1 DESCRIPTION
 157
 158 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,
 159
 160   @entries = $sl->entries(position    => 5,
 161                           num_entries => 10);
 162
 163 returning an array of I<IDZebra::ScanEntry> objects.
 164 The possible arguments are:
 165
 166 =over 4
 167
 168 =item B<position>
 169
 170 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.
 171
 172 =item B<num_entries>
 173
 174 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.
 175
 176 =back
 177
 178 =head1 PROPERTIES
 179
 180 You can reach the following properties as function calls on the IDZebra::ScanList object:
 181
 182 =over 4
 183
 184 =item B<position>
 185
 186 After calling I<entries>, the actual position of the requested term.
 187
 188 =item B<num_entries>
 189
 190 After calling I<entries>, the actual number of entries returned.
 191
 192 =item B<is_partial>
 193
 194 Only partial list is returned by I<entries>.
 195
 196 =back
 197
 198 =head1 COPYRIGHT
 199
 200 Fill in
 201
 202 =head1 AUTHOR
 203
 204 Peter Popovics, pop@technomat.hu
 205
 206 =head1 SEE ALSO
 207
 208 Zebra documentation, IDZebra::Session manpage.
 209
 210 =cut