Z3950.pm

filter: Statementstmt 77.7% 7 / 9 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 83.3% 10 / 12 CC 1 SCAR 0.9
CC
1
Cov
78%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« Z3950/ResultSet.pm ↑ Summary
1 package Search::Z3950;
2  
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 0 ▶use Net::Z3950;
Subroutine BEGIN: called CC=1 SCAR=2.6
7  
8 use Search::Z3950::ResultSet;
9  
10 BEGIN {
11 use vars qw($VERSION $have_time_hires);
12 $VERSION = '0.05';
13 eval "use Time::HiRes qw()";
14 $have_time_hires = not $@;
15 }
16  
17 sub new {
18 my ($cls, %args) = @_;
19 my %options = (
20 # Defaults - return full MARC records
21 'preferredRecordSyntax' => Net::Z3950::RecordSyntax::USMARC,
22 'elementSetName' => 'F', # Full record
23 );
24
25 foreach (qw/
26
27 mode
28 preferredMessageSize
29 maximumRecordSize
30
31 user
32 password
33 groupid
34
35 implementationId
36 implementationName
37 implementationVersion
38
39 querytype
40 databaseName
41 prefetch
42
43 smallSetUpperBound
44 largeSetLowerBound
45 mediumSetPresentNumber
46 smallSetElementSetName
47 mediumSetElementSetName
48
49 preferredRecordSyntax
50 elementSetName
51 namedResultSets
52
53 /) {
54 $options{$_} = delete $args{$_}
55 if exists $args{$_};
56 }
57 my $self = bless {
58 # --- Default args
59 'host' => $args{'host'},
60 'port' => $args{'port'} || 210,
61 'search_types' => {},
62 'delay' => undef, # no delays
63
64 # --- Args the caller may specify
65 %args,
66
67 # --- Args to ignore
68 '_connection' => undef,
69 # '_manager' => undef,
70 '_options' => \%options,
71
72 }, $cls;
73 return $self->_init;
74 }
75  
76 sub search {
77 my ($self, $key, $str) = @_;
78 # --- Connect if necessary
79 my $conn = $self->_connection
80 || $self->_connect
81 || die "Couldn't connect";
82 my $search = $self->_make_search($key, $str);
83 die "Bad search term: $key => $str"
84 unless defined $search;
85 # --- Pause, then perform the search
86 $self->_pause;
87 my $rs = $conn->search($search);
88 die sprintf(
89 "Search failed: %s (error code %s, add. info <%s>)",
90 $conn->errmsg,
91 $conn->errcode,
92 $conn->addinfo,
93 ) unless defined $rs;
94 return Search::Z3950::ResultSet->new($rs);
95 }
96  
97 sub disconnect {
98 my ($self) = @_;
99 $self->_connection->close;
100 $self->_connection(undef);
101 }
102  
103 sub DESTROY {
104 my ($self) = @_;
105 my $conn = $self->_connection;
106 $conn->close if defined $conn;
107 }
108  
109 sub host { scalar(@_) > 1 ? $_[0]->{'host'} = $_[1] : $_[0]->{'host'} }
110 sub port { scalar(@_) > 1 ? $_[0]->{'port'} = $_[1] : $_[0]->{'port'} }
111 sub delay { scalar(@_) > 1 ? $_[0]->{'delay'} = $_[1] : $_[0]->{'delay'} }
112 sub search_types { scalar(@_) > 1 ? $_[0]->{'search_types'} = $_[1] : $_[0]->{'search_types'} }
113 sub logic_types { scalar(@_) > 1 ? $_[0]->{'logic_types'} = $_[1] : $_[0]->{'logic_types'} }
114  
115  
116 # --- P R I V A T E M E T H O D S --------------------------------------------
117  
118 sub _init {
119 my ($self) = @_;
120 return $self;
121 }
122  
123 sub _pause {
124 my ($self) = @_;
125 my $delay = $self->delay;
126 return unless defined $delay and $delay > 0;
127 if ($have_time_hires) {
128 Time::HiRes::sleep($delay);
129 } else {
130 # --- Try to get the desired delay *on average*.
131 # For example, a delay of 3.4 means that 40%
132 # of the time we'll sleep for 4 seconds; 60%
133 # of the time we'll only sleep for 3 seconds.
134 my $int_delay = int $delay;
135 $int_delay++ if rand() < $delay - $int_delay;
136 sleep $int_delay if $int_delay;
137 }
138 }
139  
140 sub _connect {
141 my ($self) = @_;
142 my $conn = Net::Z3950::Connection->new(
143 $self->host,
144 $self->port,
145 %{ $self->_options },
146 ) || die "Can't connect: $!";
147 $self->_connection($conn);
148 }
149  
150 #sub _connect {
151 # my ($self) = @_;
152 # my $conn = $self->_manager->connect($self->host, $self->port);
153 # $self->_connection($conn);
154 #}
155  
156 sub _make_search {
157 my ($self, @args) = @_;
158 my ($search_key, $search_str) = @args;
159 die "Sorry, can't do explicit multiple search terms yet"
160 if scalar @args > 2;
161 my ($stype) = grep { $_->{'name'} eq $search_key } @{ $self->search_types };
162 my $search_syntax = $self->_options->{'querytype'};
163 my $template = $stype->{'templates'}->{$search_syntax};
164 if ($search_str =~ /\s/) {
165 if ($stype->{'multiple'}) {
166 die "Sorry, can't do implicit multiple search terms yet";
167 # XXX First pass at multiple-term code...
168 my @substrs = split(/\s+/, $search_str);
169 my $and = $self->logic_types->{'and'};
170 my $and_tmpl = $and->{'templates'}->{$search_syntax}
171 || die "No AND logic specified for search syntax $search_syntax";
172 $search_str = sprintf($template, shift @substrs);
173 while (@substrs) {
174 my $term = sprintf($template, shift @substrs);
175 $search_str = sprintf($and_tmpl, $search_str, $term);
176 };
177 return $search_str;
178 # XXX Check this for errors
179 } else {
180 # XXX Is there anything to do here?
181 }
182 }
183 return sprintf($template, $search_str);
184 }
185  
186 sub _connection { scalar(@_) > 1 ? $_[0]->{'_connection'} = $_[1] : $_[0]->{'_connection'} }
187 sub _manager { scalar(@_) > 1 ? $_[0]->{'_manager'} = $_[1] : $_[0]->{'_manager'} }
188 sub _options { scalar(@_) > 1 ? $_[0]->{'_options'} = $_[1] : $_[0]->{'_options'} }
189  
190  
191 1;
192  
193  
194 =head1 NAME
195  
196 Search::Z3950 - Simple Z39.50 searching for ordinary folk
197  
198 =head1 SYNOPSIS
199  
200 $z = Search::Z3950->new(
201 host => $host,
202 port => $port,
203 user => $user,
204 password => $pwd,
205 databaseName => $dbname,
206 delay => 0.5, # half a second
207 search_types => [
208 {
209 name => 'title',
210 host => 'z3950.loc.gov',
211 port => 7090,
212 ... other Z39.50 params here ...
213 },
214 ...
215 ],
216 );
217 $results = $z->search('title' => 'water method man');
218 $numrecs = $results->count();
219 for (1..$numrecs) {
220 $rec = $results->record($_);
221 ...
222 }
223 ...
224  
225 =head1 DESCRIPTION
226  
227 Search::Z3950 aims to simplify the coding of Z39.50 clients in Perl by reducing
228 the amount of information the programmer needs to to know about the Z39.50
229 protocol. (Z39.50 is a standard for information retrieval commonly used by
230 libraries.)
231  
232 For each Z39.50 server and database (a Z39.50 "service" or "target"), a set of
233 desired search types is written once by someone who knows Z39.50 search syntax
234 and the requirements of the particular service. These search types are
235 typically stored in a configuration file (e.g., the YAML file F<services.yml>
236 included in the Search-Z3950 distribution). All the Perl programmer has to know
237 is the search type's name (e.g., 'author') and whether it accepts multiple-word
238 search strings.
239  
240 =head1 PUBLIC METHODS
241  
242 =over 4
243  
244 =item new
245  
246 $z = Search::Z3950->new(%args);
247  
248 Construct a new Search::Z3950 object. The following named arguments may be provided:
249  
250 =over 4
251  
252 =item host
253  
254 The host name or IP address of the Z39.50 server.
255  
256 =item port
257  
258 (Optional.) The port on which the Z39.50 server listens. The default is 210.
259  
260 =item user
261  
262 If the Z39.50 service requires authentication, you must supply a user name here.
263  
264 =item password
265  
266 If the Z39.50 service requires authentication, you must supply a password here.
267  
268 =item databaseName
269  
270 The name of the database to search. Some Z39.50 services provide access to many
271 different databases, others to only one.
272  
273 =item delay
274  
275 See the description of the C<delay> method below.
276  
277 =item search_types
278  
279 See the description of the C<search_types> method below.
280  
281 =item querytype
282  
283 The type of query you'll be sending (i.e., the search syntax you'll be using).
284 Different Z39.50 services allow for different query types; see the Library of
285 Congress's Z39.50 web site (URL below) for details.
286  
287 The two query types most likely to be supported are C<prefix> (Prefix Query
288 Notation, a kind of RPN) and C<ccl> (Common Command Language). The query type
289 C<ccl2rpn> may be used to write searches in CCL and have them automatically
290 translated into prefix notation before being sent to the Z39.50 server.
291  
292 =item preferredRecordSyntax
293  
294 The default value is C<Net::Z3950::RecordSyntax::USMARC()> (i.e., 19). Using
295 this default, records are returned (from the results object) as instances of
296 the class C<MARC::Record>.
297  
298 =back
299  
300 A whole slew of other arguments may also be provided; these are passed on to the
301 L<Net::Z3950::Connection|Net::Z3950::Connection> object that's created for each
302 service used.
303  
304 =item search
305  
306 $results = $z->search('title' => 'rutabaga tales');
307  
308 Perform a search, connecting to the Z39.50 server the first time it's called.
309 Returns a L<Search::Z3950::ResultSet|Search::Z3950::ResultSet>.
310  
311 =item disconnect
312  
313 $z->disconnect;
314  
315 Disconnect from the Z39.50 server.
316  
317 =item host
318  
319 $host = $z->host();
320 $z->host($host);
321  
322 Get or set the host.
323  
324 =item port
325  
326 $port = $z->port();
327 $z->port($port);
328  
329 Get or set the port.
330  
331 =item delay
332  
333 $delay = $z->delay;
334 $z->delay($delay);
335  
336 Get or set the number of seconds to delay (i.e., sleep) before sending
337 a request. The delay may be specified as an integer or a floating-point
338 number. The delay will be done using C<Time::HiRes::usleep> if it's
339 available; otherwise, C<sleep> is used and the delay is taken as an
340 B<average>.
341  
342 For example, if the delay is specified as 1.5 seconds and Time::HiRes
343 isn't available, sleep(1) will be called half the time and sleep(2) the
344 other half.
345  
346 =item search_types
347  
348 $searches = $z->search_types;
349 $z->search_types($searches);
350  
351 Get or set the search types available. The search types are specified as
352 an array of hashes, each of which should have elements C<name>, C<multiple>,
353 C<templates>, and (optionally) C<description>. (Search::Z3950 will ignore any other
354 elements present in the hash.)
355  
356 The C<multiple> element indicates whether the search string should be broken
357 down into separate search terms when it consists of multiple words (separated
358 by whitespace).
359  
360 For example, given this set of search types:
361  
362 [
363 {
364 'name' => 'isbn',
365 'description' => 'Search by ISBN',
366 'multiple' => 0,
367 'templates' => ...
368 }
369 {
370 'name' => 'authed',
371 'description' => 'Search by author, editor, etc.',
372 'multiple' => 1,
373 'templates' => ...
374 },
375 ]
376  
377 An ISBN search should specify only one ISBN:
378  
379 $z->search('isbn' => '0721655342');
380  
381 While an author/editor search may contain several words:
382  
383 $z->search('author' => 'ulysses fishwick');
384  
385 This latter example would result in a search something like this:
386  
387 au=ulysses and au=fishwick
388  
389 Depending on the search syntax desired, of course.
390  
391 B<WARNING:> Multiple search terms aren't allowed yet. Trying to do
392 a search that would entail making multiple search terms will result
393 in an exception being thrown.
394  
395 =back
396  
397 =head1 PREREQUISITES
398  
399 L<Net::Z3950|Net::Z3950> (which in turn requires the yaz toolkit).
400  
401 =head1 FILES
402  
403 =over 4
404  
405 =item services.yml
406  
407 This is a YAML file that defines a number of Z39.50 services (also known as
408 "targets"). The Search-Z3950 distribution uses this file only for testing
409 purposes, but you may copy it and adapt it for your own purposes. See the code
410 in F<t/test-base.pl> for an example of how to use it.
411  
412 NOTE: The fields `name', `abbrev', `location', and `searches' are used only for
413 testing purposes and may be deleted from the copy you make for your own purposes.
414  
415 =back
416  
417 =head1 BUGS
418  
419 At this point, Search::Z3950 really doesn't do a very good job of insulating the
420 Perl programmer from Z39.50 details.
421  
422 =head1 TO DO
423  
424 =over 4
425  
426 =item *
427  
428 Allow for multiple search terms!
429  
430 =item *
431  
432 Better error checking when connecting.
433  
434 =item *
435  
436 Include a simple client as an example.
437  
438 =item *
439  
440 Make C<Search::Z3950::Database> and C<Search::Z3950::SearchType> modules
441 to simplify the specification of Z39.50 databases and
442 search types?
443  
444 =item *
445  
446 Enable asynchronous operation??
447  
448 =back
449  
450 =head1 SEE ALSO
451  
452 L<Net::Z3950|Net::Z3950>,
453 L<Search::Z3950::ResultSet|Search::Z3950::ResultSet>.
454  
455 =head1 VERSION
456  
457 0.05
458  
459 =head1 AUTHOR
460  
461 Paul Hoffman (nkuitse AT cpan DOT org)
462  
463 =head1 CREDITS
464  
465 Many thanks to Mike Taylor (mike AT zoom DOT z3950 DOT org) for Net::Z3950,
466 without whom Search::Z3950 wouldn't exist.
467  
468 The good folks who created the ZOOM abstract API (see
469 L<http://zoom.z3950.org/>), of which Net::Z3950 is a binding.
470  
471 Index Data of Copenhagen for the yaz toolkit, upon which Net::Z3950 is built.
472  
473 Finally, thanks to ISO, NISO, and the Library of Congress for the Z39.50
474 standard (see L<http://lcweb.loc.gov/z3950/agency/>).
475  
476 =head1 COPYRIGHT
477  
478 Copyright 2003 Paul M. Hoffman. All rights reserved.
479  
480 This program is free software; you can redistribute it
481 and modify it under the same terms as Perl itself.
482  
« Z3950/ResultSet.pm ↑ Summary