7.6. High-level XML helpers (pugixml boost)

The PUGIXML_BOOST module provides high-level daScript helpers on top of the low-level pugixml C++ bindings.

Includes RAII document management (open_xml, parse_xml, with_doc), iterator-based traversal (each, each_child, each_attribute), a builder EDSL (tag, attr), quick attribute/text accessors, XPath convenience functions, is/as type-conversion operators, and generic struct ↔ XML serialization (to_XML, from_XML, XML).

All functions and symbols are in “PUGIXML_boost” module, use require to get access to it.

require pugixml/PUGIXML_boost

See also:

7.6.1. Block-based iteration

for_each(node_set: xpath_node_set?; blk: block<(xn:xpath_node):void> )

Iterates over all xpath_node entries in an xpath_node_set.

Arguments:
for_each_attribute(node: xml_node; blk: block<(attr:xml_attribute):void> )

Iterates over all attributes of node.

Arguments:

7.6.1.1. for_each_child

for_each_child(node: xml_node; blk: block<(child:xml_node):void> )

Iterates over all child elements of node.

Arguments:
for_each_child(node: xml_node; name: string; blk: block<(child:xml_node):void> )

7.6.2. Iterator-based iteration

each(node_set: xpath_node_set? ): iterator<xpath_node>

Returns a lazy iterator over all xpath_node entries in an xpath_node_set. Intended for use in for loops. Because the iterator is named each, the call can be omitted:

for (xn in node_set) { ... }

Arguments:
each_attribute(node: xml_node ): iterator<xml_attribute>

Returns a lazy iterator over all attributes of node. Intended for use in for loops:

for (a in each_attribute(node)) { ... }

Arguments:

7.6.2.1. each_child

each_child(node: xml_node ): iterator<xml_node>

Returns a lazy iterator over all child elements of node. Intended for use in for loops:

for (ch in each_child(node)) { ... }

Arguments:
each_child(node: xml_node; name: string ): iterator<xml_node>

7.6.3. LINQ source

build_xml_row(node: xml_node; row: auto ): auto

Fills row’s scalar fields from same-named attributes of node. A missing attribute leaves the field at its declared default. Supported field types: int, uint, float, double, bool, string — fields of other types keep their default.

Arguments:

7.6.3.1. from_xml_node

from_xml_node(node: xml_node; name: string; t: type<auto(TT) const> ): iterator<TT>

As from_xml_node above, but only walks child elements whose tag matches name (child/next_sibling by name already match elements only).

Arguments:

  • node : xml_node

  • name : string

  • t : auto(TT)

from_xml_node(node: xml_node; t: type<auto(TT) const> ): iterator<TT>
read_xml_field(node: xml_node; name: string; defv: auto(TT) ): TT

Reads one same-named attribute of node into a TT-typed value — the field-pruned counterpart to build_xml_row, emitted by linq_fold’s fused XML lane. A missing attribute keeps defv, so pass the struct field’s declared default to match build_xml_row semantics. Same supported field types as build_xml_row.

Arguments:

  • node : xml_node

  • name : string

  • defv : auto(TT)

7.6.4. RAII document handling

open_xml(filename: string; blk: block<(doc:xml_document?;success:bool):void> )

Opens an XML file, invokes blk with the parsed document and a success flag, then automatically frees the document. The caller never needs unsafe { delete ... }.

Arguments:

  • filename : string

  • blk : block<(doc: xml_document?;success:bool):void>

parse_xml(content: string; blk: block<(doc:xml_document?;success:bool):void> )

Parses an XML string, invokes blk with the document and a success flag, then automatically frees the document.

Arguments:

  • content : string

  • blk : block<(doc: xml_document?;success:bool):void>

with_doc(blk: block<(doc:xml_document?):void> )

Creates an empty xml_document, invokes blk, then frees it. Use this when building XML from scratch.

Arguments:

7.6.5. Quick accessors

node_attr(node: xml_node; attr_name: string; default_value: string = "" ): string

Returns the string value of attribute attr_name, or default_value if no such attribute exists.

Arguments:

  • node : xml_node

  • attr_name : string

  • default_value : string

node_attr_bool(node: xml_node; attr_name: string; default_value: bool = false ): bool

Returns the boolean value of attribute attr_name.

Arguments:

  • node : xml_node

  • attr_name : string

  • default_value : bool

node_attr_float(node: xml_node; attr_name: string; default_value: float = 0f ): float

Returns the float value of attribute attr_name.

