GXml: Summer of broken API

Welcome back to the wonderful world of GXml.  Here's an update on progress so far.  (Also, thanks to Daniel Espinosa and Adam Ples for recent contributions to serialisation, XPath support, and bug fixes.)

Code

For those interested in the code so far, it's in its own branch thanks to the abundant API breakage (detailed below): 

https://git.gnome.org/browse/gxml/log/?h=gsoc2013



My plan is to release another in the 0.3.x series without major API breakage, and then release 0.4 soon (during GUADEC) with the major API changes.

GUADEC

Thanks to sponsorship from the GNOME foundation, GXml is going to Brno!  In previous years, I've gotten to know some of you.  This year, I'm going to bug you about your code and, if you use GXml, find out what will get you to use GXml. :D

Memory Magic

Changing models

Before, when you obtained a reference to a node from GXml, you owned it and had to unref it.  However, with GXml, nodes are only really useful while their document exists (which manages things like attribute synchronisation with the underlying libxml2 structures).  Consequently, and to simplify reference handling for users, a GXml document alone now owns references to its nodes, and is entirely responsible for freeing its memory.  All a user of the library must do is unref their GXmlDocument when they're done with it.

Valgrind

Valgrind was used to identify memory leaks, where we failed to free libxml2 data or where we created reference cycles.  I'm hoping to write a useful guide on using valgrind later.  It required a lot of suppression file writing and testing, too, to determine which memory from glib and libxml2 could be released by a user, and which couldn't.

Tests

We have a collection of small valgrind tests now so it should be harder to introduce new memory leaks in the future.

API Chaos

DOM spec compliance: GXmlNode

Formerly, XML nodes were called GXmlDomNode.  That was to avoid namespace conflict in languages where Node could mean GLib.Node or GXml.Node.  However, that meant a lot of extra characters in C.  Since I started using DomNode, it's also grated on me, especially because it's not the name known to the DOM spec.  Consequently, pursuant to earlier blog posts and IRC discussions on the matter, it's now GXmlNode.  Dun dun dun!



Attribute might become Attr and Implementation might become DomImplementation, and DocumentType might become DocType.  Feel free to comment on your thoughts on those compliance questions.  I don't want to change entity names again the future.

Error Reporting Revolution

Regarding an earlier discussion, GXml has been misusing GError just because try-catch exception handling is addictive.  Ultimately, after some discussions and analysis, we've switched from GErrors to issuing g_warnings (and having a last_error variable a user can check after running a function if they're unsure of their code's correctness).



Also, all but one DOMException from the DOM Level 1 Core is now tested for!  (Before, only a few actually were.)  The one that isn't so far is whether a node is readonly, since GXml doesn't have a concept of read-only nodes yet. :)

Educational Euphoria

Documentation

Every property and function should now include a reference to its definition in the DOM Level 1 Core spec.  It should also specify the version of the spec the property or function complies with, so that when we move towards Level 2, etc., you can know what to expect.

Examples

More examples exist under examples/c and examples/js now, and there'll be more to come.

Gritty Reality

Writing test patches for projects like yelp, glade, dconf, and libgdata has helped identify a few bugs or failings in the API which have been fixed.  If you're working on those projects and wonder why you haven't seen a patch yet, it's because they're in flux and need to be re-written once I stop changing the API above. :D

A bold new future

Going forward, there's still a lot to do.  Finalise the API, integrate patches accumulating in bugzilla and in branches (XPath support courtesy Adam Ples?!), serialization update (courtesy of Daniel Espinoza) and measure performance.