Delete RS

[simpleserver-moved-to-github.git] / SimpleServer.pm

diff --git a/SimpleServer.pm b/SimpleServer.pm
index 6ab4042..003efea 100644 (file)
--- a/SimpleServer.pm
+++ b/SimpleServer.pm
@@ -25,7 +25,7 @@
 ##
 ##
 
-## $Id: SimpleServer.pm,v 1.34 2007-08-15 13:14:29 mike Exp $
+## $Id: SimpleServer.pm,v 1.40 2007-08-20 11:06:09 mike Exp $
 
 package Net::Z3950::SimpleServer;
 
@@ -39,7 +39,7 @@ require AutoLoader;
 
 @ISA = qw(Exporter AutoLoader DynaLoader);
 @EXPORT = qw( );
-$VERSION = '1.06';
+$VERSION = '1.07';
 
 bootstrap Net::Z3950::SimpleServer $VERSION;
 
@@ -102,16 +102,60 @@ sub launch_server {
 
 
 # Register packages that we will use in translated RPNs
+package Net::Z3950::RPN::Node;
 package Net::Z3950::APDU::Query;
+our @ISA = qw(Net::Z3950::RPN::Node);
 package Net::Z3950::APDU::OID;
 package Net::Z3950::RPN::And;
+our @ISA = qw(Net::Z3950::RPN::Node);
 package Net::Z3950::RPN::Or;
+our @ISA = qw(Net::Z3950::RPN::Node);
 package Net::Z3950::RPN::AndNot;
+our @ISA = qw(Net::Z3950::RPN::Node);
 package Net::Z3950::RPN::Term;
+our @ISA = qw(Net::Z3950::RPN::Node);
 package Net::Z3950::RPN::RSID;
+our @ISA = qw(Net::Z3950::RPN::Node);
 package Net::Z3950::RPN::Attributes;
 package Net::Z3950::RPN::Attribute;
 
+
+# Utility method for re-rendering Type-1 query back down to PQF
+package Net::Z3950::RPN::Node;
+
+sub toPQF {
+    my $this = shift();
+    my $class = ref $this;
+
+    if ($class eq "Net::Z3950::APDU::Query") {
+       my $res = "";
+       my $set = $this->{attributeSet};
+       $res .= "\@attrset $set " if defined $set;
+       return $res . $this->{query}->toPQF();
+    } elsif ($class eq "Net::Z3950::RPN::Or") {
+       return '@or ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
+    } elsif ($class eq "Net::Z3950::RPN::And") {
+       return '@and ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
+    } elsif ($class eq "Net::Z3950::RPN::AndNot") {
+       return '@not ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
+    } elsif ($class eq "Net::Z3950::RPN::RSID") {
+       return '@set ' . $this->{id};
+    } elsif ($class ne "Net::Z3950::RPN::Term") {
+       die "unknown PQF node-type '$class'";
+    }
+
+    my $res = "";
+    foreach my $attr (@{ $this->{attributes} }) {
+       $res .= "\@attr ";
+       my $set = $attr->{attributeSet};
+       $res .= "$set " if defined $set;
+       $res .= $attr->{attributeType} . "=" . $attr->{attributeValue} . " ";
+    }
+
+    return $res . $this->{term};
+}
+
+
 # Must revert to original package for Autoloader's benefit
 package Net::Z3950::SimpleServer;
 
@@ -418,9 +462,6 @@ of the result-set is in the C<id> element.
 
 =back
 
-(I guess I should make a superclass C<Net::Z3950::RPN::Node> and make
-all of these subclasses of it.  Not done that yet, but will do one day.)
-
 =back
 
 =over 4
@@ -469,7 +510,7 @@ a ``relation'' attribute, etc.
 
 =item C<attributeValue>
 
-An integer indicating the value of the attribute - for example, under
+An integer or string indicating the value of the attribute - for example, under
 BIB-1, if the attribute type is 1, then value 4 indictates a title
 search and 7 indictates an ISBN search; but if the attribute type is
 2, then value 4 indicates a ``greater than or equal'' search, and 102
@@ -479,7 +520,12 @@ indicates a relevance match.
 
 =back
 
-Note that, at the moment, none of these classes have any methods at
+All of these classes except C<Attributes> and C<Attribute> are
+subclasses of the abstract class C<Net::Z3950::RPN::Node>.  That class
+has a single method, C<toPQF()>, which may be used to turn an RPN
+tree, or part of one, back into a textual prefix query.
+
+Note that, apart to C<toPQF()>, none of these classes have any methods at
 all: the blessing into classes is largely just a documentation thing
 so that, for example, if you do
 
@@ -601,6 +647,8 @@ an index of a book, you always find something! The parameters exchanged are
                DATABASES       => ["xxx"],     ## Reference to a list of data-
                                                ## bases to search
                TERM            => 'start',     ## The start term
+               RPN             =>  $obj,       ## Reference to a Net::Z3950::RPN::Term
+
                NUMBER          => xx,          ## Number of requested terms
                POS             => yy,          ## Position of starting point
                                                ## within returned list
@@ -633,14 +681,23 @@ should point at a data structure of this kind,
                                ...
        ];
 
-The $status flag should be assigned one of two values:
+The $status flag is only meaningful after a successful scan, and
+should be assigned one of two values:
 
-  Net::Z3950::SimpleServer::ScanSuccess  On success (default)
-  Net::Z3950::SimpleServer::ScanPartial  Less terms returned than requested
+  Net::Z3950::SimpleServer::ScanSuccess  Full success (default)
+  Net::Z3950::SimpleServer::ScanPartial  Fewer terms returned than requested
 
 The STEP member contains the requested number of entries in the term-list
 between two adjacent entries in the response.
 
+A better alternative to the TERM member is the the RPN
+member, which is a reference to a Net::Z3950::RPN::Term object
+representing the scan cloause.  The structure of that object is the
+same as for Term objects included as part of the RPN tree passed to
+search handlers.  This is more useful than the simple TERM because it
+includes attributes (e.g. access points associated with the term),
+which are discarded by the TERM element.
+
 =head2 Close handler
 
 The argument hash recieved by the close handler has two elements only: