Framework/XMLTree.h

   1 // A slightly modified version of Robert Harder's XMLTree, which he released into the public domain.
   2
   3
   4 #import <Cocoa/Cocoa.h>
   5
   6 /*!
   7  @header XMLTree
   8  XMLTree provides an Objective-C wrapper for Apple's built-in C-language
   9  XML parser and manipulation functions.
  10  */
  11
  12
  13 /*!
  14  @class XMLTree
  15  @abstract Wraps some C-level functions from Apple for XML manipulation.
  16  @discussion
  17  <p>
  18  XMLTree provides an Objective-C wrapper for Apple's built-in C-language
  19  XML parser and manipulation functions.
  20  At the moment it only supports basic element and attribute information.
  21  However Apple's XML parser supports processing instructions, CDATA,
  22  and some other things I've never seen, so I'll add support for these
  23  as I go along.
  24  </p>
  25  <p>
  26  I'm releasing this code into the Public Domain, so you can include it
  27  with your software regardless of the license you use. If you make any
  28  useful additions or bug fixes (especially with retain/release), we
  29  would all appreciate it if you would let me know so we can give the
  30  changes to everyone else too.
  31  </p>
  32  <p>Author: Robert Harder, rob -at- iharder.net</p>
  33  <p>version: 0.1</p>
  34  */
  35 @interface XMLTree : NSObject
  36 {
  37     CFXMLTreeRef _tree;
  38     CFXMLNodeRef _node;
  39
  40     NSString    *_lastUnknownSelector;
  41         NSString *_namespacePrefix;
  42 }
  43
  44
  45 /*!
  46  @method dealloc
  47  @abstract Be a good citizen and clean up after ourselves.
  48  */
  49 -(void)dealloc;
  50
  51
  52 /*!
  53  @method treeWithURL:
  54  @abstract Creates an autoreleased XMLTree with the contents of <var>url</var>.
  55  @discussion
  56  Creates an autoreleased XMLTree with the contents of <var>url</var> or
  57  <tt>nil</tt> if there was an error.
  58  Of course the URL can be pointing to a file or a URL on the internet
  59  such as a GET command to a SOAP application.
  60  @param url The <tt>NSURL</tt> pointing to your XML data.
  61  @result An autoreleased <tt>XMLTree</tt> with the contents
  62  of <var>url</var> or <tt>nil</tt> if there was a problem.
  63  */
  64 +(XMLTree *)treeWithURL:(NSURL *)url;
  65
  66
  67
  68
  69 /*!
  70  @method init
  71  @abstract Initializes and returns an <tt>XMLTree</tt>.
  72  @discussion
  73   Initializes and returns an <tt>XMLTree</tt> (with a retain count of 1).
  74   There isn't much point to creating an <tt>XMLTree</tt> this way until
  75   I add methods for manuallying adding XML nodes to the tree.
  76  @result An <tt>XMLTree</tt> (with a retain count of 1).
  77  */
  78 -(XMLTree *)init;
  79
  80
  81
  82
  83 /*!
  84  @method initWithURL:
  85  @abstract Initializes and returns an <tt>XMLTree</tt>
  86  with the contents of <var>url</var>.
  87  @discussion
  88   Initializes and returns an <tt>XMLTree</tt> (with a retain count of 1)
  89   with the XML contents of <var>url</var> or <tt>nil</tt> if there is an error.
  90  @param url The <tt>NSURL</tt> pointing to your XML data.
  91  @result An <tt>XMLTree</tt> with a retain count of 1.
  92  */
  93 -(XMLTree *)initWithURL:(NSURL *)url;
  94
  95
  96
  97
  98
  99
 100 /*!
 101  @method initWithCFXMLTreeRef:
 102  @abstract Initializes and returns an <tt>XMLTree</tt>
 103  with the internal data represented by <var>ref</var>.
 104  @discussion
 105   Initializes and returns an <tt>XMLTree</tt> (with a retain count of 1)
 106   with the internal <tt>CFXMLTreeRef</tt> data represented by <var>ref</var>.
 107   You probably won't ever need to call this yourself, but I call it internally
 108   and may move it to a Private API in the XMLTree.m file later.
 109  @param ref The <tt>CFXMLTreeRef</tt> containing the XML data.
 110  @result An <tt>XMLTree</tt> with a retain count of 1.
 111  */
 112 -(XMLTree *)initWithCFXMLTreeRef:(CFXMLTreeRef)ref;
 113
 114
 115
 116     /*!
 117      @method initWithData:withResolvingURL:
 118      @abstract Initializes and returns an <tt>XMLTree</tt>
 119      with the XML data stored in <var>inData</var> and
 120      an optional URL used to resolve references.
 121      @discussion
 122      Initializes and returns an <tt>XMLTree</tt> (with a retain count of 1)
 123      with the internal <tt>NSData</tt> data represented by <var>inData</var>.
 124      The <tt>NSURL</tt> url is optional. If provided, Apple's XML parser
 125      may use it to resolve links in the XML code.
 126      @param inData The <tt>NSData</tt> containing the XML data.
 127      @param url The <tt>NSURL</tt> for resolving links.
 128      @result An <tt>XMLTree</tt> with a retain count of 1.
 129      */
 130 - (XMLTree *)initWithData:(NSData *)inData withResolvingURL:(NSURL *)url;
 131
 132
 133     /*!
 134      @method initWithData:
 135      @abstract Initializes and returns an <tt>XMLTree</tt>
 136      with the XML data stored in <var>inData</var>.
 137      @discussion
 138      Initializes and returns an <tt>XMLTree</tt> (with a retain count of 1)
 139      with the internal <tt>NSData</tt> data represented by <var>inData</var>.
 140      @param inData The <tt>NSData</tt> containing the XML data.
 141      @result An <tt>XMLTree</tt> with a retain count of 1.
 142      */
 143 - (XMLTree *)initWithData:(NSData *)inData;
 144
 145
 146 /* ********  A B O U T   S E L F ******** */
 147
 148
 149 /*!
 150  @method name
 151  @abstract Returns the name of the root node in the tree.
 152  @discussion
 153  Returns the name of the root node in the tree or <tt>nil</tt>
 154  if a name is not appropriate in the current context such as
 155  if the "tree" is actually a single XML Processing Instruction node.
 156  @result The name of the root node in the tree..
 157  */
 158 -(NSString *)name;
 159
 160
 161 /*!
 162  @method xml
 163  @abstract Returns the <tt>XMLTree</tt> in an XML-looking form.
 164  @discussion
 165  Returns the <tt>XMLTree</tt> in an XML-looking form as performed
 166  by Apple's own <tt>CFXMLTreeCreateXMLData(...)</tt> method.
 167  @result The <tt>XMLTree</tt> in an XML-looking form.
 168  */
 169 -(NSString *)xml;
 170
 171
 172
 173 /*!
 174  @method description
 175  @abstract Returns a textual representation of the <tt>XMLTree</tt>.
 176  @discussion
 177  <p>
 178   Returns a textual representation of the <tt>XMLTree</tt>.
 179   The way the tree is interpreted depends on what kind of root
 180   node is represented by the receiver.
 181  </p>
 182  <p>
 183   Listed below are the actions this method takes depending
 184   on the type of node this is.
 185  </p>
 186  <table border="1">
 187    <thead>
 188     <tr>
 189      <th>Node Type</th><th>CFXMLNodeTypeCode</th><th>Action</th>
 190     </tr>
 191    </thead>
 192    <tbody>
 193     <tr>
 194      <td>Document</td><td>kCFXMLNodeTypeDocument</td>
 195      <td rowspan="2" valign="top">
 196         Recursively descends XML document piecing together
 197         the Text and CDATA nodes that are encountered.
 198         You can think of this as returning the plaintext
 199         version of the XML data, that is, with all tags removed.
 200     </td>
 201     </tr>
 202     <td>Element</td><td>kCFXMLNodeTypeElement</td>
 203    </tr>
 204    <tr>
 205     <td>Attribute</td><td>kCFXMLNodeTypeAttribute</td>
 206     <td rowspan="13" valign="top">
 207         Default action: Whatever is returned by Apple's
 208         <tt>CFXMLNodeGetString(...)</tt> method.
 209     </td>
 210    </tr>
 211     <tr><td>Processing Instruction</td><td>kCFXMLNodeTypeProcessingInstruction</td></tr>
 212     <tr><td>Comment</td><td>kCFXMLNodeTypeComment</td></tr>
 213     <tr><td>Text</td><td>kCFXMLNodeTypeText</td></tr>
 214     <tr><td>CDATA Section</td><td>kCFXMLNodeTypeCDATASection</td></tr>
 215     <tr><td>Document Fragment</td><td>kCFXMLNodeTypeDocumentFragment</td></tr>
 216     <tr><td>Entity</td><td>kCFXMLNodeTypeEntity</td></tr>
 217     <tr><td>Entity Reference</td><td>kCFXMLNodeTypeEntityReference</td></tr>
 218     <tr><td>Document Type</td><td>kCFXMLNodeTypeDocumentType</td></tr>
 219     <tr><td>Whitespace</td><td>kCFXMLNodeTypeWhitespace</td></tr>
 220     <tr><td>Notation Element</td><td>kCFXMLNodeTypeNotation</td></tr>
 221     <tr><td>Element Type Declaration</td><td>kCFXMLNodeTypeElementTypeDeclaration</td></tr>
 222     <tr><td>Attribute List Declaration</td><td>kCFXMLNodeTypeAttributeListDeclaration</td></tr>
 223    </tr>
 224   </tbody>
 225  </table>
 226
 227  @result A textual representation of the <tt>XMLTree</tt>.
 228  */
 229 -(NSString *)description;
 230
 231
 232 /*!
 233  @method attributeNamed:
 234  @abstract Returns the attribute named <var>name</var>.
 235  @discussion
 236   Returns the attribute named <var>name</var> or
 237   <tt>nil</tt> if no such attribute is found or
 238   the node is not an Element node.
 239  @param name The name of the attribute to return.
 240  @result The attribute named <var>name</var>.
 241  */
 242 -(NSString *)attributeNamed:(NSString *)name;
 243
 244
 245
 246 /*!
 247  @method attributes
 248  @abstract Returns a dictionary of all the attributes.
 249  @discussion
 250   Returns a dictionary of all the attributes in the node
 251   or <tt>nil</tt> if the node is not an Element node.
 252  @result A dictionary of all the attributes.
 253  */
 254 -(NSDictionary *)attributes;
 255
 256
 257 /*!
 258  @method type
 259  @abstract Returns the type of node this is.
 260  @discussion
 261   Returns the type of node this is as defined by Apple's
 262   <tt>enum</tt>:
 263   <pre>
 264  enum CFXMLNodeTypeCode {
 265      kCFXMLNodeTypeDocument = 1,
 266      kCFXMLNodeTypeElement = 2,
 267      kCFXMLNodeTypeAttribute = 3,
 268      kCFXMLNodeTypeProcessingInstruction = 4,
 269      kCFXMLNodeTypeComment = 5,
 270      kCFXMLNodeTypeText = 6,
 271      kCFXMLNodeTypeCDATASection = 7,
 272      kCFXMLNodeTypeDocumentFragment = 8,
 273      kCFXMLNodeTypeEntity = 9,
 274      kCFXMLNodeTypeEntityReference = 10,
 275      kCFXMLNodeTypeDocumentType = 11,
 276      kCFXMLNodeTypeWhitespace = 12,
 277      kCFXMLNodeTypeNotation = 13,
 278      kCFXMLNodeTypeElementTypeDeclaration = 14,
 279      kCFXMLNodeTypeAttributeListDeclaration = 15
 280  };
 281  </pre>
 282  @result The type of node this is.
 283  */
 284 -(CFXMLNodeTypeCode)type;
 285
 286
 287
 288
 289 /* ********  A B O U T   P A R E N T  ******** */
 290
 291
 292
 293 /*!
 294  @method parent
 295  @abstract Returns the parent of the tree.
 296  @discussion
 297   Returns the parent of the tree or <tt>nil</tt>
 298   if the parent does not exist.
 299  @result The tree's parent.
 300  */
 301 -(XMLTree *)parent;
 302
 303
 304
 305 /* ********  A B O U T   C H I L D R E N  ******** */
 306
 307
 308
 309
 310     /*!
 311     @method xpath:
 312      @abstract Returns the value indicated by the xpath.
 313      @discussion
 314      Returns the value indicated by the xpath.
 315      Only basic xpath values are supported at this time.
 316      Basically it supports accessing elements and attributes.
 317      @param xpath The xpath to evaluate
 318      @result The XMLTree or NSString of the result.
 319      */
 320 -(id)xpath:(NSString *)xpath;
 321
 322
 323
 324 /*!
 325  @method childAtIndex:
 326  @abstract Returns the child at the given index.
 327  @discussion
 328   Returns the child at the given index or <tt>nil</tt>
 329   if no such child exists or it doesn't make sense
 330   to have children (such as a Processing Instruction node).
 331  @param index The index of the child to get.
 332  @result The child at <var>index</var>.
 333  */
 334 -(XMLTree *)childAtIndex:(int)index;
 335
 336 -(NSArray *)childrenNamed:(NSString *)name;
 337
 338 - (XMLTree *)childWithLocalName:(NSString *)localName prefix:(NSString *)prefix;
 339 - (NSArray *)childrenWithLocalName:(NSString *)localName prefix:(NSString *)prefix;
 340
 341
 342 /*!
 343  @method childNamed:
 344  @abstract Returns the first child named <var>name</var>.
 345  @discussion
 346  Returns the first child named <var>name</var> or <tt>nil</tt>
 347  if no such child exists or it doesn't make sense
 348  to have children (such as a Processing Instruction node).
 349  @param name The name of the child.
 350  @result The child named <var>name</var>.
 351 */
 352 -(XMLTree *)childNamed:(NSString *)name;
 353
 354
 355     /*!
 356     @method childNamed:withAttribute:equalTo:
 357      @abstract Returns the first child named <var>name</var>
 358       that has a matching attribute.
 359      @discussion
 360      Returns the first child named <var>name</var> with
 361      attribute <var>attrName</var> equal to <var>attrVal</var>
 362      or <tt>nil</tt> if no such child exists or it doesn't make sense
 363      to have children (such as a Processing Instruction node).
 364      @param name The name of the child.
 365      @param attrName The name of the attribute to look up.
 366      @param attrVal  The attribute value to match.
 367      @result The matching child.
 368      */
 369 -(XMLTree *)childNamed:(NSString *)name
 370          withAttribute:(NSString *)attrName
 371                equalTo:(NSString *)attrVal;
 372
 373
 374 /*!
 375  @method descendentNamed:
 376  @abstract Returns the first descendent named <var>name</var>.
 377  @discussion
 378   Returns the descendent named <var>name</var> or <tt>nil</tt>
 379   if no such descendent exists or it doesn't make sense
 380   to have descendents (such as a Processing Instruction node).
 381   This is a depth-first search.
 382  @param name The name of the child.
 383  @result The child named <var>name</var>.
 384 */
 385 -(XMLTree *)descendentNamed:(NSString *)name;
 386
 387
 388 /*!
 389  @method count
 390  @abstract Returns the number of children in the tree.
 391  @discussion
 392   Returns the number of children in the tree or <tt>-1</tt>
 393   if there is no valid tree contained within (like if you
 394   tried to create an <tt>XMLTree</tt> with <tt>init</tt>).
 395  @result The number of children in the tree.
 396  */
 397 -(int)count;
 398
 399
 400 @end
 401
 402 /*!
 403  @function XMLTreeDescription
 404  @abstract Used internally to recursively generate tree descriptions.
 405  @discussion
 406   Used internally to recursively generate tree descriptions.
 407   The returned string is just the mutable string that was passed in.
 408   It's retain count is unchanged.
 409  @param descr The mutable string that will have descriptions appended to it.
 410  @param tree The tree from which to make a description.
 411  @result A description of <var>tree</var>.
 412   It is the <var>descr</var> that was passed in.
 413  */
 414 CFStringRef XMLTreeDescription( CFMutableStringRef descr, CFXMLTreeRef tree );
 415
 416
 417
 418 /*!
 419 @function XMLTreeDescendentNamed
 420  @abstract Used internally to recursively search for a descendent.
 421  @discussion
 422   Used internally to recursively search for a descendent.
 423   The tree that is returned, if any, has a retain count of one more
 424   than it ought (it cannot be autoreleased, so far as I know), so
 425   you are responsible for releasing it, whether or not you retain it.
 426  @param name The name of the descendent to search for.
 427  @param tree The tree in which to recursively search.
 428  @result The matching descendent or <tt>NULL</tt> if no descendent is found.
 429  */
 430 CFXMLTreeRef XMLTreeDescendentNamed( CFStringRef name, CFXMLTreeRef tree );
 431
 432
 433
 434
 435 CFTypeRef XMLTreeXPath( CFMutableStringRef xpath, CFXMLTreeRef tree );
 436