Script function

world.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.

Available in MUSHclient 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.

Return value

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

See Also ...

Topics

Scripting
Utilities

Functions

(AddAlias) Adds an alias
(AddFont) Adds a custom font for use by MUSHclient
(AddTimer) Adds a timer
(AddTrigger) Adds a trigger
(Base64Decode) Takes a base-64 encoded string and decodes it.
(Base64Encode) Encodes a string using base-64 encoding.
(BlendPixel) Blends a single pixel with another, using a specified blending mode
(ChangeDir) Changes the MUSHclient working directory
(CreateGUID) Creates a GUID - Global Unique Identifier
(EditDistance) Returns the Levenshtein Edit Distance between two words
(ErrorDesc) Converts a MUSHclient script error code into an human-readable description
(ExportXML) Exports a world item in XML format
(FilterPixel) Performs a filtering operation on one pixel
(FixupEscapeSequences) Converts "escape sequences" like \t to their equivalent codes.
(FixupHTML) Fixes up text for writing as HTML
(FlashIcon) Flashes the MUSHclient icon on the Windows taskbar
(GenerateName) Generates a random character name
(GetClipboard) Gets the clipboard contents
(GetScriptTime) Returns the amount of time spent in script routines
(GetSoundStatus) Gets the status of a sound started by PlaySound
(GetUniqueID) Creates a unique ID for general use, or for making Plugin IDs
(GetUniqueNumber) Returns a unique number
(Hash) Produces a hash (checksum) of a specified piece of text
(Help) Shows help for a script function, or a list of functions
(Menu) Creates a pop-up menu inside the command window
(Metaphone) Returns the metaphone code for the supplied word
(MoveMainWindow) Move and resize the main MUSHclient window
(MoveWorldWindow) Move and resize a world window
(MoveWorldWindowX) Move and resize a specific world window
(MtRand) Returns pseudo-random number using the Mersenne Twister algorithm
(MtSrand) Seed the Mersenne Twister pseudo-random number generator
(PlaySound) Plays a sound using DirectSound
(ReadNamesFile) Loads in a file for generating character names
(Replace) Replaces one substring with another
(SetAlphaOption) Sets value of a named world alphanumeric option
(SetBackgroundColour) Sets a background colour for the output window
(SetBackgroundImage) Sets a background image for the output window
(SetClipboard) Sets the clipboard contents
(SetForegroundImage) Sets a foreground image for the output window
(SetMainTitle) Sets the main output window title
(SetOption) Sets value of a named world option
(SetSelection) Sets a selection range in the output window
(SetStatus) Sets the status line text
(SetTitle) Sets the world window title
(SetToolBarPosition) Sets the position of the game toolbars on the screen.
(SetUnseenLines) Sets the number of "unseen lines" for this world
(ShiftTabCompleteItem) Adds an item to the list shown for Shift+Tab completion
(Simulate) Simulate input from the MUD, for debugging purposes
(Sound) Plays a sound
(StopSound) Stop playing a sound started by PlaySound
(StripANSI) Strips ANSI colour sequences from a string
(Trace) Trace mode property
(TraceOut) Outputs the supplied message to the world Trace
(TranslateDebug) Sends a debugging message to the localizing translator script
(TranslateGerman) Translate German umluat sequences
(Transparency) Sets the transparency of the main MUSHclient window under Windows XP
(Trim) Trims leading and trailing spaces from a string

(Help topic: function=ImportXML)