c1690e843190072a66a128af6a706da8a24530ad
[perl-pqf.git] / PQF.pm
1 # $Id: PQF.pm,v 1.2 2004-12-17 12:58:51 mike Exp $
2
3 package Net::Z3950::PQF;
4
5 use 5.006;
6 use strict;
7 use warnings;
8
9 #use Net::Z3950::PQF::Node;
10
11 our $VERSION = '0.02';
12
13
14 =head1 NAME
15
16 Net::Z3950::PQF - Perl extension for parsing PQF (Prefix Query Format)
17
18 =head1 SYNOPSIS
19
20  use Net::Z3950::PQF;
21  $parser = new Net::Z3950::PQF();
22  $node = $parser->parse('@and @attr 1=1003 kernighan @attr 1=4 unix');
23  print $node->render();
24
25 =head1 DESCRIPTION
26
27 This library provides a parser for PQF (Prefix Query Format), an ugly
28 but precise string format for expressing Z39.50 Type-1 queries.  This
29 format is widely used behind the scenes of Z39.50 applications, and is
30 also used extensively with test-harness programs such as the YAZ
31 command-line client, C<yaz-client>.
32
33 It is simple to use.  Create a parser object, then pass PQF strings
34 into its C<parse()> method to yield parse-trees.  The trees are made
35 up of nodes whose types are all of the form
36 C<Net::Z3950::PQF::xxxNode>.  You may find it helpful to use
37 C<Data::Dumper> to visualise the structure of the returned
38 parse-trees.
39
40 What is a PQF parse-tree good for?  Not much.  You can render a
41 human-readable version by invoking the top node's C<render()> method,
42 which is probably useful only for debugging.  If you want to do
43 anything useful, such as implementing an actual query server that
44 understands PQF, you'll have to walk the tree.
45
46 =head1 METHODS
47
48 =head2 new()
49
50  $parser = new Net::Z3950::PQF();
51
52 Creates a new parser object.
53
54 =cut
55
56 sub new {
57     my $class = shift();
58
59     return bless {
60         errmsg => undef,
61     }, $class;
62 }
63
64
65 =head2 parse()
66
67  $query = '@and @attr 1=1003 kernighan @attr 1=4 unix';
68  $node = $parser->parse($query);
69  if (!defined $node)
70      die "parse($query) failed: " . $parser->errmsg();
71  } 
72
73 Parses the PQF string provided as its argument.  If an error occurs,
74 then an undefined value is returned, and the error message can be
75 obtained by calling the C<errmsg()> method.  Otherwise, the top node
76 of the parse tree is returned.
77
78 =cut
79
80 sub parse {
81     my $this = shift();
82
83     die "parse($this) not yet implemented";
84 }
85
86
87 =head2 errmsg()
88
89  print $parser->errmsg();
90
91 =cut
92
93 sub errmsg {
94     my $this = shift();
95     return $this->{errmsg};
96 }
97
98
99 =head1 SEE ALSO
100
101 The definition of the Type-1 query in the Z39.50 standard, the
102 relevant section of which is on-line at
103 http://www.loc.gov/z3950/agency/markup/09.html#3.7
104
105 The documentation of Prefix Query Format in the YAZ Manual, the
106 relevant section of which is on-line at
107 http://indexdata.com/yaz/doc/tools.tkl#PQF
108
109 =head1 AUTHOR
110
111 Mike Taylor, E<lt>mike@indexdata.comE<gt>
112
113 =head1 COPYRIGHT AND LICENSE
114
115 Copyright 2004 by Index Data ApS.
116
117 This library is free software; you can redistribute it and/or modify
118 it under the same terms as Perl itself. 
119
120 =cut