lib/ZOOM.pod

   1 # $Id: ZOOM.pod,v 1.3 2005-11-15 17:33:04 mike Exp $
   2
   3 use strict;
   4 use warnings;
   5
   6 =head1 NAME
   7
   8 ZOOM - Perl extension implementing the ZOOM API for Information Retrieval
   9
  10 =head1 SYNOPSIS
  11
  12  use ZOOM;
  13  eval {
  14      $conn = new ZOOM::Connection($host, $port)
  15      $conn->option(preferredRecordSyntax => "usmarc");
  16      $rs = $conn->search_pqf('@attr 1=4 dinosaur');
  17      $n = $rs->size();
  18      print $rs->record(0)->render();
  19  };
  20  if ($@) {
  21      print "Error ", $@->code(), ": ", $@->message(), "\n";
  22  }
  23
  24 =head1 DESCRIPTION
  25
  26 This module provides a nice, Perlish implementation of the ZOOM
  27 Abstract API described at http://zoom.z3950.org/api/
  28
  29 the ZOOM module is implemented as a set of thin classes on top of the
  30 non-OO functions provided by this distribution's C<Net::Z3950::ZOOM>
  31 module, which in
  32 turn is a thin layer on top of the ZOOM-C code supplied as part of
  33 Index Data's YAZ Toolkit.  Because ZOOM-C is also the underlying code
  34 that implements ZOOM bindings in C++, Visual Basic, Scheme, Ruby, .NET
  35 (including C#) and other languages, this Perl module works compatibly
  36 with those other implementations.  (Of course, the point of a public
  37 API such as ZOOM is that all implementations should be compatible
  38 anyway; but knowing that the same code is running is reassuring.)
  39
  40 The ZOOM module provides two enumerations (C<ZOOM::Error> and
  41 C<ZOOM::Event>), a single utility function C<diag_str()> in the C<ZOOM>
  42 package itself, and eight classes:
  43 C<ZOOM::Exception>,
  44 C<ZOOM::Options>,
  45 C<ZOOM::Connection>,
  46 C<ZOOM::Query>,
  47 C<ZOOM::ResultSet>,
  48 C<ZOOM::Record>,
  49 C<ZOOM::ScanSet>
  50 and
  51 C<ZOOM::Package>.
  52 Of these, the Query class is abstract, and has two concrete
  53 subclasses:
  54 C<ZOOM::Query::CQL>
  55 and
  56 C<ZOOM::Query::PQF>.
  57 Many useful ZOOM applications can be built using only the Connection,
  58 ResultSet and Record classes, as in the example code-snippet above.
  59
  60 A typical application will begin by creating an Connection object,
  61 then using that to execute searches that yield ResultSet objects, then
  62 fetching records from the result-sets to yield Record objects.  If an
  63 error occurs, an Exception object is thrown and can be dealt with.
  64 More sophisticated applications might browse the server's indexes to
  65 create a ScanSet, from which indexed terms may be retrieved; others
  66 might send ``Extended Services'' Packages to the server, to achieve
  67 non-standard tasks such as database creation and record update.
  68 Searching using a query syntax other than PQF can be done using an
  69 query object of one of the Query subclasses.  Finally, sets of options
  70 may be manipulated independently of the objects they are associated
  71 with using an Options object.
  72
  73
  74 =head1 SEE ALSO
  75
  76 The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
  77
  78 The C<Net::Z3950> module, which this one supersedes.
  79
  80 =head1 AUTHOR
  81
  82 Mike Taylor, E<lt>mike@indexdata.comE<gt>
  83
  84 =head1 COPYRIGHT AND LICENCE
  85
  86 Copyright (C) 2005 by Index Data.
  87
  88 This library is free software; you can redistribute it and/or modify
  89 it under the same terms as Perl itself, either Perl version 5.8.4 or,
  90 at your option, any later version of Perl 5 you may have available.
  91
  92 =cut
  93
  94 1;