clojure/data.xml — pull request #7 by dpx-infinity (2012-12-21 20:53:19+00:00)
Title: Proper indenting XMLStreamWriter; support for loading comments; support for storing location metadata

My pull request consists of three main parts:
1. proper implementation of XML indentation via custom implementation of XMLStreamWriter;
2. support for loading comments;
3. support for storing location information.

Justification for each one is as follows.
1. Currently indenting an XML document created via clojure.data.xml is very hacky: XML document is first printed into a string and then read again via another API and then emitted even again, which is certainly not acceptable for applications requiring either performance or processing of large XML documents or both.
An implementation of custom XMLStreamWriter wrapper which will indent the document serially while it is being written to the output is the preferred way to use StAX API. This pull request includes pure Clojure implementation of such indenting writer. It is heavily inspired by [stax-utils](http://java.net/projects/stax-utils/sources/svn/content/trunk/src/javanet/staxutils/IndentingXMLStreamWriter.java?rev=238) implementation, though it differs from the latter in several ways.
I guess there is no point in describing why this feature is important.
My implementation may be too hacky and it is certainly imperfect; suggestions on its improvement and fixes are welcome.
2. Currently clojure.data.xml ignores comments from the document. Sometimes this is unacceptable, for example, when the program should process, transform and write back XML configuration files, i.e. ones which are supposed to be read by humans. Comments are important part of such files, and lack of their support is serious flaw.
This pull request adds the support of loading comments. It is triggered via an optional keyword parameter to `parse` and `parse-str` functions. Adding this support was simple, esp. because emitting of comments is already supported, and there are corresponding data structures present.
3. The last feature is loading location information. Sometimes it is useful to get an information where exactly some element is located in the XML file. This could be used to process heavily formatted XML document (e.g. some unusual comments placement which is needed for human readability): first a line:column position of an XML node inside a file is found via locating it with, say, XPath selector, and reading its metadata, and then the file is processed manually with string processing functions which are very local in their effect and will not kill formatting.
This pull request adds the support for storing location information provided by StAX parser within elements metadata. Currently only start elements metadata location is supported. This feature is triggered via an optional parameter to `parse` and `parse-str` functions.

Hope this would be useful. There are no pure clojure XML parsers with support for indentation, for example, so it would be great if this pull request gets integrated into the main branch.

If something is required from me first before this could be merged, please do tell me, I'll try to do what I can. I'm not very used to advanced Git/Github features related to branching, so I'm sorry if I did/will do something wrong.

Cheers,
Vladimir.