Module parser_context 

XPath parser context and value stack (§25, 11.1-I XPath family closure).

Upstream libxml2 exposes xmlXPathParserContextPtr (a fully public struct in the headers) together with a value stack (xmlXPathPush* / xmlXPathPop*) and stack-based value operators (xmlXPathAddValues etc.).

UPSTREAM-PARITY (field layout)

The candidate struct layout mirrors the upstream _xmlXPathParserContext field-for-field (see include/libxml/xpath.h and upstream xpath.h):

struct _xmlXPathParserContext {
    const xmlChar *cur;      /* the current char being parsed */
    const xmlChar *base;     /* the full expression */
    int error;               /* error code */
    xmlXPathContext *context;/* the evaluation context */
    xmlXPathObject *value;   /* the current value */
    int valueNr;             /* number of values stacked */
    int valueMax;            /* max number of values stacked */
    xmlXPathObject **valueTab;/* stack of values */
    xmlXPathCompExpr *comp;  /* the precompiled expression */
    int xptr;                /* it this an XPointer expression */
    xmlNode *ancestor;       /* used for walking preceding axis */
    int valueFrame;          /* always zero for compatibility */
};

The XPATH-001 differential court verifies the stack operators and the parser-context APIs against the oracle.

Historical quirks & epochs

The _xmlXPathParserContext layout has been stable across the whole libxml2 matrix (2.7.8..2.15.3): the valueFrame field is documented upstream as always zero for compatibility, and the value-stack operators (xmlXPathPush*/xmlXPathPop*) have not changed semantics. The XPath node-set serialization capability E-001 (2.9.10 boundary) is handled at the CLI layer, not here.

Tempting simplifications that would break parity

A tempting simplification is to represent the value stack with a Rust Vec and pop by truncation. Upstream pops return the object and shift the stack; the public xmlXPathPop* functions are ABI-observable and their NULL-on-empty / last-value behavior is court-checked (XPATH-001). Keep the explicit valueTab/valueNr/valueMax fields byte-compatible.

Structs

XmlXPathParserContext

The public xmlXPathParserContext (layout mirrors upstream xpath.h).

Functions

binary_number_op^⚠

Pop two number operands from the stack and apply op.

cast_top_to_number^⚠

Number → number conversion of the top-of-stack object, in place (upstream CAST_TO_NUMBER): the object’s type becomes XPATH_NUMBER and floatval holds the converted value. A NULL top (or a USERS object) reports XPATH_INVALID_OPERAND.

compare_values_impl^⚠

Pop two objects and compare with <, <=, >, >= (upstream xmlXPathCompareValues with the inf / strict encoding).

equal_values_impl^⚠

Pop two objects and compare for equality (upstream xmlXPathEqualValues / xmlXPathNotEqualValues semantics): pushes the boolean result object and returns the comparison value.

equal_values_inner

Full XPath 1.0 equality matrix (§3.4) matching upstream 2.15 xmlXPathEqualValues / xmlXPathNotEqualValues (including the node-set pair/string/number/boolean special cases).

free_parser_context^⚠

Free a parser context.

new_bool^⚠

Build a boolean object.

new_number^⚠

Build a number object.

new_parser_context^⚠

Create a new parser context over str with the given evaluation context.

new_string^⚠

Build a string object (copies the value).

pc_set_error^⚠

Set the parser-context error code (upstream xmlXPathSetError / XP_ERROR).

pop_boolean^⚠

Pop a boolean.

pop_external^⚠

Pop an external (user) pointer.

pop_node_set^⚠

Pop a node set (freshly allocated; caller frees with xmlXPathFreeNodeSet).

pop_number^⚠

Pop a number (upstream xmlXPathPopNumber): converts the top of the stack to a number, frees it, returns the value.

pop_string^⚠

Pop a string (freshly allocated; caller frees with xmlFree).

value_pop^⚠

Pop a value object from the stack (upstream valuePop).

value_push^⚠

Push a value object onto the stack (upstream valuePush).

value_to_object^⚠

Convert an internal value to a C object.