XScript Manual · Chapter 35

XML Object — XML document handling

The script keyword XML provides XML utilities. A single process can hold multiple XML documents identified by name; nodes and attributes are addressed via path notation.

Concept	Meaning
`xmlName`	Document identifier (`"recipe"`, `"settings"`, …)
`path`	Node location — `"/root/items/item"` (XPath-style)
`attributeName`	Attribute name (optional) — empty means the node text value
Result / error	Every call updates an internal flag — `GetResult` / `GetErrorMessage`

Basic flow

// 1) Empty document
XML.Create("recipe");
 
// 2) Add nodes + values
XML.AddNode("recipe", "/root", "");                 // <root/>
XML.SetString ("recipe", "/root/title",  "AlignRecipe");
XML.SetInteger("recipe", "/root/version", 2);
XML.SetDouble ("recipe", "/root/exposure_ms", 18.5);
XML.SetBool   ("recipe", "/root/use_filter",  true);
 
// 3) Save
XML.Save("recipe", "D:/Recipes/align.xml");
 
// 4) Drop when done
XML.Remove("recipe");

Document lifecycle

XML.Create("doc");                              // empty
XML.Parse ("doc", "<root><a>1</a></root>");     // parse string
XML.Load  ("doc", "D:/Settings/sys.xml");       // load file
XML.Save  ("doc", "D:/Settings/sys.xml");       // save file
 
if( XML.Contains("doc") )  XML.Remove("doc");
XML.RemoveAll();

Adding nodes — AddNode / AddNodeCDATA

XML.AddNode("doc", "/root/items/item", "auto");
// <root><items><item>auto</item></items></root>
//   missing parent paths are auto-created.
 
// CDATA-wrapped text (HTML, multi-line, < > & inside)
XML.AddNodeCDATA("doc", "/root/desc", "<b>hello</b>\nworld");

Calling the same path twice appends one more node, stacking siblings.

Writing node text — SetXxx

XML.SetString ("doc", "/root/name",     "Alice");
XML.SetInteger("doc", "/root/age",      30);
XML.SetDouble ("doc", "/root/weight",   62.4);
XML.SetBool   ("doc", "/root/active",   true);
 
// Wrap in CDATA
XML.SetStringCDATA("doc", "/root/desc", "<html>...</html>");

Missing nodes are auto-created. If the same path is a list of siblings, the first one's value is updated.

Writing attributes — SetXxxAttribute

XML.SetStringAttribute ("doc", "/root/name", "lang", "en");
XML.SetIntegerAttribute("doc", "/root/age",  "ver", 2);
XML.SetDoubleAttribute ("doc", "/root/weight", "kg", 0.001);
XML.SetBoolAttribute   ("doc", "/root/active", "auto", true);

Reading — GetXxx

// Node text value
string s = XML.GetString ("doc", "/root/name");
int    i = XML.GetInteger("doc", "/root/age");
double d = XML.GetDouble ("doc", "/root/weight");
bool   b = XML.GetBool   ("doc", "/root/active");
 
// Attribute (3rd argument)
string lang = XML.GetString ("doc", "/root/name", "lang");
int    ver  = XML.GetInteger("doc", "/root/age",  "ver");

If the 3rd argument (attributeName) is empty — node text. If filled — that attribute value.

Counting children — GetCount

// Total children under /root/items
int total = XML.GetCount("doc", "/root/items");
 
// Children named 'item' under /root/items
int items = XML.GetCount("doc", "/root/items", "item");
 
for(i, 0, items - 1)
{
    string name = XML.GetString("doc", $"/root/items/item[{i}]/name");
    // ...
}

Result / error handling

XML.ResetResult("doc");
XML.SetInteger("doc", "/root/missing/path", 1);
if( XML.GetResult("doc") == false )
{
    LogError($"XML write failed : {XML.GetErrorMessage("doc")}");
}

Verify after a series of SetXxx calls is the cleanest pattern.

Common patterns

Save / load system settings

FUNCTION SaveSettings(string path)
{
    XML.Create("set");
    XML.AddNode("set", "/Settings", "");
    XML.SetInteger("set", "/Settings/Light",    Data::Light);
    XML.SetDouble ("set", "/Settings/Exposure", Data::Exposure);
    XML.SetBool   ("set", "/Settings/UseAuto",  Data::UseAuto);
 
    XML.Save("set", path);
    XML.Remove("set");
}
 
FUNCTION LoadSettings(string path)
{
    XML.Load("set", path);
    if( XML.GetResult("set") == false )
    {
        ShowMessage(EB_Ok, XML.GetErrorMessage("set"));
        return false;
    }
 
    Data::Light    = XML.GetInteger("set", "/Settings/Light");
    Data::Exposure = XML.GetDouble ("set", "/Settings/Exposure");
    Data::UseAuto  = XML.GetBool   ("set", "/Settings/UseAuto");
 
    XML.Remove("set");
    return true;
}

Parse external XML

XML.Load("rep", "D:/Reports/lot_001.xml");
 
int n = XML.GetCount("rep", "/Report/Items", "Item");
for(i, 0, n - 1)
{
    string name  = XML.GetString ("rep", $"/Report/Items/Item[{i}]/Name");
    int    count = XML.GetInteger("rep", $"/Report/Items/Item[{i}]/Count");
    Log($"#{i} {name} = {count}");
}
XML.Remove("rep");

Quick reference

Group	Functions
Lifecycle	`Create` · `Parse` · `Load` · `Save` · `Remove` · `RemoveAll` · `Contains`
Result	`GetResult` · `GetErrorMessage` · `ResetResult`
Nodes	`AddNode` · `AddNodeCDATA` · `GetCount`
Write text	`SetString` · `SetInteger` · `SetDouble` · `SetBool` · `SetStringCDATA`
Write attribute	`SetStringAttribute` · `SetIntegerAttribute` · `SetDoubleAttribute` · `SetBoolAttribute`
Read	`GetString` · `GetInteger` · `GetDouble` · `GetBool` (path + optional attributeName)