| 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 | |||