include/yaz/cql.h

   1 /* $Id: cql.h,v 1.11 2005-01-15 19:47:09 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 */