XMLTree.h

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