Arguments:

  • node : xml_node

  • attr_name : string

  • default_value : float

node_attr_int(node: xml_node; attr_name: string; default_value: int = 0 ): int

Returns the integer value of attribute attr_name.

Arguments:

  • node : xml_node

  • attr_name : string

  • default_value : int

node_text(node: xml_node; child_name: string; default_value: string = "" ): string

Returns the text content of the child element named child_name, or default_value if the child does not exist or has no text.

Arguments:

  • node : xml_node

  • child_name : string

  • default_value : string

7.6.6. Builder helpers

7.6.6.1. add_attr

add_attr(node: xml_node; name: string; value: bool ): xml_attribute

Appends an attribute with name and value (bool).

Arguments:

  • node : xml_node

  • name : string

  • value : bool

add_attr(node: xml_node; name: string; value: float ): xml_attribute
add_attr(node: xml_node; name: string; value: int ): xml_attribute
add_attr(node: xml_node; name: string; value: string ): xml_attribute
add_child(node: xml_node; name: string; text_content: string ): xml_node

Appends a child element with name and sets its text content. Returns the new child node.

Arguments:

  • node : xml_node

  • name : string

  • text_content : string

add_child_ex(node: xml_node; name: string; attr_name: string; attr_value: string ): xml_node

Appends a child element with name and a single attribute. Returns the new child node.

Arguments:

  • node : xml_node

  • name : string

  • attr_name : string

  • attr_value : string

7.6.7. Builder EDSL

7.6.7.1. attr

attr(node: xml_node; name: string; value: bool ): xml_node

Appends a bool attribute, returns parent for chaining.

Arguments:

  • node : xml_node

  • name : string

  • value : bool

attr(node: xml_node; name: string; value: float ): xml_node
attr(node: xml_node; name: string; value: int ): xml_node
attr(node: xml_node; name: string; value: string ): xml_node

7.6.7.2. tag

tag(doc: xml_document?; name: string ): xml_node

Appends a bare child element to a document.

Arguments:
tag(doc: xml_document?; name: string; blk: block<(var child:xml_node):void> ): xml_node
tag(doc: xml_document?; name: string; text_content: string ): xml_node
tag(node: xml_node; name: string ): xml_node
tag(node: xml_node; name: string; blk: block<(var child:xml_node):void> ): xml_node
tag(node: xml_node; name: string; text_content: string ): xml_node

7.6.8. String conversion

7.6.8.1. to_string

to_string(doc: xml_document? ): string

Serializes the entire document to a pretty-printed XML string with two-space indentation and default formatting.

Arguments:
to_string(node: xml_node ): string

7.6.9. XPath helpers

for_each_select(node: xml_node; xpath_query: string; blk: block<(xn:xpath_node):void> )

Selects all nodes matching xpath_query and invokes blk for each result. The temporary xpath_node_set is freed automatically.

Arguments:
select_text(node: xml_node; xpath_query: string; default_value: string = "" ): string

Runs an XPath query and returns the text content of the first matching node, or default_value if nothing matches.

Arguments:

  • node : xml_node

  • xpath_query : string

  • default_value : string

select_value(node: xml_node; xpath_query: string; default_value: string = "" ): string

Runs an XPath query and returns the value of the first matching node. If the result is an attribute, returns its string value; if an element, returns its text content.

Arguments:

  • node : xml_node

  • xpath_query : string

  • default_value : string

with_xpath(query_str: string; blk: block<(query:xpath_query?):void> )

Compiles an XPath expression, invokes blk with the compiled query handle, then frees it. Avoids manual delete.

Arguments:

  • query_str : string

  • blk : block<(query: xpath_query?):void>

7.6.10. Serialization

XML(node: xml_node; value: auto(TT) ): auto

Serializes a native value into XML child elements of node. Structs/tuples: each field becomes a child element (via apply). Variants: stores _variant attribute with the active index. Tables (key-value): each entry becomes an entry child with _key / _val sub-elements. Tables (key-only): each key becomes an item child. Arrays/dim: each element becomes an item child. Enumerations: stored as string name. Bitfields: stored as integer value. Primitives: sets the text content of node.

Arguments:

7.6.10.1. XML_table

XML_table(node: xml_node; value: table<auto(KT), auto(VT)> ): auto

def XML_table (var node: xml_node; value: table<auto(KT), auto(VT)>) : auto

Arguments:

  • node : xml_node

  • value : table<auto(KT);auto(VT)>

