XInclude for Haxe

When working with XML files, it’s often convenient to break the data structure down into smaller parts, each saved within a separate file.
There is a standard called XInclude which allows XML sources to reference other XML sources which can help reassemble your separate files into one structure.

As part of my XML Tools library, I’ve implemented an XInclude system which takes in a root XML file, loads in any referenced XML files and returns the complete XML structure.

Note: I’m well aware that XML has become the whipping boy of the web-dev world, but despite it’s verbosity we still have to deal with it.

Structuring your XML

To reference a file from within your root XML file (or any subsequent file), use the ‘include’ element like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// root.xml
<root>
    <include href="child.xml"/>
</root>

// child.xml
<child>
    <grandchild/>
</child>

// results in
<root>
    <child>
        <grandchild/>
    </child>
</root>

Or if you’re already using elements with the name ‘include’, you can use the XInclude namespace:

1
2
3
<root xmlns:xi="http://www.w3.org/2001/XInclude" >
    <xi:include href="child.xml"/>
</root>

As per the spec, if you want the referenced file to be added as a text node, you can specify using the ‘parse’ attribute:

1
<include href="child.xml" parse="text"/>

I’ve also added a feature which is not in the spec but I have found useful in the past. Using the ‘inParent’ attribute, you can have the root element of the referenced XML file ignored, with all of it’s attributes and chidl nodes being added directly to the parent node of the ‘include’ element. Here’s an example of the results:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// root.xml
<root>
    <include href="child.xml" inParent="true"/>
</root>

// child.xml
<child attribute="test">
    <grandchild/>
</child>

// results in
<root attribute="test">
    <grandchild/>
</root>

Installataion

As per usual, you have to install the xmlTools library from haxelib like this:

1
haxelib install xmlTools

And then include this library in your project settings.

Usage

Scroll to the bottom if you’re interested in using the tool from the Command line.
By default it uses the ‘mloader’ haxelib for all of it’s file-system access (you can use your own I/O system by implementing the org.tbyrne.io.IInputProvider interface).

1
2
3
var xmlIncluder = new XmlIncludeManager(new MLoader());
var task:IXmlIncludeTask = xmlIncluder.add("root.xml", "C:/xml/folder");
task.startInclude();

The first parameter here is the name of the root XML file, the second is the folder where all of the XML files are located.
The XML file-paths can include sub-directories of the root directory passed through.

You can then monitor the progress of the task like this:

1
2
3
4
5
6
7
8
9
xmlIncluder.progressChanged.add(onProgressChanged);
xmlIncluder.completeChanged.add(onCompleteChanged);

function onProgressChanged(from:XmlIncludeManager):Void{
    trace("progress: "+from.getProgress()+"/"+from.getTotal());
}
function onCompleteChanged(from:XmlIncludeManager):Void{
    trace("is complete: "+from.getComplete());
}

Command Line interface

I’ve also wrapped this code in an executable shell so that it can be used from the command line.

1
2
3
4
5
// as an executable
XmlIncluderShell root-file.xml -d C:/xml-directory/ -o C:/output-file.xml

// or as a neko executable
neko XmlIncluder.n root-file.xml -d C:/xml-directory/ -o C:/output-file.xml

The first argument is always the root XML file to operate on.
The second argument (-d) is the root directory that contains all of the XML files.
The third argument (-o) is the output file to write the result to.

Multiple executions can be done with one command using the ‘–‘ separator:

1
XmlIncluderShell root-file.xml -d C:/xml-directory/ -o C:/output-file.xml -- root-file2.xml -d C:/xml-directory2/ -o C:/output-file2.xml

Download executable here
Download Neko executable here

1 Comment

  1. Pretty section of content. I just stumbled upon
    your web site and in accession capital to assert that I acquire in fact enjoyed account
    your blog posts. Anyway I’ll be subscribing to your augment and even I achievement you access consistently rapidly.

Leave a Reply

Your email address will not be published.

*

© 2017 Thomas Byrne

Theme by Anders NorenUp ↑