KissXml API

mOMo在學習KissXML時，教學文件還真的是少之又少，不簡單的在內地找到這篇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