XML_table(node: xml_node; value: table<auto(KT), void> ): auto

7.6.10.2. from_XML

from_XML(node: xml_node; anything: auto(TT) ): auto

Deserializes an XML node tree into a native value. Struct fields become child elements; arrays become sequences of child elements. Missing elements yield default values.

Arguments:
from_XML(node: xml_node; anything: table<auto(KT), auto(VT)> ): auto
from_XML(node: xml_node; anything: table<auto(KT), void> ): auto
from_XML(node: xml_node; ent: auto(VecT); defV: VecT = VecT() ): VecT
from_XML(node: xml_node; ent: bool; defV: bool = false ): bool
from_XML(node: xml_node; ent: double; defV: double = 0lf ): double
from_XML(node: xml_node; ent: float; defV: float = 0f ): float
from_XML(node: xml_node; ent: int16; defV: int16 = int16(0) ): int16
from_XML(node: xml_node; ent: int64; defV: int64 = 0 ): int64
from_XML(node: xml_node; ent: int8; defV: int8 = int8(0) ): int8
from_XML(node: xml_node; ent: int; defV: int = 0 ): int
from_XML(node: xml_node; ent: string; defV: string = "" ): string
from_XML(node: xml_node; ent: uint16; defV: uint16 = uint16(0) ): uint16
from_XML(node: xml_node; ent: uint64; defV: uint64 = 0x0 ): uint64
from_XML(node: xml_node; ent: uint8; defV: uint8 = uint8(0) ): uint8
from_XML(node: xml_node; ent: uint; defV: uint = 0x0 ): uint
from_XML(xml_str: string; anything: auto(TT) ): auto
to_XML(value: auto(TT); root_name: string = "root" ): string

Serializes a struct to a complete XML string, wrapping it in an element named root_name (default "root").

Arguments:

  • value : auto(TT)

  • root_name : string

7.6.11. Type conversion operators

7.6.11.1. operator as bool

operator as bool(a: xml_attribute ): bool

Converts an xml_attribute value to bool (default false).

Arguments:
operator as bool(t: xml_text ): bool

7.6.11.2. operator as double

operator as double(a: xml_attribute ): double

Converts an xml_attribute value to double (default 0.0lf).

Arguments:
operator as double(t: xml_text ): double

7.6.11.3. operator as float

operator as float(a: xml_attribute ): float

Converts an xml_attribute value to float (default 0.0).

Arguments:
operator as float(t: xml_text ): float

7.6.11.4. operator as int

operator as int(a: xml_attribute ): int

Converts an xml_attribute value to int (default 0).

Arguments:
operator as int(t: xml_text ): int

7.6.11.5. operator as string

operator as string(a: xml_attribute ): string

Converts an xml_attribute value to string (default "").

Arguments:
operator as string(node: xml_node ): string
operator as string(t: xml_text ): string

7.6.11.6. operator as uint

operator as uint(a: xml_attribute ): uint

Converts an xml_attribute value to uint (default 0u).

Arguments:
operator as uint(t: xml_text ): uint
operator as xml_node(doc: xml_document? ): xml_node

Returns the document as an xml_node handle for mutation APIs that require a node (e.g. append_child).

Arguments:

7.6.11.7. operator is bool

operator is bool(a: xml_attribute ): bool

Returns true if the attribute exists.

Arguments:
operator is bool(t: xml_text ): bool

7.6.11.8. operator is double

operator is double(a: xml_attribute ): bool

Returns true if the attribute exists.

Arguments:
operator is double(t: xml_text ): bool

7.6.11.9. operator is float

operator is float(a: xml_attribute ): bool

Returns true if the attribute exists.

Arguments:
operator is float(t: xml_text ): bool

7.6.11.10. operator is int

operator is int(a: xml_attribute ): bool

Returns true if the attribute exists (has a value convertible to int).

Arguments:
operator is int(t: xml_text ): bool

7.6.11.11. operator is string

operator is string(a: xml_attribute ): bool

Returns true if the attribute exists.

Arguments:
operator is string(t: xml_text ): bool

7.6.11.12. operator is uint

operator is uint(a: xml_attribute ): bool

Returns true if the attribute exists.

Arguments:
operator is uint(t: xml_text ): bool
xml_node[](node: xml_node; attr_name: string ): xml_attribute

Returns the attribute named attr_name. Combine with is/as operators for typed access:

node["price"] as float

if (node["discount"] is float) { ... }

Arguments: