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 属性,无其他属性

注意：

XML 节点对象的 tagName 属性是用于表示 XML 标签名的保留属性，XML 定义的 tagName 属性将被忽略。
XML 节点对象的 localTagName 属于是用于表示去掉命名空间前缀的保留属性，XML 定义的 localTagName 属性将被忽略。
string.xml 在解析 XML 时自动忽略所有注释，不会将注释存为节点对象。
将 XML 节点对象用于 tostring 函数或连接操作符时会自动调用 outerXml 方法转换为字符串。

如何正确遍历 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(xmlText,elementTypes,optionalTags,inlineElements,preserveSpace) #

参数 @xmlText 指定 XML 文本。
其他参数仅预留用于 string.html，一般不需要指定。

string.xml 成员列表 #

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

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

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

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

string.xml.escape() #

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

string.xml.escape2(str,pattern) #

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

返回编码后的字符串。

string.xml.unescape() #

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

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.eachEle(查询参数表) #

eachQuery 方法的别名。
创建搜索并遍历标签元素（element）的迭代器。

stringXmlObject.eachQuery() #

返回对象:stringXmlObject

stringXmlObject.eachQuery(查询参数表) #

for ele in stringXmlObject.eachQuery(tagName="img"/*创建搜索并遍历元素的迭代器，内部调用 queryEles 方法。  

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

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

}

stringXmlObject.eachTag() #

返回对象:stringXmlObject

stringXmlObject.eachTag(标签名) #

for ele in stringXmlObject.eachTag(/*搜索并遍历匹配指定标签名（tagName）的元素（element）。  

参数 @1 忽略大小写并执行完全匹配（禁用模式匹配与部分匹配）*/){  

}

stringXmlObject.encoding #

源文本字符集

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

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

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

stringXmlObject.findChild(标签名) #

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

stringXmlObject.findChildren(标签名) #

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

stringXmlObject.getAttribute() #

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

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

获取指定 id 属性的标签元素（element）。
参数 @1 指定元素 id 属性的值,忽略大小写,支持模式匹配规则

stringXmlObject.getEleByTag() #

返回对象:stringXmlObject

stringXmlObject.getEleByTag(标签名) #

获取具有指定标签名（tagName）的首个标签元素（element）。
参数忽略大小写并执行完全匹配（禁用模式匹配与部分匹配）。

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

获取所有指定相同 name 属性的标签元素（element），返回值为数组。
即使找不到节点,也会返回空数组,
参数指定元素的 name 属性，忽略大小写，支持模式匹配规则

stringXmlObject.getElesByTag() #

返回对象:stringXmlObject

stringXmlObject.getElesByTag(标签名) #

获取具有指定标签名（tagName）的全部标签元素（element），返回值为数组。
即使找不到节点,此函数也会返回一个空数组。
参数忽略大小写并执行完全匹配（禁用模式匹配与部分匹配）。

stringXmlObject.getParent() #

获取父节点

stringXmlObject.innerText() #

返回节点内部文本或 CDATA 节点文本。
可作为属性直接返回文本，也可以作为方法调用（onwerCall）。
如果当前对象是 string.html 对象（继承自 string.xml ），则执行以下操作：

具有 tagName 的普通元素内文本去除首尾空白与换行，压缩中间的空白与换行为单个空格
除常见的内联元素以外的其他具有 tagName 的元素在首尾边缘添加换行
br 元素转换为单个换行

注意这个函数在处理时并不会事先移除 head,style,script 等元素

stringXmlObject.innerXml() #

将子节点转换 XML 代码（string.html 返回 HTML）。
可作为属性直接返回 XML / HTML，也可以作为方法调用（onwerCall）。
如果调用参数 @1 为 true 则缩进格式化返回的 XML 代码,
可选在参数 @2 中自定义换行符

stringXmlObject.localTagName #

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

stringXmlObject.outerXml() #

转换为 XML 代码（string.html 返回 HTML）。
可作为属性直接返回 XML / HTML，也可以作为方法调用（onwerCall）。
如果调用参数 @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() #

返回对象:stringXmlObject

stringXmlObject.queryEle(查询参数表) #

搜索标签元素（element），
此函数调用 queryEles 方法取第 1 个元素。
参数@1用一个表对象指定搜索条件。

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

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

stringXmlObject.queryEles #

搜索标签元素（element），该函数返回的是一个数组。
即使找不到节点，此函数也会返回一个空数组。

queryEle,eachQuery,eachEle 等方法都是调用 queryEles，
因此支持的相同的参数写法（参数可以是表也可以是简单 CSS 选择器）

stringXmlObject.queryEles() #

返回对象:stringXmlObject

stringXmlObject.queryEles(selectors) #

参数 @1 指定字符串时可支持有限的简单 CSS 选择器：
tagName, .class, [attr], #id ，例如 "div#id" 。
解析后的查询条件仍然会被被换为表参数，查询值可使用 aardio 模式匹配语法。

解析 selectors 参数的代码非常简单（只有几句代码），
因此不支持复杂语法以及多层级选择器

stringXmlObject.queryEles(查询参数表) #

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

stringXmlObject.remove() #

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

stringXmlObject.tagName #

节点标签名

Markdown 格式