XmlTools: Difference between revisions

==XML Background==

This documentation uses many [[wikipedia:XML|XML]] technical expressions such as: element, parent element, node, attribute. Because of this it is highly recommended that you have a basic background of XML before using XmlTools or any of its documentation.

You can get a rapid and good tutorial to get familiar with this expressions and XML itself [http://www.w3schools.com/xml/xml_whatis.asp in this page].

XmlTools is a command-line modding tool that operates on XML files, including those exported by [[OniSplit#XML|OniSplit]]. It supports many operations in XML files and even non implemented operations using custom javascript code.  

 

The initial version was written to help with the development of the Old China level mod and was also written in C# (previous 2.0) but later it was rewritten to C++ due to performance reasons and cross platform problems. 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|AE Framework - XML patching]].

 

XmlTools can be used as a standalone tool or as a base for another tools. 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.

 

Aditional documentation for XmlTools can be found in [[XmlTools/Full documentation]].

*Download the tool [http://mods.oni2.net/node/265 here] and its dependencies [http://mods.oni2.net/node/304 here] or download them all using the [[AEI]].

*XmlTools is used along with OniSplit as the backend for the GUI tool [[Vago_(tool)|Vago]].

*'''Update all values in a set of XML elements''' (e.g., repositioning an OBAN animation or adjusting the pelvis height of a TRAM).

*'''Inverts a set of XML elements''' (e.g., invert an OBAN animation).

*'''Powerful custom XML editing using [[wikipedia:JavaScript|JavaScript]]''' (e.g., to employ complex logical or mathematical operations) (patch only).

* To select elements to the above operations it can be used the '''element name, parent element name, attribute name/value and [http://www.w3.org/TR/xpath/ XPath 1.0]'''.

You can find out the XmlTools options if you don't provide any or when using --help option. You can get the version with the option "--version". The commands below must be preceded by either <tt>XmlTools.exe</tt> (Windows) or <tt>./XmlTools</tt> (Mac). If XmlTools 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.

|Note that if XmlTools is not in the Command Prompt/Terminal's current directory, you must provide the full path to it or set the path variable.

|<span style="background:rgb(175,175,255); border-radius:0.33em;">'''Option'''</span>||The command to perform. Note the commands are prefaced by a <tt>--</tt>, some commands have a short version which is prefaced by a single <tt>-</tt> followed by a letter.

|<span style="background:rgb(156,255,156); border-radius:0.33em;">'''Option Value'''</span>||This is where you supply the value that this specific command needs. As seen below, --element-name requires the XML element name, so we provide that here. Quotes should be used when the value has spaces or to avoid [http://tldp.org/LDP/Bash-Beginners-Guide/html/sect_03_04.html Unix shell expansion].

You can use any of the following operations bellow with XmlTools. If you don't provide all the required options to an operation XmlTools will notice you.

:Add new values to a set of XML elements;

:Replaces 1 value in a set of XML elements;

:Updates all values in a set of XML elements;

:Inverts a set of XML elements.

===Input Options===

:Current value(s) [use space as separator];

:New value(s) [use space as separator];

:Difference between old and new value;

:Positions [use space as separator] [0-index based];

:XML files to process [wildcards supported];

:Patch files to process [wildcards supported];

:Force the patch-files operation in the specified XML files. [wildcards supported];

:Name of the XML element(s) where processing will occur;

:Name of the XML parent element of <element-name> [used as filter];

:Attribute name of <element-name> [used as filter];

:Attribute value of <attribute-name> [used as filter];

:[http://www.w3.org/TR/xpath/ XPath 1.0] expression to select elements where processing will occur;

:No backups [faster processing];

:Reduce the number of text messages output [faster processing].

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, to remove XML nodes, to insert new XML nodes and to use [[wikipedia:JavaScript|JavaScript]] code to modify the XML.

Comments in patch files begin with '#'.

 

Operations in patch files always begin with '@'. They are named using all letters in upper case and words separated by underscore (_).

:XmlTools information. Right now is only used to specify the executable minimum version for the current patch file;

:Adds new XML nodes;

:Removes existing XML nodes;

:Runs any of the commands available under "Command-line options" above. Use standard command-line syntax described in that section;

:Executes the [[wikipedia:JavaScript|JavaScript]] code for XML editing. When specifically you are using this operation for [[Anniversary_Edition/Framework#XML_patching|AE Patches]] <u>you should try to avoid this operation as much as possible</u> because it is much slower than the native XmlTools commands;

 

The values of the following options inputs must be <u>always</u> inside of quotes (""). The input options use [http://c2.com/cgi/wiki?PascalCase pascal casing].

:[http://www.computerhope.com/jargon/w/wildcard.htm Wildcard] that matches the file(s) that you want to edit;

:XML element name where processing will occur;

:XML parent element name of ElementName, used as filter;

:XML attribute name of the ElementName, used as filter;

:XML attribute value of the AttributeName, used as filter;

:[http://zvon.org/comp/r/tut-XPath_1.html#intro XPath 1.0] expression to select elements where the processing will occur;

:Allows to specify any option of [[#Command-line_operations| command-line operations]]. Values must be within " ' " to avoid confusion with the quotes.