lib/Net/Z3950/PQF.pm

   1 # $Id: PQF.pm,v 1.2 2004-12-17 15:28:30 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(0);
  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 subclasses of
  36 C<Net::Z3950::PQF::Node>.
  37 and have names of the form
  38 C<Net::Z3950::PQF::somethingNode>.  You may find it helpful to use
  39 C<Data::Dumper> to visualise the structure of the returned
  40 parse-trees.
  41
  42 What is a PQF parse-tree good for?  Not much.  You can render a
  43 human-readable version by invoking the top node's C<render()> method,
  44 which is probably useful only for debugging.  If you want to do
  45 anything useful, such as implementing an actual query server that
  46 understands PQF, you'll have to walk the tree.
  47
  48 =head1 METHODS
  49
  50 =head2 new()
  51
  52  $parser = new Net::Z3950::PQF();
  53
  54 Creates a new parser object.
  55
  56 =cut
  57
  58 sub new {
  59     my $class = shift();
  60
  61     return bless {
  62         errmsg => undef,
  63     }, $class;
  64 }
  65
  66
  67 =head2 parse()
  68
  69  $query = '@and @attr 1=1003 kernighan @attr 1=4 unix';
  70  $node = $parser->parse($query);
  71  if (!defined $node)
  72      die "parse($query) failed: " . $parser->errmsg();
  73  }
  74
  75 Parses the PQF string provided as its argument.  If an error occurs,
  76 then an undefined value is returned, and the error message can be
  77 obtained by calling the C<errmsg()> method.  Otherwise, the top node
  78 of the parse tree is returned.
  79
  80  $node2 = $parser->parse($query, "zthes");
  81  $node3 = $parser->parse($query, "1.2.840.10003.3.13");
  82
  83 A second argument may be provided, after the query itself.  If it is
  84 provided, then it is taken to be either the name or the OID of a
  85 default attribute set, which attributes specified in the query belong
  86 to if no alternative attribute set is explicitly specified.  When this
  87 second argument is absent, the default attribute set is BIB-1.
  88
  89 =cut
  90
  91 sub parse {
  92     my $this = shift();
  93     my($attrset) = @_;
  94     $attrset = "bib-1" if !defined $attrset;
  95
  96     die "parse($this) not yet implemented";
  97 }
  98
  99
 100 =head2 errmsg()
 101
 102  print $parser->errmsg();
 103
 104 =cut
 105
 106 sub errmsg {
 107     my $this = shift();
 108     return $this->{errmsg};
 109 }
 110
 111
 112 =head1 SEE ALSO
 113
 114 The definition of the Type-1 query in the Z39.50 standard, the
 115 relevant section of which is on-line at
 116 http://www.loc.gov/z3950/agency/markup/09.html#3.7
 117
 118 The documentation of Prefix Query Format in the YAZ Manual, the
 119 relevant section of which is on-line at
 120 http://indexdata.com/yaz/doc/tools.tkl#PQF
 121
 122 =head1 AUTHOR
 123
 124 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 125
 126 =head1 COPYRIGHT AND LICENSE
 127
 128 Copyright 2004 by Index Data ApS.
 129
 130 This library is free software; you can redistribute it and/or modify
 131 it under the same terms as Perl itself.
 132
 133 =cut
 134
 135
 136 1;