-# $Id: ZOOM.pod,v 1.16 2005-12-13 14:01:59 mike Exp $
+# $Id: ZOOM.pod,v 1.19 2005-12-13 15:30:26 mike Exp $
use strict;
use warnings;
=head2 ZOOM::Query
-I<###>
+ $q = new ZOOM::Query::CQL("creator=pike and subject=unix");
+ $q->sortby("1=4 >i 1=21 >s");
+ $rs = $conn->search($q);
+ $q->destroy();
+
+C<ZOOM::Query> is a virtual base class from which various concrete
+subclasses can be derived. Different subclasses implement different
+types of query. The sole purpose of a Query object is to be used in a
+C<search()> on a Connection; because PQF is such a common special
+case, the shortcut Connection method C<search_pqf()> is provided.
+
+The following Query subclasses are provided, both of the providing the
+same set of methods described below:
+
+=over 4
+
+=item ZOOM::Query::PQF
+
+Implements Prefix Query Format (PQF), also sometimes known as Prefix
+Query Notation (PQN). This esoteric but rigorous and expressive
+format is described in the YAZ Manual at
+http://indexdata.com/yaz/doc/tools.tkl#PQF
+
+=item ZOOM::Query::CQL
+
+Implements the Common Query Language (CQL) of SRU, the Search/Retrieve
+URL. CQL is a much friendlier notation than PQF, using a simple infix
+notation. The queries are passed ``as is'' to the server rather than
+being compiled into a Z39.50 Type-1 query, so only CQL-compliant
+servers can support such querier. CQL is described at
+http://www.loc.gov/standards/sru/cql/
+and in a slight out-of-date but nevertheless useful tutorial at
+http://zing.z3950.org/cql/intro.html
+
+=back
+
+See the description of the C<Query> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.3
+
+=head3 Methods
+
+=head4 new()
+
+ $q = new ZOOM::Query::CQL('title=dinosaur'));
+ $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+
+Creates a new query object, compiling the query passed as its argument
+according to the rules of the particular query-type being
+instantiated. If compilation fails, an exception is thrown.
+Otherwise, the query may be passed to the C<Connection> method
+<search()>.
+
+=head4 sortby()
+
+ $q->sortby("1=4 >i 1=21 >s");
+
+Sets a sort specification into the query, so that when a C<search()>
+is run on the query, the result is automatically sorted. The sort
+specification language is the same as the C<yaz> sort-specification
+type of the C<ResultSet> method C<sort()>, described above.
+
+B<It ought to be possible to sort by CQL query, too, but at present
+limitations in the underlying ZOOM-C library make this impossible.>
+
+=head4 destroy()
+
+ $p->destroy()
+
+Destroys a Query object, freeing its resources. It is an error to
+reuse a Query that has been C<destroy()>ed.
=head2 ZOOM::Options
+ $o1 = new ZOOM::Options();
+ $o1->option(user => "alf");
+ $o2 = new ZOOM::Options();
+ $o2->option(password => "fruit");
+ $opts = new ZOOM::Options($o1, $o2);
+ $conn = create ZOOM::Connection($opts);
+ $conn->connect($host); # Uses the specified username and password
+
+Several classes of ZOOM objects carry their own sets of options, which
+can be manipulated using their C<option()> method. Sometimes,
+however, it's useful to deal with the option sets directly, and the
+C<ZOOM::Options> class exists to enable this approach.
+
+Option sets are B<not currently described> in the ZOOM
+Abstract API at
+http://zoom.z3950.org/api/zoom-current.html
+They are an extension to that specification.
+
+=head3 Methods
+
+=head4 new()
+
+I<###>
+
+=head4 option()
+
+I<###>
+
+=head4 option_binary()
+
+I<###>
+
+=head4 bool() / int()
+
+I<###>
+
+=head4 set_int()
+
+I<###>
+
+=head4 set_callback()
+
+I<###>
+
+=head4 destroy()
+
I<###>
=head1 ENUMERATIONS