X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=include%2Fyaz%2Fcql.h;h=33c72953ee4b271f15e007540ebc6acf6d493469;hp=4b75df2ce8376ff3657ec272eba74d4e5d862ed2;hb=4c176312acdc3444c9afc820f76a393e64668e52;hpb=f512aa33473ae86f8e8efd8da749a82c398e87f0 diff --git a/include/yaz/cql.h b/include/yaz/cql.h index 4b75df2..33c7295 100644 --- a/include/yaz/cql.h +++ b/include/yaz/cql.h @@ -1,5 +1,5 @@ -/* $Id: cql.h,v 1.3 2003-02-18 21:27:53 adam Exp $ - Copyright (C) 2002-2003 +/* $Id: cql.h,v 1.11 2005-01-15 19:47:09 adam Exp $ + Copyright (C) 1995-2005, Index Data ApS Index Data Aps This file is part of the YAZ toolkit. @@ -7,57 +7,53 @@ This file is part of the YAZ toolkit. See the file LICENSE. */ +/** \file cql.h + \brief Header with public definitions about CQL. +*/ + #ifndef CQL_H_INCLUDED #define CQL_H_INCLUDED #include -#include +#include + +YAZ_BEGIN_CDECL +/** CQL parser handle */ typedef struct cql_parser *CQL_parser; /** - * cql_parser_create: - * - * creates a CQL parser. - * - * Returns CQL parser or NULL if parser could not be created. + * Creates a CQL parser. + * Returns CQL parser handle or NULL if parser could not be created. */ YAZ_EXPORT CQL_parser cql_parser_create(void); /** - * cql_parser_destroy: - * @cp: A CQL parser + * Destroys a CQL parser. * - * Destroy CQL parser. This function does nothing if - * NULL pointer is received. + * This function does nothing if NULL if received. */ YAZ_EXPORT void cql_parser_destroy(CQL_parser cp); /** - * cql_parser_string: - * @cp: A CQL parser. - * @str: A query string to be parsed. + * Parses a CQL string query. * - * Parses a CQL query string. - * - * Returns 0 if parsing was succesful; non-zero (error code) if - * unsuccesful. + * Returns 0 if on success; non-zero (error code) on failure. */ YAZ_EXPORT int cql_parser_string(CQL_parser cp, const char *str); /** - * cql_parser_stream: - * @cp: A CQL parser. - * @getbyte: Handler to read one character (for parsing). - * @ungetbyte: Handler to unread one byte (for parsing). - * @client_data: User data associated with getbyte/ungetbyte handlers. + * Parses a CQL query - streamed query. + * + * This function is similar to cql_parser_string but takes a + * functions to read each query character from a stream. * - * Parses a CQL query from a user defined stream. + * The functions pointers getbytes, ungetbyte are similar to + * that known from stdios getc, ungetc. * - * Returns 0 if parsing was succesful; non-zero (error code) if - * unsuccesful. + * Returns 0 if on success; non-zero (error code) on failure. */ YAZ_EXPORT int cql_parser_stream(CQL_parser cp, @@ -66,162 +62,226 @@ int cql_parser_stream(CQL_parser cp, void *client_data); /** - * cql_parser_stdio: - * @cp: A CQL parser. - * @f: FILE handler in read mode. + * Parses a CQL query from a FILE handle. * - * Parses a CQL query from a file. + * This function is similar to cql_parser_string but reads from + * stdio FILE handle instead. * - * Returns 0 if parsing was succesful; non-zero (error code) if - * unsuccesful. + * Returns 0 if on success; non-zero (error code) on failure. */ YAZ_EXPORT int cql_parser_stdio(CQL_parser cp, FILE *f); +/** + * The node in a CQL parse tree. + */ #define CQL_NODE_ST 1 #define CQL_NODE_BOOL 2 -#define CQL_NODE_MOD 3 struct cql_node { + /** node type */ int which; union { + /** which == CQL_NODE_ST */ struct { + /** CQL index */ char *index; + /** CQL index URI or NULL if no URI */ + char *index_uri; + /** Search term */ char *term; + /** relation */ char *relation; + /** relation URL or NULL if no relation URI) */ + char *relation_uri; + /** relation modifiers */ struct cql_node *modifiers; - struct cql_node *prefixes; } st; + /** which == CQL_NODE_BOOL */ struct { + /** operator name "and", "or", ... */ char *value; + /** left operand */ struct cql_node *left; + /** right operand */ struct cql_node *right; + /** modifiers (NULL for no list) */ struct cql_node *modifiers; - struct cql_node *prefixes; } boolean; - struct { - char *name; - char *value; - struct cql_node *next; - } mod; } u; }; +/** + * Private structure that describes the CQL properties (profile) + */ struct cql_properties; +/** + * Structure used by cql_buf_write_handlre + */ struct cql_buf_write_info { int max; int off; char *buf; }; +/** + * Handler for cql_buf_write_info * + */ YAZ_EXPORT void cql_buf_write_handler (const char *b, void *client_data); +/** + * Prints a CQL node and all sub nodes. Hence this function + * prints the parse tree which is as returned by cql_parser_result. + */ YAZ_EXPORT void cql_node_print(struct cql_node *cn); + +/** + * This function creates a search clause node (st). + */ YAZ_EXPORT -struct cql_node *cql_node_mk_sc(const char *index, - const char *relation, - const char *term); -YAZ_EXPORT -struct cql_node *cql_node_mk_boolean(const char *op); +struct cql_node *cql_node_mk_sc(NMEM nmem, const char *index, + const char *relation, const char *term); + +/** + * This function applies a prefix+uri to "unresolved" index and relation + * URIs. + * + * "unresolved" URIs are those nodes where member index_uri / relation_uri + * is NULL. + */ YAZ_EXPORT -void cql_node_destroy(struct cql_node *cn); +struct cql_node *cql_apply_prefix(NMEM nmem, struct cql_node *cn, + const char *prefix, const char *uri); + +/** + * This function creates a boolean node. + */ YAZ_EXPORT -struct cql_node *cql_node_prefix(struct cql_node *n, - const char *prefix, - const char *uri); +struct cql_node *cql_node_mk_boolean(NMEM nmem, const char *op); + +/** + * Destroys a node and its children. + */ YAZ_EXPORT -struct cql_node *cql_node_mk_mod(const char *name, - const char *value); +void cql_node_destroy(struct cql_node *cn); +/** + * Duplicate a node (returns a copy of supplied node) . + */ YAZ_EXPORT -struct cql_node *cql_node_dup (struct cql_node *cp); +struct cql_node *cql_node_dup (NMEM nmem, struct cql_node *cp); + +/** + * This function returns the parse tree of the most recently parsed + * CQL query. + * + * The function returns NULL if most recently parse failed. + */ YAZ_EXPORT struct cql_node *cql_parser_result(CQL_parser cp); +/** + * This function converts a CQL node tree to XCQL and writes the + * resulting XCQL to a user-defined output stream. + */ YAZ_EXPORT void cql_to_xml(struct cql_node *cn, void (*pr)(const char *buf, void *client_data), void *client_data); +/** + * This function converts a CQL node tree to XCQL and writes the + * resulting XCQL to a FILE handle (stdio) + */ YAZ_EXPORT void cql_to_xml_stdio(struct cql_node *cn, FILE *f); -YAZ_EXPORT -int cql_to_xml_buf(struct cql_node *cn, char *out, int max); +/** + * This function converts a CQL node tree to XCQL and writes + * the resulting XCQL to a buffer + */ YAZ_EXPORT -struct cql_node *cql_node_mk_proxargs(const char *relation, - const char *distance, - const char *unit, - const char *ordering); - +int cql_to_xml_buf(struct cql_node *cn, char *out, int max); +/** + * Utility function that prints to a FILE. + */ YAZ_EXPORT void cql_fputs(const char *buf, void *client_data); +/** + * The CQL transform handle. The transform describes how to + * convert from CQL to PQF (Type-1 AKA RPN). + */ typedef struct cql_transform_t_ *cql_transform_t; +/** + * Creates a CQL transform handle. The transformation spec is read from + * a FILE handle (which is assumed opened in read mode). + */ YAZ_EXPORT cql_transform_t cql_transform_open_FILE (FILE *f); + +/** + * Creates a CQL transform handle. The transformation spec is read from + * a file with the filename given. + */ YAZ_EXPORT cql_transform_t cql_transform_open_fname(const char *fname); + +/** + * Destroys a CQL transform handle. + */ YAZ_EXPORT void cql_transform_close(cql_transform_t ct); +/** + * Performs a CQL transform to PQF given a CQL node tree and a CQL + * transformation handle. The result is written to a user-defined stream. + */ YAZ_EXPORT void cql_transform_pr(cql_transform_t ct, struct cql_node *cn, void (*pr)(const char *buf, void *client_data), void *client_data); +/** + * Performs a CQL transform to PQF given a CQL node tree and a CQL + * transformation handle. The result is written to a file specified by + * FILE handle (which must be opened for writing). + */ YAZ_EXPORT int cql_transform_FILE(cql_transform_t ct, struct cql_node *cn, FILE *f); +/** + * Performs a CQL transform to PQF given a CQL node tree and a CQL + * transformation handle. The result is written to a buffer. + */ YAZ_EXPORT int cql_transform_buf(cql_transform_t ct, struct cql_node *cn, char *out, int max); +/** + * Returns error code and additional information from last transformation. + * Performs a CQL transform given a CQL node tree and a CQL transformation. + */ YAZ_EXPORT int cql_transform_error(cql_transform_t ct, const char **addinfo); -/* -10 Illegal query -11 Unsupported query type (XCQL vs CQL) -12 Too many characters in query -13 Unbalanced or illegal use of parentheses -14 Unbalanced or illegal use of quotes -15 Illegal or unsupported index set -16 Illegal or unsupported index -17 Illegal or unsupported combination of index and index set -18 Illegal or unsupported combination of indexes -19 Illegal or unsupported relation -20 Illegal or unsupported relation modifier -21 Illegal or unsupported combination of relation modifers -22 Illegal or unsupported combination of relation and index -23 Too many characters in term -24 Illegal combination of relation and term -25 Special characters not quoted in term -26 Non special character escaped in term -27 Empty term unsupported -28 Masking character not supported -29 Masked words too short -30 Too many masking characters in term -31 Anchoring character not supported -32 Anchoring character in illegal or unsupported position -33 Combination of proximity/adjacency and masking characters not supported -34 Combination of proximity/adjacency and anchoring characters not supported -35 Terms only exclusion (stop) words -36 Term in invalid format for index or relation -37 Illegal or unsupported boolean operator -38 Too many boolean operators in query -39 Proximity not supported -40 Illegal or unsupported proximity relation -41 Illegal or unsupported proximity distance -42 Illegal or unsupported proximity unit -43 Illegal or unsupported proximity ordering -44 Illegal or unsupported combination of proximity modifiers -45 Index set name (prefix) assigned to multiple identifiers -*/ +/** + * Returns the CQL message corresponding to a given error code. + */ +YAZ_EXPORT +const char *cql_strerror(int code); + +/** + * Returns the standard CQL context set URI. + */ +YAZ_EXPORT +const char *cql_uri(); + +YAZ_END_CDECL #endif /* CQL_H_INCLUDED */