Xml2Doc¶

Wrapper around a libxml2 xmlDoc pointer, providing convenient parsing and XPath evaluation helpers.

class ref Xml2Doc

Constructors¶

parseFile¶

[Source]

Parse an XML document from the given file path using libxml2.

auth: Capability proving the caller has permission to read files.
pfilename: Path to the XML file to parse.

On success, stores the underlying xmlDoc* in ptr' and its non-null value in ptr. Raises an error if parsing fails or returns a null document pointer.

new ref parseFile(
  auth: FileAuth val,
  pfilename: String val)
: Xml2Doc ref^ ?

Parameters¶

auth: FileAuth val
pfilename: String val

Returns¶

Xml2Doc ref^ ?

parseDoc¶

[Source]

Parse an XML document from an in-memory string using libxml2.

pcur: String containing the complete XML document.

On success, stores the underlying xmlDoc* in ptr' and its non-null value in ptr. Raises an error if parsing fails or returns a null document pointer.

new ref parseDoc(
  pcur: String val)
: Xml2Doc ref^ ?

Parameters¶

pcur: String val

Returns¶

Xml2Doc ref^ ?

create¶

[Source]

Create a new empty XML document with the specified version.

version: XML version string (default: "1.0")

Creates an empty document with no root element. Use setRootElement() or createElement() to build the document tree.

Example:

let doc = Xml2Doc.create()?
let root = doc.createElement("root")?
doc.setRootElement(root)?

new ref create(
  version: String val = "1.0")
: Xml2Doc ref^ ?

Parameters¶

version: String val = "1.0"

Returns¶

Xml2Doc ref^ ?

createWithRoot¶

[Source]

Create a new XML document with a root element.

root_name: Name of the root element
version: XML version string (default: "1.0")

Convenience constructor that creates a document and sets the root element in one step.

Example:

let doc = Xml2Doc.createWithRoot("root")?
let root = doc.getRootElement()?
let child = root.addChild("item")?

new ref createWithRoot(
  root_name: String val,
  version: String val = "1.0")
: Xml2Doc ref^ ?

Parameters¶

root_name: String val
version: String val = "1.0"

Returns¶

Xml2Doc ref^ ?

Public fields¶

let ptr': NullablePointer[XmlDoc ref] ref¶

[Source]

Public Functions¶

xpathEval¶

[Source]

Evaluate an XPath expression against this document and return the result.

xpath: The XPath expression to evaluate.
namespaces: Optional list of (prefix, uri) pairs to register on a temporary XPath context before evaluation, for namespace-aware queries.

Internally, creates a new xmlXPathContext for the document, registers the provided namespaces, calls xmlXPathEval, then frees the context. Returns an Xml2XPathResult wrapper around the resulting xmlXPathObject*.

fun box xpathEval(
  xpath: String val,
  namespaces: Array[(String val , String val)] ref = array)
: (None val | Array[Xml2Node ref] ref | Bool val | 
    String val | F64 val)

Parameters¶

xpath: String val
namespaces: Array[(String val , String val)] ref = array

Returns¶

(None val | Array[Xml2Node ref] ref | Bool val | String val | F64 val)

xpathEvalNodes¶

[Source]

A convenience method that calls xpathEval and returns an Array[Xml2Node].

fun box xpathEvalNodes(
  xpath: String val,
  namespaces: Array[(String val , String val)] ref = array)
: Array[Xml2Node ref] ref ?

Parameters¶

xpath: String val
namespaces: Array[(String val , String val)] ref = array

Returns¶

Array[Xml2Node ref] ref ?

xpathEvalString¶

[Source]

A convenience method that calls xpathEval and returns a String val.

fun box xpathEvalString(
  xpath: String val,
  namespaces: Array[(String val , String val)] ref = array)
: String val ?

Parameters¶

xpath: String val
namespaces: Array[(String val , String val)] ref = array

Returns¶

String val ?

xpathEvalF64¶

[Source]

