Expanded tabs in all source files. Added vim/emacs local variables
[yaz-moved-to-github.git] / include / yaz / cql.h
1 /* $Id: cql.h,v 1.12 2005-06-25 15:46:02 adam Exp $
2    Copyright (C) 1995-2005, Index Data ApS
3    Index Data Aps
4
5 This file is part of the YAZ toolkit.
6
7 See the file LICENSE.
8 */
9
10 /** \file cql.h
11     \brief Header with public definitions about CQL.
12 */
13
14 #ifndef CQL_H_INCLUDED
15 #define CQL_H_INCLUDED
16 #include <stdio.h>
17 #include <yaz/nmem.h>
18
19 YAZ_BEGIN_CDECL
20
21 /** CQL parser handle */
22 typedef struct cql_parser *CQL_parser;
23
24 /**
25  * Creates a CQL parser.
26  * Returns CQL parser handle or NULL if parser could not be created.
27  */
28 YAZ_EXPORT 
29 CQL_parser cql_parser_create(void);
30
31 /**
32  * Destroys a CQL parser.
33  *
34  * This function does nothing if NULL if received.
35  */
36 YAZ_EXPORT 
37 void cql_parser_destroy(CQL_parser cp);
38
39 /**
40  * Parses a CQL string query.
41  *
42  * Returns 0 if on success; non-zero (error code) on failure.
43  */
44 YAZ_EXPORT 
45 int cql_parser_string(CQL_parser cp, const char *str);
46
47 /**
48  * Parses a CQL query - streamed query.
49  *
50  * This function is similar to cql_parser_string but takes a
51  * functions to read each query character from a stream.
52  *
53  * The functions pointers getbytes, ungetbyte are similar to
54  * that known from stdios getc, ungetc.
55  *
56  * Returns 0 if on success; non-zero (error code) on failure.
57  */
58 YAZ_EXPORT 
59 int cql_parser_stream(CQL_parser cp,
60                       int (*getbyte)(void *client_data),
61                       void (*ungetbyte)(int b, void *client_data),
62                       void *client_data);
63
64 /**
65  * Parses a CQL query from a FILE handle.
66  *
67  * This function is similar to cql_parser_string but reads from 
68  * stdio FILE handle instead.
69  *
70  * Returns 0 if on success; non-zero (error code) on failure.
71  */
72 YAZ_EXPORT
73 int cql_parser_stdio(CQL_parser cp, FILE *f);
74
75 /**
76  * The node in a CQL parse tree. 
77  */
78 #define CQL_NODE_ST 1
79 #define CQL_NODE_BOOL 2
80 struct cql_node {
81     /** node type */
82     int which;
83     union {
84         /** which == CQL_NODE_ST */
85         struct {
86             /** CQL index */
87             char *index;
88             /** CQL index URI or NULL if no URI */
89             char *index_uri;
90             /** Search term */
91             char *term;
92             /** relation */
93             char *relation;
94             /** relation URL or NULL if no relation URI) */
95             char *relation_uri;
96             /** relation modifiers */
97             struct cql_node *modifiers;
98         } st;
99         /** which == CQL_NODE_BOOL */
100         struct {
101             /** operator name "and", "or", ... */
102             char *value;
103             /** left operand */
104             struct cql_node *left;
105             /** right operand */ 
106             struct cql_node *right;
107             /** modifiers (NULL for no list) */
108             struct cql_node *modifiers;
109         } boolean;
110     } u;
111 };
112
113 /**
114  * Private structure that describes the CQL properties (profile)
115  */
116 struct cql_properties;
117
118 /**
119  * Structure used by cql_buf_write_handlre
120  */
121 struct cql_buf_write_info {
122     int max;
123     int off;
124     char *buf;
125 };
126
127 /**
128  * Handler for cql_buf_write_info *
129  */
130 YAZ_EXPORT
131 void cql_buf_write_handler (const char *b, void *client_data);
132
133 /**
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.
136  */
137 YAZ_EXPORT
138 void cql_node_print(struct cql_node *cn);
139
140 /**
141  * This function creates a search clause node (st).
142  */
143 YAZ_EXPORT
144 struct cql_node *cql_node_mk_sc(NMEM nmem, const char *index,
145                                 const char *relation, const char *term);
146
147 /**
148  * This function applies a prefix+uri to "unresolved" index and relation
149  * URIs.
150  *
151  * "unresolved" URIs are those nodes where member index_uri / relation_uri
152  * is NULL.
153  */
154 YAZ_EXPORT
155 struct cql_node *cql_apply_prefix(NMEM nmem, struct cql_node *cn,
156                                   const char *prefix, const char *uri);
157
158 /**
159  * This function creates a boolean node.
160  */
161 YAZ_EXPORT
162 struct cql_node *cql_node_mk_boolean(NMEM nmem, const char *op);
163
164 /**
165  * Destroys a node and its children.
166  */
167 YAZ_EXPORT
168 void cql_node_destroy(struct cql_node *cn);
169
170 /**
171  * Duplicate a node (returns a copy of supplied node) .
172  */
173 YAZ_EXPORT
174 struct cql_node *cql_node_dup (NMEM nmem, struct cql_node *cp);
175
176 /**
177  * This function returns the parse tree of the most recently parsed
178  * CQL query.
179  *
180  * The function returns NULL if most recently parse failed.
181  */
182 YAZ_EXPORT
183 struct cql_node *cql_parser_result(CQL_parser cp);
184
185 /**
186  * This function converts a CQL node tree to XCQL and writes the
187  * resulting XCQL to a user-defined output stream.
188  */
189 YAZ_EXPORT
190 void cql_to_xml(struct cql_node *cn, 
191                 void (*pr)(const char *buf, void *client_data),
192                 void *client_data);
193 /**
194  * This function converts a CQL node tree to XCQL and writes the
195  * resulting XCQL to a FILE handle (stdio) 
196  */
197 YAZ_EXPORT
198 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
199
200 /**
201  * This function converts a CQL node tree to XCQL and writes
202  * the resulting XCQL to a buffer 
203  */
204 YAZ_EXPORT
205 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
206
207 /**
208  * Utility function that prints to a FILE.
209  */
210 YAZ_EXPORT
211 void cql_fputs(const char *buf, void *client_data);
212
213 /**
214  * The CQL transform handle. The transform describes how to
215  * convert from CQL to PQF (Type-1 AKA RPN).
216  */
217 typedef struct cql_transform_t_ *cql_transform_t;
218
219 /**
220  * Creates a CQL transform handle. The transformation spec is read from
221  * a FILE handle (which is assumed opened in read mode).
222  */
223 YAZ_EXPORT
224 cql_transform_t cql_transform_open_FILE (FILE *f);
225
226 /**
227  * Creates a CQL transform handle. The transformation spec is read from
228  * a file with the filename given.
229  */
230 YAZ_EXPORT
231 cql_transform_t cql_transform_open_fname(const char *fname);
232
233 /**
234  * Destroys a CQL transform handle.
235  */
236 YAZ_EXPORT
237 void cql_transform_close(cql_transform_t ct);
238
239 /**
240  * Performs a CQL transform to PQF given a CQL node tree and a CQL
241  * transformation handle. The result is written to a user-defined stream.
242  */
243 YAZ_EXPORT
244 void cql_transform_pr(cql_transform_t ct,
245                       struct cql_node *cn,
246                       void (*pr)(const char *buf, void *client_data),
247                       void *client_data);
248
249 /**
250  * Performs a CQL transform to PQF given a CQL node tree and a CQL
251  * transformation handle. The result is written to a file specified by
252  * FILE handle (which must be opened for writing).
253  */
254 YAZ_EXPORT
255 int cql_transform_FILE(cql_transform_t ct,
256                        struct cql_node *cn, FILE *f);
257
258 /**
259  * Performs a CQL transform to PQF given a CQL node tree and a CQL
260  * transformation handle. The result is written to a buffer. 
261  */
262 YAZ_EXPORT
263 int cql_transform_buf(cql_transform_t ct,
264                       struct cql_node *cn, char *out, int max);
265 /**
266  * Returns error code and additional information from last transformation.
267  * Performs a CQL transform given a CQL node tree and a CQL transformation.
268  */
269 YAZ_EXPORT
270 int cql_transform_error(cql_transform_t ct, const char **addinfo);
271
272 /**
273  * Returns the CQL message corresponding to a given error code.
274  */
275 YAZ_EXPORT
276 const char *cql_strerror(int code);
277
278 /**
279  * Returns the standard CQL context set URI.
280  */
281 YAZ_EXPORT
282 const char *cql_uri();
283
284 YAZ_END_CDECL
285
286 #endif
287 /* CQL_H_INCLUDED */
288 /*
289  * Local variables:
290  * c-basic-offset: 4
291  * indent-tabs-mode: nil
292  * End:
293  * vim: shiftwidth=4 tabstop=8 expandtab
294  */
295