REGXML(3)

NAME
regxml, regxml_create, regxml_destroy, regxml_strerror, regxml_pushopening, regxml_pushclosing, regxml_pushtext, regxml_pushcomment, regxml_pushpi, regxml_end, regxml_match, regxml_fetch, regxml_reset - XML interval matching library

LIBRARY
libregxml

SYNOPSIS
#include <regxml/regxml.h>
int
regxml_create(struct regxml **regptr, const char *pattern, int flags);
void
regxml_destroy(struct regxml *reg);
size_t
regxml_strerror(struct regxml *reg, int code, char *buf, size_t bufsize);
int
regxml_pushopening(struct regxml *reg, const char *tag, char * const *attrv);
int
regxml_pushclosing(struct regxml *reg);
int
regxml_pushtext(struct regxml *reg, const char *content);
int
regxml_pushcomment(struct regxml *reg, const char *content);
int
regxml_pushpi(struct regxml *reg, const char *target, const char *content);
int
regxml_end(struct regxml *reg);
int
regxml_match(struct regxml *reg, struct regxml_elem **match);
int
regxml_fetch(struct regxml *reg);
void
regxml_reset(struct regxml *reg);
void
regxml_inititer(struct regxml_iter *, struct regxml_elem *, struct regxml_elem *);
int
regxml_fetchiter(struct regxml_iter *);

DESCRIPTION
The regxml library provides routines to find and report XML intervals matching a pattern, as described in xmltools(7). It is similar in scope to regex(3), albeit working on XML streams and patterns.

The regxml_create() function compiles a pattern written as a string into an internal matcher state object, which should be freed by regxml_destroy().

The regxml_pushopening(), regxml_pushclosing(), regxml_pushtext(), regxml_pushcomment() and regxml_pushpi() are low-level interfaces that feed XML data as individual elements to the matcher. See regxml_xml(3) for a high-level API that directly reads XML as strings. A call to regxml_end() marks the end of the input stream.

The regxml_match() function finds the longest intervals starting at the current element and then advances the current pointer onto the next element in document order. The match argument should point to an array of struct elem *, which will be filled with pairs of pointers to lower/upper bounds of matching capturing subpatterns, or REGXML_FAIL if the subpattern doesn't match; it must be able to hold at least rx_msize elements, where rx_msize is a public field of the matcher state structure. The current element can be accessed through the rx_start field of the same object. The regxml_fetch() function is similar to regxml_match(), except it also reports closing element events, and doesn't return match information. It is intended for traversing a matched interval after regxml_match() has returned 0.

After a successful call to regxml_match(), captured intervals can be traversed by calling the regxml_inititer() function to initialize a struct regxml_iter object with the desired interval, and then repeatedly calling the regxml_fetchiter() function to iterate over it.

The regxml_reset() function resets the internal state of the matcher so that it can process another stream, against the same compiled pattern.

The regxml_strerror() function converts an error code into a human-readable string representation.

The header regxml/regxml.h declares the following types and structures:

struct regxml_elem
    Structure representing an XML element in memory.

struct regxml_iter
    Structure representing the state of an iteration over an XML interval.

struct regxml
    Structure representing the matcher state.

regxml_xid_t
    Integral type of XML offsets, which define interval boundaries. This is the type of the rxe_lowid and rxe_highid fields of the struct regxml_elem structure.

regxml_xtype_t
    Integral type of XML element types.

The struct regxml_elem structure contains at least the following fields:

    struct regxml_elem {
    	regxml_xid_t rxe_lowid, rxe_highid;
    	regxml_xtype_t rxe_type;
    	char *rxe_name, *rxe_value;
    	char **rxe_attrv;
    	regxml_xid_t rxe_nattr;
    	struct regxml_elem *rxe_parent;
    	regxml_xid_t rxe_pos;
    };

rxe_lowid, rxe_highid
    The XML offsets corresponding to the start and end of the element. Every element whose delimiting offsets are contained in that numeric interval is a descendant. The element whose start offset is equal to rxe_highid+1 is the next sibling.

    Upon return from regxml_match(), the upper bound of returned intervals may not contain a useful rxe_highid value, because of partial fetching.

rxe_type
    The type of the element. It can take any of the following values:

    REGXML_ROOT
        The virtual root element of the XML document. The virtual root is the parent of the actual root element as defined by the XML specification (the topmost element which appears in the XML stream).

    REGXML_NODE
        A node element.

    REGXML_TEXT
        A text element.

    REGXML_COMMENT
        A comment element.

    REGXML_PI
        A processing instruction element.

    Please see the XML standard for more information.

rxe_name
    The name component of the element. It corresponds to the tag name of a node, the target of a preprocessing instruction, and is NULL otherwise.

rxe_value
    The value component of the element. It corresponds to the string value of a text element, the content of a comment or preprocessing instruction without the delimiters, and is NULL otherwise.

rxe_attrv
    An array containing alternating keys and values. The array is NULL-terminated and contains rxe_nattr elements.

rxe_nattr
    The number of elements in the array pointed to by rxe_attrv.

rxe_parent
    A pointer to the parent element. Ancestors are always available in any state of the matcher.

rxe_pos
    The relative position of the element, that is, its position amongst its siblings. Relative positions start at 1 for the first sibling of any given element.

The struct regxml_iter structure contains at least the following fields:

    struct regxml_iter {
    	struct regxml_elem *rxi_ptr;
            struct regxml_elem *rxi_end;
    };

rxi_ptr
    A pointer to the current element. After a successful call to regxml_fetchiter(), this field points to the element being opened or closed, or is NULL if there is no more element.

rxi_end
    A pointer to the end of the iterable interval.

The struct regxml structure contains at least the following fields:

    struct regxml {
    	struct regxml_elem *rx_start;
    	regxml_id_t rx_msize, rx_maxmatch;
    };

rx_start
    A pointer to the current element. After a call to regxml_match() or regxml_fetch(), this field points to the potential lower bound of the matched intervals.

rx_msize
    The required size of the match array passed to regxml_match(). It is always equal to twice the number of capturing subpatterns in the compiled pattern (accounting for the 0th subpattern; see the REGXML_LONGEST flag below for more information).

rx_maxmatch
    Index of the longest matching subpattern, when REGXML_LONGEST is specified.

The header also defines the following flags for regxml_create():

REGXML_LONGEST
    Compute the longest capturing subpattern in match[1]. By default, the 0th capturing subpattern holds an unspecified value on return from regxml_match(); capturing subpatterns start with index 1.

REGXML_ENTITIZE
    Automatically convert apostrophes ‘('’), double quotes ‘(’), less-than ‘(’) and greater-than signs ‘(’) in patterns to XML entities.

REGXML_ICASE
    Make regular expression matching case-insensitive. The equality operators are not affected by this flag.

REGXML_MATCHSTEP
    Instruct regxml_match() to report (return at) every step, returning REGXML_CLOSING when appropriate, the same way regxml_fetch() does.

RETURN VALUES
The functions regxml_create(), regxml_pushopening(), regxml_pushclosing(), regxml_pushtext(), regxml_pushcomment() and regxml_end() return 0 on success, or a non-zero error code.

The function regxml_match() normally returns 0 on success, REGXML_NOMATCH on failure, or another non-zero code if an error has occurred. If the matcher was created with REGXML_MATCHSTEP, regxml_match() returns REGXML_CLOSING upon closing an element.

The functions regxml_fetch() and regxml_fetchiter() return REGXML_OPENING upon opening an element, and REGXML_CLOSING on a closing event; otherwise, it returns a non-zero code on error.

DIAGNOSTICS
The return codes are:

REGXML_EOF
    End-of-file has been reached.

REGXML_NOMATCH
    The pattern did not match.

REGXML_OPENING
    Defined as 0, for symmetry with REGXML_CLOSING. An opening tag event occurred.

REGXML_CLOSING
    An closing tag event occurred.

REGXML_ESYSTEM
    A system error occurred; the system error code is in errno(3).

REGXML_EREGEX
    An error occurred while compiling or matching a regular expression. See regex(3) for more information.

REGXML_EXML
    An XML structural error occurred.

REGXML_EAGAIN
    The match result cannot be computed without additional data.

REGXML_ESYNTAX
    The pattern string contains a syntax error.

REGXML_EUSER
    A user-supplied function returned an error.

REGXML_ENOIMPL
    The requested feature is not yet implemented.

SEE ALSO
xmltools(7), regex(3)

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

BUGS
The regxml_create() function depends on yacc(1) for its pattern parsing, and is currently not reentrant. If you are going to use this library, please ensure that calls to regxml_create() are exclusive.