NAME

       CQL::Parser - compiles CQL strings into parse trees of Node subtypes.

SYNOPSIS

           use CQL::Parser;
           my $parser = CQL::Parser->new();
           my $root = $parser->parse( $cql );

DESCRIPTION

       CQL::Parser provides a mechanism to parse Common Query Language (CQL) statements. The best
       description of CQL comes from the CQL homepage at the Library of Congress
       <http://www.loc.gov/z3950/agency/zing/cql/>

       CQL is a formal language for representing queries to information retrieval systems such as
       web indexes, bibliographic catalogs and museum collection information. The CQL design
       objective is that queries be human readable and human writable, and that the language be
       intuitive while maintaining the expressiveness of more complex languages.

       A CQL statement can be as simple as a single keyword, or as complicated as a set of
       compoenents indicating search indexes, relations, relational modifiers, proximity clauses
       and boolean logic. CQL::Parser will parse CQL statements and return the root node for a
       tree of nodes which describes the CQL statement.  This data structure can then be used by
       a client application to analyze the statement, and possibly turn it into a query for a
       local repository.

       Each CQL component in the tree inherits from CQL::Node and can be one of the following:
       CQL::AndNode, CQL::NotNode, CQL::OrNode, CQL::ProxNode, CQL::TermNode, CQL::PrefixNode.
       See the documentation for those modules for their respective APIs.

       Here are some examples of CQL statements:

       •   george

       •   dc.creator=george

       •   dc.creator="George Clinton"

       •   clinton and funk

       •   clinton and parliament and funk

       •   (clinton or bootsy) and funk

       •   dc.creator="clinton" and dc.date="1976"

METHODS

   new()
   parse( $query )
       Pass in a CQL query and you'll get back the root node for the CQL parse tree.  If the CQL
       is invalid an exception will be thrown.

   parseSafe( $query )
       Pass in a CQL query and you'll get back the root node for the CQL parse tree.  If the CQL
       is invalid, an error code from the SRU Diagnostics List will be returned.

XCQL

       CQL has an XML representation which you can generate from a CQL parse tree. Just call the
       toXCQL() method on the root node you get back from a call to parse().

ERRORS AND DIAGNOSTICS

       As mentioned above, a CQL syntax error will result in an exception being thrown. So if you
       have any doubts about the CQL that you are parsing you should wrap the call to parse() in
       an eval block, and check $@ afterwards to make sure everything went ok.

           eval {
               my $node = $parser->parse( $cql );
           };
           if ( $@ ) {
               print "uhoh, exception $@\n";
           }

       If you'd like to see blow by blow details while your CQL is being parsed set $CQL::DEBUG
       equal to 1, and you will get details on STDERR. This is useful if the parse tree is
       incorrect and you want to locate where things are going wrong. Hopefully this won't
       happen, but if it does please notify the author.

TODO

       •   toYourEngineHere() please feel free to add functionality and send in patches!

THANKYOUS

       CQL::Parser is essentially a Perl port of Mike Taylor's cql-java package
       http://zing.z3950.org/cql/java/. Mike and IndexData were kind enough to allow the author
       to write this port, and to make it available under the terms of the Artistic License.
       Thanks Mike!

       The CQL::Lexer package relies heavily on Stevan Little's excellent String::Tokenizer.
       Thanks Stevan!

       CQL::Parser was developed as a component of the Ockham project, which is funded by the
       National Science Foundation. See http://www.ockham.org for more information about Ockham.

AUTHOR

       •   Ed Summers - ehs at pobox dot com

       •   Brian Cassidy - bricas at cpan dot org

       •   Wilbert Hengst - W.Hengst at uva dot nl

COPYRIGHT AND LICENSE

       Copyright 2004-2009 by Ed Summers

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