XScript 手册 · Chapter 35

XML 对象 — XML 文档处理

脚本中以关键字 XML 访问的 XML 工具。一个进程中可以按名称同时管理多个 XML 文档,节点与属性都通过 path 表示法操作。

概念	说明
`xmlName`	文档标识(`"recipe"`、`"settings"` 等)
`path`	节点位置 — `"/root/items/item"`(类似 XPath)
`attributeName`	属性名(可选)— 留空表示节点文本值
结果 / 错误	每次调用都更新内部标志 — `GetResult` / `GetErrorMessage`

基本流程

// 1) 创建空文档
XML.Create("recipe");
 
// 2) 添加节点 + 设值
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) 保存到磁盘
XML.Save("recipe", "D:/Recipes/align.xml");
 
// 4) 清理
XML.Remove("recipe");

文档生命周期

XML.Create("doc");                              // 空文档
XML.Parse ("doc", "<root><a>1</a></root>");     // 解析字符串
XML.Load  ("doc", "D:/Settings/sys.xml");       // 文件加载
XML.Save  ("doc", "D:/Settings/sys.xml");       // 保存到文件
 
if( XML.Contains("doc") )  XML.Remove("doc");
XML.RemoveAll();

添加节点 — AddNode / AddNodeCDATA

XML.AddNode("doc", "/root/items/item", "auto");
// <root><items><item>auto</item></items></root>
//   父路径不存在则自动生成。
 
// 需要 CDATA 包裹的文本(HTML、多行、< > & 包含等)
XML.AddNodeCDATA("doc", "/root/desc", "<b>hello</b>\nworld");

同一 path 调用两次 会再追加一个同名节点,作为兄弟节点叠加。

写节点文本 — 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);
 
// 用 CDATA 包裹保存
XML.SetStringCDATA("doc", "/root/desc", "<html>...</html>");

节点不存在时 自动创建。同一 path 有多个兄弟节点时,只会更新第一个。

写属性 — SetXxxAttribute

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

读 — GetXxx

// 节点文本值
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");
 
// 属性读取(第 3 参数)
string lang = XML.GetString ("doc", "/root/name", "lang");
int    ver  = XML.GetInteger("doc", "/root/age",  "ver");

第 3 参数(attributeName)留空时取节点文本,填入时取该属性值。

子节点数 — GetCount

// /root/items 下所有子节点
int total = XML.GetCount("doc", "/root/items");
 
// /root/items 下名为 'item' 的子节点
int items = XML.GetCount("doc", "/root/items", "item");
 
for(i, 0, items - 1)
{
    string name = XML.GetString("doc", $"/root/items/item[{i}]/name");
    // ...
}

结果 / 错误处理

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

多次 SetXxx 后统一校验比较干净。

常用模式

系统设置保存 / 读取

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;
}

解析外部 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");

函数一览

分类	函数
生命周期	`Create` · `Parse` · `Load` · `Save` · `Remove` · `RemoveAll` · `Contains`
结果	`GetResult` · `GetErrorMessage` · `ResetResult`
节点	`AddNode` · `AddNodeCDATA` · `GetCount`
写文本	`SetString` · `SetInteger` · `SetDouble` · `SetBool` · `SetStringCDATA`
写属性	`SetStringAttribute` · `SetIntegerAttribute` · `SetDoubleAttribute` · `SetBoolAttribute`
读	`GetString` · `GetInteger` · `GetDouble` · `GetBool`(path + 可选 attributeName)