.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "CQL::Parser 3pm" .TH CQL::Parser 3pm "2018-08-25" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CQL::Parser \- compiles CQL strings into parse trees of Node subtypes. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use CQL::Parser; \& my $parser = CQL::Parser\->new(); \& my $root = $parser\->parse( $cql ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" CQL::Parser provides a mechanism to parse Common Query Language (\s-1CQL\s0) statements. The best description of \s-1CQL\s0 comes from the \s-1CQL\s0 homepage at the Library of Congress .PP \&\s-1CQL\s0 is a formal language for representing queries to information retrieval systems such as web indexes, bibliographic catalogs and museum collection information. The \s-1CQL\s0 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. .PP A \s-1CQL\s0 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 \s-1CQL\s0 statements and return the root node for a tree of nodes which describes the \s-1CQL\s0 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. .PP Each \s-1CQL\s0 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. .PP Here are some examples of \s-1CQL\s0 statements: .IP "\(bu" 4 george .IP "\(bu" 4 dc.creator=george .IP "\(bu" 4 dc.creator=\*(L"George Clinton\*(R" .IP "\(bu" 4 clinton and funk .IP "\(bu" 4 clinton and parliament and funk .IP "\(bu" 4 (clinton or bootsy) and funk .IP "\(bu" 4 dc.creator=\*(L"clinton\*(R" and dc.date=\*(L"1976\*(R" .SH "METHODS" .IX Header "METHODS" .SS "\fInew()\fP" .IX Subsection "new()" .ie n .SS "parse( $query )" .el .SS "parse( \f(CW$query\fP )" .IX Subsection "parse( $query )" Pass in a \s-1CQL\s0 query and you'll get back the root node for the \s-1CQL\s0 parse tree. If the \s-1CQL\s0 is invalid an exception will be thrown. .ie n .SS "parseSafe( $query )" .el .SS "parseSafe( \f(CW$query\fP )" .IX Subsection "parseSafe( $query )" Pass in a \s-1CQL\s0 query and you'll get back the root node for the \s-1CQL\s0 parse tree. If the \s-1CQL\s0 is invalid, an error code from the \s-1SRU\s0 Diagnostics List will be returned. .SH "XCQL" .IX Header "XCQL" \&\s-1CQL\s0 has an \s-1XML\s0 representation which you can generate from a \s-1CQL\s0 parse tree. Just call the \fItoXCQL()\fR method on the root node you get back from a call to \fIparse()\fR. .SH "ERRORS AND DIAGNOSTICS" .IX Header "ERRORS AND DIAGNOSTICS" As mentioned above, a \s-1CQL\s0 syntax error will result in an exception being thrown. So if you have any doubts about the \s-1CQL\s0 that you are parsing you should wrap the call to \fIparse()\fR in an eval block, and check $@ afterwards to make sure everything went ok. .PP .Vb 6 \& eval { \& my $node = $parser\->parse( $cql ); \& }; \& if ( $@ ) { \& print "uhoh, exception $@\en"; \& } .Ve .PP If you'd like to see blow by blow details while your \s-1CQL\s0 is being parsed set \f(CW$CQL::DEBUG\fR equal to 1, and you will get details on \s-1STDERR.\s0 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. .SH "TODO" .IX Header "TODO" .IP "\(bu" 4 \&\fItoYourEngineHere()\fR please feel free to add functionality and send in patches! .SH "THANKYOUS" .IX Header "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! .PP The CQL::Lexer package relies heavily on Stevan Little's excellent String::Tokenizer. Thanks Stevan! .PP 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. .SH "AUTHOR" .IX Header "AUTHOR" .IP "\(bu" 4 Ed Summers \- ehs at pobox dot com .IP "\(bu" 4 Brian Cassidy \- bricas at cpan dot org .IP "\(bu" 4 Wilbert Hengst \- W.Hengst at uva dot nl .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2004\-2009 by Ed Summers .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.