KissXml API

KissXml是iPhone平台目前比较好的xml解析&操作的框架，尤其是他集成了XPath功能，但是网上没有成型的api，就连KissXml自己也没有出过完整的api。

为了方便大家快速入门、使用KissXML，就勉强做了这个所谓的API，如有谬误，敬请斧正。

==========================================================

DDXMLNode（结点类，所有结点类的父类）

//创建元素结点的方法
+ (id)elementWithName:(NSString *)name;
+ (id)elementWithName:(NSString *)name URI:(NSString *)URI;
+ (id)elementWithName:(NSString *)name stringValue:(NSString *)string;
+ (id)elementWithName:(NSString *)name children:(NSArray *)children attributes:(NSArray *)attributes;

//创建属性结点
+ (id)attributeWithName:(NSString *)name stringValue:(NSString *)stringValue;
+ (id)attributeWithName:(NSString *)name URI:(NSString *)URI stringValue:(NSString *)stringValue;
//创建一个命名空间
+ (id)namespaceWithName:(NSString *)name stringValue:(NSString *)stringValue;
//创建处理指令，形如<?name stringValue?>
+ (id)processingInstructionWithName:(NSString *)name stringValue:(NSString *)stringValue;
//创建一个注释结点
+ (id)commentWithStringValue:(NSString *)stringValue;
//创建一个textValue结点
+ (id)textWithStringValue:(NSString *)stringValue;

#pragma mark ———————— Properties —————————
//返回结点类型
- (DDXMLNodeKind)kind;
//设置结点名
- (void)setName:(NSString *)name;
//获得结点名
- (NSString *)name;

//设置结点的stringValue，Element设置之后其子结点尽失，只剩下stringValue
- (void)setStringValue:(NSString *)string;
//获得stringValue
- (NSString *)stringValue;

#pragma mark ———————— Tree Navigation ——————————
//返回当前结点在兄弟结点中的index
- (NSUInteger)index;
//返回当前结点在树中的level
- (NSUInteger)level;
//获得所在树的根结点
- (DDXMLDocument *)rootDocument;
- (DDXMLNode *)parent;//获得父结点
- (NSUInteger)childCount;//获取子结点个数（所有的node子类）
- (NSArray *)children;//子结点列表
- (DDXMLNode *)childAtIndex:(NSUInteger)index;//指定index的子结点列表
- (DDXMLNode *)previousSibling;//上一个兄弟结点
- (DDXMLNode *)nextSibling;//下一个兄弟结点
- (DDXMLNode *)previousNode;//深度遍历顺序的上一个结点
- (DDXMLNode *)nextNode;//深度遍历顺序的下一个结点
- (void)detach;//当前结点所带子树，从父树上分离下来
- (NSString *)XPath;//当前结点所在树的XPath,[n]表示是（深度遍历顺序中）连续同名结点的第几个

#pragma mark ———————— QNames —————————
- (NSString *)localName;//返回去掉第一个冒号和之前prefix之后的localName
- (NSString *)prefix;//返回去掉第一个冒号和之后localName之后的prefix
- (void)setURI:(NSString *)URI;//设置URI，形如<tag xmlns=”URIString” …> 注：只在attribute中设置xmlns属性之后，用URI的get方法是读不到的
- (NSString *)URI;//URI的get方法
+ (NSString *)localNameForName:(NSString *)name;//处理name获得localName的方法
+ (NSString *)prefixForName:(NSString *)name;//处理name获得prefixForName的方法

#pragma mark ———————— Output —————————
//description & XMLString相同，等价于[XMLStringWithOptions:0]
- (NSString *)description;
- (NSString *)XMLString;
//options>=0一行输出，且空标签不合并；option<0，合并空标签例如<eptTag/>,且缩进输出。
- (NSString *)XMLStringWithOptions:(NSUInteger)options;

#pragma mark ———————— XPath/XQuery —————————
//获得对应XPath的结点，Document和Element有不同表示（其实一样，都是从其子结点开始path）
- (NSArray *)nodesForXPath:(NSString *)xpath error:(NSError **)error;

