CQL::Parser(3pm)

💖 CQL::Parser — the vibe ✨

okay bestie, so this is the manual page for CQL::Parser(3pm), from the User Contributed Perl Documentation collection. She's a Perl module, she compiles CQL strings into parse trees of Node subtypes, and she is lowkey iconic. Let's get into it. 🫶

---

✨ NAME ✨

CQL::Parser — compiles CQL strings into parse trees of Node subtypes. that's it, that's the whole job, and she does it flawlessly. 💅

---

🌸 SYNOPSIS 🌸

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

three lines. three little lines and you're parsing. main character energy fr fr. 🎀

---

🦋 DESCRIPTION 🦋

CQL::Parser gives you a mechanism to parse Common Query Language (CQL) statements. and the best description of CQL comes from the CQL homepage at the Library of Congress <http://www.loc.gov/z3950/agency/zing/cql/> — go look, it's giving academic but make it slay. 📚✨

CQL is a formal language for representing queries to information retrieval systems — think web indexes, bibliographic catalogs, museum collection information. the whole design objective? that queries be human readable and human writable, and that the language stay intuitive while still keeping the expressiveness of more complex languages. like yes, be cute AND be powerful. we love a multitasker. 👑

a CQL statement can be as simple as a single keyword, or as complicated as a set of components indicating search indexes, relations, relational modifiers, proximity clauses and boolean logic. CQL::Parser will parse CQL statements and hand you back the root node for a tree of nodes that describes the CQL statement. then your client application can use that data structure to analyze the statement, and possibly turn it into a query for a local repository. iconic behaviour tbh. 🌈

every 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. hit up the docs for those modules for their respective APIs, bestie, they each have their own thing going on. 💜

here are some examples of CQL statements, and yes they're all bangers:

• 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"

not the George Clinton / Parliament / Bootsy Collins run 😭 the taste jumped OUT.

---

🎀 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. no cap, she will simply throw. 🚨

💫 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 instead. the gentle version. the soft launch. 🫶

---

🧚 XCQL 🧚

CQL has an XML representation, and you can generate it straight from a CQL parse tree. just call the toXCQL() method on the root node you get back from a call to parse(). that's it. one method. obsessed. 💖

---

🔥 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 you're 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";
}

look at that "uhoh, exception $@\n" — she's honest, she's real, she's all of us when the parse fails. 😭

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. (please be nice about it, they're doing their best 💜)

---

⭐ TODO ⭐

• toYourEngineHere() — please feel free to add functionality and send in patches! this is your moment, bestie. the door is OPEN. 🚪✨

---

💜 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. science + Perl + funding = the dream combo fr fr. 🔬💖

---

👑 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.

open source, free to remix, free to redistribute, same terms as Perl itself — the whole community vibe. slay. 💅

---

and that's the page!! 💖 she's version perl v5.36.0, dated 2022-12-11, and she's been out here parsing CQL since way back. go forth, parse responsibly, check your $@, and remember: parseSafe() if you're feeling fragile, parse() if you're feeling brave. mwah!! 🎀✨🦋