Iconara DOM framework

A Cocoa framework for manipulating XML-data via the Document Object Model.

• Requirements
• Read me
• Download
• Documentation
• Known bugs & shortcomings
• Forthcoming
• Release notes

Update The code is now available at Google Code: http://code.google.com/p/iconaradom. The contents of this page should be moving there soonish.

Requirements

Mac OS X 10.2 or newer, may work with earlier versions, but that is not tested. Mac OS X 10.3 is recommended (that's the system I'm developing on).

Notice to iPhone developers

I haven't personally tested the framework on the iPhone, but I know of people who at least have tried it out. It may or may not work. It shouldn't be too hard to make work and I'm sure it would be easier to work with than using libxml2 directly.

Notice to users of Mac OS X 10.4 (Tiger)

The framework builds and runs on Tiger, in fact, the current version should have no problem running on Tiger, Panther or earlier systems. There seems to be an issue with the optional NSXML builder, but I'm not certain it's critical, if you need it, you should try for yourself.

In Tiger, Apple has included a tree based API in NSXML, and for most purposes it seems to fill the role of this framework as good, or better. I recommend that if use NSXML before Iconara DOM if you develop for only Tiger. You will have one dependency less, and better reliability than I can ever offer. For most of you, Tiger-only is not an option, and for you Iconara DOM remains, and will continue to be developed.

Read me

What is DOM?

DOM stands for Document Object Model and can be thought as a way of describing an XML-document in terms of a tree of objects. A document has nodes, which in turn contains other nodes, all represented by objects. For those of you who have programmed JavaScript, the document-object is a kind of DOM, representing all (well, almost), tags and other things on the web-page, in Mozilla and Safari this is actually true. DOM is a recommendation from W3C (www.w3c.org/DOM).

What is Iconara DOM?

Iconara DOM is a W3C DOM compliant framework for manipulating XML-data. It defines the core module, plus a basic implementation of the XPath module. I have followed the JDOM and XOM philosophy of integrating DOM into the language, more than being 100% compliant. In my humble opinion, the W3C DOM-interfaces are ugly as hell. Especially if you apply them to Objective-C. Iconara DOM can do more or less everything that a DOM compliant framework can do, in a nice Objective-C way, not in the ugly IDL way. The framework is licenced under the GNU GPL, but I'm willing to release specially licenced versions that can be used in non-GPLed applications. If you are interested in such an arrangement, please contact me, and we'll work something out. As of v2.0 there is a special exception for Free and Open Source software which allows for linking the framework with non-GPL'ed code, as long as that code is licensed under a OSI- approved license (see the documentation for more info).

Why Iconara DOM?

The Document Object Model (the DOM, that is) is a nice interface to work with. It represents XML in a intuitive way, at least if you see XML as a tree-like structure with nodes of different types containing different kinds of data. There has not been, to my knowledge, any DOM framework for Cocoa, before NSXML in Tiger, but even that is not actually DOM compliant. For Java developers there are lots of frameworks available. For us Not so for us Cocoa developers. I wanted to fill a hole in Cocoa.

Installation

The framework is build to be embedded into applications, add it to your project and make sure that it is copied to the frameworks-directory inside the application bundle when the project is built. If you would like a framework that is built to be installed as a standalone framework, you can download the source and build it with the build style ”Deployment (standalone)”. Iconara DOM Framework is written in Objective-C, for those developing Cocoa-applications in Java I suggest using JDOM or XOM which are much better alternatives, but not available to Objective-C-programmers. This framework will do for the basic needs, and perhaps some more demanding and complex tasks as well. Mail your success stories to me!

Download

The framework is currently at v2.0 (released 15 March 2005).

• Download v2.0 (includes API documentation, FAQ and a small example application)
• Browse v2.0 API documentation
• Browse the source

These are some extras that you can download and use with the framework. Currently there is an experimental builder based on the libxml2 library, and a stable builder based on Apple's NSXML (may be shaky on Tiger, because of the updates to NSXML).

• Download Libxml2Builder
• Download NSXMLBuilder

Documentation

• FAQ
• API documentation

Known bugs & shortcomings

• XPath support is not complete. Complex (depending on how you define it) predicates are not supported yet.
• There's a bug in -[DOMText wholeText], it will be fixed in the next release.

Forthcoming

• Bugfixes for v2.0
• XSL transformation support
• NSXML (Tiger) integration
• Support for complex and arbitrary predicates in XPath expressions
• A proper front-end to the libxml DOM (the basics are already there)
• More questions & answers for the FAQ

Release notes

2005-03-15 (v2.0)

Major rewrite, new XPath support and lots of bug-fixes. The framework is now tested to a much larger extent than before, much thanks to the TestRunner framework, which I developed to be able to do unit testing properly (the existing frameworks are too bloated for my taste/needs).

