1 /* $Id: cql.h,v 1.9 2004-10-03 22:34:07 adam Exp $
2 Copyright (C) 2002-2004
5 This file is part of the YAZ toolkit.
11 \brief Header with public definitions about CQL.
14 #ifndef CQL_H_INCLUDED
15 #define CQL_H_INCLUDED
17 #include <yaz/yconfig.h>
21 /** CQL parser handle */
22 typedef struct cql_parser *CQL_parser;
25 * Creates a CQL parser.
26 * Returns CQL parser handle or NULL if parser could not be created.
29 CQL_parser cql_parser_create(void);
32 * Destroys a CQL parser.
34 * This function does nothing if NULL if received.
37 void cql_parser_destroy(CQL_parser cp);
40 * Parses a CQL string query.
42 * Returns 0 if on success; non-zero (error code) on failure.
45 int cql_parser_string(CQL_parser cp, const char *str);
48 * Parses a CQL query - streamed query.
50 * This function is similar to cql_parser_string but takes a
51 * functions to read each query character from a stream.
53 * The functions pointers getbytes, ungetbyte are similar to
54 * that known from stdios getc, ungetc.
56 * Returns 0 if on success; non-zero (error code) on failure.
59 int cql_parser_stream(CQL_parser cp,
60 int (*getbyte)(void *client_data),
61 void (*ungetbyte)(int b, void *client_data),
65 * Parses a CQL query from a FILE handle.
67 * This function is similar to cql_parser_string but reads from
68 * stdio FILE handle instead.
70 * Returns 0 if on success; non-zero (error code) on failure.
73 int cql_parser_stdio(CQL_parser cp, FILE *f);
76 * The node in a CQL parse tree.
79 #define CQL_NODE_BOOL 2
84 /** which == CQL_NODE_ST */
88 /** CQL index URI or NULL if no URI */
94 /** relation URL or NULL if no relation URI) */
96 /** relation modifiers */
97 struct cql_node *modifiers;
99 /** which == CQL_NODE_BOOL */
101 /** operator name "and", "or", ... */
104 struct cql_node *left;
106 struct cql_node *right;
107 /** modifiers (NULL for no list) */
108 struct cql_node *modifiers;
114 * Private structure that describes the CQL properties (profile)
116 struct cql_properties;
119 * Structure used by cql_buf_write_handlre
121 struct cql_buf_write_info {
128 * Handler for cql_buf_write_info *
131 void cql_buf_write_handler (const char *b, void *client_data);
134 * Prints a CQL node and all sub nodes. Hence this function
135 * prints the parse tree which is as returned by cql_parser_result.
138 void cql_node_print(struct cql_node *cn);
141 * This function creates a search clause node (st).
144 struct cql_node *cql_node_mk_sc(const char *index,
145 const char *relation,
150 * This function applies a prefix+uri to "unresolved" index and relation
153 * "unresolved" URIs are those nodes where member index_uri / relation_uri
157 struct cql_node *cql_apply_prefix(struct cql_node *cn,
162 * This function creates a boolean node.
165 struct cql_node *cql_node_mk_boolean(const char *op);
168 * Destroys a node and its children.
171 void cql_node_destroy(struct cql_node *cn);
174 * Duplicate a node (returns a copy of supplied node) .
177 struct cql_node *cql_node_dup (struct cql_node *cp);
180 * This function returns the parse tree of the most recently parsed
183 * The function returns NULL if most recently parse failed.
186 struct cql_node *cql_parser_result(CQL_parser cp);
189 * This function converts a CQL node tree to XCQL and writes the
190 * resulting XCQL to a user-defined output stream.
193 void cql_to_xml(struct cql_node *cn,
194 void (*pr)(const char *buf, void *client_data),
197 * This function converts a CQL node tree to XCQL and writes the
198 * resulting XCQL to a FILE handle (stdio)
201 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
204 * This function converts a CQL node tree to XCQL and writes
205 * the resulting XCQL to a buffer
208 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
211 * Utility function that prints to a FILE.
214 void cql_fputs(const char *buf, void *client_data);
217 * The CQL transform handle. The transform describes how to
218 * convert from CQL to PQF (Type-1 AKA RPN).
220 typedef struct cql_transform_t_ *cql_transform_t;
223 * Creates a CQL transform handle. The transformation spec is read from
224 * a FILE handle (which is assumed opened in read mode).
227 cql_transform_t cql_transform_open_FILE (FILE *f);
230 * Creates a CQL transform handle. The transformation spec is read from
231 * a file with the filename given.
234 cql_transform_t cql_transform_open_fname(const char *fname);
237 * Destroys a CQL transform handle.
240 void cql_transform_close(cql_transform_t ct);
243 * Performs a CQL transform to PQF given a CQL node tree and a CQL
244 * transformation handle. The result is written to a user-defined stream.
247 void cql_transform_pr(cql_transform_t ct,
249 void (*pr)(const char *buf, void *client_data),
253 * Performs a CQL transform to PQF given a CQL node tree and a CQL
254 * transformation handle. The result is written to a file specified by
255 * FILE handle (which must be opened for writing).
258 int cql_transform_FILE(cql_transform_t ct,
259 struct cql_node *cn, FILE *f);
262 * Performs a CQL transform to PQF given a CQL node tree and a CQL
263 * transformation handle. The result is written to a buffer.
266 int cql_transform_buf(cql_transform_t ct,
267 struct cql_node *cn, char *out, int max);
269 * Returns error code and additional information from last transformation.
270 * Performs a CQL transform given a CQL node tree and a CQL transformation.
273 int cql_transform_error(cql_transform_t ct, const char **addinfo);
276 * Returns the CQL message corresponding to a given error code.
279 const char *cql_strerror(int code);
282 * Returns the standard CQL context set URI.
285 const char *cql_uri();