string.xml 库模块帮助文档

使用说明

string.xml 简介

string.html 则基于 string.xml 可用于解析 HTML 。

string.xml 的原则是实现宽松与简化的解析器。对于 XML,HTML 中的笔误等努力尝试修正为正确的结构(例如属性值为空或没放在引号中,标记忘记关闭, 忘记写开始标识不配对,或大小写首尾不匹配 - 关于大小写会首先尝试严格配对,配对不成功会检测是否笔误并进行修正 )

注意此支持库的作用是简单解析,校验 XML 错误等不是此支持库的目标, 所以只会尽可能的解析出能解析的结果,尽可能宽容错误写法并试图自动修正。如果需要比较严谨的XML解析器 - 请使用标准库中的 web.msxml

string.xml 不会将属性值中的回车换行规范化为空格。

关于 XML 节点对象

string.xml 解析 XML 文档后会返回一个表对象。在这个表对象里所有的 XML 节点都是表对象。

这些 XML 节点对象可能具有 3 类元素：节点对象可能具有 3 类元素：

节点的属性存储为名值对成员，键值都是字符串。
所有相同标签名的子节点也存储为名值对成员，键为标签名，值为子节点数组。
节点对象的数组成员存储了全部子节点。

XML 节点对象分为 4 类：

拥有标签名（ tagName 属性）的普通 XML 元素
string.xml 总是虚拟出一个空的没有 tagName 属性的顶层根节点。
文本节点：使用 text 属性表示文本,无 tagName 属性,无其他属性。
CDATA节点：使用 cdata 属性表示数据, 无 tagName 属性,无其他属性

注意：

tagName 属性是用于表示 XML 标签名的保留属性，XML 定义的 tagName 属性将被忽略。
localTagName 属于是用于表示去掉命名空间前缀的保留属性，XML 定义的 localTagName 属性将被忽略。
string.xml 在解析 XML 时自动忽略所有注释，不会将注释存为节点对象。

如何正确遍历 XML 子节点

下面这样会遍历 XML 节点对象的全部属性（名值对成员）与子节点（数组成员）

for(k,v in parentNode){

}

下面这样仅遍历数组成员（也就是子节点数组）

for(i=1;#parentNode;1){
    var node = parentNode[i]

}

也可以使用节点的 eachChild 方法创建迭代器以遍历全部子节点

for(i,localTagName,childCount,xNode in parentNode.eachChild(tagName) ){
    /*
    参数中的 tagName 是可选的，忽略大小写且忽略目标节点的命名空间前缀。

    迭代变量：
    - i 为索引，
    - localTagName 为标签名（去掉命名空间前缀），
    - childCount 为当前子节点包含的子节点数目，
    - xNode 为当前子节点
    */
}

//查找第一个节点，参数 tagName 忽略大小写且忽略目标节点的命名空间前缀。 var first = parentNode.eachChild(tagName)

注意如果 eachChild 与 eachChild 方法的 tagName 参数本身指定命名空间前缀则不会被忽略。

遍历相同标签名的子节点：

for(i,node in parentNode[tagName]){
    //parentNode[tagName] 只包含数组成员，可以用 for in 直接遍历

}

string 成员列表 #

string.xml() #

返回对象:stringXmlObject

string.xml(xml字符串) #

创建 XML 对象。
此对象不支持 table.tostring , console.dump 函数，不能跨线程传递。

严格的校验XML语法正确性不是本模块的义务和目标,
所以,此解析器尽可能兼容错误,兼容了HTML,SGML的部分规则:
1、不要求存在根标签
2、尝试自动修正不配对的标记
3、在有必要的时候尝试忽略大小写

string.xml 成员列表 #

简单 XML 解析器。
严格的校验 XML 语法正确性不是本模块的设计目标，
所以此解析器尽可能兼容错误，兼容了 HTML，SGML 的部分规则:

不要求存在根标签
尝试自动修正不配对的标记
在有必要的时候尝试忽略大小写。

string.xml.escape() #

将字符串中的 < > " ' & 等 XML 标记字符编码为实体字符（entity）。
如果参数为非 null 值则返回转换后的字符串。
参数只能是 null 或字符串、buffer

string.xml.ncrDecode() #

NCR 编码字符、HTML 实体字符还原为 UTF8 文本。
此函数默认只会解码 XML 基本命名实体与常用 HTML 命名实体字符。
如果提前导入 web.entities 库则支持解码全部 HTML 命名实体（实体必须以 ; 号结尾）。

string.xml.ncrEncode(str,pattern) #