==========================================================

DDXMLDocument（DOC根结点类）

//初始化
- (id)initWithXMLString:(NSString *)string options:(NSUInteger)mask error:(NSError **)error;//用一段xml代码创建一颗dom树，mask无用，0即可。
- (id)initWithData:(NSData *)data options:(NSUInteger)mask error:(NSError **)error;//用一段xml代码创建一颗dom树，mask无用，0即可，上一个就是调用此法

- (DDXMLElement *)rootElement;//获得根元素Element

- (NSData *)XMLData;//获得包含XMLString的NSData对象
- (NSData *)XMLDataWithOptions:(NSUInteger)options;//获得包含XMLString的NSData对象,option>=0:一行，不合并空元素；option<0:合并，缩进；

==========================================================

DDXMLElement（元素结点类）

#pragma mark ————————— Init —————————
- (id)initWithName:(NSString *)name;//创建名为name的Element
- (id)initWithName:(NSString *)name URI:(NSString *)URI;//创建名为name，且URI为URIString的Element
- (id)initWithName:(NSString *)name stringValue:(NSString *)string;//创建名为name且只有一个textVaule结点的Element
- (id)initWithXMLString:(NSString *)string error:(NSError **)error;//用一段xml子树代码创建一个Element对象

#pragma mark —————————— Elements by name ——————————
- (NSArray *)elementsForName:(NSString *)name;//按照name获取Element列表
- (NSArray *)elementsForLocalName:(NSString *)localName URI:(NSString *)URI;//按照LocalName和URI获取Element列表

#pragma mark —————————— Attributes ——————————
- (void)addAttribute:(DDXMLNode *)attribute;//在属性列表最后添加一个信属性
- (void)removeAttributeForName:(NSString *)name;//移除指定属性（属性列表里不存在同名的属性，诸如名如xmlns等URI其实不在属性列表里，虽然显示在属性的位置上）
- (void)setAttributes:(NSArray *)attributes;//为当前Element设置属性列表
- (DDXMLNode *)attributeForName:(NSString *)name;//获得指定属性
- (NSArray *)attributes;//属性列表的get方法

#pragma mark —————————— Namespaces ——————————
//命名空间，形如：<tag xmlns:nsName=”nsValue”>
- (void)addNamespace:(DDXMLNode *)aNamespace;//为当前Element一个添加命名空间
- (void)removeNamespaceForPrefix:(NSString *)name;//移除指定的命名空间
- (void)setNamespaces:(NSArray *)namespaces;//设置命名空间列表
- (NSArray *)namespaces;//命名空间列表
- (DDXMLNode *)namespaceForPrefix:(NSString *)prefix;//根据prefix（即nsName）获得namespace
- (DDXMLNode *)resolveNamespaceForName:(NSString *)name;//获得指定标签名所属的namespace，例如:<teach:number …>,将此结点的name传入即可获得所属的namespace对象
- (NSString *)resolvePrefixForNamespaceURI:(NSString *)namespaceURI;//获得指定URI值的namespace的nsName

#pragma mark —————————— Children ——————————
- (void)insertChild:(DDXMLNode *)child atIndex:(NSUInteger)index;//在children（子结点列表）中插入子结点
- (void)removeChildAtIndex:(NSUInteger)index;//移除指定index的子结点
- (void)setChildren:(NSArray *)children;//设置子结点列表
- (void)addChild:(DDXMLNode *)child;//子结点列表的get方法

#pragma mark —————————— Extra——————————
+ (DDXMLElement *)elementWithName:(NSString *)name xmlns:(NSString *)ns;//创建一个结点,形如：<name xmlns=”ns”/>
- (DDXMLElement *)elementForName:(NSString *)name;//返回所有子元素中第一个名为name的element
- (DDXMLElement *)elementForName:(NSString *)name xmlns:(NSString *)xmlns;//返回所有子元素中第一个名为name且xmlns为xmlns值的element

//xmlns值的set和get方法
- (void)setXmlns:(NSString *)ns;
- (NSString *)xmlns;

