TBXML

Adding TBXML to your project

In order to use TBXML, you need to include the following 2 files only.

   TBXML.h
   TBXML.m

If you would like TBXML to automatically decompress XML files before parsing (more info), you will need to include

   TBXML+Compression.h
   TBXML+Compression.m

If you would like TBXML to perform asynchronous HTTP requests (more info), you will need to include

   TBXML+HTTP.h
   TBXML+HTTP.m

Load an XML file from the app bundle

To load an xml file, you need to instantiate a TBXML object and supply the XML file to parse.

    NSError *error;
    TBXML * tbxml = [TBXML tbxmlWithXMLFile:@"books.xml" error:&error];
    
    if (error) {
        NSLog(@"%@ %@", [error localizedDescription], [error userInfo]);
    } else {
        NSLog(@"%@", [TBXML elementName:tbxml.rootXMLElement]);
    }

Optionally specify a file extension.

    NSError *error;
    TBXML * tbxml = [TBXML tbxmlWithXMLFile:@"books" fileExtension:@"xml" error:&error];
    
    if (error) {
        NSLog(@"%@ %@", [error localizedDescription], [error userInfo]);
    } else {
        NSLog(@"%@", [TBXML elementName:tbxml.rootXMLElement]);
    }

Parsing an XML string

Instantiate a TBXML object and supply the XML string to parse.

    NSError *error;
    TBXML * tbxml = [TBXML tbxmlWithXMLString:@"<root><belt color=\"red\"/><belt color=\"green\"/></root>" error:&error];
    
    if (error) {
        NSLog(@"%@ %@", [error localizedDescription], [error userInfo]);
    } else {
        NSLog(@"%@", [TBXML elementName:tbxml.rootXMLElement]);
    }

Parsing XML contained within an NSData object

Instantiate a TBXML object and supply the NSData object containing XML data to parse.

    NSError *error;
    NSData * data = [NSData dataWithContentsOfFile:@"aFile.xml"];
    TBXML * tbxml = [TBXML tbxmlWithXMLData:data error:&error];
    
    if (error) {
        NSLog(@"%@ %@", [error localizedDescription], [error userInfo]);
    } else {
        NSLog(@"%@", [TBXML elementName:tbxml.rootXMLElement]);
    }

Obtaining the XML document's root element

You can obtain the root node of the parsed XML document by accessing TBXML's property "rootXMLElement".

TBXMLElement * rootXMLElement = tbxml.rootXMLElement;

Extracting Elements

The "childElementNamed: parentElement:" method allows you to search for a child element with a given name. The following returns the first "author" element from the document root.

[TBXML childElementNamed:@"author" parentElement:root];

Extracting Attributes

You can obtain an attribute from an element using TBXML's "valueOfAttributeNamed: forElement:" method. The code below shows how you would extract the "name" attribute from the author element.

name = [TBXML valueOfAttributeNamed:@"name" forElement:author];

Extracting Element Text

Given an XML element, you can obtain the text using the "textForElement:" method. The code below extracts the text from the descriptionElement.

NSString * description = [TBXML textForElement:descriptionElement];

Traversing Unknown Elements and Attributes

Each element contains a pointer to the next sibling element called "nextSibling". You can use this to loop through all sibling element. Each element also has a pointer to the first child element called "firstChild". Once you have a child element, you can use [TBXML elementName:element] to return an NSString containing the name of the element.

Each element also has a pointer to the first attribute. You can use [TBXML attributeName:attribute] and [TBXML attributeValue:attribute] to return the name and value of the attribute. Each attribute has a pointer to the next attribute called "next". This can be used to loop through all attributes

- (void)loadUnknownXML {   
    NSError *error = nil;
    
    // Load and parse the books.xml file   
    tbxml = [TBXML tbxmlWithXMLFile:@"books.xml" error:&error];
    
    if (error) {
        NSLog(@"%@ %@", [error localizedDescription], [error userInfo]);
    } else {
        // If TBXML found a root node, process element and iterate all children
        if (tbxml.rootXMLElement)
            [self traverseElement:tbxml.rootXMLElement];
    }
}   

- (void) traverseElement:(TBXMLElement *)element {
   do {
      // Display the name of the element
      NSLog(@"%@",[TBXML elementName:element]);

      // Obtain first attribute from element
      TBXMLAttribute * attribute = element->firstAttribute;

      // if attribute is valid
      while (attribute) {
         // Display name and value of attribute to the log window
         NSLog(@"%@->%@ = %@",  [TBXML elementName:element],
                                [TBXML attributeName:attribute],
                                [TBXML attributeValue:attribute]);

         // Obtain the next attribute
         attribute = attribute->next;
      }

      // if the element has child elements, process them
      if (element->firstChild) 
         [self traverseElement:element->firstChild];

   // Obtain next sibling element
   } while ((element = element->nextSibling));  
}