A convenience method that calls xpathEval and returns an F64 (XML's default number type in libxml2).

fun box xpathEvalF64(
  xpath: String val,
  namespaces: Array[(String val , String val)] ref = array)
: F64 val ?

Parameters¶

xpath: String val
namespaces: Array[(String val , String val)] ref = array

Returns¶

F64 val ?

xpathEvalBool¶

[Source]

A convenience method that calls xpathEval and returns a Bool.

fun box xpathEvalBool(
  xpath: String val,
  namespaces: Array[(String val , String val)] ref = array)
: Bool val ?

Parameters¶

xpath: String val
namespaces: Array[(String val , String val)] ref = array

Returns¶

Bool val ?

getRootElement¶

[Source]

Return the root element node of this document as an Xml2Node.

Calls xmlDocGetRootElement on the underlying xmlDoc*. Raises an error if the document has no root element or the returned pointer is null.

fun ref getRootElement()
: Xml2Node ref ?

Returns¶

Xml2Node ref ?

createElement¶

[Source]

Create a new element node belonging to this document.

name: Element name (tag name)
content: Optional text content

Returns an Xml2Node wrapper. The node is created but not yet attached to the document tree. Use setRootElement() or appendChild() to add it.

Example:

let doc = Xml2Doc.create()?
let elem = doc.createElement("item", "Hello")?
elem.setProp("id", "1")

fun ref createElement(
  name: String val,
  content: String val = "")
: Xml2Node ref ?

Parameters¶

name: String val
content: String val = ""

Returns¶

Xml2Node ref ?

setRootElement¶

[Source]

Set the root element of this document.

root: The node to set as root element

Returns the old root element if one existed, otherwise returns the new root. Raises error if the operation fails.

Example:

let doc = Xml2Doc.create()?
let root = doc.createElement("root")?
doc.setRootElement(root)?

fun ref setRootElement(
  root: Xml2Node ref)
: Xml2Node ref ?

Parameters¶

root: Xml2Node ref

Returns¶

Xml2Node ref ?

createTextNode¶

[Source]

Create a text node belonging to this document.

content: Text content

Text nodes are typically added as children of element nodes to create mixed content (text and elements combined).

Example:

let doc = Xml2Doc.createWithRoot("para")?
let para = doc.getRootElement()?
para.appendChild(doc.createTextNode("Some text "))?
let bold = doc.createElement("b", "bold")?
para.appendChild(bold)?
para.appendChild(doc.createTextNode(" more text"))?

fun ref createTextNode(
  content: String val)
: Xml2Node ref ?

Parameters¶

content: String val

Returns¶

Xml2Node ref ?

createComment¶

[Source]

Create a comment node belonging to this document.

content: Comment text (without delimiters)

Comment nodes can be added to the document tree using appendChild().

Example:

let doc = Xml2Doc.createWithRoot("root")?
let root = doc.getRootElement()?
root.appendChild(doc.createComment("This is a comment"))?

fun ref createComment(
  content: String val)
: Xml2Node ref ?

Parameters¶

content: String val

Returns¶

Xml2Node ref ?

serialize¶

[Source]

Serialize this document to a String with optional formatting.

format: If true, enables pretty-printing (indentation, newlines). If false, produces compact output.
encoding: Character encoding for the output (default: "UTF-8"). Common values: "UTF-8", "ISO-8859-1", "UTF-16".

Returns the serialized XML as a String val. Raises an error if serialization fails or returns null memory.

Example:

let doc = Xml2Doc.parseDoc("<root><child>text</child></root>")?
let xml_string = doc.serialize()?  // Pretty-printed UTF-8
let compact = doc.serialize(false)?  // Compact output

fun box serialize(
  format: Bool val = true,
  encoding: String val = "UTF-8")
: String val ?

Parameters¶

format: Bool val = true
encoding: String val = "UTF-8"

Returns¶

String val ?

saveToFile¶

[Source]

Save this document to a file with optional formatting and encoding.

auth: Capability proving the caller has permission to write files.
filename: Path to the file where the document should be saved.
format: If true, enables pretty-printing (indentation, newlines). If false, produces compact output.
encoding: Character encoding for the output (default: "UTF-8"). Common values: "UTF-8", "ISO-8859-1", "UTF-16".

Returns None on success. Raises an error if the file cannot be written or if libxml2 returns an error code (negative return value).

Example:

let doc = Xml2Doc.parseDoc("<root><child>text</child></root>")?
doc.saveToFile(auth, "output.xml")?  // Pretty-printed UTF-8
doc.saveToFile(auth, "compact.xml", false, "ISO-8859-1")?

fun box saveToFile(
  auth: FileAuth val,
  filename: String val,
  format: Bool val = true,
  encoding: String val = "UTF-8")
: None val ?

Parameters¶

auth: FileAuth val
filename: String val
format: Bool val = true
encoding: String val = "UTF-8"

Returns¶

None val ?