NAME

Net::Z3950::PQF - Perl extension for parsing PQF (Prefix Query Format)

SYNOPSIS

 use Net::Z3950::PQF;
 $parser = new Net::Z3950::PQF();
 $node = $parser->parse('@and @attr 1=1003 kernighan @attr 1=4 unix');
 print $node->render(0);

DESCRIPTION

This library provides a parser for PQF (Prefix Query Format), an ugly but precise string format for expressing Z39.50 Type-1 queries. This format is widely used behind the scenes of Z39.50 applications, and is also used extensively with test-harness programs such as the YAZ command-line client, yaz-client. A few particularly misguided souls have been known to type it by hand.

Unlike PQF itself, this module is simple to use. Create a parser object, then pass PQF strings into its parse() method to yield parse-trees. The trees are made up of nodes whose types are subclasses of Net::Z3950::PQF::Node. and have names of the form Net::Z3950::PQF::somethingNode. You may find it helpful to use Data::Dumper to visualise the structure of the returned parse-trees.

What is a PQF parse-tree good for? Not much. You can render a human-readable version by invoking the top node's render() method, which is probably useful only for debugging. Or you can turn it into tree of nodes like those passed into SimpleServer search handlers using toSimpleServer(). If you want to do anything useful, such as implementing an actual query server that understands PQF, you'll have to walk the tree.

METHODS

new()

 $parser = new Net::Z3950::PQF();

Creates a new parser object.

parse()

 $query = '@and @attr 1=1003 kernighan @attr 1=4 unix';
 $node = $parser->parse($query);
 if (!defined $node) {
     die "parse($query) failed: " . $parser->errmsg();
 }

Parses the PQF string provided as its argument. If an error occurs, then an undefined value is returned, and the error message can be obtained by calling the errmsg() method. Otherwise, the top node of the parse tree is returned.

 $node2 = $parser->parse($query, "zthes");
 $node3 = $parser->parse($query, "1.2.840.10003.3.13");

A second argument may be provided after the query itself. If it is provided, then it is taken to be either the name or the OID of a default attribute set, which attributes specified in the query belong to if no alternative attribute set is explicitly specified within the query. When this second argument is absent, the default attribute set is BIB-1.

errmsg()

 print $parser->errmsg();

Returns the last error-message generated by a failed attempt to parse a query.

SEE ALSO

The Net::Z3950::PQF::Node module.

The definition of the Type-1 query in the Z39.50 standard, the relevant section of which is on-line at http://www.loc.gov/z3950/agency/markup/09.html#3.7

The documentation of Prefix Query Format in the YAZ Manual, the relevant section of which is on-line at http://indexdata.com/yaz/doc/tools.tkl#PQF

AUTHOR

Mike Taylor, <mike@indexdata.com>

COPYRIGHT AND LICENSE

Copyright 2004 by Index Data ApS.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.