将字符串参数 @str 中以 @pattern 指定模式串所匹配的字符进行 NCR 编码。
参数 @pattern 可用模式匹配语法指定要编码的字符，省略则默认为 :|[\<\>\&"']，也就是仅编码非 ACSII 字符与 <>&"' 这 5 个基本实体字符。

返回编码后的字符串。

stringXmlObject 成员列表 #

stringXmlObject.* #

属性或子节点数组

返回对象:stringXmlObject

stringXmlObject.codepage #

源文本代码页

stringXmlObject.eachAttribute() #

for( k,v in stringXmlObject.eachAttribute() ){
    /*遍历节点所有属性,k 为属性名,v 为属性值*/
}

stringXmlObject.eachChild() #

返回对象:stringXmlObject

stringXmlObject.eachChild(tagName) #

for(i,localTagName,childCount,xNode in stringXmlObject.eachChild() ){  
    /*  
    可选参数 @tagName 指定子节点标签名（忽略大小写，忽略目标节点命名空间前缀）。  

    迭代变量：  
    - i 为索引，  
    - localTagName 为标签名（去掉命名空间前缀），  
    - childCount 为当前子节点包含的子节点数目，  
    - xNode 为当前子节点  
    */  
}

stringXmlObject.eachQuery(查询参数表) #

for ele in stringXmlObject.eachQuery(tagName="img"/*搜索并遍历节点对象,  

参数@1指定一个表对象，  
该参数表可包含一个或多个键值，用于匹配节点的属性值,  
可使用tagName属性指定节点的标签名,  
可使用parent属性指定开始查询节点的父节点，parent可以是ID或者节点对象。  
属性值使用 string.cmpMatch函数进行比对，  
等价于调用string.cmp函数进行忽略大小写的比较,  
并且在失败后调用 string.match函数使用模式匹配语法进行比较  

注意在匹配节点属性时有几个例外：  
parent属性不使用模式匹配进行比对，  
tagName,id,name属性如果匹配值不含标点则使用忽略大小写的完全比对（禁用模式匹配和部分匹配）*/){  

}  

[返回对象:stringXmlObject](#stringXmlObject)

stringXmlObject.encoding #

源文本字符集

stringXmlObject.enumNodes(枚举函数,搜索标签名) #

stringXmlObject.enumNodes(   
    function(parentElement,index,tagName,childCount,xNode){   

    },/*可选指定要查找的标签名（tagName），忽略大小写  
回调函数返回非 null 值时退出枚举，并返回回调函数的所有返回值*/  
)

stringXmlObject.findChild(tagName) #

查找第一个匹配参数 @1 标签名的节点。
匹配时忽略大小写，如果参数没有指定命名空间则忽略目标节点的命名空间。

stringXmlObject.findChildren(tagName) #

查找所有匹配参数 @1 标签名的节点，返回数组。
匹配时忽略大小写，如果参数没有指定命名空间则忽略目标节点的命名空间。

stringXmlObject.getAttribute() #

取属性值,
参数中指定属性名字,属性名忽略大小写,
如果通过下标或成员操作符直接获取属性时区分大小写的

stringXmlObject.getEle("字符串参数") #

获取指定id的节点对象,
参数指定节点id,忽略大小写,支持模式匹配规则

stringXmlObject.getEles("字符串参数") #

获取所有指定相同name的节点对象,返回数组,
即使找不到节点,也会返回空数组,
参数指定节点name,忽略大小写,支持模式匹配规则

stringXmlObject.getParent() #

获取父节点

stringXmlObject.innerText() #

返回节点内部文本或CDATA文本

stringXmlObject.innerXml() #

将子节点转换XML文本,
如果参数@1为true则缩进格式化返回的xml文本,
可选在参数@2中自定义换行符

stringXmlObject.localTagName #

保留原始大小写（与 tagName 一致，只是去掉了命名空间前缀）

stringXmlObject.outerXml() #

转换为XML文本,
如果参数@1为true则缩进格式化返回的xml文本,
可选在参数@2中自定义换行符

stringXmlObject.pushElement() #

返回对象:stringXmlObject

stringXmlObject.pushElement(节点属性表) #

stringXmlObject.pushElement(  
    tagName =   
    cdata =   
    text = /*注意text,cdata,tagName三个属性只能指定一个,  
可选使用参数@2指定新增节点的位置,不指定则添加到子节点数组尾部,  
返回新增的节点对象*/  
)

stringXmlObject.pushXml() #

将字符串参数@1中指定的XML添加到当前节点的子节点,
可选用参数@2指定新节点的位置,不指定则添加到子节点数组尾部,
返回新增XML中最后一个根节点

返回对象:stringXmlObject

stringXmlObject.queryEle(查询参数表) #

搜索节点对象,参数@1指定一个表对象，

该参数表可包含一个或多个键值，用于匹配节点的属性值,
可使用tagName属性指定节点的标签名,
可使用parent属性指定开始查询节点的父节点，parent可以是ID或者节点对象。
属性值使用 string.cmpMatch函数进行比对，
等价于调用string.cmp函数进行忽略大小写的比较,
并且在失败后调用 string.match函数使用模式匹配语法进行比较

注意在匹配节点属性时有几个例外：
parent属性不使用模式匹配进行比对，
tagName,id,name属性如果匹配值不含标点则使用忽略大小写的完全比对（禁用模式匹配和部分匹配）

stringXmlObject.queryEles( 查询参数表) #

搜索节点对象,该函数返回的是一个数组,
即使找不到节点,此函数也会返回一个空数组,

参数@1指定一个表对象，
该参数表可包含一个或多个键值，用于匹配节点的属性值,
可使用tagName属性指定节点的标签名,
可使用parent属性指定开始查询节点的父节点，parent可以是ID或者节点对象。
属性值使用 string.cmpMatch函数进行比对，
等价于调用string.cmp函数进行忽略大小写的比较,
并且在失败后调用 string.match函数使用模式匹配语法进行比较

stringXmlObject.queryEles() #

返回对象:stringXmlObject

stringXmlObject.remove() #

如果存在父节点,在父节点中移除此节点

stringXmlObject.tagName #

节点标签名

Markdown 格式