- (void)addAttributeWithName:(NSString *)name stringValue:(NSString *)string;//为当前结点添加属性&属性值
- (NSDictionary *)attributesAsDictionary;//返回属性字典列表

==========================================================

其他私有的方法（基本用不到，主要是内部调用，有兴趣的自己试下）

@interface DDXMLNode (PrivateAPI)

+ (id)nodeWithPrimitive:(xmlKindPtr)nodePtr;
- (id)initWithCheckedPrimitive:(xmlKindPtr)nodePtr;
- (id)initWithUncheckedPrimitive:(xmlKindPtr)nodePtr;

+ (id)nodeWithPrimitive:(xmlKindPtr)nodePtr nsParent:(xmlNodePtr)parentPtr;
- (id)initWithCheckedPrimitive:(xmlKindPtr)nodePtr nsParent:(xmlNodePtr)parentPtr;
- (id)initWithUncheckedPrimitive:(xmlKindPtr)nodePtr nsParent:(xmlNodePtr)parentPtr;

+ (BOOL)isXmlAttrPtr:(xmlKindPtr)kindPtr;
- (BOOL)isXmlAttrPtr;

+ (BOOL)isXmlNodePtr:(xmlKindPtr)kindPtr;
- (BOOL)isXmlNodePtr;

+ (BOOL)isXmlDocPtr:(xmlKindPtr)kindPtr;
- (BOOL)isXmlDocPtr;

+ (BOOL)isXmlDtdPtr:(xmlKindPtr)kindPtr;
- (BOOL)isXmlDtdPtr;

+ (BOOL)isXmlNsPtr:(xmlKindPtr)kindPtr;
- (BOOL)isXmlNsPtr;

- (BOOL)hasParent;//是否有父结点

+ (void)recursiveStripDocPointersFromNode:(xmlNodePtr)node;

+ (void)detachAttribute:(xmlAttrPtr)attr fromNode:(xmlNodePtr)node;
+ (void)removeAttribute:(xmlAttrPtr)attr fromNode:(xmlNodePtr)node;
+ (void)removeAllAttributesFromNode:(xmlNodePtr)node;

+ (void)detachNamespace:(xmlNsPtr)ns fromNode:(xmlNodePtr)node;
+ (void)removeNamespace:(xmlNsPtr)ns fromNode:(xmlNodePtr)node;
+ (void)removeAllNamespacesFromNode:(xmlNodePtr)node;

+ (void)detachChild:(xmlNodePtr)child fromNode:(xmlNodePtr)node;
+ (void)removeChild:(xmlNodePtr)child fromNode:(xmlNodePtr)node;
+ (void)removeAllChildrenFromNode:(xmlNodePtr)node;

+ (void)removeAllChildrenFromDoc:(xmlDocPtr)doc;

- (void)nodeRetain;
- (void)nodeRelease;

+ (NSError *)lastError;

@end

@interface DDXMLElement (PrivateAPI)

+ (id)nodeWithPrimitive:(xmlKindPtr)nodePtr;
- (id)initWithCheckedPrimitive:(xmlKindPtr)nodePtr;
- (id)initWithUncheckedPrimitive:(xmlKindPtr)nodePtr;

- (NSArray *)elementsWithName:(NSString *)name uri:(NSString *)URI;

+ (DDXMLNode *)resolveNamespaceForPrefix:(NSString *)prefix atNode:(xmlNodePtr)nodePtr;
+ (NSString *)resolvePrefixForURI:(NSString *)uri atNode:(xmlNodePtr)nodePtr;

@end

@interface DDXMLDocument (PrivateAPI)

+ (id)nodeWithPrimitive:(xmlKindPtr)nodePtr;
- (id)initWithCheckedPrimitive:(xmlKindPtr)nodePtr;
- (id)initWithUncheckedPrimitive:(xmlKindPtr)nodePtr;

@end

如果不了解KissXml的配置和使用方法，请参见：http://pimacun.72pines.com/2010/12/31/kissxml/