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.19 2007-11-14 21:03:59 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         } st;
 125         /** which == CQL_NODE_BOOL */
 126         struct {
 127             /** operator name "and", "or", ... */
 128             char *value;
 129             /** left operand */
 130             struct cql_node *left;
 131             /** right operand */
 132             struct cql_node *right;
 133             /** modifiers (NULL for no list) */
 134             struct cql_node *modifiers;
 135         } boolean;
 136     } u;
 137 };
 138
 139 /** \brief Private structure that describes the CQL properties (profile)
 140  */
 141 struct cql_properties;
 142
 143 /** \brief Structure used by cql_buf_write_handler
 144  */
 145 struct cql_buf_write_info {
 146     int max;
 147     int off;
 148     char *buf;
 149 };
 150
 151 /** \brief Handler for cql_buf_write_info
 152  */
 153 YAZ_EXPORT
 154 void cql_buf_write_handler(const char *b, void *client_data);
 155
 156 /** \brief Prints a CQL node and all sub nodes.
 157     Hence this function prints the parse tree which is as returned by
 158     cql_parser_result.
 159 */
 160 YAZ_EXPORT
 161 void cql_node_print(struct cql_node *cn);
 162
 163 /** \brief creates a search clause node (st). */
 164 YAZ_EXPORT
 165 struct cql_node *cql_node_mk_sc(NMEM nmem, const char *index,
 166                                 const char *relation, const char *term);
 167
 168 /** \brief applies a prefix+uri to "unresolved" index and relation URIs.
 169     "unresolved" URIs are those nodes where member index_uri / relation_uri
 170     is NULL.
 171 */
 172 YAZ_EXPORT
 173 struct cql_node *cql_apply_prefix(NMEM nmem, struct cql_node *cn,
 174                                   const char *prefix, const char *uri);
 175
 176 /** \brief creates a boolean node. */
 177 YAZ_EXPORT
 178 struct cql_node *cql_node_mk_boolean(NMEM nmem, const char *op);
 179
 180 /** \brief destroys a node and its children. */
 181 YAZ_EXPORT
 182 void cql_node_destroy(struct cql_node *cn);
 183
 184 /** duplicates a node (returns a copy of supplied node) . */
 185 YAZ_EXPORT
 186 struct cql_node *cql_node_dup (NMEM nmem, struct cql_node *cp);
 187
 188 /** \brief returns the parse tree of the most recently parsed CQL query.
 189     \param cp CQL parser
 190     \returns CQL node or NULL for failure
 191 */
 192 YAZ_EXPORT
 193 struct cql_node *cql_parser_result(CQL_parser cp);
 194
 195 /** \brief converts CQL tree to XCQL and writes to user-defined stream
 196     \param cn CQL node (tree)
 197     \param pr print function
 198     \param client_data data to be passed to pr function
 199  */
 200 YAZ_EXPORT
 201 void cql_to_xml(struct cql_node *cn,
 202                 void (*pr)(const char *buf, void *client_data),
 203                 void *client_data);
 204 /** \brief converts CQL tree to XCQL and writes to file
 205     \param cn CQL node (tree)
 206     \param f file handle
 207  */
 208 YAZ_EXPORT
 209 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
 210
 211 /** \brief converts CQL tree to XCQL and writes result to buffer
 212     \param cn CQL node (tree)
 213     \param out buffer
 214     \param max size of buffer (max chars to write)
 215     \returns length of resulting buffer
 216  */
 217 YAZ_EXPORT
 218 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
 219
 220 /** \brief stream handle for file (used by cql_to_xml_stdio) */
 221 YAZ_EXPORT
 222 void cql_fputs(const char *buf, void *client_data);
 223
 224 /** \brief CQL transform handle.
 225     The transform describes how to convert from CQL to PQF (Type-1 AKA RPN).
 226 */
 227 typedef struct cql_transform_t_ *cql_transform_t;
 228
 229 /** \brief creates a CQL transform handle from am opened file handle
 230     \param f file where transformation spec is read
 231     \returns transform handle or NULL for failure
 232
 233     The transformation spec is read from a FILE handle which is assumed
 234     opened for reading.
 235 */
 236 YAZ_EXPORT
 237 cql_transform_t cql_transform_open_FILE (FILE *f);
 238
 239 /** \brief creates a CQL transform handle from a file
 240     \param fname name of where transformation spec is read
 241     \returns transform handle or NULL for failure
 242 */
 243 YAZ_EXPORT
 244 cql_transform_t cql_transform_open_fname(const char *fname);
 245
 246 /** \brief destroys a CQL transform handle
 247     \param ct CQL transform handle
 248  */
 249 YAZ_EXPORT
 250 void cql_transform_close(cql_transform_t ct);
 251
 252 /** \brief tranforms PQF given a CQL tree
 253     \param ct CQL transform handle
 254     \param cn CQL node tree
 255     \param pr print function
 256     \param client_data data to be passed to pr
 257     \retval 0 success
 258     \retval != 0 error
 259
 260     The result is written to a user-defined stream.
 261 */
 262 YAZ_EXPORT
 263 int cql_transform(cql_transform_t ct,
 264                   struct cql_node *cn,
 265                   void (*pr)(const char *buf, void *client_data),
 266                   void *client_data);
 267
 268 /** \brief transforms PQF given a CQL tree (from FILE)
 269     \param ct CQL transform handle
 270     \param cn CQL tree
 271     \param f FILE where output is written
 272     \retval 0 success
 273     \retval !=0 failure (error code)
 274
 275     The result is written to a file specified by FILE handle (which must
 276     be opened for writing.
 277 */
 278 YAZ_EXPORT
 279 int cql_transform_FILE(cql_transform_t ct,
 280                        struct cql_node *cn, FILE *f);
 281
 282 /** \brief transforms PQF given a CQL tree (from FILE)
 283     \param ct CQL transform handle
 284     \param cn CQL tree
 285     \param out buffer for output
 286     \param max maximum bytes for output (size of buffer)
 287     \retval 0 success
 288     \retval !=0 failure (error code)
 289  */
 290 YAZ_EXPORT
 291 int cql_transform_buf(cql_transform_t ct,
 292                       struct cql_node *cn, char *out, int max);
 293
 294 /** \brief returns additional information for last transform
 295     \param ct CQL transform handle
 296     \param addinfo additional info (result)
 297     \returns error code
 298  */
 299 YAZ_EXPORT
 300 int cql_transform_error(cql_transform_t ct, const char **addinfo);
 301
 302 /** \brief returns the CQL message corresponding to a given error code.
 303     \param code error code
 304     \returns text message
 305 */
 306 YAZ_EXPORT
 307 const char *cql_strerror(int code);
 308
 309 /** \brief returns the standard CQL context set URI.
 310     \returns CQL URI string
 311 */
 312 YAZ_EXPORT
 313 const char *cql_uri(void);
 314
 315 /** \brief compares two CQL strings (ala strcmp)
 316     \param s1 string 1
 317     \param s2 string 2
 318     \returns comparison value
 319     Compares two CQL strings (for relations, operators, etc)
 320     (unfortunately defined as case-insensitive unlike XML etc)
 321 */
 322 YAZ_EXPORT
 323 int cql_strcmp(const char *s1, const char *s2);
 324
 325 /** \brief compares two CQL strings (ala strncmp)
 326     \param s1 string 1
 327     \param s2 string 2
 328     \param n size
 329     \returns comparison value
 330     Compares two CQL strings at most n bytes
 331     (unfortunately defined as case-insensitive unlike XML etc)
 332  */
 333 YAZ_EXPORT
 334 int cql_strncmp(const char *s1, const char *s2, size_t n);
 335
 336 YAZ_END_CDECL
 337
 338 #endif
 339 /* CQL_H_INCLUDED */
 340 /*
 341  * Local variables:
 342  * c-basic-offset: 4
 343  * indent-tabs-mode: nil
 344  * End:
 345  * vim: shiftwidth=4 tabstop=8 expandtab
 346  */
 347