From: Adam Dickmeiss Date: Wed, 22 Jan 2003 09:43:32 +0000 (+0000) Subject: CQL section in tools. Not yet finished X-Git-Tag: YAZ.2.0~63 X-Git-Url: http://lists.indexdata.dk/?a=commitdiff_plain;h=e13889f2448f526c2d7be104228a76278fdd1e18;p=yaz-moved-to-github.git CQL section in tools. Not yet finished --- diff --git a/doc/tools.xml b/doc/tools.xml index 28ad015..841fb9a 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -464,6 +464,228 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, + CQL + + CQL + - Common Query Language - was defined for the + SRW + protocol. + In many ways CQL has a similar syntax to CCL. + The objective of CQL is different. Where CCL aims to be + an end-user language, CQL is the protocol + query language for SRW. Unlike PQF (Z39.50 Type-1), CQL is easy + to read. + + + + If you are new to CQL, read the + Gentle + Introduction. + + + + The CQL parser in &yaz; provides the following: + + + + It parses and validates a CQL query. + + + + + It generates a C structure that allows you to convert + a CQL query to some other query language, such as SQL. + + + + + The parser converts a valid CQL query to PQF, thus providing a + way to use CQL for both SRW/SRU servers and Z39.50 targets at the + same time. + + + + + The parser converts CQL to + + XCQL. + XCQL is an XML representation of CQL. + XCQL is part of the SRW specification. However, since SRU + supports CQL only, we don't expect XCQL to be widely used. + Furthermore, CQL has the advantage over XCQL that it is + easy to read. + + + + + CQL parsing + + A CQL parser is represented by the CQL_parser + handle. Its contents should be considered &yaz; internal (private). + +#include <yaz/cql.h> + +typedef struct cql_parser *CQL_parser; + +CQL_parser cql_parser_create(void); +void cql_parser_destroy(CQL_parser cp); + +int cql_parser_string(CQL_parser cp, const char *str); + + A parser is created by cql_parser_create and + is destroyed by cql_parser_destroy. + + + A CQL query is parsed by the cql_parser_string + which takes a query str. + If the query was valid (no syntax errors), then zero is returned; + otherwise a non-zero error code is returned. + + + +int cql_parser_stream(CQL_parser cp, + int (*getbyte)(void *client_data), + void (*ungetbyte)(int b, void *client_data), + void *client_data); + +int cql_parser_stdio(CQL_parser cp, FILE *f); + + The functions cql_parser_stream and + cql_parser_stdio parses a CQL query + - just like cql_parser_string. + The only difference is that the CQL query can be + fed to the parser in different ways. + The cql_parser_stream uses a generic + byte stream as input. The cql_parser_stdio + uses a FILE handle which is opened for reading. + + + CQL tree + + We now turn to the tree representation of a valid CQL query. + +#define CQL_NODE_ST 1 +#define CQL_NODE_BOOL 2 +#define CQL_NODE_MOD 3 +struct cql_node { + int which; + union { + struct { + char *index; + char *term; + char *relation; + struct cql_node *modifiers; + struct cql_node *prefixes; + } st; + struct { + char *value; + struct cql_node *left; + struct cql_node *right; + struct cql_node *modifiers; + struct cql_node *prefixes; + } bool; + struct { + char *name; + char *value; + struct cql_node *next; + } mod; + } u; +}; + + There are three kinds of nodes, search term (ST), boolean (BOOL), + and modifier (MOD). + + + The search term node has five members: + + + + index: index for search term. + If an index is unspecified for a search term, + index will be NULL. + + + + + term: the search term itself. + + + + + relation: relation for search term. + + + + + modifiers: relation modifiers for search + term. The modifiers is a simple linked + list (NULL for last entry). Each relation modifier node + is of type MOD. + + + + + prefixes: index prefixes for search + term. The prefixes is a simple linked + list (NULL for last entry). Each prefix node + is of type MOD. + + + + + + + The boolean node represents both and, + or, not as well as + proximity. + + + + left and right: left + - and right operand respectively. + + + + + modifiers: proximity arguments. + + + + + prefixes: index prefixes. + The prefixes is a simple linked + list (NULL for last entry). Each prefix node + is of type MOD. + + + + + + + The modifier node is a "utility" node used for name-value pairs, + such as prefixes, proximity arguements, etc. + + + + name name of mod node. + + + + + value value of mod node. + + + + + next: pointer to next node which is + always a mod node (NULL for last entry). + + + + + + + Object Identifiers