From: mike <mike>
Date: Mon, 19 Dec 2005 17:53:00 +0000 (+0000)
Subject: Updated documentation for the scanning methods in the Connection
X-Git-Tag: cpan_1_22~292
X-Git-Url: http://lists.indexdata.com/cgi-bin?a=commitdiff_plain;h=bd7842f431edd7fa568cec28f4dbf6cf11b5c1ea;p=ZOOM-Perl-moved-to-github.git

Updated documentation for the scanning methods in the Connection
class: The old scan() is now scan_pqf(), which is considered a mere
short-cut to the new Query-oriented scan().
---

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 998a03a..ee8162b 100644
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.23 2005-12-19 17:42:15 mike Exp $
+# $Id: ZOOM.pod,v 1.24 2005-12-19 17:53:00 mike Exp $
 
 use strict;
 use warnings;
@@ -294,15 +294,18 @@ and it creates and returns a new ResultSet object representing the set
 of records resulting from the search.
 
 Since queries using PQF (Prefix Query Format) are so common, we make
-them a special case by providing a C<search_prefix()> method.  This is
+them a special case by providing a C<search_pqf()> method.  This is
 identical to C<search()> except that it accepts a string containing
 the query rather than an object, thereby obviating the need to create
 a C<ZOOM::Query::PQF> object.  See the documentation of that class for
 information about PQF.
 
-=head4 scan() / scan1()
+=head4 scan() / scan_pqf()
 
- ### Code sample needed here!
+ $rs = $conn->scan(new ZOOM::Query::CQL('title=dinosaur'));
+ # The next two lines are equivalent
+ $rs = $conn->scan(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+ $rs = $conn->scan_pqf('@attr 1=4 dinosaur');
 
 Many Z39.50 servers allow you to browse their indexes to find terms to
 search for.  This is done using the C<scan> method, which creates and
@@ -318,13 +321,11 @@ or single words (e.g. the title ``I<The Empire Strikes Back>'', or the
 four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved
 with words from other titles in the same index.
 
-All of this is done by using a single term from the PQF query as the
-C<scan()> argument.  (At present, only PQF is supported, although
-there is no reason in principle why CQL and other query syntaxes
-should not be supported in future).  The attributes associated with
+All of this is done by using a Query object representing a query of a
+single term as the C<scan()> argument.  The attributes associated with
 the term indicate which index is to be used, and the term itself
 indicates the point in the index at which to start the scan.  For
-example, if the argument is C<@attr 1=4 fish>, then
+example, if the argument is the query C<@attr 1=4 fish>, then
 
 =over 4
 
@@ -374,10 +375,11 @@ each one returned in the ScanSet.  By default, no terms are skipped,
 but overriding this can be useful to get a high-level overview of the
 index.
 
-The C<scan1()> method is the same as C<scan()> except that it takes a
-Query object as its argument instead of a PQF string.  This means
-that it can be used to scan using a CQL term, so long as the
-underlying ZOOM-C library supports this.
+Since scans using PQF (Prefix Query Format) are so common, we make
+them a special case by providing a C<scan_pqf()> method.  This is
+identical to C<scan()> except that it accepts a string containing the
+query rather than an object, thereby obviating the need to create a
+C<ZOOM::Query::PQF> object.
 
 =back
 
@@ -434,7 +436,7 @@ need the C<size()>, C<record()> and C<sort()> methods.
 
 There is no C<new()> method nor any other explicit constructor.  The
 only way to create a new ResultSet is by using C<search()> (or
-C<search_prefix()>) on a Connection.
+C<search_pqf()>) on a Connection.
 
 See the description of the C<Result Set> class in the ZOOM Abstract
 API at