TBXML V1.2

TBXML is a light-weight XML document parser written in Objective-C designed for use on Apple iPhone / iPod Touch devices. TBXML aims to provide the fastest possible XML parsing whilst utilising the fewest resources. This requirement for absolute efficiency is achieved at the expence of XML validation and modification. It is NOT possible to modify and generate valid XML from a TBXML object and NO validation is performed whatsoever whilst importing and parsing an XML document.

TBXML is developed and maintained by Tom Bradley.

The design goals for TBXML are:

Files included with TBXML are:

1. TBXMLElement

   The TBXMLElement structure holds information about a single XML element. The structure holds the element name & text along with pointers to the first attribute, parent element, first child element and first sibling element. Using this structure, we can create a linked list of TBXMLElements to map out an entire XML file.

   typedef struct _TBXMLElement { char * name; char * text; TBXMLAttribute * firstAttribute; struct _TBXMLElement * parentElement; struct _TBXMLElement * firstChild; struct _TBXMLElement * currentChild; struct _TBXMLElement * nextSibling; struct _TBXMLElement * previousSibling; } TBXMLElement;

2. TBXMLAttribute

   The TBXMLAttribute structure holds information about a single XML attribute. The structure holds the attribute name, value and next sibling attribute. This structure allows us to create a linked list of attributes belonging to a specific element

   typedef struct _TBXMLAttribute { char * name; char * value; struct _TBXMLAttribute * next; } TBXMLAttribute;

3. TBXMLElementBuffer

   The TBXMLElementBuffer is a structure that holds a buffer of TBXMLElements. When the buffer of elements is used, an additional buffer is created and linked to the previous one. This allows for efficient memory allocation/deallocation elements.

   typedef struct _TBXMLElementBuffer { TBXMLElement * elements; struct _TBXMLElementBuffer * next; struct _TBXMLElementBuffer * previous; } TBXMLElementBuffer;

4. TBXMLAttributeBuffer

   The TBXMLAttributeBuffer is a structure that holds a buffer of TBXMLAttributes. When the buffer of attributes is used, an additional buffer is created and linked to the previous one. This allows for efficient memeory allocation/deallocation of attributes.

   typedef struct _TBXMLAttributeBuffer { TBXMLAttribute * attributes; struct _TBXMLAttributeBuffer * next; struct _TBXMLAttributeBuffer * previous; } TBXMLAttributeBuffer;

1. - (id)initWithXMLFile:(NSString*)aXMLFile fileExtension:(NSString*)aFileExtension

   Instantiates a TBXML object and parses the specified file. The following code instantiates a TBXML object and parses books.xml

   TBXML * tbxml = [[TBXML alloc] initWithXMLFile:@"books" fileExtension:@"xml"];

2. - (id)initWithXMLString:(NSString*)aXMLString

   Instantiates a TBXML object and parses the specified XML string. The following code instantiates a TBXML object and parses the given XML

   tbxml = [[TBXML alloc] initWithXMLString:@"<root><elem1 attribute1=\"elem1-attribute1\"/><elem2 attribute2=\"attribute2\"/></root>"];

3. - (id)initWithXMLData:(NSData*)aData

   Instantiates a TBXML object and parses the specified XML in an NSData object. The following code instantiates a TBXML object and parses an XML document held in an NSData object

   TBXML * tbxml = [[TBXML alloc] initWithXMLData:myXMLData];

4. - (id)initWithURL:(NSURL*)aURL

   Instantiates a TBXML object then downloads and parses an XML file for the given URL. The following code instantiates a TBXML object and parses the note.xml file from w3schools.com

   tbxml = [[TBXML alloc] initWithURL:[NSURL URLWithString:@"http://www.w3schools.com/XML/note.xml"]];

5. - (TBXMLElement*) childElementNamed:(NSString*)aName parentElement:(TBXMLElement*)aParentXMLElement

   Retrieves the first child element of the specified name from the given parent element. The following code retrieves the first author element from the root element

   TBXMLElement * author = [tbxml childElementNamed:@"author" parentElement:rootXMLElement];

6. - (TBXMLElement*) nextSiblingNamed:(NSString*)aName searchFromElement:(TBXMLElement*)aXMLElement

   Retrieves the next sibling with the specified name starting from the given element. The following returns the next "author" element starting from the given author element

   TBXMLElement * author = [tbxml nextSiblingNamed:@"author" searchFromElement:author];

7. - (NSString*) valueOfAttributeNamed:(NSString *)aName forElement:(TBXMLElement*)aXMLElement

   Returns an NSString containing the value of the specified attribute belonging to the given element. The following returns the name attribute from the given author element

   NSString * authorName = [tbxml valueOfAttributeNamed:@"name" forElement:authorElement];

8. - (NSString*) textForElement:(TBXMLElement*)aXMLElement

   Returns an NSString containing the text for the specified element. The following returns the text from the book element

   NSString * bookDescription = [tbxml textForElement:bookElement];

9. - (NSString*) elementName:(TBXMLElement*)aXMLElement;

   Returns an NSString containing the element name for the specified element.

   NSString * elementName = [tbxml elementName:element];

10. - (NSString*) attributeName:(TBXMLAttribute*)aXMLAttribute;

    Returns an NSString containing the attribute name for the specified attribute.

    NSString * attributeName = [tbxml attributeName:attribute];

11. - (NSString*) attributeValue:(TBXMLAttribute*)aXMLAttribute;

    Returns an NSString containing the attribute value for the specified attribute.

    NSString * attributeValue = [tbxml attributeValue:attribute];

To use TBXML, simply include the 4 files into your project.

1. In xcode right click your project file and select "New Group". Type TBXML as the group name.
2. Right click the TBXML group and select "Add" then "Existing Files".
3. Find and select the 4 files (TBXML.h, TBXML.m, NSDataAdditions.h, NSDataAdditions.m). Check the "Copy items into destination group's folder (if needed)" checkbox is ticked. This ensures a copy of TBXML stays with the project.
4. Locate the Targets node in the group tree under your project. Click the arrow to expand and right click your project's target file. Select "Get Info" and navigate to the "General" tab. Click the plus symbol at the bottom of the window to add a linked library. From the list, select "libz.dylib". You can now close this info window.

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

Or instantiate a TBXML object and supply the XML string to parse.

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

Or instantiate a TBXML object and supply the URL of an XML document to retrieve and parse.

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

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.

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.

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

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.

The following sample code gives an example of how you would use TBXML to decode an XML file.

The sample code is based on the below XML.

The following code can be used to pass the sample "books.xml" file into Author and Book classes. It starts by obtaining the root document element and traversing all child elements named "author". For each author found, an Author class is instantiated and populated with the author name. We then pass all child elements of the author element looking for book elements. For each book found, a Book class is instantiated and populated with the book title. The "description" child element is then obtained from the book element, and it's text extracted to give us the books description.

The following code loads the "books.xml" file then traverses all elements, displaying their name along with all attributes and values to the log window.

Copyright (c) 2009 Tom Bradley

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Problem

bytesLength is not set correctly for the required encoding scheme

Solution

On Line 80 of TBXML.m in method "- (id)initWithXMLString:(NSString*)aXMLString"

Replace

bytesLength = [aXMLString length];

With

bytesLength = [aXMLString lengthOfBytesUsingEncoding:NSASCIIStringEncoding];