perl/lib/IDZebra/ScanList.pm

   1 # $Id: ScanList.pm,v 1.3 2003-03-12 17:08:53 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.3 $ =~ /\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 #    logf(LOG_LOG,"DESTROY: IDZebra::ScanList");
  49
  50     if ($self->{odr_stream}) {
  51         IDZebra::odr_reset($self->{odr_stream});
  52         IDZebra::odr_destroy($self->{odr_stream});
  53         $self->{odr_stream} = undef;
  54     }
  55
  56     delete($self->{so});
  57     delete($self->{session});
  58 }
  59
  60 # =============================================================================
  61 sub is_partial {
  62     my ($self) = @_;
  63     return ($self->{so}{is_partial});
  64 }
  65
  66 sub position {
  67     my ($self) = @_;
  68     return ($self->{so}{position});
  69 }
  70
  71 sub num_entries {
  72     my ($self) = @_;
  73     return ($self->{so}{num_entries});
  74 }
  75
  76 sub errCode {
  77     my ($self) = @_;
  78     return ($self->{session}->errCode);
  79 }
  80
  81 sub errString {
  82     my ($self) = @_;
  83     return ($self->{session}->errString);
  84 }
  85
  86 # -----------------------------------------------------------------------------
  87 sub entries {
  88     my ($self, %args) = @_;
  89
  90     unless ($self->{session}{zh}) {
  91         croak ("Session is closed or out of scope");
  92     }
  93
  94     my $so=$self->{so};
  95
  96     $so->{position}    = defined($args{position})    ? $args{position}    : 1;
  97     $so->{num_entries} = defined($args{num_entries}) ? $args{num_entries} : 20;
  98
  99     my @origdbs;
 100     if ($self->{databases}) {
 101         @origdbs = $self->{session}->databases;
 102         $self->{session}->databases(@{$self->{databases}});
 103     }
 104
 105     $so->{is_partial} = 0;
 106
 107     my $r = IDZebra::scan_PQF($self->{session}{zh}, $so,
 108                               $self->{odr_stream},
 109                               $self->{expression});
 110
 111     if ($self->{session}->errCode) {
 112         croak ("Error in scan, code: ".$self->{session}->errCode .
 113                ", message: ".$self->{session}->errString);
 114     }
 115
 116     my @res;
 117     for (my $i=1; $i<=$so->{num_entries}; $i++) {
 118         my $se = IDZebra::getScanEntry($so, $i);
 119         push (@res,
 120             IDZebra::ScanEntry->new($se->{term},
 121                                     $se->{occurrences},
 122                                     $i,
 123                                     $self));
 124     }
 125
 126     if ($self->{databases}) {
 127         $self->{session}->databases(@origdbs);
 128     }
 129
 130     IDZebra::odr_reset($self->{odr_stream});
 131
 132     $self->{so} = $so;
 133
 134     return (@res);
 135 }
 136
 137
 138 # ============================================================================
 139 __END__
 140
 141 =head1 NAME
 142
 143 IDZebra::ScanList - Scan results
 144
 145 =head1 SYNOPSIS
 146
 147   $sl = $sess->scan(expression => "\@attr 1=4 \@attr 6=2 a",
 148                     databases => [qw(demo1 demo2)]);
 149
 150   @entries = $sl->entries(position    => 5,
 151                           num_entries => 10);
 152
 153   print STDERR
 154     $sl->num_entries,','
 155     $sl->is_partail,',',
 156     $sl->position;
 157
 158
 159 =head1 DESCRIPTION
 160
 161 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,
 162
 163   @entries = $sl->entries(position    => 5,
 164                           num_entries => 10);
 165
 166 returning an array of I<IDZebra::ScanEntry> objects.
 167 The possible arguments are:
 168
 169 =over 4
 170
 171 =item B<position>
 172
 173 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.
 174
 175 =item B<num_entries>
 176
 177 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.
 178
 179 =back
 180
 181 =head1 PROPERTIES
 182
 183 You can reach the following properties as function calls on the IDZebra::ScanList object:
 184
 185 =over 4
 186
 187 =item B<position>
 188
 189 After calling I<entries>, the actual position of the requested term.
 190
 191 =item B<num_entries>
 192
 193 After calling I<entries>, the actual number of entries returned.
 194
 195 =item B<is_partial>
 196
 197 Only partial list is returned by I<entries>.
 198
 199 =back
 200
 201 =head1 COPYRIGHT
 202
 203 Fill in
 204
 205 =head1 AUTHOR
 206
 207 Peter Popovics, pop@technomat.hu
 208
 209 =head1 SEE ALSO
 210
 211 Zebra documentation, IDZebra::Session manpage.
 212
 213 =cut