Register forum user name Search FAQ

MUSHclient scripting

Description of MUSHclient world function: world.ImportXML


Name ImportXML
Type Method
Summary Imports configuration data in XML format
Prototype long ImportXML(BSTR XML);
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.


Note: Available in version 3.39 onwards.


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.
Returns -1 : not XML format - failed initial check
-2 : error parsing XML - see error window
0 or more: count of items imported
Introduced in version 3.39

See also ...

Function Description
AddAlias Adds an alias
AddTimer Adds a timer
AddTrigger Adds a trigger
ExportXML Exports a world item in XML format
SetAlphaOption Sets value of a named world alphanumeric option
SetOption Sets value of a named world option

Search for script function

Enter a word or phrase in the box below to narrow the list down to those that match.

The function name, prototype, summary, and description are searched.

Search for:   

Leave blank to show all functions.


Return codes

Many functions return a "code" which indicates the success or otherwise of the function.

You can view a list of the return codes


Function prototypes

The "prototype" part of each function description lists exactly how the function is called (what arguments, if any, to pass to it).

You can view a list of the data types used in function prototypes


View all functions

[Back]

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.