7.4. 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.4.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.4.1.1. for_each_child

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

Iterates over child elements of node whose tag matches name.

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

7.4.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.4.2.1. each_child

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

Returns a lazy iterator over child elements of node whose tag matches name. Intended for use in for loops:

for (ch in each_child(node, "item")) { ... }

Arguments:
each_child(node: xml_node): iterator<xml_node>

7.4.3. 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.4.4. 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.4.5. Builder helpers

7.4.5.1. add_attr

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

Appends an attribute with name and value (string).

Arguments:

  • node : xml_node

  • name : string

  • value : string

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: bool): 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.4.6. Builder EDSL

7.4.6.1. attr

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

Appends an int attribute, returns parent for chaining.

Arguments:

  • node : xml_node

  • name : string

  • value : int

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

7.4.6.2. tag

tag(node: xml_node; name: string; text_content: string): xml_node

Appends a child element with name and text content. Returns the new child. Use for leaf elements:

node |> tag("title", "The C Programming Language")

Arguments:

  • node : xml_node

  • name : string

  • text_content : string

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

7.4.7. String conversion

7.4.7.1. to_string

to_string(node: xml_node): string

Serializes a single node (and its subtree) to an XML string with two-space indentation.

Arguments:
to_string(doc: xml_document?): string

7.4.8. 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.4.9. 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.4.9.1. XML_table

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

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

Arguments:

  • node : xml_node

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

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

7.4.9.2. from_XML

from_XML(node: xml_node; ent: double; defV: double = 0lf): double

Reads the text content of node as a double.

Arguments:

  • node : xml_node

  • ent : double

  • defV : double

from_XML(node: xml_node; ent: int8; defV: int8 = int8(0)): int8
from_XML(node: xml_node; ent: uint; defV: uint = 0x0): uint
from_XML(node: xml_node; ent: uint8; defV: uint8 = uint8(0)): uint8
from_XML(node: xml_node; ent: int; defV: int = 0): int
from_XML(node: xml_node; ent: int64; defV: int64 = 0): int64
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; anything: auto(TT)): auto
from_XML(node: xml_node; ent: auto(VecT); defV: VecT = VecT()): VecT
from_XML(node: xml_node; ent: string; defV: string = ""): string
from_XML(node: xml_node; ent: float; defV: float = 0f): float
from_XML(node: xml_node; ent: bool; defV: bool = false): bool
from_XML(node: xml_node; ent: int16; defV: int16 = int16(0)): int16
from_XML(node: xml_node; anything: table<auto(KT), void>): auto
from_XML(node: xml_node; anything: table<auto(KT), auto(VT)>): auto
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.4.10. Type conversion operators

7.4.10.1. operator as bool

operator as bool(t: xml_text): bool

Converts xml_text content to bool (default false).

Arguments:
operator as bool(a: xml_attribute): bool

7.4.10.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.4.10.3. operator as float

operator as float(t: xml_text): float

Converts xml_text content to float (default 0.0).

Arguments:
operator as float(a: xml_attribute): float

7.4.10.4. operator as int

operator as int(t: xml_text): int

Converts xml_text content to int (default 0).

Arguments:
operator as int(a: xml_attribute): int

7.4.10.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.4.10.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.4.10.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.4.10.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.4.10.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.4.10.10. operator is int

operator is int(t: xml_text): bool

Returns true if the text node is non-empty.

Arguments:
operator is int(a: xml_attribute): bool

7.4.10.11. operator is string

operator is string(t: xml_text): bool

Returns true if the text node is non-empty.

Arguments:
operator is string(a: xml_attribute): bool

7.4.10.12. operator is uint

operator is uint(t: xml_text): bool

Returns true if the text node is non-empty.

Arguments:
operator is uint(a: xml_attribute): 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: