pattern: pattern expression handling

## pattern

pattern - pattern expression handling

allows to compile and test pattern expressions for nodes either in a tree or based on a parser state.

Author(s): Daniel Veillard

## Synopsis

    typedef xmlStreamCtxt * xmlStreamCtxtPtr;
    typedef enum xmlPatternFlags;
    typedef struct _xmlStreamCtxt xmlStreamCtxt;
    typedef struct _xmlPattern xmlPattern;
    typedef xmlPattern * xmlPatternPtr;
    int	xmlPatternMinDepth		(xmlPatternPtr comp);
    xmlStreamCtxtPtr	xmlPatternGetStreamCtxt	(xmlPatternPtr comp);
    int	xmlPatternFromRoot		(xmlPatternPtr comp);
    void	xmlFreePatternList		(xmlPatternPtr comp);
    int	xmlPatternStreamable		(xmlPatternPtr comp);
    int	xmlStreamPushAttr		(xmlStreamCtxtPtr stream,
    					 const xmlChar * name,
    					 const xmlChar * ns);
    int	xmlPatternMatch			(xmlPatternPtr comp,
    					 xmlNodePtr node);
    int	xmlStreamWantsAnyNode		(xmlStreamCtxtPtr streamCtxt);
    int	xmlStreamPop			(xmlStreamCtxtPtr stream);
    void	xmlFreePattern			(xmlPatternPtr comp);
    int	xmlStreamPush			(xmlStreamCtxtPtr stream,
    					 const xmlChar * name,
    					 const xmlChar * ns);
    int	xmlPatternMaxDepth		(xmlPatternPtr comp);
    xmlPatternPtr	xmlPatterncompile	(const xmlChar * pattern,
    					 xmlDict * dict,
    					 int flags,
    					 const xmlChar ** namespaces);
    int	xmlStreamPushNode		(xmlStreamCtxtPtr stream,
    					 const xmlChar * name,
    					 const xmlChar * ns,
    					 int nodeType);
    void	xmlFreeStreamCtxt		(xmlStreamCtxtPtr stream);

## Description

## Details

### Structure xmlPattern

    struct _xmlPattern {
    The content of this structure is not made public by the API.
    } xmlPattern;

### Enum xmlPatternFlags

    enum xmlPatternFlags {
        XML_PATTERN_DEFAULT = 0 /* simple pattern match */
        XML_PATTERN_XPATH = 1 /* standard XPath pattern */
        XML_PATTERN_XSSEL = 2 /* XPath subset for schema selector */
        XML_PATTERN_XSFIELD = 4 /*  XPath subset for schema field */
    };

### Typedef xmlPatternPtr

    xmlPattern * xmlPatternPtr;

### Structure xmlStreamCtxt

    struct _xmlStreamCtxt {
    The content of this structure is not made public by the API.
    } xmlStreamCtxt;

### Typedef xmlStreamCtxtPtr

    xmlStreamCtxt * xmlStreamCtxtPtr;

### xmlFreePattern ()

    void	xmlFreePattern			(xmlPatternPtr comp)

Free up the memory allocated by @comp

`comp`: | an XSLT comp

### xmlFreePatternList ()

    void	xmlFreePatternList		(xmlPatternPtr comp)

Free up the memory allocated by all the elements of @comp

`comp`: | an XSLT comp list

### xmlFreeStreamCtxt ()

    void	xmlFreeStreamCtxt		(xmlStreamCtxtPtr stream)

Free the stream context

`stream`: | the stream context

### xmlPatternFromRoot ()

    int	xmlPatternFromRoot		(xmlPatternPtr comp)

Check if the pattern must be looked at from the root.

`comp`: | the precompiled pattern
`Returns`: | 1 if true, 0 if false and -1 in case of error

### xmlPatternGetStreamCtxt ()

    xmlStreamCtxtPtr	xmlPatternGetStreamCtxt	(xmlPatternPtr comp)

Get a streaming context for that pattern Use xmlFreeStreamCtxt to free the context.

`comp`: | the precompiled pattern
`Returns`: | a pointer to the context or NULL in case of failure

### xmlPatternMatch ()

    int	xmlPatternMatch			(xmlPatternPtr comp,
    					 xmlNodePtr node)

Test whether the node matches the pattern

`comp`: | the precompiled pattern
`node`: | a node
`Returns`: | 1 if it matches, 0 if it doesn't and -1 in case of failure

### xmlPatternMaxDepth ()

    int	xmlPatternMaxDepth		(xmlPatternPtr comp)

Check the maximum depth reachable by a pattern

`comp`: | the precompiled pattern
`Returns`: | -2 if no limit (using //), otherwise the depth, and -1 in case of error

### xmlPatternMinDepth ()

    int	xmlPatternMinDepth		(xmlPatternPtr comp)

Check the minimum depth reachable by a pattern, 0 mean the / or . are part of the set.

`comp`: | the precompiled pattern
`Returns`: | -1 in case of error otherwise the depth,

### xmlPatternStreamable ()

    int	xmlPatternStreamable		(xmlPatternPtr comp)

Check if the pattern is streamable i.e. xmlPatternGetStreamCtxt() should work.

`comp`: | the precompiled pattern
`Returns`: | 1 if streamable, 0 if not and -1 in case of error.

### xmlPatterncompile ()

    xmlPatternPtr	xmlPatterncompile	(const xmlChar * pattern,
    					 xmlDict * dict,
    					 int flags,
    					 const xmlChar ** namespaces)

Compile a pattern.

`pattern`: | the pattern to compile
`dict`: | an optional dictionary for interned strings
`flags`: | compilation flags, see xmlPatternFlags
`namespaces`: | the prefix definitions, array of [URI, prefix] or NULL
`Returns`: | the compiled form of the pattern or NULL in case of error

### xmlStreamPop ()

    int	xmlStreamPop			(xmlStreamCtxtPtr stream)

push one level from the stream.

`stream`: | the stream context
`Returns`: | -1 in case of error, 0 otherwise.

### xmlStreamPush ()

    int	xmlStreamPush			(xmlStreamCtxtPtr stream,
    					 const xmlChar * name,
    					 const xmlChar * ns)

Push new data onto the stream. NOTE: if the call xmlPatterncompile() indicated a dictionary, then strings for name and ns will be expected to come from the dictionary. Both @name and @ns being NULL means the / i.e. the root of the document. This can also act as a reset. Otherwise the function will act as if it has been given an element-node.

`stream`: | the stream context
`name`: | the current name
`ns`: | the namespace name
`Returns`: | -1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.

### xmlStreamPushAttr ()

    int	xmlStreamPushAttr		(xmlStreamCtxtPtr stream,
    					 const xmlChar * name,
    					 const xmlChar * ns)

Push new attribute data onto the stream. NOTE: if the call xmlPatterncompile() indicated a dictionary, then strings for name and ns will be expected to come from the dictionary. Both @name and @ns being NULL means the / i.e. the root of the document. This can also act as a reset. Otherwise the function will act as if it has been given an attribute-node.

`stream`: | the stream context
`name`: | the current name
`ns`: | the namespace name
`Returns`: | -1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.

### xmlStreamPushNode ()

    int	xmlStreamPushNode		(xmlStreamCtxtPtr stream,
    					 const xmlChar * name,
    					 const xmlChar * ns,
    					 int nodeType)

Push new data onto the stream. NOTE: if the call xmlPatterncompile() indicated a dictionary, then strings for name and ns will be expected to come from the dictionary. Both @name and @ns being NULL means the / i.e. the root of the document. This can also act as a reset. Different from xmlStreamPush() this function can be fed with nodes of type: element-, attribute-, text-, cdata-section-, comment- and processing-instruction-node.

`stream`: | the stream context
`name`: | the current name
`ns`: | the namespace name
`nodeType`: | the type of the node being pushed
`Returns`: | -1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.

### xmlStreamWantsAnyNode ()

    int	xmlStreamWantsAnyNode		(xmlStreamCtxtPtr streamCtxt)

Query if the streaming pattern additionally needs to be fed with text-, cdata-section-, comment- and processing-instruction-nodes. If the result is 0 then only element-nodes and attribute-nodes need to be pushed.

`streamCtxt`: | the stream context
`Returns`: | 1 in case of need of nodes of the above described types, 0 otherwise. -1 on API errors.