Move PQF.pm to lib/Net/Z3950/PQF.pm

[perl-pqf.git] / lib / Net / Z3950 / PQF.pm

diff --git a/lib/Net/Z3950/PQF.pm b/lib/Net/Z3950/PQF.pm
new file mode 100644 (file)
index 0000000..e5e9d6f
--- /dev/null
+++ b/lib/Net/Z3950/PQF.pm
@@ -0,0 +1,120 @@
+# $Id: PQF.pm,v 1.1 2004-12-17 13:44:47 mike Exp $
+
+package Net::Z3950::PQF;
+
+use 5.006;
+use strict;
+use warnings;
+
+#use Net::Z3950::PQF::Node;
+
+our $VERSION = '0.02';
+
+
+=head1 NAME
+
+Net::Z3950::PQF - Perl extension for parsing PQF (Prefix Query Format)
+
+=head1 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();
+
+=head1 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, C<yaz-client>.
+
+It is simple to use.  Create a parser object, then pass PQF strings
+into its C<parse()> method to yield parse-trees.  The trees are made
+up of nodes whose types are all of the form
+C<Net::Z3950::PQF::xxxNode>.  You may find it helpful to use
+C<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 C<render()> method,
+which is probably useful only for debugging.  If you want to do
+anything useful, such as implementing an actual query server that
+understands PQF, you'll have to walk the tree.
+
+=head1 METHODS
+
+=head2 new()
+
+ $parser = new Net::Z3950::PQF();
+
+Creates a new parser object.
+
+=cut
+
+sub new {
+    my $class = shift();
+
+    return bless {
+       errmsg => undef,
+    }, $class;
+}
+
+
+=head2 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 C<errmsg()> method.  Otherwise, the top node
+of the parse tree is returned.
+
+=cut
+
+sub parse {
+    my $this = shift();
+
+    die "parse($this) not yet implemented";
+}
+
+
+=head2 errmsg()
+
+ print $parser->errmsg();
+
+=cut
+
+sub errmsg {
+    my $this = shift();
+    return $this->{errmsg};
+}
+
+
+=head1 SEE ALSO
+
+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
+
+=head1 AUTHOR
+
+Mike Taylor, E<lt>mike@indexdata.comE<gt>
+
+=head1 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. 
+
+=cut