2 * Copyright (c) 1995-2006, Index Data
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of Index Data nor the names of its contributors
13 * may be used to endorse or promote products derived from this
14 * software without specific prior written permission.
16 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
17 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
20 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 /* $Id: cql.h,v 1.15 2006-10-09 21:02:41 adam Exp $ */
29 /* $Id: cql.h,v 1.15 2006-10-09 21:02:41 adam Exp $
30 Copyright (C) 1995-2005, Index Data ApS
33 This file is part of the YAZ toolkit.
39 \brief Header with public definitions about CQL.
42 #ifndef CQL_H_INCLUDED
43 #define CQL_H_INCLUDED
49 /** CQL parser handle */
50 typedef struct cql_parser *CQL_parser;
53 * Creates a CQL parser.
54 * Returns CQL parser handle or NULL if parser could not be created.
57 CQL_parser cql_parser_create(void);
60 * Destroys a CQL parser.
62 * This function does nothing if NULL if received.
65 void cql_parser_destroy(CQL_parser cp);
68 * Parses a CQL string query.
70 * Returns 0 if on success; non-zero (error code) on failure.
73 int cql_parser_string(CQL_parser cp, const char *str);
76 * Parses a CQL query - streamed query.
78 * This function is similar to cql_parser_string but takes a
79 * functions to read each query character from a stream.
81 * The functions pointers getbytes, ungetbyte are similar to
82 * that known from stdios getc, ungetc.
84 * Returns 0 if on success; non-zero (error code) on failure.
87 int cql_parser_stream(CQL_parser cp,
88 int (*getbyte)(void *client_data),
89 void (*ungetbyte)(int b, void *client_data),
93 * Parses a CQL query from a FILE handle.
95 * This function is similar to cql_parser_string but reads from
96 * stdio FILE handle instead.
98 * Returns 0 if on success; non-zero (error code) on failure.
101 int cql_parser_stdio(CQL_parser cp, FILE *f);
104 * The node in a CQL parse tree.
106 #define CQL_NODE_ST 1
107 #define CQL_NODE_BOOL 2
112 /** which == CQL_NODE_ST */
116 /** CQL index URI or NULL if no URI */
122 /** relation URL or NULL if no relation URI) */
124 /** relation modifiers */
125 struct cql_node *modifiers;
127 /** which == CQL_NODE_BOOL */
129 /** operator name "and", "or", ... */
132 struct cql_node *left;
134 struct cql_node *right;
135 /** modifiers (NULL for no list) */
136 struct cql_node *modifiers;
142 * Private structure that describes the CQL properties (profile)
144 struct cql_properties;
147 * Structure used by cql_buf_write_handlre
149 struct cql_buf_write_info {
156 * Handler for cql_buf_write_info *
159 void cql_buf_write_handler (const char *b, void *client_data);
162 * Prints a CQL node and all sub nodes. Hence this function
163 * prints the parse tree which is as returned by cql_parser_result.
166 void cql_node_print(struct cql_node *cn);
169 * This function creates a search clause node (st).
172 struct cql_node *cql_node_mk_sc(NMEM nmem, const char *index,
173 const char *relation, const char *term);
176 * This function applies a prefix+uri to "unresolved" index and relation
179 * "unresolved" URIs are those nodes where member index_uri / relation_uri
183 struct cql_node *cql_apply_prefix(NMEM nmem, struct cql_node *cn,
184 const char *prefix, const char *uri);
187 * This function creates a boolean node.
190 struct cql_node *cql_node_mk_boolean(NMEM nmem, const char *op);
193 * Destroys a node and its children.
196 void cql_node_destroy(struct cql_node *cn);
199 * Duplicate a node (returns a copy of supplied node) .
202 struct cql_node *cql_node_dup (NMEM nmem, struct cql_node *cp);
205 * This function returns the parse tree of the most recently parsed
208 * The function returns NULL if most recently parse failed.
211 struct cql_node *cql_parser_result(CQL_parser cp);
214 * This function converts a CQL node tree to XCQL and writes the
215 * resulting XCQL to a user-defined output stream.
218 void cql_to_xml(struct cql_node *cn,
219 void (*pr)(const char *buf, void *client_data),
222 * This function converts a CQL node tree to XCQL and writes the
223 * resulting XCQL to a FILE handle (stdio)
226 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
229 * This function converts a CQL node tree to XCQL and writes
230 * the resulting XCQL to a buffer
233 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
236 * Utility function that prints to a FILE.
239 void cql_fputs(const char *buf, void *client_data);
242 * The CQL transform handle. The transform describes how to
243 * convert from CQL to PQF (Type-1 AKA RPN).
245 typedef struct cql_transform_t_ *cql_transform_t;
248 * Creates a CQL transform handle. The transformation spec is read from
249 * a FILE handle (which is assumed opened in read mode).
252 cql_transform_t cql_transform_open_FILE (FILE *f);
255 * Creates a CQL transform handle. The transformation spec is read from
256 * a file with the filename given.
259 cql_transform_t cql_transform_open_fname(const char *fname);
262 * Destroys a CQL transform handle.
265 void cql_transform_close(cql_transform_t ct);
268 * Performs a CQL transform to PQF given a CQL node tree and a CQL
269 * transformation handle. The result is written to a user-defined stream.
272 void cql_transform_pr(cql_transform_t ct,
274 void (*pr)(const char *buf, void *client_data),
278 * Performs a CQL transform to PQF given a CQL node tree and a CQL
279 * transformation handle. The result is written to a file specified by
280 * FILE handle (which must be opened for writing).
283 int cql_transform_FILE(cql_transform_t ct,
284 struct cql_node *cn, FILE *f);
287 * Performs a CQL transform to PQF given a CQL node tree and a CQL
288 * transformation handle. The result is written to a buffer.
291 int cql_transform_buf(cql_transform_t ct,
292 struct cql_node *cn, char *out, int max);
294 * Returns error code and additional information from last transformation.
295 * Performs a CQL transform given a CQL node tree and a CQL transformation.
298 int cql_transform_error(cql_transform_t ct, const char **addinfo);
301 * Returns the CQL message corresponding to a given error code.
304 const char *cql_strerror(int code);
307 * Returns the standard CQL context set URI.
310 const char *cql_uri(void);
313 * Compares two CQL strings (for relations, operators, etc)
314 * (unfortunately defined as case-insensitive unlike XML etc)
317 int cql_strcmp(const char *s1, const char *s2);
320 * Compares two CQL strings at most n bytes
321 * (unfortunately defined as case-insensitive unlike XML etc)
324 int cql_strncmp(const char *s1, const char *s2, size_t n);
333 * indent-tabs-mode: nil
335 * vim: shiftwidth=4 tabstop=8 expandtab