Easy XML使用指南.doc

Easy XML使用指南文档信息项目名称Easy XML - 通用XML解析器需求编号文档编号作者曾臻创建日期2006-3-10版本号1.0审核人审核日期修改记录修改日期作者说明审核人1 引言Easy XML是为C+开发的XML解析器，它利用了C+的函数重载、函数对象等语言特性方便了程序员对XML解析代码的编写。本库不依赖于其它的XML解析器（如XML4C），实现上完全基于STL。2 指南2.1 例子2.1.1 XML的生成下面这段代码演示了怎样使用Easy XML来生成XML文档:#include pub_easy_xml.h#include #include #include void main() /create root element Element info(info,Element:ROOT|Element:COMPLEX); /create and assemble pet elements Element pet(pet); pet.setAttribute(species,mouse) (sex,female) (age,1) (name,Jerry) (weight,200g); info.addChild(pet); pet(species)=cat; pet(sex)=male; pet(age)=2; pet(name)=Tom; pet(weight)=2kg; info.addChild(pet); /create and assemble band elements Element band(band); band.setAttribute(name,BEYOND) (style,Art Rock) (members,5) (birthday,1983); Element member(member); member.addChild(name,Huang Jia Ju) (position,Voice,Lead Guitar); band.addChild(member); membername=Huang Jia Qiang; memberposition=Bass; band.addChild(member); info.addChild(band); /generate xml string string outXml; Parser parser; parseroutXml; /output to xml file ofstream of(info.xml); ofoutXml; of.close();生成的info.xml内容如下：2.1.2 XML的解析下面这段代码演示了怎样使用Easy XML来解析XML文档:#include pub_easy_xml.h#include #include #include void main() /input from xml file ifstream file(info.xml); string inXml; while(!file.eof() inXml+=file.get(); file.close(); /parse xml string Parser parser; Element info; parserinfo; /access element through operator coutThe first petname is infopet0(name)endl; coutThe first member of the first band is infoband0member0name.getValue()endl; /access element through reference Element& mouse=infopet1; coutThe second pets name is mouse(name)endl; /access element through index coutendlList of all pets:endl; Element& pet=infopet; for(long index=0;indexpet.getCount();index+) Element& e=petindex; coutNo.index+1endl; coutspecies: e(species)endl; coutname: e(name)endl; coutage: e(age)endl; coutsex: e(sex)endl; /access element through iterator coutendlList of all members of BEYOND:endl; Element& member=infoband0member; for(Element* pe=member.firstElement();member.hasMoreElements();pe=member.nextElement() Element& e=*pe; coutename.getValue() is playing eposition.getValue() in the bandendl; 运行结果如下：The first petname is JerryThe first member of the first band is Huang Jia JuThe second pets name is TomList of all pets:No.1species: mousename: Jerryage: 1sex: femaleNo.2species: catname: Tomage: 2sex: maleList of all members of BEYOND:Huang Jia Ju is playing Voice,Lead Guitar in the bandHuang Jia Qiang is playing Bass in the band3 详细介绍3.1 Element组件3.1.1 基本概念Element用来描述XML的元素，它可以分为复合元素和非复合元素。非复合元素属于XML结构树中“叶子”,用于存放文本信息；复合元素是任意元素的容器，不可以存放信息。如图，member就是复合元素，name和position都是非复合元素。XML元素还可以分为可重复元素和不可重复元素。可重复元素用来描述所有结构相同的同名元素，不可重复元素则只能描述独一无二的元素。如图，pet和member是可重复元素；info,name和position是不可重复元素；band是可重复元素，只不过它当前的重复度为1。还有一种XML元素叫根元素,它表示一个XML文档中唯一的那个顶层元素，根元素不能是可重复元素，可以是复合元素或非复合元素。如图，info就是根元素。XML元素还可以携带若干个属性信息。3.1.2 Element的创建在Element中用了下面这样一个枚举来表示元素类型：enum ElementTypeREPEATABLE=0x1,COMPLEX=0x2,SIMPLE=0x0,ROOT=0x4;Element的一个构造方法定义如下：explicit Element(const string& str_name,int n_type=COMPLEX);参数一表示元素名，参数二表示元素类型，缺省值是复合元素。元素类型可以通过运算符|进行组合，REPEATABLE不能和ROOT组合。例如,要构造一个前面提到的可重复的复合元素member可以这么写：Element e(member,Element:REPEATABLE|Element:COMPLEX);要构造一个复合顶层元素root可以这么写：Element e(info,Element:ROOT|Element:COMPLEX);3.1.3 Element的组装可以用过下面几种方式把一个元素组装到另一个复合元素中：1. 以Element的引用为参数加入已存在的子元素，子元素可以是任意类型member.addChild(name)(position);2. 以元素名和元素值（可缺省）为参数加入子元素，这将生成一个新的携带着给定值（或缺省）的非复合型的元素pet.addChild(species,dog) (name) /缺省元素值为空字符串 (age,2) /整型元素值将被装换成字符串 (sex,male)(weight,2kg);应该注意的是，当加入新的不可重复的元素时，如果容器中已经存在同名元素，则新元素将合并到容器中的同名元素中，如果容器中的同名元素是不可重复型的，则它将在合并后转变为可重复型的。3.1.4 Element的属性设置用以下几种方式可以设置元素的属性：1. 用setAttribute()pet.setAttribute(species,mouse) (sex,female) (age,1) (name,Jerry)(weight,200g);2. 通过重载操作符()pet(species)=cat;pet(sex)=male;pet(age)=2;pet(name)=Tom;pet(weight)=2kg;3.1.5 Element的访问3.1.5.1 访问元素值1. 通过getValue()/setValue()访问值Element element(element,Element:SIMPLE);string value=element.getValue();element.setValue(thit is value);element.setValue(12);/值将被转换为string2. 通过重载操作符=赋值，重载类型转换string()获取值Element element(element,Element:SIMPLE);string value=element;element=this is value;element=12;/值将被转换为string3.1.5.2 访问属性1. 通过getAttribute()访问属性string name=pet.getAttribute(name);2. 通过重载操作符()反问属性string name=pet(name);这两种方式的区别在于：前者获取的属性必须是存在的，否则会抛出异常；当后者获取的属性不存在时将会自动将其设为空字符串，并返回其引用。3.1.5.3 访问子元素1. 通过getChild()访问子元素Element& name=member.getChild(name);2. 通过重载操作符访问子元素Element& name=membername;这两种方式的区别在于：当前者获取的子元素不存在时，将返回一个空元素的引用（空元素的表示不存在的元素它的重复度为0，相当与集合中的空集）；当后者获取的元素不存在时，将会自动生成相应的子元素该元素的类型为SIMPLE,并返回其引用。于是我们可以像下面这样设置子元素:membername=Huang Jia Qiang;memberposition=Bass;3.1.5.4 访问可重复元素1. 通过elementAt()访问可重复元素Element& mouse=pet.elementAt(1);2. 通过重载操作符访问可重复元素Element& e=petindex;这两种方式没有区别，都表示从元素pet所描述的一系列的同名元素中获得某个元素的引用，当索引超出容器范围时会抛出异常。3. 通过迭代器遍历可重复元素，请注意firstElement(),hasMoreElements(),nextElement()的用法coutendlList of all members of BEYOND:endl;Element& member=infoband0member;for(Element* pe=member.firstElement();member.hasMoreElements();pe=member.nextElement()Element& e=*pe;coutename.getValue() is playing eposition.getValue() in the bandendl;这三种访问可重复元素的方法同样适用与简单元素。在这些情况中，可以把后者看作重复度为1的可重复元素。3.1.6 Element的其它功能l toProperties() 获取属性mapl newElement() 生成同名同构属性框架l growElement() 可重复元素的膨胀l shrink() 类型缩水l listAttributeName() 列出属性名l listChildrenName() 列出子元素名l gc() 垃圾收集（清除临时Element引用持有容器）待添加3.2 Parser组件3.2.1 用Parser生成XML有三个步骤：1. 创建Parser实例Parser parser;2. 读取Element，在Parser中生成目标XML字符串parseroutXml; /outXml是用于存放目标XMLstring的实例或者这么写parser.write(outXml);后两步可以写在同一行，如下所示parseroutXml;或parser.read