include/yaz/cql.h

   1 /*
   2  * Copyright (c) 1995-2007, Index Data
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   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.
  15  *
  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.
  26  */
  27 /* $Id: cql.h,v 1.20 2008-01-06 16:22:02 adam Exp $ */
  28
  29 /** \file cql.h
  30     \brief Header with public definitions about CQL.
  31 */
  32
  33 #ifndef CQL_H_INCLUDED
  34 #define CQL_H_INCLUDED
  35 #include <stdio.h>
  36 #include <yaz/nmem.h>
  37
  38 YAZ_BEGIN_CDECL
  39
  40 /** \brief CQL parser handle (opaque pointer) */
  41 typedef struct cql_parser *CQL_parser;
  42
  43 /** \brief creates a CQL parser.
  44     \returns CCL parser
  45
  46     Returns CQL parser or NULL if parser could not be created.
  47  */
  48 YAZ_EXPORT
  49 CQL_parser cql_parser_create(void);
  50
  51 /** \brief destroys a CQL parser.
  52     \param cp CQL parser
  53
  54     This function does nothing if NULL if received.
  55  */
  56 YAZ_EXPORT
  57 void cql_parser_destroy(CQL_parser cp);
  58
  59 /** \brief parses a CQL query (string)
  60     \param cp CQL parser
  61     \param str CQL string
  62     \retval 0 success
  63     \retval !=0 failure
  64  */
  65 YAZ_EXPORT
  66 int cql_parser_string(CQL_parser cp, const char *str);
  67
  68 /** \brief parses CQL query (query stream)
  69     \param cp CQL parser
  70     \param getbyte function which reads one character from stream
  71     \param ungetbyte function which unreads one character from stream
  72     \param client_data data to be passed to stream functions
  73     \retval 0 success
  74     \retval !=0 failure
  75
  76     This function is similar to cql_parser_string but takes a
  77     functions to read each query character from a stream.
  78
  79     The functions pointers getbytes, ungetbyte are similar to
  80     that known from stdios getc, ungetc.
  81 */
  82 YAZ_EXPORT
  83 int cql_parser_stream(CQL_parser cp,
  84                       int (*getbyte)(void *client_data),
  85                       void (*ungetbyte)(int b, void *client_data),
  86                       void *client_data);
  87
  88 /** \brief parses CQL query (from FILE)
  89     \param cp CQL parser
  90     \param f file where query is read from
  91     \retval 0 success
  92     \retval !=0 failure
  93
  94     This function is similar to cql_parser_string but reads from
  95     stdio FILE handle instead.
  96 */
  97 YAZ_EXPORT
  98 int cql_parser_stdio(CQL_parser cp, FILE *f);
  99
 100 /** \brief Node type: search term */
 101 #define CQL_NODE_ST 1
 102 /** \brief Node type: boolean */
 103 #define CQL_NODE_BOOL 2
 104 /** \brief CQL parse tree (node)
 105  */
 106 struct cql_node {
 107     /** node type */
 108     int which;
 109     union {
 110         /** which == CQL_NODE_ST */
 111         struct {
 112             /** CQL index */
 113             char *index;
 114             /** CQL index URI or NULL if no URI */
 115             char *index_uri;
 116             /** Search term */
 117             char *term;
 118             /** relation */
 119             char *relation;
 120             /** relation URL or NULL if no relation URI) */
 121             char *relation_uri;
 122             /** relation modifiers */
 123             struct cql_node *modifiers;
 124             /** term list */
 125             struct cql_node *extra_terms;
 126         } st;
 127         /** which == CQL_NODE_BOOL */
 128         struct {
 129             /** operator name "and", "or", ... */
 130             char *value;
 131             /** left operand */
 132             struct cql_node *left;
 133             /** right operand */
 134             struct cql_node *right;
 135             /** modifiers (NULL for no list) */
 136             struct cql_node *modifiers;
 137         } boolean;
 138     } u;
 139 };
 140
 141 /** \brief Private structure that describes the CQL properties (profile)
 142  */
 143 struct cql_properties;
 144
 145 /** \brief Structure used by cql_buf_write_handler
 146  */
 147 struct cql_buf_write_info {
 148     int max;
 149     int off;
 150     char *buf;
 151 };
 152
 153 /** \brief Handler for cql_buf_write_info
 154  */
 155 YAZ_EXPORT
 156 void cql_buf_write_handler(const char *b, void *client_data);
 157
 158 /** \brief Prints a CQL node and all sub nodes.
 159     Hence this function prints the parse tree which is as returned by
 160     cql_parser_result.
 161 */
 162 YAZ_EXPORT
 163 void cql_node_print(struct cql_node *cn);
 164
 165 /** \brief creates a search clause node (st). */
 166 YAZ_EXPORT
 167 struct cql_node *cql_node_mk_sc(NMEM nmem, const char *index,
 168                                 const char *relation, const char *term);
 169
 170 /** \brief applies a prefix+uri to "unresolved" index and relation URIs.
 171     "unresolved" URIs are those nodes where member index_uri / relation_uri
 172     is NULL.
 173 */
 174 YAZ_EXPORT
 175 struct cql_node *cql_apply_prefix(NMEM nmem, struct cql_node *cn,
 176                                   const char *prefix, const char *uri);
 177
 178 /** \brief creates a boolean node. */
 179 YAZ_EXPORT
 180 struct cql_node *cql_node_mk_boolean(NMEM nmem, const char *op);
 181
 182 /** \brief destroys a node and its children. */
 183 YAZ_EXPORT
 184 void cql_node_destroy(struct cql_node *cn);
 185
 186 /** duplicates a node (returns a copy of supplied node) . */
 187 YAZ_EXPORT
 188 struct cql_node *cql_node_dup (NMEM nmem, struct cql_node *cp);
 189
 190 /** \brief returns the parse tree of the most recently parsed CQL query.
 191     \param cp CQL parser
 192     \returns CQL node or NULL for failure
 193 */
 194 YAZ_EXPORT
 195 struct cql_node *cql_parser_result(CQL_parser cp);
 196
 197 /** \brief converts CQL tree to XCQL and writes to user-defined stream
 198     \param cn CQL node (tree)
 199     \param pr print function
 200     \param client_data data to be passed to pr function
 201  */
 202 YAZ_EXPORT
 203 void cql_to_xml(struct cql_node *cn,
 204                 void (*pr)(const char *buf, void *client_data),
 205                 void *client_data);
 206 /** \brief converts CQL tree to XCQL and writes to file
 207     \param cn CQL node (tree)
 208     \param f file handle
 209  */
 210 YAZ_EXPORT
 211 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
 212
 213 /** \brief converts CQL tree to XCQL and writes result to buffer
 214     \param cn CQL node (tree)
 215     \param out buffer
 216     \param max size of buffer (max chars to write)
 217     \returns length of resulting buffer
 218  */
 219 YAZ_EXPORT
 220 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
 221
 222 /** \brief stream handle for file (used by cql_to_xml_stdio) */
 223 YAZ_EXPORT
 224 void cql_fputs(const char *buf, void *client_data);
 225
 226 /** \brief CQL transform handle.
 227     The transform describes how to convert from CQL to PQF (Type-1 AKA RPN).
 228 */
 229 typedef struct cql_transform_t_ *cql_transform_t;
 230
 231 /** \brief creates a CQL transform handle from am opened file handle
 232     \param f file where transformation spec is read
 233     \returns transform handle or NULL for failure
 234
 235     The transformation spec is read from a FILE handle which is assumed
 236     opened for reading.
 237 */
 238 YAZ_EXPORT
 239 cql_transform_t cql_transform_open_FILE (FILE *f);
 240
 241 /** \brief creates a CQL transform handle from a file
 242     \param fname name of where transformation spec is read
 243     \returns transform handle or NULL for failure
 244 */
 245 YAZ_EXPORT
 246 cql_transform_t cql_transform_open_fname(const char *fname);
 247
 248 /** \brief destroys a CQL transform handle
 249     \param ct CQL transform handle
 250  */
 251 YAZ_EXPORT
 252 void cql_transform_close(cql_transform_t ct);
 253
 254 /** \brief tranforms PQF given a CQL tree
 255     \param ct CQL transform handle
 256     \param cn CQL node tree
 257     \param pr print function
 258     \param client_data data to be passed to pr
 259     \retval 0 success
 260     \retval != 0 error
 261
 262     The result is written to a user-defined stream.
 263 */
 264 YAZ_EXPORT
 265 int cql_transform(cql_transform_t ct,
 266                   struct cql_node *cn,
 267                   void (*pr)(const char *buf, void *client_data),
 268                   void *client_data);
 269
 270 /** \brief transforms PQF given a CQL tree (from FILE)
 271     \param ct CQL transform handle
 272     \param cn CQL tree
 273     \param f FILE where output is written
 274     \retval 0 success
 275     \retval !=0 failure (error code)
 276
 277     The result is written to a file specified by FILE handle (which must
 278     be opened for writing.
 279 */
 280 YAZ_EXPORT
 281 int cql_transform_FILE(cql_transform_t ct,
 282                        struct cql_node *cn, FILE *f);
 283
 284 /** \brief transforms PQF given a CQL tree (from FILE)
 285     \param ct CQL transform handle
 286     \param cn CQL tree
 287     \param out buffer for output
 288     \param max maximum bytes for output (size of buffer)
 289     \retval 0 success
 290     \retval !=0 failure (error code)
 291  */
 292 YAZ_EXPORT
 293 int cql_transform_buf(cql_transform_t ct,
 294                       struct cql_node *cn, char *out, int max);
 295
 296 /** \brief returns additional information for last transform
 297     \param ct CQL transform handle
 298     \param addinfo additional info (result)
 299     \returns error code
 300  */
 301 YAZ_EXPORT
 302 int cql_transform_error(cql_transform_t ct, const char **addinfo);
 303
 304 /** \brief returns the CQL message corresponding to a given error code.
 305     \param code error code
 306     \returns text message
 307 */
 308 YAZ_EXPORT
 309 const char *cql_strerror(int code);
 310
 311 /** \brief returns the standard CQL context set URI.
 312     \returns CQL URI string
 313 */
 314 YAZ_EXPORT
 315 const char *cql_uri(void);
 316
 317 /** \brief compares two CQL strings (ala strcmp)
 318     \param s1 string 1
 319     \param s2 string 2
 320     \returns comparison value
 321     Compares two CQL strings (for relations, operators, etc)
 322     (unfortunately defined as case-insensitive unlike XML etc)
 323 */
 324 YAZ_EXPORT
 325 int cql_strcmp(const char *s1, const char *s2);
 326
 327 /** \brief compares two CQL strings (ala strncmp)
 328     \param s1 string 1
 329     \param s2 string 2
 330     \param n size
 331     \returns comparison value
 332     Compares two CQL strings at most n bytes
 333     (unfortunately defined as case-insensitive unlike XML etc)
 334  */
 335 YAZ_EXPORT
 336 int cql_strncmp(const char *s1, const char *s2, size_t n);
 337
 338 YAZ_END_CDECL
 339
 340 #endif
 341 /* CQL_H_INCLUDED */
 342 /*
 343  * Local variables:
 344  * c-basic-offset: 4
 345  * indent-tabs-mode: nil
 346  * End:
 347  * vim: shiftwidth=4 tabstop=8 expandtab
 348  */
 349