REGXML_XML(3)

NAME
regxml_xml, regxml_xml_create, regxml_xml_destroy, regxml_xml_strerror, regxml_xml_getbuf, regxml_xml_pushraw, regxml_xml_push, regxml_xml_end, regxml_xml_setfilename, regxml_xml_setindent, regxml_xml_setprint, regxml_xml_printopening, regxml_xml_printclosing, regxml_xml_printempty, regxml_xml_printtext, regxml_xml_printcomment, regxml_xml_printpi, regxml_xml_printf, regxml_xml_fprintf - XML interval matching string representation wrapper

LIBRARY
libregxml

SYNOPSIS
#include <regxml/xml.h>
int
regxml_xml_create(struct regxml_xml **xmlptr, struct regxml *reg, int flags);
void
regxml_xml_destroy(struct regxml_xml *xml);
size_t
regxml_xml_strerror(struct regxml_xml *xml, int code, char *buf, size_t bufsize);
int
regxml_xml_getbuf(struct regxml_xml *xml, char **bufptr, size_t bufsize);
regxml_xml_pushraw(struct regxml_xml *xml, const char *buf, size_t bufsize);
int
regxml_xml_push(struct regxml_xml *xml, const char *str);
int
regxml_xml_end(struct regxml_xml *xml);
void
regxml_xml_setfilename(struct regxml_xml *xml, const char *);
void
regxml_xml_setindent(struct regxml_xml *xml, unsigned int);
void
regxml_xml_setprint(struct regxml_xml *xml, int (*print)(void *, const char *, ...), void *arg);
int
regxml_xml_printopening(struct regxml_xml *xml, const char *tag, char * const *attrv);
int
regxml_xml_printclosing(struct regxml_xml *xml, const char *tag);
int
regxml_xml_printempty(struct regxml_xml *xml, const char *tag, char * const *attrv);
int
regxml_xml_printtext(struct regxml_xml *xml, const char *content);
int
regxml_xml_printcomment(struct regxml_xml *xml, const char *content);
int
regxml_xml_printpi(struct regxml_xml *xml, const char *target, const char *content);
int
regxml_xml_printf(void *arg, const char *fmt, ...);
int
regxml_xml_fprintf(void *arg, const char *fmt, ...);

DESCRIPTION
The regxml_xml family of functions provides an auxiliary API to regxml(3) for reading and writing XML data as text. It depends on expat(3).

The regxml_xml_create() function creates a new XML parser/printer object which feeds data to the matcher reg. The object should be freed by regxml_xml_destroy().

The regxml_xml_pushraw() and regxml_xml_push() feed chunks of XML text to the parser. A call to regxml_xml_end() marks the end of the input stream. When using the regxml_xml auxiliary library, these functions effectively supersede the regxml_pushopening(), regxml_pushclosing(), regxml_pushtext(), regxml_pushcomment() and regxml_end() functions.

Instead of providing a user-allocated buffer, the regxml_xml_getbuf() function can be used to get a parser-allocated buffer for the next push call. In that case, NULL shall be passed as the second argument to the next call to regxml_xml_pushraw(), which invalidates the buffer.

The regxml_xml_setfilename() function sets the file name to be used in error messages returned by regxml_xml_strerror().

The regxml_xml_setindent() function sets the base indentation step, which defaults to 0 (no indentation). The regxml_xml_setprint() function changes the user callback function associated with the printer object to print and the user callback argument to arg. The callback function must return 0 on success or non-zero on error. By default, the callback function is set to regxml_xml_printf() and the callback argument is NULL.

The regxml_xml_printopening(), regxml_xml_printclosing(), regxml_xml_printempty(), regxml_xml_printtext(), regxml_xml_printcomment() and regxml_xml_printpi() functions print XML constructs through the user-supplied callback function associated with the parser. The callback function is called with a printf(3)-like format, though it is only required to support the ‘%s’ and ‘%c’ format specifiers with no flags.

The regxml_xml_printf() and regxml_xml_fprintf() functions expose the behavior of printf(3) and fprintf(3) through an interface suitable for regxml_xml_setprint(). regxml_xml_printf() ignores its user-supplied argument. regxml_xml_fprintf() assumes that it will be passed a FILE * object as argument.

The regxml_xml_strerror() function converts an error code into a human-readable string representation. When using the regxml_xml auxiliary library, this function effectively supersedes the regxml_strerror() function.

The header regxml/xml.h defines the following flags for regxml_xml_create():

REGXML_XML_TRIM
    Trim all-whitespace text elements. These will not be pushed into the matcher object.

REGXML_XML_EXPAND
    Expand internally defined entities. The parser will fail with an error if it encounters an undefined entity.

REGXML_XML_TABINDENT
    Use one horizontal tab as the indentation unit, rather than one space.

REGXML_XML_ATTRLINE
    Print attribute key/value pairs on a lines by themselves.

RETURN VALUES
The functions regxml_xml_create(), regxml_xml_pushraw(), regxml_xml_push(), regxml_xml_end(), regxml_xml_setfilename(), regxml_xml_printopening(), regxml_xml_printclosing(), regxml_xml_printempty(), regxml_xml_printtext(), regxml_xml_printcomment() and regxml_xml_printpi() return 0 on success, or a non-zero error code. The regxml_xml_printf() and regxml_xml_fprintf() functions return 0 on success, or -1 on error.

DIAGNOSTICS
The return codes are described in regxml(3).

SEE ALSO
expat(3), regex(3), regxml(3)

AUTHORS
Nhat Minh Lê <minh@NetBSD.org>