include/yaz/cql.h

   1 /* $Id: cql.h,v 1.9 2004-10-03 22:34:07 adam Exp $
   2    Copyright (C) 2002-2004
   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/yconfig.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(const char *index,
 145                                 const char *relation,
 146                                 const char *term);
 147
 148
 149 /**
 150  * This function applies a prefix+uri to "unresolved" index and relation
 151  * URIs.
 152  *
 153  * "unresolved" URIs are those nodes where member index_uri / relation_uri
 154  * is NULL.
 155  */
 156 YAZ_EXPORT
 157 struct cql_node *cql_apply_prefix(struct cql_node *cn,
 158                                   const char *prefix,
 159                                   const char *uri);
 160
 161 /**
 162  * This function creates a boolean node.
 163  */
 164 YAZ_EXPORT
 165 struct cql_node *cql_node_mk_boolean(const char *op);
 166
 167 /**
 168  * Destroys a node and its children.
 169  */
 170 YAZ_EXPORT
 171 void cql_node_destroy(struct cql_node *cn);
 172
 173 /**
 174  * Duplicate a node (returns a copy of supplied node) .
 175  */
 176 YAZ_EXPORT
 177 struct cql_node *cql_node_dup (struct cql_node *cp);
 178
 179 /**
 180  * This function returns the parse tree of the most recently parsed
 181  * CQL query.
 182  *
 183  * The function returns NULL if most recently parse failed.
 184  */
 185 YAZ_EXPORT
 186 struct cql_node *cql_parser_result(CQL_parser cp);
 187
 188 /**
 189  * This function converts a CQL node tree to XCQL and writes the
 190  * resulting XCQL to a user-defined output stream.
 191  */
 192 YAZ_EXPORT
 193 void cql_to_xml(struct cql_node *cn,
 194                 void (*pr)(const char *buf, void *client_data),
 195                 void *client_data);
 196 /**
 197  * This function converts a CQL node tree to XCQL and writes the
 198  * resulting XCQL to a FILE handle (stdio)
 199  */
 200 YAZ_EXPORT
 201 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
 202
 203 /**
 204  * This function converts a CQL node tree to XCQL and writes
 205  * the resulting XCQL to a buffer
 206  */
 207 YAZ_EXPORT
 208 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
 209
 210 /**
 211  * Utility function that prints to a FILE.
 212  */
 213 YAZ_EXPORT
 214 void cql_fputs(const char *buf, void *client_data);
 215
 216 /**
 217  * The CQL transform handle. The transform describes how to
 218  * convert from CQL to PQF (Type-1 AKA RPN).
 219  */
 220 typedef struct cql_transform_t_ *cql_transform_t;
 221
 222 /**
 223  * Creates a CQL transform handle. The transformation spec is read from
 224  * a FILE handle (which is assumed opened in read mode).
 225  */
 226 YAZ_EXPORT
 227 cql_transform_t cql_transform_open_FILE (FILE *f);
 228
 229 /**
 230  * Creates a CQL transform handle. The transformation spec is read from
 231  * a file with the filename given.
 232  */
 233 YAZ_EXPORT
 234 cql_transform_t cql_transform_open_fname(const char *fname);
 235
 236 /**
 237  * Destroys a CQL transform handle.
 238  */
 239 YAZ_EXPORT
 240 void cql_transform_close(cql_transform_t ct);
 241
 242 /**
 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.
 245  */
 246 YAZ_EXPORT
 247 void cql_transform_pr(cql_transform_t ct,
 248                       struct cql_node *cn,
 249                       void (*pr)(const char *buf, void *client_data),
 250                       void *client_data);
 251
 252 /**
 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).
 256  */
 257 YAZ_EXPORT
 258 int cql_transform_FILE(cql_transform_t ct,
 259                        struct cql_node *cn, FILE *f);
 260
 261 /**
 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.
 264  */
 265 YAZ_EXPORT
 266 int cql_transform_buf(cql_transform_t ct,
 267                       struct cql_node *cn, char *out, int max);
 268 /**
 269  * Returns error code and additional information from last transformation.
 270  * Performs a CQL transform given a CQL node tree and a CQL transformation.
 271  */
 272 YAZ_EXPORT
 273 int cql_transform_error(cql_transform_t ct, const char **addinfo);
 274
 275 /**
 276  * Returns the CQL message corresponding to a given error code.
 277  */
 278 YAZ_EXPORT
 279 const char *cql_strerror(int code);
 280
 281 /**
 282  * Returns the standard CQL context set URI.
 283  */
 284 YAZ_EXPORT
 285 const char *cql_uri();
 286
 287 YAZ_END_CDECL
 288
 289 #endif
 290 /* CQL_H_INCLUDED */