-/* $Id: cql.h,v 1.2 2003-02-14 18:49:23 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.
See the file LICENSE.
*/
+/** \file cql.h
+ \brief Header with public definitions about CQL.
+*/
+
#ifndef CQL_H_INCLUDED
#define CQL_H_INCLUDED
#include <stdio.h>
+#include <yaz/nmem.h>
+
+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,
int (*getbyte)(void *client_data),
void (*ungetbyte)(int b, void *client_data),
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);
-struct cql_node *cql_node_mk_sc(const char *index,
- const char *relation,
- const char *term);
-struct cql_node *cql_node_mk_boolean(const char *op);
+
+/**
+ * This function creates a search clause node (st).
+ */
+YAZ_EXPORT
+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
+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_mk_boolean(NMEM nmem, const char *op);
+
+/**
+ * Destroys a node and its children.
+ */
+YAZ_EXPORT
void cql_node_destroy(struct cql_node *cn);
-struct cql_node *cql_node_prefix(struct cql_node *n, const char *prefix,
- const char *uri);
-struct cql_node *cql_node_mk_mod(const char *name,
- const char *value);
-struct cql_node *cql_node_dup (struct cql_node *cp);
+/**
+ * Duplicate a node (returns a copy of supplied node) .
+ */
+YAZ_EXPORT
+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);
-int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
-
-struct cql_node *cql_node_mk_proxargs(const char *relation,
- const char *distance,
- const char *unit,
- const char *ordering);
+/**
+ * This function converts a CQL node tree to XCQL and writes
+ * the resulting XCQL to a buffer
+ */
+YAZ_EXPORT
+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 */
projects / yaz-moved-to-github.git / blobdiff