* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-/* $Id: cql.h,v 1.18 2007-03-21 10:12:09 adam Exp $ */
+/* $Id: cql.h,v 1.19 2007-11-14 21:03:59 adam Exp $ */
/** \file cql.h
\brief Header with public definitions about CQL.
YAZ_BEGIN_CDECL
-/** CQL parser handle */
+/** \brief CQL parser handle (opaque pointer) */
typedef struct cql_parser *CQL_parser;
-/**
- * Creates a CQL parser.
- * Returns CQL parser handle or NULL if parser could not be created.
+/** \brief creates a CQL parser.
+ \returns CCL parser
+
+ Returns CQL parser or NULL if parser could not be created.
*/
YAZ_EXPORT
CQL_parser cql_parser_create(void);
-/**
- * Destroys a CQL parser.
- *
- * This function does nothing if NULL if received.
+/** \brief destroys a CQL parser.
+ \param cp CQL parser
+
+ This function does nothing if NULL if received.
*/
YAZ_EXPORT
void cql_parser_destroy(CQL_parser cp);
-/**
- * Parses a CQL string query.
- *
- * Returns 0 if on success; non-zero (error code) on failure.
+/** \brief parses a CQL query (string)
+ \param cp CQL parser
+ \param str CQL string
+ \retval 0 success
+ \retval !=0 failure
*/
YAZ_EXPORT
int cql_parser_string(CQL_parser cp, const char *str);
-/**
- * Parses a CQL query - streamed query.
- *
- * This function is similar to cql_parser_string but takes a
- * functions to read each query character from a stream.
- *
- * The functions pointers getbytes, ungetbyte are similar to
- * that known from stdios getc, ungetc.
- *
- * Returns 0 if on success; non-zero (error code) on failure.
- */
+/** \brief parses CQL query (query stream)
+ \param cp CQL parser
+ \param getbyte function which reads one character from stream
+ \param ungetbyte function which unreads one character from stream
+ \param client_data data to be passed to stream functions
+ \retval 0 success
+ \retval !=0 failure
+
+ This function is similar to cql_parser_string but takes a
+ functions to read each query character from a stream.
+
+ The functions pointers getbytes, ungetbyte are similar to
+ that known from stdios getc, ungetc.
+*/
YAZ_EXPORT
int cql_parser_stream(CQL_parser cp,
int (*getbyte)(void *client_data),
void (*ungetbyte)(int b, void *client_data),
void *client_data);
-/**
- * Parses a CQL query from a FILE handle.
- *
- * This function is similar to cql_parser_string but reads from
- * stdio FILE handle instead.
- *
- * Returns 0 if on success; non-zero (error code) on failure.
- */
+/** \brief parses CQL query (from FILE)
+ \param cp CQL parser
+ \param f file where query is read from
+ \retval 0 success
+ \retval !=0 failure
+
+ This function is similar to cql_parser_string but reads from
+ stdio FILE handle instead.
+*/
YAZ_EXPORT
int cql_parser_stdio(CQL_parser cp, FILE *f);
-/**
- * The node in a CQL parse tree.
- */
+/** \brief Node type: search term */
#define CQL_NODE_ST 1
+/** \brief Node type: boolean */
#define CQL_NODE_BOOL 2
+/** \brief CQL parse tree (node)
+ */
struct cql_node {
/** node type */
int which;
} u;
};
-/**
- * Private structure that describes the CQL properties (profile)
+/** \brief Private structure that describes the CQL properties (profile)
*/
struct cql_properties;
-/**
- * Structure used by cql_buf_write_handlre
+/** \brief Structure used by cql_buf_write_handler
*/
struct cql_buf_write_info {
int max;
char *buf;
};
-/**
- * Handler for cql_buf_write_info *
+/** \brief Handler for cql_buf_write_info
*/
YAZ_EXPORT
-void cql_buf_write_handler (const char *b, void *client_data);
+void cql_buf_write_handler(const char *b, void *client_data);
-/**
- * Prints a CQL node and all sub nodes. Hence this function
- * prints the parse tree which is as returned by cql_parser_result.
- */
+/** \brief Prints a CQL node and all sub nodes.
+ Hence this function prints the parse tree which is as returned by
+ cql_parser_result.
+*/
YAZ_EXPORT
void cql_node_print(struct cql_node *cn);
-/**
- * This function creates a search clause node (st).
- */
+/** \brief creates a search clause node (st). */
YAZ_EXPORT
struct cql_node *cql_node_mk_sc(NMEM nmem, const char *index,
const char *relation, const char *term);
-/**
- * This function applies a prefix+uri to "unresolved" index and relation
- * URIs.
- *
- * "unresolved" URIs are those nodes where member index_uri / relation_uri
- * is NULL.
- */
+/** \brief applies a prefix+uri to "unresolved" index and relation URIs.
+ "unresolved" URIs are those nodes where member index_uri / relation_uri
+ is NULL.
+*/
YAZ_EXPORT
struct cql_node *cql_apply_prefix(NMEM nmem, struct cql_node *cn,
const char *prefix, const char *uri);
-/**
- * This function creates a boolean node.
- */
+/** \brief creates a boolean node. */
YAZ_EXPORT
struct cql_node *cql_node_mk_boolean(NMEM nmem, const char *op);
-/**
- * Destroys a node and its children.
- */
+/** \brief destroys a node and its children. */
YAZ_EXPORT
void cql_node_destroy(struct cql_node *cn);
-/**
- * Duplicate a node (returns a copy of supplied node) .
- */
+/** duplicates a node (returns a copy of supplied node) . */
YAZ_EXPORT
struct cql_node *cql_node_dup (NMEM nmem, struct cql_node *cp);
-/**
- * This function returns the parse tree of the most recently parsed
- * CQL query.
- *
- * The function returns NULL if most recently parse failed.
- */
+/** \brief returns the parse tree of the most recently parsed CQL query.
+ \param cp CQL parser
+ \returns CQL node or NULL for failure
+*/
YAZ_EXPORT
struct cql_node *cql_parser_result(CQL_parser cp);
-/**
- * This function converts a CQL node tree to XCQL and writes the
- * resulting XCQL to a user-defined output stream.
+/** \brief converts CQL tree to XCQL and writes to user-defined stream
+ \param cn CQL node (tree)
+ \param pr print function
+ \param client_data data to be passed to pr function
*/
YAZ_EXPORT
void cql_to_xml(struct cql_node *cn,
void (*pr)(const char *buf, void *client_data),
void *client_data);
-/**
- * This function converts a CQL node tree to XCQL and writes the
- * resulting XCQL to a FILE handle (stdio)
+/** \brief converts CQL tree to XCQL and writes to file
+ \param cn CQL node (tree)
+ \param f file handle
*/
YAZ_EXPORT
void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
-/**
- * This function converts a CQL node tree to XCQL and writes
- * the resulting XCQL to a buffer
+/** \brief converts CQL tree to XCQL and writes result to buffer
+ \param cn CQL node (tree)
+ \param out buffer
+ \param max size of buffer (max chars to write)
+ \returns length of resulting buffer
*/
YAZ_EXPORT
int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
-/**
- * Utility function that prints to a FILE.
- */
+/** \brief stream handle for file (used by cql_to_xml_stdio) */
YAZ_EXPORT
void cql_fputs(const char *buf, void *client_data);
-/**
- * The CQL transform handle. The transform describes how to
- * convert from CQL to PQF (Type-1 AKA RPN).
- */
+/** \brief CQL transform handle.
+ The transform describes how to convert from CQL to PQF (Type-1 AKA RPN).
+*/
typedef struct cql_transform_t_ *cql_transform_t;
-/**
- * Creates a CQL transform handle. The transformation spec is read from
- * a FILE handle (which is assumed opened in read mode).
- */
+/** \brief creates a CQL transform handle from am opened file handle
+ \param f file where transformation spec is read
+ \returns transform handle or NULL for failure
+
+ The transformation spec is read from a FILE handle which is assumed
+ opened for reading.
+*/
YAZ_EXPORT
cql_transform_t cql_transform_open_FILE (FILE *f);
-/**
- * Creates a CQL transform handle. The transformation spec is read from
- * a file with the filename given.
- */
+/** \brief creates a CQL transform handle from a file
+ \param fname name of where transformation spec is read
+ \returns transform handle or NULL for failure
+*/
YAZ_EXPORT
cql_transform_t cql_transform_open_fname(const char *fname);
-/**
- * Destroys a CQL transform handle.
+/** \brief destroys a CQL transform handle
+ \param ct CQL transform handle
*/
YAZ_EXPORT
void cql_transform_close(cql_transform_t ct);
-/**
- * Performs a CQL transform to PQF given a CQL node tree and a CQL
- * transformation handle. The result is written to a user-defined stream.
- */
+/** \brief tranforms PQF given a CQL tree
+ \param ct CQL transform handle
+ \param cn CQL node tree
+ \param pr print function
+ \param client_data data to be passed to pr
+ \retval 0 success
+ \retval != 0 error
+
+ The result is written to a user-defined stream.
+*/
YAZ_EXPORT
int cql_transform(cql_transform_t ct,
struct cql_node *cn,
void (*pr)(const char *buf, void *client_data),
void *client_data);
-/**
- * Performs a CQL transform to PQF given a CQL node tree and a CQL
- * transformation handle. The result is written to a file specified by
- * FILE handle (which must be opened for writing).
- */
+/** \brief transforms PQF given a CQL tree (from FILE)
+ \param ct CQL transform handle
+ \param cn CQL tree
+ \param f FILE where output is written
+ \retval 0 success
+ \retval !=0 failure (error code)
+
+ The result is written to a file specified by FILE handle (which must
+ be opened for writing.
+*/
YAZ_EXPORT
int cql_transform_FILE(cql_transform_t ct,
struct cql_node *cn, FILE *f);
-/**
- * Performs a CQL transform to PQF given a CQL node tree and a CQL
- * transformation handle. The result is written to a buffer.
+/** \brief transforms PQF given a CQL tree (from FILE)
+ \param ct CQL transform handle
+ \param cn CQL tree
+ \param out buffer for output
+ \param max maximum bytes for output (size of buffer)
+ \retval 0 success
+ \retval !=0 failure (error code)
*/
YAZ_EXPORT
int cql_transform_buf(cql_transform_t ct,
struct cql_node *cn, char *out, int max);
-/**
- * Returns error code and additional information from last transformation.
- * Performs a CQL transform given a CQL node tree and a CQL transformation.
+
+/** \brief returns additional information for last transform
+ \param ct CQL transform handle
+ \param addinfo additional info (result)
+ \returns error code
*/
YAZ_EXPORT
int cql_transform_error(cql_transform_t ct, const char **addinfo);
-/**
- * Returns the CQL message corresponding to a given error code.
- */
+/** \brief returns the CQL message corresponding to a given error code.
+ \param code error code
+ \returns text message
+*/
YAZ_EXPORT
const char *cql_strerror(int code);
-/**
- * Returns the standard CQL context set URI.
- */
+/** \brief returns the standard CQL context set URI.
+ \returns CQL URI string
+*/
YAZ_EXPORT
const char *cql_uri(void);
-/**
- * Compares two CQL strings (for relations, operators, etc)
- * (unfortunately defined as case-insensitive unlike XML etc)
- */
+/** \brief compares two CQL strings (ala strcmp)
+ \param s1 string 1
+ \param s2 string 2
+ \returns comparison value
+ Compares two CQL strings (for relations, operators, etc)
+ (unfortunately defined as case-insensitive unlike XML etc)
+*/
YAZ_EXPORT
int cql_strcmp(const char *s1, const char *s2);
-/**
- * Compares two CQL strings at most n bytes
- * (unfortunately defined as case-insensitive unlike XML etc)
+/** \brief compares two CQL strings (ala strncmp)
+ \param s1 string 1
+ \param s2 string 2
+ \param n size
+ \returns comparison value
+ Compares two CQL strings at most n bytes
+ (unfortunately defined as case-insensitive unlike XML etc)
*/
YAZ_EXPORT
int cql_strncmp(const char *s1, const char *s2, size_t n);
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-/* $Id: nmem.h,v 1.25 2007-04-17 20:26:18 adam Exp $ */
+/* $Id: nmem.h,v 1.26 2007-11-14 21:03:59 adam Exp $ */
/**
- * \file nmem.h
+ * \file
* \brief Header for Nibble Memory functions
*
* This is a simple and fairly wasteful little module for nibble memory
- * allocation. Evemtually we'll put in something better.
+ * allocation. Eventually we'll put in something better.
*/
#ifndef NMEM_H
#define NMEM_H
/** \brief NMEM handle (an opaque pointer to memory) */
typedef struct nmem_control *NMEM;
-/** \brief release all memory associaged with an NMEM handle */
+/** \brief releases memory associaged with an NMEM handle
+ \param n NMEM handle
+*/
YAZ_EXPORT void nmem_reset(NMEM n);
-/** \brief returns size in bytes of memory for NMEM handle */
+
+/** \brief returns size in bytes of memory for NMEM handle
+ \returns number of bytes
+ */
YAZ_EXPORT int nmem_total(NMEM n);
-/** \brief allocates string on NMEM handle (similar strdup) */
-YAZ_EXPORT char *nmem_strdup (NMEM mem, const char *src);
-/** \brief allocates string on NMEM handle - allows NULL ptr buffer */
-YAZ_EXPORT char *nmem_strdup_null (NMEM mem, const char *src);
-/** \brief allocates string of certain size on NMEM handle */
-YAZ_EXPORT char *nmem_strdupn (NMEM mem, const char *src, size_t n);
+/** \brief allocates string on NMEM handle (similar strdup)
+ \param mem HNEM handle
+ \param src string
+ \returns duplicated string
+ */
+YAZ_EXPORT char *nmem_strdup(NMEM mem, const char *src);
+/** \brief allocates string on NMEM handle - allows NULL ptr buffer
+ \param mem HNEM handle
+ \param src string
+ \returns duplicated string or NULL if src was NULL
+ */
+YAZ_EXPORT char *nmem_strdup_null(NMEM mem, const char *src);
+
+/** \brief allocates string of certain size on NMEM handle
+ \param mem NMEM handle
+ \param src string
+ \param n size of string
+ \returns duplicated string (0 terminated)
+ */
+YAZ_EXPORT char *nmem_strdupn(NMEM mem, const char *src, size_t n);
/** \brief allocates sub strings out of string using certain delimitors
\param nmem NMEM handle
YAZ_EXPORT void nmem_strsplit_blank(NMEM nmem, const char *dstr,
char ***darray, int *num);
-/** \brief creates and allocates integer for NMEM */
-YAZ_EXPORT int *nmem_intdup (NMEM mem, int v);
+/** \brief allocates integer for NMEM
+ \param nmem NMEM handle
+ \param v integer value
+ \returns pointer to created integer
+*/
+YAZ_EXPORT int *nmem_intdup(NMEM nmem, int v);
-/** \brief transfers memory from one NMEM handle to another */
-YAZ_EXPORT void nmem_transfer (NMEM dst, NMEM src);
+/** \brief transfers memory from one NMEM handle to another
+ \param src source NMEM handle
+ \param dst destination NMEM handle
+ */
+YAZ_EXPORT void nmem_transfer(NMEM dst, NMEM src);
-/** \brief returns new NMEM handle */
+/** \brief returns new NMEM handle
+ \returns NMEM handle
+ */
YAZ_EXPORT NMEM nmem_create(void);
-/** \brief destroys NMEM handle and memory associated with it */
+/** \brief destroys NMEM handle and memory associated with it
+ \param n NMEM handle
+ */
YAZ_EXPORT void nmem_destroy(NMEM n);
-/** \brief allocate memory block on NMEM handle */
+/** \brief allocates memory block on NMEM handle
+ \param n NMEM handle
+ \param size number of bytes to be allocated
+ \returns pointer to allocated memory
+ */
YAZ_EXPORT void *nmem_malloc(NMEM n, int size);
-YAZ_EXPORT int yaz_errno (void);
+YAZ_EXPORT int yaz_errno(void);
YAZ_EXPORT void yaz_set_errno (int v);
YAZ_EXPORT void yaz_strerror(char *buf, int max);
projects / yaz-moved-to-github.git / commitdiff