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.