world.ImportXML

MUSHclient script function (Method) — introduced in version 3.39

Imports configuration data in XML format

Prototype

long ImportXML(BSTR XML);

Data type meanings

Description

This duplicates the functionality in the File menu -> Import -> Clipboard.

It allows you to import one or more triggers, aliases, macros, timers, variables, colours, numeric keypad configuration items.

The two things you cannot import here are general world configuration (use SetOption and SetAlphaOption for that), and plugins.

The XML text should start with one of the following, or -1 will be returned:

<?xml
<!--
<!DOCTYPE
<muclient
<world
<triggers
<aliases
<timers
<macros
<variables
<colours
<keypad
<printing
<comment
<include
<plugin
<script

In other words, to import a trigger you should start with <triggers>. You can import more than one type of thing, eg.

<triggers> ... </triggers> <aliases> ... </aliases>

The syntax is exactly the same as used in the world file, or if you copy a trigger/alias/timers/variable to the clipboard from the world configuration screens.

If there is a parsing error (eg. bad XML format, like unterminated element, or unknown option for an item) then a text window will open with the error description shown. Also, the function will return -2.

If there is no parsing error then the function will return the number of items imported, which might be zero if the syntax was OK, but nothing was actually added, eg. "<triggers></triggers>" would parse OK but not add anything.

If you copy triggers etc. from the world configuration then you will need to "double" the quotes (or escape them appropriately) as you will probably have quotes within quotes. See the examples below for more details.

Note that duplicate items are replaced by ImportXML - so if you already have a trigger / alias / timer of the same name, it will be replaced.

VBscript example

ImportXML _
  "<timers>" & _
  "<timer name=""mylabel"" script=""timerscript"" enabled=""y"" hour=""16"" at_time=""y"" >" & _
  "</timer>" &_
  "</timers>"

Jscript example

ImportXML (
  "<timers>" +
  "<timer name="mylabel" script="timerscript" enabled="y" hour="16" at_time="y" >" +
  "</timer>" +
  "</timers>");

PerlScript example

ImportXML (
  "<timers>" .
  "<timer name="mylabel" script="timerscript" enabled="y" hour="16" at_time="y" >" .
  "</timer>" .
  "</timers>");

Python example

world.ImportXML (
  "<timers>" +
  "<timer name="mylabel" script="timerscript" enabled="y" hour="16" at_time="y" >" +
  "</timer>" +
  "</timers>")

Lua example

ImportXML
[[
<timers>
  <timer name="mytimer" 
         enabled="y" 
         minute="10" 
         group="battle" >
  <send>sigh</send>
  </timer>
</timers>
]]

Lua notes

A useful trick in Lua is to use multiple-line constants, as illustrated above.

Return value

-1 : not XML format - failed initial check
-2 : error parsing XML - see error window
0 or more: count of items imported

Related topic

Utilities

See also