Iconara DOM framework
A Cocoa framework for manipulating XML-data via the
Document Object Model.
Update The code is now available at Google Code:
The contents of this page should be moving there soonish.
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.
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
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
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
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.
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
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!
The framework is currently at v2.0 (released 15 March 2005).
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).
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.
- 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
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
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
Rewrote the formatter with the new traversal classes.
New postprocessor API (for handling things like XInclude).
Bugfixes for v1.1, plus some more DOM-compliance
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.
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.
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...
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
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
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.
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.
- 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
- 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").
- Added support for filters.
- Wrote examples, this Readme and the Usage document.
- Created the first version of the parser.
- Added the class for namespaces and incorporated namespaces throughout the framework.
- Added classes for comments, text nodes and attributes.
- Created the basic framework, including the classes for document, generic node, element and processing instruction.