Z3950/ResultSet.pm untested

filter: Statementstmt 0.0% 0 / 26 Branchbran 0.0% 0 / 12 Conditioncond 0.0% 0 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 0.0% 0 / 11 Podpod 0.0% 0 / 9 totaltotal 0.0% 0 / 63 CC 7 SCAR 28.1
CC
7
Cov
0%
record
42.0
zrs
6.0
new
2.0
CRAP 16.6
1 package Search::Z3950::ResultSet;
2  
3 use strict;
4  
5 use MARC::Record;
6  
7 sub new {
8 my ($cls, $zrs) = @_;
9 bless { 'zrs' => $zrs }, $cls;
10 }
11  
12 sub count { shift->zrs->size }
13 sub prefetch { shift->zrs->present(@_) }
14 sub errcode { shift->zrs->errcode(@_) }
15 sub errmsg { shift->zrs->errmsg(@_) }
16 sub addinfo { shift->zrs->addinfo(@_) }
17 sub option { shift->zrs->option(@_) }
18  
19 sub record {
20 my ($self, $i) = @_;
21 die "Invalid record number ($i)"
22 unless defined $i and $i =~ /^\d+$/;
23 die "Record numbers begin with 1, not 0"
24 if $i == 0;
25 die "Record number ($i) is greater than the number of matches"
26 unless $i <= $self->count;
27 my $zrs = $self->zrs;
28 my $rec = $zrs->record($i);
29 unless (defined $rec) {
30 die sprintf(<<'EOS', $i, $zrs->errcode, $zrs->errmsg, $zrs->addinfo);
31 Matching record (%s) couldn't be retrieved:
32 error code: %s
33 error message: %s
34 add'l info: %s
35 EOS
36 }
37 return MARC::Record->new_from_usmarc($rec->rawdata)
38 if UNIVERSAL::isa($rec, 'Net::Z3950::Record::USMARC');
39 return $rec;
40 }
41  
42 # --- Get or set the underlying Net::Z3950::ResultSet object
43 sub zrs { scalar(@_) > 1 ? $_[0]->{'zrs'} = $_[1] : $_[0]->{'zrs'} }
44  
45  
46 1;
47  
48  
49 =head1 NAME
50  
51 Search::Z3950::ResultSet - Z39.50 search results
52  
53 =head1 SYNOPSIS
54  
55 $n = $rs->count;
56 $rs->prefetch(1, $n) if $n > 0 and $n <= 20;
57 foreach my $i (1..$n) {
58 my $rec = $rs->record($i);
59 if ($rec->isa('MARC::Record')) {
60 my $title = $rec->title;
61 my $author = $rec->author;
62 ...
63 }
64 ...
65 }
66  
67 =head1 DESCRIPTION
68  
69 L<Search::Z3950::ResultSet|Search::Z3950::ResultSet> provides access to the
70 records found in a search using L<Search::Z3950|Search::Z3950>.
71  
72 =head1 PUBLIC METHODS
73  
74 =head2 new
75  
76 $rs = Search::Z3950::ResultSet->new($zrs);
77  
78 Construct a new L<Search::Z3950::ResultSet|Search::Z3950::ResultSet>. The
79 single parameter is the Z39.50 result set (an instance of
80 L<Net::Z3950::ResultSet|Net::Z3950::ResultSet>).
81  
82 This method should normally be called only by L<Search::Z3950|Search::Z3950>.
83  
84 =head2 count
85  
86 $n = $rs->count;
87  
88 The number of matching records.
89  
90 =head2 record
91  
92 $rec = $rs->record($i);
93  
94 Retrieve a matching record. This will be a L<MARC::Record|MARC::Record>
95 when possible (i.e., when the underlying object returned by
96 L<Net::3950::ResultSet|Net::3950::ResultSet> C<isa>
97 L<Net::3950::Record::USMARC|Net::3950::Record::USMARC>); otherwise,
98 it will be an instance of a class in the
99 L<Net::3950::Record|Net::3950::Record> hierarchy.
100  
101 The single parameter is the record number, which starts at 1 (not zero).
102  
103 C<record> throws an error if the record couldn't be fetched (e.g.,
104 if the server connection has just been lost).
105  
106 B<NOTE:> the record numbers start at 1.
107  
108 Did I mention that the record numbers start at 1?
109  
110 =head2 prefetch
111  
112 $rs->prefetch($i, $n);
113  
114 Pre-fetch records C<$i> to C<$i+$n-1> (inclusive) from the
115 Z39.50 server. Call this method (before calling C<record>)
116 to reduce the number of record requests sent over the network
117 to the server.
118  
119 (If you're only interested in the first matching record, it
120 probably makes no difference whether you call C<prefetch> or not.)
121  
122 Returns a true value if the record(s) were successfully
123 retrieved, or a false value otherwise. The retrieved records are
124 B<not> returned.
125  
126 (As currently implemented, this method simply invokes the C<present>
127 method on the Search::Z3950 object's L<Net::Z3950|Net::Z3950> object.)
128  
129 =head1 PRIVATE METHODS
130  
131 These methods are for the internal use of C<Search::Z3950::ResultSet>
132 (and its subclasses, if any).
133  
134 =head2 zrs
135  
136 $zrs = $rs->zrs;
137 $rs->zrs($zrs);
138  
139 Get or set the Z39.50 result set (an instance of
140 L<Net::Z3950::ResultSet|Net::Z3950::ResultSet>).
141  
142 =head1 BUGS
143  
144 None that I know of. You might check L<http://rt.cpan.org> to
145 see if others have reported any bugs.
146  
147 =head1 TO DO
148  
149 =over 4
150  
151 =item *
152  
153 Allow user to specify whether errors should be thrown.
154  
155 =item *
156  
157 Instead of relying on the undocumented C<prefetch> option in
158 L<Net::Z3950|Net::Z3950>, use C<prefetch> behind the scenes
159 to speed up
160  
161 =item *
162  
163 Optionally return raw data? Probably not needed.
164  
165 =item *
166  
167 Add C<records> method to retrieve all records at once?
168 Probably not needed.
169  
170 =item *
171  
172 Generally, make Search::Z3950 taste less Z39.50-ish (without eliminating
173 its expressiveness).
174  
175 =back
176  
177 =head1 SEE ALSO
178  
179 L<Search::Z3950|Search::Z3950>, L<Net::Z3950::ResultSet|Net::Z3950::ResultSet>,
180 L<MARC::Record|MARC::Record>.
181  
182 =head1 AUTHOR
183  
184 Paul Hoffman <nkuitse AT cpan DOT org>
185  
186 =head1 COPYRIGHT
187  
188 Copyright 2003-2004 Paul M. Hoffman. All rights reserved.
189  
190 This program is free software; you can redistribute it
191 and modify it under the same terms as Perl itself.