FAQ

¶ I have a file, I want to parse it into a document object.

You want to build a document form a file, this is the easiest way to do it:

id <DOMDocument> document = [DOMBuilder documentFromFile:@"path/to/file.xml"];

¶ I have a document object, I want to write it to a file.

You want to output the document to a file, this is sometimes called serialization. In this framework it accomplished like this:

id <DOMDocument> document = ...; // create a document somehow

[DOMFormatter writeNode:document toFile:@"path/to/file.xml"];

¶ I have a string with some XML, I want to parse it into a document object.

It's not obvious how to do this, but it's really very easy. We start by converting the string to a data object, and then hand it along to the parser:

NSString *XMLText = @"<test>test doc</test>";
NSData *XMLData = [NSData dataWithBytes:[XMLText UTF8String]];

DOMBuilder *builder = [DOMBuilder builder];

id <DOMDocument> document = [builder buildWithData:XMLData];

¶ What about configuring the format when outputing an XML-document?

That's what the DOMFormatOptions class is for. The default options should suffice in most cases, but if you have special needs you can create a format options object and set the properties you want, and then make the formatter use the options. Like this:

id <DOMDocument> document = ...; // create a document somehow

DOMFormatOptions *options = [DOMFormatOptions options];

[options setIndentString:@"    "]; // four spaces

NSString *xmlString = [DOMFormatter stringFromNode:document formatOptions:options];

¶ The license is GPL, what does that mean?

It means that if you just the framework in your application, that application, too, needs to be licensed as GPL, or a compatible license. See http://www.gnu.org/copyleft/gpl.html for more information. The Iconara DOM framework is free software. It is free of charge, and it is free in spirit. If you want to create commercial software (that is not open source or free software), you'll either have to use another framework, or discuss an alternative licencing scheme with me. I could be persuaded into releasing a specially licensed version in exchange for a fee. See the next question. As of v2.0 the framework is GPL'ed with a special exception for free/libre and open source software (FLOSS), which makes it possible to link the framework with any code that is released under an OSI- approved license (for example BSD, Apache and LGPL), without that code having to be GPL'ed.

¶ Any chance of changing the license to Lesser GPL or something else so that I can use the library in my commercial program?

The correct question would have been "can I use your framework in my commercial program if I pay you royalty?". Yes you can. If you want to use the framework in your commercial program, please contact me and describe your licensing scheme. I am not unwilling to release specially-licensed versions of the framework (à la MySQL). The rationale behind GPL in the case of the DOM framework is that I want to release the source, but at the same time I'm not interested in anyone using it for commercial programs because of all the work I have put into it. It's free as in beer if you give something back to the community, it's not if you don't. So if it's pay ware we're talking about, I want my share. If it's just closed source, I want a good reason for not releasing it as open source. See the previous question.

¶ I have an idea/request, do you want to hear it?

Yes. Mail me now. theo at iconara dot net.

¶ What about XSLT? Do you plan to add XSLT-functionality to the framework?

I would really like to have some kind of XSLT-functionality, but it would be very tricky to implement XSLT by myself. I am looking for a XSLT library written in C that can be integrated into the framework without too much hassle. libxslt (http://www.xmlsoft.org) is a hot candidate. I doubt that I'll ever have a solution which transforms the DOM-tree. I think that a possible implementation would serialize the DOM-tree to disk/a string and then pass it on to the XSLT-engine, and then parsing the result into a new DOM-tree. This could be done in about ten lines with libxslt.

¶ What is the state of the XPath support?

The XPath support of the framework is progressing. Most things work nicely, but predicates (the things within [ ]) are tricky bastards. Most things you usually use work, but some complex expressions, or predicates that contain functions may not work. Test you expressions thoroughly! The XPath engine is about a third of the code of the whole framework, that's how complicated it is. And no, I haven't used yacc. I was warned early on that it would be far more complicated than writing the parser myself. There are a few things I would like to change and add, but I think that the current version is ready for release (and it would be about time).

¶ What about encodings? How does the framework support encodings in parsing and outputting?

The framework itself is encoding neutral. It's only when parsing and outputting that encoding is important. The default parser tries to auto-detect the encoding of the data, but if it fails it will assume UTF-8. The default formatter used for output currently only supports outputting UTF-8-encoded documents, and no encoding will be specified in the XML-prolog (which, according to the specs, means that the encoding is UTF-8).

¶Why protocols? I find the syntax ugly.

It's a pity that Objective-C's syntax makes a difference between protocol types and class types, it seems to me that people tend to avoid protocols for this reason. If you really hate the syntax I suggest you use the class types and cast to id where needed. You'll loose some type checking, so it's up to you. As to why protocols: I find programming to protocols much better than programming to concrete implementations. Besides object instantiation, there is no need to know the concrete implementation of an object, and not knowing means that your code doesn't have to change if the underlying implementation changes. For starters check out http://www.cocoadev.com/index.pl?ExtendsIsEvil on CococaDev. The protocols that form the public API of the framework are intended to be a standardized DOM API for Cocoa. However, there are licencing issues that must be dealt with first. Perhaps I will release the protocols as LGPL to enable other Cocoa developers to use them, it depends on whether anyone is interested.

¶ Libxml2 is bundled with Panther, why should I use your framework?

Not to be rude to the developers of libxml2, but the API sucks, and the documentation is even worse. I have written an experimental wrapper for libxml2 for this framework, and it's a pain just to try to understand how to do things. I guess it's robust, but it's robust in a C kind of way, do the wrong thing and it crashes and burns. Iconara DOM is OO and more or less DOM-compliant. Documentation and ease of use that makes Iconara DOM better for Cocoa developers than libxml2.

¶ Tiger adds DOM support to NSXML, what are you going to do about that?

I haven't confirmed this one, as I don't have access to Tiger, but it seems that Apple has finally realized that a proper DOM framework is vital for Cocoa. Bummer for me. I've worked on this framework for three years, just to be replaced by Apple. But their implementation is probably better, anyway. Maybe this framework can co-exist with Apple's, adding the functionality that is missing. We will have to wait and see.

¶ I've got a problem, the default builder can't handle my XML file. It reports an error, but I know that the document is OK.

There's a command-line utility called xmllint that checks XML documents for well-formedness, if that doesn't report any error (it just prints the document back on stdout) then try the NSXML builder (which you can download from the same place as the DOM framework), it might work where the default parser does not (and vice-versa).