XmlTools: Difference between revisions

The initial version was written to help with the development of the Old China level mod. It was then developed further for the purposes of the [[AE]] so that resources could be patched smartly. To learn about the overall process, read [[Making a patch mod]] and [[Anniversary Edition/Framework#XML patching]].

XmlTools can be used as a standalone tool or as a base for another tool. It can be issued commands directly on the command-line interface (CLI) or passed a text file on the CLI with a list of commands to perform.

*Download the tool in a standalone form [http://mods.oni2.net/node/224 here] or download it using the AEI's [[AEI#Tools|Tool Manager]].

*'''Modify a chain of values''' by supplying a new starting point for the chain (sample use: repositioning an OBAN animation or adjusting the pelvis height of a TRAM).

*'''Invert a chain of values''' (sample use: inverting an OBAN animation).

*'''Add new values into XML elements''' (sample use: adding an item to a space-separated list, i.e. adding to some characters in a level).

*'''Remove values from XML elements''' (sample use: removing boss shields from characters in a level).

*'''Replace values in XML elements''' (sample use: increasing the health of characters by replacing the old HP value).

*'''Add/remove XML elements''' (sample use: adding particles to an attack).

*'''Powerful custom XML editing using JavaScript''' (sample use: any time you need to insert XML dynamically based on what you find in the XML file, or employ logical or mathematical operations).

==Syntax==

The following actions are listed when calling XmlTools with no options passed in. You can get the version with the argument "version". The commands below must be preceded by either <tt>xmlTools.exe</tt> (Windows) or <tt>mono xmlTools.exe</tt> (Mac). If xmlTools.exe is not in the current folder, you can provide the full/relative path to it or set the path variable. On the Mac, be sure to use <tt>/</tt> rather than <tt>\</tt> in paths. The following instructions are for Windows by default.

 

 

==Global command-line arguments==

You may use these arguments with each command listed in the "Command-line operations" section below. Note that the <tt>-element</tt> is required in all CLI commands, otherwise you can't tell XmlTools what to modify.

|'''(Optional)'''||<tt>-nobackups</tt>||XmlTools will not create a backup file (speeds up operations)

|'''(Optional)'''||<tt>-debug</tt>||Not used yet. It will be probably used to output some debugging information in the future.

|'''(Optional)'''||<tt>-filename:<XML file></tt>||Specifies file to modify (allows wildcards '*','?') (backup made by default) (when not used will apply the operation over all the xml files in the same directory of xmlTools.exe)

|style="background-color:rgb(175,175,0)"|'''(Required)'''||<tt>-element:<XML tag></tt>||Specifies XML tag to look for in the file

|'''(Optional)'''||<tt>-parelement:<XML tag></tt>||Specifies XML tag that contains -element tag to pick between elements that have the same name but have different parent elements

<xml>

<xml>

In the above code you can differentiate the two "Min" elements by their parent elements. So you can use <tt>-element:Min -parelement:Pitch</tt> to refer to the "Min" element under "Pitch".

==Command-line operations==

Arguments in square brackets are optional.

:Update a value chain, starting at the -newvalue;

:Inverts a value chain

==Patch file operations==

Patch files are mainly used for two purposes: to create a list of commands within one file that you can pass to XmlTools to execute all at once, and to use [[wikipedia:JavaScript|JavaScript]] code to modify the XML.

 

To make a patch, create a plain-text file that uses the following commands and pass it to XmlTools using the <tt>patchfile</tt> command documented above. See [[Making a patch mod|HERE]] for instructions on making a patch mod package for the AE and [[Anniversary Edition/Framework#XML patching|HERE]] to learn how the [[AEI]] handles patch mods.

 

Arguments in square brackets are optional.

<tt>@REMOVE Element <quoted tag name> [ParentElement <quoted tag name>] [File <quoted file name>]</tt>

<tt>@CUSTOMCODE [File <quoted file name>]</tt>

:Executes the JavaScript code inside a <tt><nowiki><code></nowiki></tt> tag. <u>You should avoid this method when possible</u> because it is much slower than the native XmlTools commands.

:The XML library that you can use in your JavaScript code is called ''W3C DOM Parser'' and its documentation is available [http://xmljs.sourceforge.net/website/documentation-w3cdom.html here]. The most important thing to know about the DOM Parser is that the contents of the XML file are saved in the global variable ''$xmlData''. So you will need to access it to edit the XML. Make sure that after the editing process you update ''$xmlData'' with the new XML so the file gets correctly edited.

:Usage example:

Sample XML file to be patched:

       <FirstLevel>4</FirstLevel><span style="color:#008000"><nowiki><!--</nowiki>The JavaScript code below will change this tag's value from 4 to 0--></span>

XmlTools patch file contents:

   var levelNode = domDoc.getDocumentElement().getElementsByTagName("FirstLevel").item(0).firstChild;

   if (levelNode.toString() == "4")

       levelNode.setNodeValue("0"); <span style="color:#008000">// change level from 4 to 0</span>

   $xmlData = domDoc.getDocumentElement().getXML(); <span style="color:#008000">// update the global variable with the new XML</span>

Note that if you don't specify the optional <tt>File <quoted file name></tt> argument, the operation will applied over all the XML files in the same directory as xmlTools.exe. The File argument allows wildcards ('*', '?').