XmlTools: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (touch-up)
m (using hatnote template)
 
(48 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Overview==
{{Hatnote|This documentation uses many technical [[wp:XML|XML]]-related expressions such as: element, parent element, node, attribute. Therefore it is highly recommended that you have a basic background in XML before using XmlTools or reading its documentation. You'll find a good quick tutorial to familiarize yourself with these terms and XML itself [https://www.w3schools.com/xml/xml_whatis.asp on this page].}}
XmlTools is a command-line modding tool that operates on XML files, especially those exported by [[OniSplit#XML|OniSplit]]. It was developed in C# and works in both Mac OS X (Latest Mono required) and Windows (.NET 3.5 required).
XmlTools is a command-line modding tool developed by [[User:Script 10k|s10k]] to operate on XML files, especially those exported by [[OniSplit#XML|OniSplit]]. It supports many basic operations, and allows more complex programmable operations through [[wp:JavaScript|JavaScript]]. It is written in C++, works in both macOS and Windows, and is currently very efficient in terms of performance.


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|AE Framework - XML patching]].
The initial version was written to help with the development of the Old China level mod and was written in C# previous to v2.0, but later was rewritten in C++ for performance and cross-platform reasons. It was then developed further for the purposes of the [[AE]] so that resources could be patched smartly.  


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.
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.
The full documentation for XmlTools' commands is found on the [[XmlTools/Full documentation|Full documentation]] subpage.


==Links==
==Links==
*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]].
*Download the tool [http://mods.oni2.net/node/265 here] and its dependencies [http://mods.oni2.net/node/304 here], or download them together using the [[AEI]]'s Tools menu.
*XmlTools is used along with OniSplit as the backend for the GUI tool [[Vago_(tool)|Vago]].
*XmlTools is used along with OniSplit as the backend for the GUI modding tool [[Vago_(tool)|Vago]].


==Features==
==Features==
*'''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).
*'''Update all values in a set of XML elements''' (e.g., re-position an OBAN animation or adjusting the pelvis height of a TRAM).
*'''Invert a chain of values''' (sample use: inverting an OBAN animation).
*'''Inverts a set of XML elements''' (e.g., reverse the motion of 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).
*'''Add new values to a set of XML elements''' (e.g., add the 'unkillable' flag to some characters in a level).
*'''Remove values from XML elements''' (sample use: removing boss shields from characters in a level).
*'''Remove values from a set of XML elements''' (e.g., remove 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).
*'''Replace values in a set of XML elements''' (e.g., increase the health of characters by replacing the old HP value).
*'''Add/remove XML elements''' (sample use: adding particles to an attack).
*'''Patch file support''' that allows the modder to list multiple commands in a file, to all be performed at once.
*'''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).
*'''Add new XML inside existing nodes''' (patch only).
*'''Patch file support''' allows the modder to list multiple commands in a file, on separate lines, to all be performed at once.
*'''Remove XML nodes''' (patch only).
*'''Powerful custom XML editing using JavaScript''' (e.g., to employ complex logical or mathematical operations) (patch only).
 
* To select the elements to which the above operations will apply, you can supply the '''element name, parent element name, attribute name/value, or an XPath expression'''.


==Syntax==
==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.
You can see XmlTools' options by supplying the '''--help''' option or no option at all. 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 environment variable. On the Mac, be sure to use <tt>/</tt> rather than <tt>\</tt> in paths.


The basic syntax is:
The basic syntax is:
{|
{|
|-
|-
|'''Windows'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em;">xmlTools.exe</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">addvalue</span> <span style="background:rgb(255,156,156); border-radius:0.33em;">-value:"DropWeapon"</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">-element:Flags</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">-filename:TRAMSTRCOMhit_fallen1.xml</span></tt>
|'''Windows'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em;">XmlTools.exe</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--add-values</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--element-name</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">"Weapon"</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--new-val</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">"w1_tap"</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--files</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">"BINACJBOCharacter.xml"</span></tt>
|-
|-
|'''Mac'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em;">mono xmlTools.exe</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">addvalue</span> <span style="background:rgb(255,156,156); border-radius:0.33em;">-value:"DropWeapon"</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">-element:Flags</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">-filename:TRAMSTRCOMhit_fallen1.xml</span></tt>
|'''Mac'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em;">./XmlTools</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--add-values</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--element-name</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">"Weapon"</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--new-val</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">"w1_tap"</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">--files</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">"BINACJBOCharacter.xml"</span></tt>
|}
|}


Line 36: Line 41:
|- valign="top"
|- valign="top"
|<span style="background:rgb(235,235,235); border-radius:0.33em;">'''Invocation'''</span>
|<span style="background:rgb(235,235,235); border-radius:0.33em;">'''Invocation'''</span>
|Windows can refer to the program directly, but Macs use Mono to run the .NET app; note also that if xmlTools.exe is not in the Command Prompt/Terminal's current directory, you must provide the full path to it or set the path variable.
|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 environment variable.
|-
|<span style="background:rgb(175,175,255); border-radius:0.33em;">'''Option'''</span>||The command to perform. Note that commands are prefaced by a <tt>--</tt>; some commands also have a short version which is composed of a single <tt>-</tt> followed by a letter.
|-
|-
|<span style="background:rgb(175,175,255); border-radius:0.33em;">'''Operation'''</span>||The command to perform. Note that commands are <u>not</u> prefaced by a <tt>-</tt>, whereas the arguments supplied after the commands <u>are</u>.
|<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 [https://tldp.org/LDP/Bash-Beginners-Guide/html/sect_03_04.html Unix shell expansion].
|- valign="top"
|- valign="top"
|<span style="background:rgb(255,156,156); border-radius:0.33em;">'''Operation-specific argument(s)'''</span>||This is where you supply the arguments that this specific command needs. As seen below, addvalue requires the value to add to a space-separated list, so we provide that here. Note the use of quotes as specified in the command's documentation below.
|- valign="top"
|<span style="background:rgb(156,255,156); border-radius:0.33em;">'''Global argument(s)'''</span>||Make sure you specify the full path to the file if the file is not in the current directory. No quotes are used for these commands unless you need to pass a file name path with spaces in it.
|}
|}


==Global command-line arguments==
==Command-line operations==
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.
You can use any of the following operations with XmlTools. If you don't provide all the required options to an operation, XmlTools will notify you.
{|
 
!
===Options===
! style="width:175px"|
<tt>[[XmlTools/Full_documentation#--add-values|-a, --add-values]]</tt>
|-
:Adds new values to a set of XML elements;
|'''(Optional)'''||<tt>-nobackups</tt>||XmlTools will not create a backup file (speeds up operations).
 
|-
<tt>[[XmlTools/Full_documentation#--remove-values|--remove-values]]</tt>
|'''(Optional)'''||<tt>-debug</tt>||Not used yet. It will be probably used to output some debugging information in the future.
:Removes values from a set of XML elements;
|- valign="top"
 
|'''(Optional)'''||<tt>-filename:<XML file></tt>||Specifies file to modify (allows wildcards '*','?') (backup made by default) (when not used, XmlTools will apply the operation over all the XML files in the same directory as xmlTools.exe).
<tt>[[XmlTools/Full_documentation#--replace-value|--replace-value]]</tt>
|-
:Replaces a specific value in a set of XML elements;
|style="background-color:rgb(175,175,0)"|'''(Required)'''||<tt>-element:<XML tag></tt>||Specifies XML tag to look for in the file.
 
|-
<tt>[[XmlTools/Full_documentation#--replace-all-values|--replace-all-values]]</tt>
|'''(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.
:Replaces all values in a set of XML elements;
|}
 
<tt>[[XmlTools/Full_documentation#--update-elements|-u, --update-elements]]</tt>
:Shifts all values in a set of XML elements by an offset;
 
<tt>[[XmlTools/Full_documentation#--invert-elements|-i, --invert-elements]]</tt>
:Reverses a set of XML elements.
 
===Input options===
<tt>-c, --current-val <current-val></tt>
:Value to be replaced or removed (use space as separator)
 
<tt>-n, --new-val <new-val></tt>
:New value(s) to add or replace current value (use space as separator)
 
<tt>-d, --diff-old-new-val <diff-old-new-val></tt>
:Difference to adjust values by, when using '''--update-values'''


;-parelement
<tt>--positions <positions></tt>
:Let's say that an XML file has two tags with the same name, e.g.:
:Positions [use space as separator] (zero-based index)
<xml>
    <Volume>
          <Min>1</Min>
          <Max>1</Max>
    </Volume>
    <Pitch>
          <Min>1</Min>
          <Max>1</Max>
    </Pitch>
<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".
<tt>-f, --files <files></tt>
:XML files to process (wildcards supported)


==Command-line operations==
<tt>-p, --patch-files <patch-files></tt>
Arguments in square brackets are optional.
:Patch files to process (wildcards supported)


<tt>updatechainvalues -newvalue:<quoted string> [-valpositions:<quoted string>] [-valrelation:<quoted string>]</tt>
<tt>--force-target-files <force-target-files></tt>
:Update a value chain, starting at the -newvalue;
:Force the patch-files operation in the specified XML files (wildcards supported)
:<tt>-valpositions</tt> (optional) is zero-indexed and can be a single value or a space-separated list, e.g. <tt>-valpositions=0 1 4</tt>;
:<tt>-valrelation</tt> (optional) means ???.


<tt>invert</tt>
<tt>-e, --element-name <element-name></tt>
:Inverts a value chain
:Name of the XML element(s) where processing will occur


<tt>addvalue -value:<quoted string></tt>
<tt>--parent-element-name <parent-element-name></tt>
:Adds value or space-separated list of values into an element.
:Name of the XML parent element of <element-name> (can be used to filter out elements in different parts of the hierarchy that have duplicate names)


<tt>removevalue -value:<quoted string></tt>
<tt>--attribute-name <attribute-name></tt>
:Removes value or space-separated list of values from an element.
:Attribute name of <element-name> (used as filter)


<tt>replacevalue -oldvalue:<string> -newvalue:<string></tt>
<tt>--attribute-value <attribute-value></tt>
:Replaces specified old value, if found, with new value.
:Attribute value of <attribute-name> (used as filter)


<tt>replaceall -value:<string> [-valpositions:<quoted string>]</tt>
<tt>-x, --xpath-expression <xpath-expression></tt>
:Replaces value in element with new value, no matter its previous value.
:[https://www.w3.org/TR/1999/REC-xpath-19991116/ XPath 1.0] expression (used as filter)


<tt>showerrtypes</tt>
<tt>--no-backups</tt>
:Show error numbers and their internal names.
:Don't make backups of XML files (faster processing)


<tt>patchfile [-forceinfiles:<file names>]</tt>
<tt>--no-verbose</tt>
:Changes <tt>-filename</tt> argument to refer to a patch file and applies this patch to the files specified. You specify the files to patch by using the patch file's <tt>[File <quoted file name>]</tt> argument (see below), or else by naming the files on the CLI with the <tt>-forceinfiles</tt> argument (allows wildcards '*', '?'). See below for patching commands.
:Reduce the number of text messages in output (faster processing)


==Patch file operations==
==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.
Patch files are primarily used to create a list of commands within one file that you can pass to XmlTools to execute all at once, to insert blocks of XML into existing nodes, and to use 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#Installation|HERE]] to learn how the [[AEI]] handles patch mods.
 
Comments in patch files begin with a '#'.
 
===Commands===
Operations in patch files always begin with an '@'. The commands are named in upper case and with words separated by an underscore (_).
 
<tt>[[XmlTools/Full_documentation#.40XML_TOOLS|@XML_TOOLS]]</tt>
:Options for running XmlTools. Right now is only used to specify the minimum version of XmlTools needed for the current patch file.
 
<tt>[[XmlTools/Full_documentation#.40ADD_INSIDE_NODES|@ADD_INSIDE_NODES]]</tt>
:Adds the following XML to existing XML nodes
 
<tt>[[XmlTools/Full_documentation#.40REMOVE_NODES|@REMOVE_NODES]]</tt>
:Removes existing XML nodes


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.
<tt>[[XmlTools/Full_documentation#.40COMMAND|@COMMAND]]</tt>
:Runs any of the commands available under "Command-line options" above. Use the usual command-line syntax described in that section.


Arguments in square brackets are optional.
<tt>[[XmlTools/Full_documentation#.40CUSTOM_CODE|@CUSTOM_CODE]]</tt>
:Executes the following JavaScript code for the purpose of editing the XML. If you are creating a patch mod for the AE, <u>you should try to avoid this operation as much as possible</u> because it is much slower than the native XmlTools commands.


<tt>@ADDTO Element <quoted tag name> [ParentElement <quoted tag name>] [File <quoted file name>]</tt>
===Command options===
:Adds the raw XML that follows to the named array tag.
The values supplied for the following options must <u>always</u> be inside quotes (""). The option names use [http://wiki.c2.com/?PascalCase Pascal case].
@ADDTO Element "Particles"
<xml>
    <Particle>
      <Start>0</Start>
      <End>45</End>
      <Bone>Head</Bone>
      <Name>glass_break</Name>
    </Particle>
</xml>


<tt>@REMOVE Element <quoted tag name> [ParentElement <quoted tag name>] [File <quoted file name>]</tt>
<tt>Files</tt>
:Removes named element from the array tag named by ParentElement.
:[https://www.computerhope.com/jargon/w/wildcard.htm Wildcard] that matches the file(s) that you want to edit


<tt>@COMMAND <command-line string></tt>
<tt>ElementName</tt>
:Runs any of the commands available under "Command-line operations" above. Use standard command-line syntax described in that section, including <tt>-filename</tt>.
:XML element name where processing will occur
@COMMAND invert -element:Height -parelement:Heights -filename:test.xml


<tt>@CUSTOMCODE [File <quoted file name>]</tt>
<tt>ParentElementName</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.
:Name of parent element of ElementName (can be used to filter out elements in different parts of the hierarchy that have duplicate names)
: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.


Here is a sample usage for <tt>@CUSTOMCODE</tt>:
<tt>AttributeName</tt>
:XML attribute name of the ElementName (used as filter)


Sample XML file to be patched:
<tt>AttributeValue</tt>
<Oni>
:XML attribute value of the AttributeName (used as filter)
  <Animation>
    <Lookup>
      <Type>KickForward</Type>
      <AimingType>KickForward</AimingType>
      <FromState>RunBackStart</FromState>
      <ToState>Standing</ToState>
      <Varient>Combat</Varient>
      <FirstLevel>4</FirstLevel><span style="color:#008000"><nowiki><!--</nowiki>The JavaScript code below will change this tag's value from 4 to 0--></span>
      ...
      </Lookup>
  </Animation>
</Oni>


<tt>XPathExpression</tt>
:[http://zvon.org/comp/r/tut-XPath_1.html#intro XPath 1.0] expression (used as filter)


XmlTools patch file contents:
<tt>Options</tt>
@CUSTOMCODE
:Allows you to name any of the [[#Command-line_operations|command-line operations]]. Values must be within " ' " to avoid confusion with the quotes.
<nowiki><code></nowiki>
  var parser = new DOMImplementation(); <span style="color:#008000">// instantiate the W3C DOM Parser</span>
  var domDoc = parser.loadXML($xmlData); <span style="color:#008000">// load the XML into the parser and get the DOMDocument, using $xmlData variable</span>
  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>
<nowiki></code></nowiki>
Note that if you don't use the optional <tt>File <quoted file name></tt> argument, the operation will be applied over all the XML files in the same directory as xmlTools.exe -- unless you used the <tt>-filename</tt> argument along with the <tt>patchfile</tt> command as described in that command's documentation above. Note that the <tt>File</tt> argument allows wildcards ('*', '?').


[[Category:Bi-platform modding tools]][[Category:Completed modding tools]][[Category:Modding tutorials]]
[[Category:Bi-platform modding tools]][[Category:Completed modding tools]][[Category:Modding tutorials]]

Latest revision as of 21:52, 2 July 2022

This documentation uses many technical XML-related expressions such as: element, parent element, node, attribute. Therefore it is highly recommended that you have a basic background in XML before using XmlTools or reading its documentation. You'll find a good quick tutorial to familiarize yourself with these terms and XML itself on this page.

XmlTools is a command-line modding tool developed by s10k to operate on XML files, especially those exported by OniSplit. It supports many basic operations, and allows more complex programmable operations through JavaScript. It is written in C++, works in both macOS and Windows, and is currently very efficient in terms of performance.

The initial version was written to help with the development of the Old China level mod and was written in C# previous to v2.0, but later was rewritten in C++ for performance and cross-platform reasons. It was then developed further for the purposes of the AE so that resources could be patched smartly.

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.

The full documentation for XmlTools' commands is found on the Full documentation subpage.

Links

  • Download the tool here and its dependencies here, or download them together using the AEI's Tools menu.
  • XmlTools is used along with OniSplit as the backend for the GUI modding tool Vago.

Features

  • Update all values in a set of XML elements (e.g., re-position an OBAN animation or adjusting the pelvis height of a TRAM).
  • Inverts a set of XML elements (e.g., reverse the motion of an OBAN animation).
  • Add new values to a set of XML elements (e.g., add the 'unkillable' flag to some characters in a level).
  • Remove values from a set of XML elements (e.g., remove boss shields from characters in a level).
  • Replace values in a set of XML elements (e.g., increase the health of characters by replacing the old HP value).
  • Patch file support that allows the modder to list multiple commands in a file, to all be performed at once.
  • Add new XML inside existing nodes (patch only).
  • Remove XML nodes (patch only).
  • Powerful custom XML editing using JavaScript (e.g., to employ complex logical or mathematical operations) (patch only).
  • To select the elements to which the above operations will apply, you can supply the element name, parent element name, attribute name/value, or an XPath expression.

Syntax

You can see XmlTools' options by supplying the --help option or no option at all. You can get the version with the option --version. The commands below must be preceded by either XmlTools.exe (Windows) or ./XmlTools (Mac). If XmlTools is not in the current folder, you can provide the full/relative path to it or set the path environment variable. On the Mac, be sure to use / rather than \ in paths.

The basic syntax is:

Windows XmlTools.exe --add-values --element-name "Weapon" --new-val "w1_tap" --files "BINACJBOCharacter.xml"
Mac ./XmlTools --add-values --element-name "Weapon" --new-val "w1_tap" --files "BINACJBOCharacter.xml"

Here's how it breaks down:

Invocation 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 environment variable.
Option The command to perform. Note that commands are prefaced by a --; some commands also have a short version which is composed of a single - followed by a letter.
Option Value 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 Unix shell expansion.

Command-line operations

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

Options

-a, --add-values

Adds new values to a set of XML elements;

--remove-values

Removes values from a set of XML elements;

--replace-value

Replaces a specific value in a set of XML elements;

--replace-all-values

Replaces all values in a set of XML elements;

-u, --update-elements

Shifts all values in a set of XML elements by an offset;

-i, --invert-elements

Reverses a set of XML elements.

Input options

-c, --current-val <current-val>

Value to be replaced or removed (use space as separator)

-n, --new-val <new-val>

New value(s) to add or replace current value (use space as separator)

-d, --diff-old-new-val <diff-old-new-val>

Difference to adjust values by, when using --update-values

--positions <positions>

Positions [use space as separator] (zero-based index)

-f, --files <files>

XML files to process (wildcards supported)

-p, --patch-files <patch-files>

Patch files to process (wildcards supported)

--force-target-files <force-target-files>

Force the patch-files operation in the specified XML files (wildcards supported)

-e, --element-name <element-name>

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

--parent-element-name <parent-element-name>

Name of the XML parent element of <element-name> (can be used to filter out elements in different parts of the hierarchy that have duplicate names)

--attribute-name <attribute-name>

Attribute name of <element-name> (used as filter)

--attribute-value <attribute-value>

Attribute value of <attribute-name> (used as filter)

-x, --xpath-expression <xpath-expression>

XPath 1.0 expression (used as filter)

--no-backups

Don't make backups of XML files (faster processing)

--no-verbose

Reduce the number of text messages in output (faster processing)

Patch file operations

Patch files are primarily used to create a list of commands within one file that you can pass to XmlTools to execute all at once, to insert blocks of XML into existing nodes, and to use 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 patchfile command documented above. See HERE for instructions on making a patch mod package for the AE and HERE to learn how the AEI handles patch mods.

Comments in patch files begin with a '#'.

Commands

Operations in patch files always begin with an '@'. The commands are named in upper case and with words separated by an underscore (_).

@XML_TOOLS

Options for running XmlTools. Right now is only used to specify the minimum version of XmlTools needed for the current patch file.

@ADD_INSIDE_NODES

Adds the following XML to existing XML nodes

@REMOVE_NODES

Removes existing XML nodes

@COMMAND

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

@CUSTOM_CODE

Executes the following JavaScript code for the purpose of editing the XML. If you are creating a patch mod for the AE, you should try to avoid this operation as much as possible because it is much slower than the native XmlTools commands.

Command options

The values supplied for the following options must always be inside quotes (""). The option names use Pascal case.

Files

Wildcard that matches the file(s) that you want to edit

ElementName

XML element name where processing will occur

ParentElementName

Name of parent element of ElementName (can be used to filter out elements in different parts of the hierarchy that have duplicate names)

AttributeName

XML attribute name of the ElementName (used as filter)

AttributeValue

XML attribute value of the AttributeName (used as filter)

XPathExpression

XPath 1.0 expression (used as filter)

Options

Allows you to name any of the command-line operations. Values must be within " ' " to avoid confusion with the quotes.
Retrieved from "https://wiki.oni2.net/w/index.php?title=XmlTools&oldid=38110"