• Huge API-changes. I have rethought some parts of the framework, and changed added, removed and changed names of methods everywhere. Sorry, but it had to be done. You'll get a ton of build errors if you try to recompile with the new version.
• The core of the framework now consist of a set of protocols that define the DOM API, and a corresponding set of classes that implement that API.
• Rewrote the XPath engine, now compiles expressions. Handles most things, but still a bit short on predicates (although only quite complex predicates, or predicates with functions and calculations in them fail).
• New namespace handling, which works.
• New parser/builder architecture.
• New builder built on top of the widely used XML-parser Expat, as well as a simple plug-in architecture for builders. It works much better than the old CoreFoundation builder.
• Support for alternative implementations of the core node classes, and mixing of implementations.
• The outputter can render elements inlined (no newline before or after).
• Added a document fragment class.
• Added some classes for encapsulation traversals of the DOM tree.
• Rewrote the formatter with the new traversal classes.
• New postprocessor API (for handling things like XInclude).

2003-07-28 (v1.1.5)

Bugfixes for v1.1, plus some more DOM-compliance

2003-07-23 (v1.1)

Added XPath filters, a really cool feature that I have been planning on including for almost a year. Parts of the framework has now been properly tested, both for functionality and for memory leaks. Also worked a lot on DOM-compliance, some methods have been renamed or removed due to this, but the changes are not that big, just recompile with the new version and fix all warnings.

• XPath filters!
• More DOM compliance, most parts of Level 1, 2 and 3 are now implemented.
• Preprocessor support for parsers, and a entity resolving preprocessor that is used by default so that external entities are resolved properly.
• Wrote some code to check for memory leaks that could be useful for other applications, check out InstanceCounting for more instructions and source code.

2003-05-16 (v1.0.1)

Bugfixes to 1.0, and a small new feature

• Added the possibility to build a document from a URL, at the request of a user.

2003-04-27 (v1.0)

Fixed the parser, which means that the framework feels complete enough for version 1.0!

• The builder/parser now works fine, I reverted to my original interface to CF XML Services using the ”high level” stuff instead of the ”low level” I have tried and failed with...

2002-12-15 (v0.9)

Created ix editor to test the framework more thoroughly

• The ix editor test application, a simple XML-editor
• Found some subtle bugs bugs in DOMParentNode/DOMElement when playing around with ix

2002-12-25 (v0.8.1)

Bugfixes to 0.8

• Precompiled prefix header
• DOMDocument can no longer contain CDATA sections
• DOMDocument handles adding and removing of root elements and doctypes correctly

2002-12-15 (v0.8)

First public release! Ignore version 0.7, it was a mistake. Complex and ugly. But DOM Level 2 Core compliant... This version build directly on 0.6, skipping 0.7.

• Added DOMCharacterData, DOMCDATASection and made DOMComment and DOMText subclasses of DOMCharacterData and DOMCDATA a subclass of DOMText.
• The framework is almost DOM Level 2 Core compliant again, following the style of JDOM and XOM.
• DOMAttribute and DOMDocument are both nodes.
• DOMDocument and DOMElement inherits from the new abstract class DOMParentNode
• Implemented the high-level interface to the low-level parser in DOMBuilder and the formatter in DOMFormatter.

2002-08-29 (v0.7)

The other day I thought to myself: "this framework is soon ready for release". Then I realised that the W3C has recommendations for the DOM... so now the framework is completely rewritten for DOM Level 2 Core compliance. This is implemented through categories on all the classes that define the methods and getters/setters required. Don't think it was easy. I threw away all my old code.

• Added a DOM Level 2 Core Compliance layer to the framework.
• Added the DOMCharacterData, DOMCDATASection, DOMDocumentFragment, DOMDocumentType, DOMEntity, DOMEntityReference and DOMNotation classes.
• Added categories to NSMutableArray and Dictionary to work as NodeList and NamedNodeMaps. Maybe this should be solved more elegantly.
• Added the DOMNodeContainer class. It is used by all nodes that contain children to simplify adding and removing.
• The framework is now completely commented with the method specifications from the DOM recommendation.

2002-08-19 (v0.6)

• All "toString*"-methods have been removed. They will soon be replaced by some other, more Objective-C-like magick.
• DOMNode does not declare the -setNamespace: and -namespace:-methods, they have been moved to DOMElement since no other node type can be in a namespace anyway.
• Started writing tests

2002-08-14 (v0.5)

• Finalised the parser and tidied up parts of the code.
• Added a lot to this readme and added more examples.
• All getter-methods were renamed to fit Objective-C-naming standards instead of my old, hard-to-shake-off Java standards (this means that all "-getXXX" were renamed to "-xxx", for example "-getName" has become "-name").

2002-05-24 (v0.4)

• Added support for filters.
• Wrote examples, this Readme and the Usage document.

2002-05-19 (v0.3)

• Created the first version of the parser.
• Added the class for namespaces and incorporated namespaces throughout the framework.

2002-05-05 (v0.2)

• Added classes for comments, text nodes and attributes.

2002-04-27 (v0.1)

• Created the basic framework, including the classes for document, generic node, element and processing instruction.